vt132-quickref/modem.tex

\chapter{The Modem}

\section{Background}

The VT132 modem part is designed to provide a modified Hayes \texttt{AT} compatible command set for connecting over WiFi via TCP/IP
sockets with an optional Telnet protocol layer.

\begin{itemize}[leftmargin=1em]
	\item The original \texttt{AT} command set was strictly in upper case. This is because the bit sequence of the ASCII values for \texttt{A} and \texttt{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 \texttt{AT} commands in upper case.}
	\item Commands are terminated by \LKeyEnter \footnote{carriage return, \LKeyCtrlX{M}, \texttt{0x0D}, decimal 13} usually generated by the \LKeyEnter{}
		(\biolinum{Enter} or \biolinum{Return}) key on your keyboard.
	\item Commands can by edited, before pressing \LKeyEnter, using \LKeyBack \footnote{backspace, \LKeyCtrlX{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 \LKeyBack{} (backspace) key on your keyboard.
	\item The \texttt{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}

\section{Communication}

\subsection{Baudrate}

To set the baudrate of the modem, press the \textbf{Prog} button on the VT132 module. After each press of this button, the modem outputs its new
baud rate to the serial port -- so you can press this button repeatedly until you can read your baud rate.

\subsection{Serial Port}

To communicate with the VT132 modem, you can use either the pins of the RC2014 extended bus (Rx2, Tx2) or the 6 pin header labelled \textit{Modem Port B}.

See section \vref{jumperheaders} \textit{(Jumper settings and headers)} for details.

\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}
\label{modemota}

\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
\section{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{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{Enabling Telnet Protocol}

Telnet protocol is \textbf{not} enabled by default. To enable it, set the S Register S15 to 1 manually:

\begin{itemize}[leftmargin=1em]
	\item Enable Telnet using: \texttt{ATS15=1}
	\item Disable Telnet using: \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.

\subsection{Telnet options}

The VT132 supports the following Telnet options:

\begin{itemize}[leftmargin=1em]
	\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 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}.

\newpage
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.

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

\newpage
\section{Answer Mode}

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

\begin{itemize}[leftmargin=1em]
	\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}