239 lines
11 KiB
TeX
239 lines
11 KiB
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}
|