vt132-quickref/modem.tex

\chapter{The Modem}

\section{Background}

Unlike the VT100 terminal, the modem does not try to faithfully emulate any particular original device.

Instead it is designed to provide an MVP (minimum viable product) providing a modified Hayes 'AT' compatible command set for connecting over Wi-Fi via TCP/IP sockets with an optional Telnet protocol layer.

\begin{itemize}
\item The original 'AT' command set was strictly in upper case. This is because the bit sequence of the ASCII values for 'A' and 'T' have a specific property that enables autobaud detection of the connection to the data terminal equipment (DTE).
\item \textbf{The modem only responds to 'AT' commands in upper case.}
\item Commands are terminated by \texttt{<CR>} (carriage return, \texttt{<ctrl>-m}, \texttt{0x0D}, decimal 13) usually generated by the \texttt{Enter} or \texttt{Return} key on your keyboard.
\item Commands can by edited, before pressing \texttt{<CR>}, using \texttt{<BS>} (backspace, \texttt{<ctrl>-H}, \texttt{0x08}, decimal 8) to erase the previous character entered. You may need to configure the terminal to generate \texttt{<BS>} when you press the \texttt{Backspace} or \texttt{<-} key on your keyboard.
\item The 'AT' command processor is based on a finite state machine (FSM). If you type anything that is not recognized by the rules of the FSM you will immediately see an \texttt{Error} message.
\end{itemize}

% TODO:
% - Hinweis auf EN-Button für Baudrate
% - Hinweis auf Nutzung via Bus oder FTDI-Header

\newpage
\section{Modem commands}
\subsection{Standard commands}

All commands (except \texttt{AT} by itself, \texttt{A/} and \texttt{+++}) need to have (uppercase) \texttt{AT} prefixed.

\begin{tabular}{p{6em} | p{0.75\textwidth}}
\hline
\textbf{Command} & \textbf{Function} \\
\hline
AT	& Test, answers \texttt{OK} \\
A/	& Repeat last command (immediate) \\
\$	& Show Help \\
I or I0	& Show modem model string \\
I1	& Show firmware version string \\
I2	& Show firmware build chain version string \\
Z	& Modem soft reset \\
\&F	& Restore factory defaults (does not store to NVRAM) \\
\&W & Write settings to NVRAM \\
D\textit{host:port}	& Open connection to \textit{host:port}, port defaults to 23 \\
$+++$	& Escape from data mode to command mode \\
O	& Return to data mode \\
H	& Hangup \\
\&A	& Enable Answer mode \\
A	& Answer an incoming call \\
S\textit{n}	& Select register \textit{n} as current register \\
?	& Query current register \\
=\textit{r}	& Set value of register to \textit{r} \\
S\textit{n}=\textit{r}	& Set value of register \textit{n} to \textit{r}, eg. \texttt{S15=1} \\
\&K or \&K0	& Disable RTS/CTS flow control \\
\&K1		& Enable RTS/CTS flow control \\
\hline
\end{tabular}

\subsection{WiFi commands}

\begin{tabular}{p{6em} | p{0.75\textwidth}}
\hline
\textbf{Command} & \textbf{Function} \\
\hline
$+$W?		& Show WiFi status \\
$+$W$=$\textit{sss},\textit{ppp}	& Connect to WiFi SSID \textit{sss} using password \textit{ppp} \\
$+$W\$		& Show WiFi IP address \\
$+$W\#		& Show Wi-Fi MAC address \\
$+$W$+$		& (Re)connect to WiFi \\
$+$W$-$		& Disconnect from WiFi \\
$+$B?		& Query Baud Rate used on serial port \\
$+$B=\textit{n}	& Set Baud Rate on serial port \newline
			(4800, 9600, 14400, 19200, 38400, 57600, 115200) \\
$+$T?		& Query Telnet TERM environment variable \\
$+$T=\textit{ttt}	& Set Telnet TERM environment variable \\
\hline
\end{tabular}

\subsection{OTA update commands}

\begin{tabular}{p{6em} | p{0.75\textwidth}}
\hline
\textbf{Command} 		& \textbf{Function} \\
\hline
$+$U=\textit{url}		& Set custom URL to fetch image from \\
$+$U?					& Query for new version online and show status \\
$+$U\textasciicircum 	& Upgrade to queried version if it is newer \\
$+$U!					& Force upgrade even if queried version is the same or older \\
$+$U\$					& Show OTA partition status \\
\hline
\end{tabular}

\subsection{Enable Telnet mode}

Use \texttt{ATS15=1} to enable Telnet mode.

\newpage
\subsection{S Registers}
\label{sregister}

The modem has a total of 51 'S' registers, \texttt{S0} to \texttt{S50}.

Most of them are undefined and unused. The following table lists all defined registers that are used by the VT132 modem part.

\begin{tabulary}{\textwidth}{L | L | L}
\hline
\mbox{\textbf{Register}} & \mbox{\textbf{Default}} & \textbf{Function} \\
\hline
S0	& 0		& Number of rings before Auto-Answer \newline (0-255, 0 = never) \\
S1	& 0		& Ring Counter (0-255 rings) \\
S14	& 23	& TCP/IP Port for Answer Mode (0-65535) \\
S15	& 0		& Telnet Protocol for Data Mode (0/1) \\
S16	& 3		& Negotiate Telnet SGA (0/1/2/3) \\
S17	& 3		& Negotiate Telnet ECHO (0/1/2/3) \\
S18	& 0		& Negotiate Telnet BIN (0/1/2/3) \\
S19	& 3		& Negotiate Telnet NAWS (0/1/2/3) \\
S20	& 80	& NAWS Negotiate Columns (0-255) \\
S21	& 24	& NAWS Negotiate Rows (0-255) \\
S22	& 3		& Negotiate Telnet TERMINAL-TYPE (0/1/2/3) \\
S39	& 0		& RTS/CTS Flow Control (0/1, set by AT\&K) \\
\hline
\end{tabulary}

\bigskip
\begin{tabular}{rl}
0/1:		& 0 - disabled, 1 - enabled \\
0/1/2/3:	& 0 - Won't/Don't, 1 - Will, 2 - Do, 3 - Will/Do \\
\end{tabular}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%55

\newpage
\section{WiFi Messages}

\subsection{Dial response messages}

The following table shows the responses to the dial command \texttt{ATDhost:port}
\medskip

\begin{tabular}{p{8em} | p{0.68\textwidth}}
\hline
\textbf{Response} & \textbf{Reason} \\
\hline
\footnotesize{\texttt{NO DIALTONE}}			& no Wi-Fi connection has been established with an AP \\
\footnotesize{\texttt{ALREADY IN CALL}}		& a connection is already established ('Dialed' or 'Answered') with another host \\
\footnotesize{\texttt{ERROR}}				& no hostname is provided \\
\footnotesize{\texttt{NO ANSWER}}			& no socket can be opened to the remote \textit{hostname}:\textit{port} \\
\footnotesize{\texttt{CONNECT}}				& a socket connection is opened with \textit{hostname}:\textit{port} \\
\footnotesize{\texttt{CONNECT TELNET}}		& a Telnet connection is opened with \textit{hostname}:\textit{port} \\
\hline
\end{tabular}

\subsection{Query Wi-Fi status messages}

The following table shows the responses to the \textbf{Query WiFi status} command \texttt{AT+W?}
\medskip

\begin{tabular}{p{10.5em} | p{0.6\textwidth}}
\hline
\textbf{Response} & \textbf{Reason} \\
\hline
\footnotesize{\texttt{WIFI NOT STARTED}}	& no Wi-Fi connection has been attempted since power-on or hardware reset \\
\footnotesize{\texttt{WIFI IDLE}}			& Wi-Fi status is queried during a connection attempt \\
\footnotesize{\texttt{WIFI NO SSID}}		& no AP with the given SSID/password is found following the \texttt{AT+W+} or \texttt{AT+W=}\dots commands \\
\footnotesize{\texttt{WIFI CONNECTED}}		& connection successful to an AP with the \texttt{AT+W+} or \texttt{AT+W=}\dots commands \\
\footnotesize{\texttt{WIFI CONNECT FAILED}}	& tba \\
\footnotesize{\texttt{WIFI CONNECTION LOST}}	& lost connection with the AP \\
\footnotesize{\texttt{WIFI DISCONNECTED}}		& unsuccessful connection attempt, or a successful disconnection with the \texttt{AT+W-} command \\
\hline
\end{tabular}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\newpage
\section{Telnet}

\subsection{Telnet options}

The VT132 supports the following Telnet options:

\begin{itemize}
 \item SGA (Suppress Go Ahead)
 \item ECHO
 \item BIN (Binary Transmission)
 \item NAWS (Negotiate About Window Size)
 \item TERMINAL-TYPE
\end{itemize}

Each Telnet Option is negotiated in via a request/response exchange described as \textit{Do/Don't} (request) and \textit{Will/Won't} (response). Trying to understand how these work for each Option usually requires reading the RFC and extreme patience and experimentation.

Usually you either want an Option completely \textbf{On} (Do/Will) or \textbf{Off} (Don't / Won't).

Setting the supported Options and their default values are defined via specific 'S' Registers \vref{sregister}.

In summary the defaults are:

\begin{tabular}{p{6em} | p{5.5em} | p{0.55\textwidth}}
\hline
\textbf{Option}	& \textbf{Default}	& \textbf{Description} \\
\hline
SGA				& Do/Will		& required for the NVT to work character by character and not in linemode \\
ECHO			& Do/Will		& tba \\
BIN				& Don't/Won't	& To operate as an NVT, binary mode is not required. File transfer protocols like KERMIT and XMODEM do their own binary encoding \\
NAWS			& Do/Will		& The remote host can learn your terminal windows size in characters, the default is 80 x 24 set in S20 and S21 respectively \\
TERMINAL-TYPE	& Do/Will		& The remote host can learn your terminal type, the default is vt100 \\
\hline
\end{tabular}
\bigskip

The \texttt{TERMINAL-TYPE} must be known by the remote system to be recognised.

When connecting to \texttt{telnetd} on MacOS I use \texttt{vt100+} from the \texttt{terminfo} database which provides support for color over and above the standard \texttt{vt100} terminal type, making text applications like \texttt{htop} work as expected and in color.

\subsection{Enabling Telnet Protocol}

Telnet protocol is \textbf{not} enabled by default.

\begin{itemize}
\item To enable the Telnet protocol you must manually set 'S' Register S15 to 1 with \texttt{ATS15=1}
\item To disable the Telnet protocol you must manually set 'S' Register S15 to 0 with \texttt{ATS15=0}
\end{itemize}

The Telnet protocol is applied to both \textbf{outgoing} connections 'Dialed' with ATD and \textbf{incoming} connections 'Answered' with \texttt{ATA} or Auto-answer.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\newpage
\section{Answer Mode}

Listening for incoming TCP/IP socket connections is \textbf{not enabled} by default.

\begin{itemize}
\item To \textbf{enable} listening for incoming TCP/IP socket connections you must manually enter \texttt{AT\&A} to \textit{Enable Answer Mode}.
\item Answer Mode will remain enabled, and can only disabled by an \texttt{ATZ} (Soft Reset), hardware reset or power-cycle.
\item Incoming TCP/IP socket connections will cause the modem to respond with \texttt{RING}, repeated every three (3) seconds.
\item As each \texttt{RING} occurs the Ring Counter in \texttt{S1} is incremented by one (1).
\item The user can \textit{Answer} the incoming call at any time with \texttt{ATA} and the modem will accept the TCP/IP socket connection and enter \textbf{Data Mode}.
\item If the \textbf{Number of rings before Auto-Answer} is set in \texttt{S0} to a number greater than zero (0 = never) and \texttt{S1} is greater-then-or-equal to \texttt{S0} the modem will \textit{Auto-answer}: accept the TCP/IP socket connection and enter \textbf{Data Mode}.
\item If Telnet protocol is enabled by \texttt{ATS15=1} then the Telnet Protocol will be negotiated with the remote host after the modem enters \textbf{Data Mode}.
\item The user can \textit{Hangup} an incoming call by sending the Escape Sequence \texttt{+++} (with guard times) to return to \textbf{Command Mode} and then sending \texttt{ATH} to \textit{Hangup}.
\item A Hangup \texttt{ATH} will reset the Ring Counter in \texttt{S1} to zero (0).
\end{itemize}