WA8DED HOST MODE USER'S GUIDE
=============================
Original by Paul T. Williamson, KB5MU, 23 May 1986
Updated by Peter Guelzow, DB2OS, 8 Aug 1993
Abstract: This document explains the use of the WA8DED Host mode with
WA8DED's AX25 Version 2 Multi-channel TNC Firmware, Version 1.1 for the TAPR
TNC-1 and the TheFirmware TF Version 2.x for the TNC-2 by NORD>JHOST1 to the TNC. But what if
something has already been sent to the TNC (say by powerup transients)? The
will be treated as data (echoed as ^[ by the TNC) and the command will be
lost. We can work around this by sending a ^U or ^X first, to clear the junk
out. It might also be a good idea to send an XON, in case the junk included an
XOFF. So we send ^Q^X^[JHOST1^M (or, if you prefer the ASCII mnemonics,
JHOST1):
11 18 1B 4A 48 4F 53 54 31 0D
^Q ^X ^[ J H O S T 1 CR
This will work every time, if the TNC is in user mode. If the TNC is in Host
mode already, we should detect that fact and recover. Host mode recovery will
be discussed later in this document.
Exiting Host mode is a simple matter of sending a JHOST0 command to the TNC.
The TNC will acknowledge the JHOST0 command in the usual Host-mode fashion
before returning to user mode, so you can use your regular Host-mode
transaction routine.
Note that a QRES command issued in Host mode will dump you back into user
mode. It does not acknowledge in Host-mode fashion before doing so. The Host
mode parameter is not stored in NOVRAM, so it is not possible to "wake up" in
Host mode. It is, however, possible to PERM other parameters from Host mode.
Chapter 3
Commanding the TNC
OK, now that we're in Host mode, let's look at a simple command exchange. We
will gloss over some of the details for this first look. Suppose we want to
turn off Unattended mode. In normal user mode, we would type U0.
That is, we would send a U0 command to the TNC. To send a U0 command in Host
mode, we have to assemble a transmission for the TNC according to the
computer-to-TNC format.
Recall that the computer-to-TNC format is:
{channel}{info/cmd}{count}{data...}
The first byte, channel, is the channel number. In user mode, it doesn't
matter what channel you are on when you give a U command. Likewise, in Host
mode, it doesn't matter which channel you send this command to. Let's choose
channel 0. The second byte is info/cmd; this is a command, so this byte has to
be 1. The command data we are going to send is simply "U0", the same ASCII
string we would have used between and to do the same thing in user
mode. This is two bytes long, so the count byte should indicate two bytes.
Count is encoded as (length - 1), so the third byte of the message should be
2 - 1 = 1.
The following is an illustration of the required transmission. The top line
lists the bytes to be sent in hex notation. The first byte sent is on the
left. Below each byte of the top line is an explanation of that byte. This
format will be used throughout this document to illustrate Host mode
transmissions.
00 01 01 55 30
! ! ! U 0
! ! !
! ! +-- Count = 1 (two bytes)
! +----- Info/cmd = 1 (this is a command)
+-------- Channel = 0
Note that no carriage return is required or allowed. As soon as the byte
count is fulfilled (i.e., when the last byte has been received) the TNC accepts
the transmission as complete.
How do we know the TNC got the command OK? Simple: it responds with a status
message. A U0 command can't fail, so we can guess that the status message will
be a success message. A U0 command doesn't return any information, either, so
no data field will be present. So, we can guess that the TNC will respond with
a transmission in the short format:
00 00
! !
! +--- Code = 0 (Success, no data follows)
+------ Channel 0
Now we can see the general shape of any computer-TNC transaction: the
computer sends a command to the TNC, and the TNC responds with an appropriate
message. In writing a program to interface with Host mode, we will have to
take care of building these outgoing frames and interpreting the incoming
frames. If we take a hint from WA8DED and W6IXU, we will implement a single
routine that does the dirty work of sending a transmission and receiving the
response.
In receiving the response, the routine will have to decide how many
characters to read from the serial port by looking at the code in the second
byte of the TNC's message. This code tells it in which format the transmission
will be: short format with no following data, null-terminated format with some
data ending in a null, or byte-count format with a count and the specified
number of bytes of information.
Notice that the routine that receives the response doesn't have to have any
knowledge of the current state of the TNC or the application program. The
meaning and encoding of the TNC's response is completely determined by the data
in that response. This simplifies the routine that receives the response by
isolating it from the complexities of the application program.
Chapter 4
Polling the TNC: the G command
The most essential, basic transaction in Host mode is the G command, which
polls a specific channel of the TNC for events and data. A typical Host-mode
application program will constantly send G commands to the TNC and interpret
the responses. Since the G command is a query to a specific channel of the
TNC, it is necessary to send G commands to all of the channels that may be in
use. Data received from a station connected on channel 1 (or 2, or 3, or 4)
will be sent to the computer as a response to a G command directed to channel 1
(or 2, or 3, or 4). Monitored data will be sent to the computer as a G command
directed to channel 0.
The G command has three forms. A command of "G" will return any of the
possible responses that is available. A command of "G0" will return only
information. A command of "G1" will return only link status responses. This
is useful when you are waiting for a link status change and do not wish to
handle data, or vice versa.
The only other thing that changes in a G command is the channel number. Be
sure to send G commands to all channels that may be active. You need not send
G commands to channel 4 if Y is 3, for instance, but you must send G commands
to channels 0 through 3. The unrestricted G command has the following format:
0x 01 00 47
! ! ! G
! ! !
! ! +--- Count = 0 (one byte of data)
! +------ Info/cmd = 1 (this is a command)
+--------- Channel = x (where x is 0, 1, 2, 3, or 4)
There are only a few possible responses to a G command. If the program polls
the TNC constantly with G commands, most of the replies will be "nothing
available". This simply means nothing new has happened on the link since the
last poll. This response applies to any of the three forms of the G command.
Each of the other possible responses indicates an event on the AX.25 channel: a
change in Link Status (such as "DISCONNECTED"), which is evoked by G or G1, or
receipt of a frame of monitored or connected data, which is evoked by G or G0.
The detailed formats of these responses will be discussed later in this
document.
Monitored information is handled specially by the G command. Monitored data
is handled on channel 0 of the TNC. The monitor header is transmitted
separately from the monitor information. The monitor header transmission
indicates whether or not there is an associated information transmission to
come. If there is, it will be the next response on channel 0. This scheme has
two results: it spares the programmer the task of parsing out monitor
information from the monitor header (if such is desired), and it keeps the
maximum transmission length down to the maximum data field size, rather than
the data field size plus the monitor header size (and thus allows the count to
be a single byte).
This scheme for monitored data might be considered a violation of the rule
that each computer-TNC transmission is self-contained and self-explanatory.
The monitored information transmission is qualified by the immediately
preceding monitor header transmission. You many want to treat a monitor header
with information as a special case in the application program, and grab the
corresponding monitor information transmission immediately.
Chapter 5
Details of Computer-to-TNC Format
As we said before, the computer-to-TNC transmissions must always follow this
format:
{channel}{info/cmd}{count}{data...}
The three header bytes (channel, info/cmd, and count) are expressed in
binary. For instance, to specify 0 for any of these values, send a NULL (^^U,
'^Y0' for C fans, CHR$(0) for BASIC fans). DON'T send the ASCII character '0'.
The data field will contain one of the following:
1. Data to be transmitted via the AX.25 link.
2. A command string just like you might issue from the normal user mode
(the part strictly between the and the ).
3. "G", the Host-mode poll command.
If data for the AX.25 link is to be sent, the info/cmd byte must be zero
(binary zero, remember, not ASCII "0"). The data field may contain any bytes
whatsoever, but not more than 256 of them. Count up the data bytes and
subtract one to find the value of the count byte. So if you're connected to me
on channel 2, and you want to say
Hello
to me, send the TNC this transmission:
02 00 05 48 65 6C 6C 6F 0D
! ! ! H e l l o CR
! ! ! !
! ! ! +---- (this is a data byte)
! ! +- Count = 5 (six bytes of data)
! +---- Info/cmd = 0 (this is information to be sent)
+------- Channel = 2 (since I'm on your channel 2)
Note that the CR is sent as data, and will be transmitted through the AX.25
link. It is not part of the transmission format.
If the information is sent to channel 0, it will go out unproto to the
address on channel 0 (default CQ). If information is sent on channel 1 - 4
while that channel is not connected, it is ignored.
If a command string is to be sent, the info/cmd byte must be one. The data
field should contain the ASCII command string. It does not contain or
, just the characters that would go between them to form a normal user-mode
command. For instance, to set TXDELAY to 30, send the TNC this transmission:
00 01 02 54 33 30
! ! ! T 3 0
! ! !
! ! +- Count = 2 (three bytes of data)
! +---- Info/cmd = 1 (this is a command)
+------- Channel = 0 (doesn't matter here)
The channel number is significant for the C, D, F, G, L, N, O, and V
commands. C, D, F, N, O, and V commands are channel specific in exactly the
same way as they are in user mode. The L command is different in Host mode,
and will be discussed later in this document. The G command has already been
discussed. The channel number is not significant for other commands. You may
use whatever channel number is convenient. (WA8DED and W6IXU send these
commands to channel 0).
The byte-count format for the computer-to-TNC transmissions is used because
it provides "data transparency". This means that any bytes whatsoever may
appear in the data field. The TNC can just accept the next so many bytes from
the computer without thinking about it. If a special character were used to
signal the end of the data, that character could not occur in the data. The
null-terminated format can use this scheme, since the data in these is
guaranteed not to contain a null.
Unfortunately, the byte-count scheme is not very robust. If a character is
lost or a spurious character is inserted, the computer and TNC could stay out
of synch forever. We must take pains to detect loss of synch and to recover
from the fault. Fortunately, the first byte of a transmission has only five
valid values (0-4) and the second byte has only two valid values (0 and 1), so
it is possible to detect a loss of synchronization in most cases. Timeouts can
also be used to detect synch failures. Once the error is detected, recovery is
possible. Host mode recovery will be discussed later in this document.
Chapter 6
Details of TNC-to-Computer Format
The TNC-to-computer transmission format is a bit more complicated than the
computer-to-TNC format. The key to decoding a transmission from the TNC is the
code byte that follows the channel number byte. The following table gives the
code values:
TNC-TO-COMPUTER CODES
Code Meaning Format
==== ======= ======
0 Success, nothing follows short format
(Nothing available)
1 Success, message follows null-terminated format
2 Failure, message follows null-terminated format
3 Link status null-terminated format
4 Monitor header/no info null-terminated format
5 Monitor header/info null-terminated format
6 Monitor information byte-count format
7 Connected information byte-count format
These various formats are used for different purposes. Codes 0, 1, and 2 are
responses to an information or command transmission from the computer. If a
batch of information was queued for transmission successfully or if a command
completes successfully without returning any information, a code 0 transmission
will be the reply:
02 00
! !
! +---- Code = 1 (Success, nothing follows)
+------- Channel = 2 (same as the info or command sent)
If the command is successful and returns information (like any command without
an argument), a code 1 transmission will be the reply. The returned data will
follow the code, "null terminated". This just means that a 0 byte will appear
after the last information byte. For example, consider an M command without an
argument. In user mode, the user would type M, and the TNC would
display something like
* IUSCRT *
In Host mode, the command would be
00 01 00 4D
! ! ! M
! ! !
! ! +---- Count = 0 (one data byte)
! +------- Info/cmd = 1 (this is a command)
+---------- Channel = 0 (Doesn't matter here)
and the response might be
00 01 49 55 53 43 52 54 00
! ! I U S C R T !
! ! +---- Null termination
! !
! +---- Code = 1 (Success with info)
+------- Channel = 0 (same as in the query)
If the command failed, or the information cannot be queued for transmission, a
code 2 transmission with one of these error messages will be the reply:
FAILURE MESSAGES
INVALID COMMAND
TNC BUSY - LINE IGNORED
CHANNEL ALREADY CONNECTED
STATION ALREADY CONNECTED
For example if you send a data line:
03 00 0C 48 65 6C 6C 6F 20 74 68 65 72 65 2E 0D
! ! ! H e l l o t h e r e . CR
! ! ! !
! ! ! (this is a data byte) ----+
! ! +---- Count = 12 (thirteen data bytes)
! +------- Info/cmd = 0 (this is information)
+---------- Channel = 3 (for instance)
when the TNC has no RAM available to buffer the data line, it will respond with
a code 2 failure message to inform you of the condition:
03 02 544C432042555359202D204C494C452049474C4F524544 00
! ! T N C B U S Y - L I N E I G N O R E D !
! ! !
! +---- Code = 2 (Failure) Null terminator ----+
+------ Channel = 3 (same as the info sent)
If you send a bad command:
00 01 03 4A 55 4C 4B
! ! ! J U N K
! ! !
! ! +---- Count = 3 (four data bytes)
! +------- Info/cmd = 1 (this is a command)
+---------- Channel = 0 (Doesn't matter here.)
It will complain about it with a code 2 failure message:
00 02 49 4E 56 41 4C 49 44 20 43 4F 4D 4D 41 4E 44 00
! ! I N V A L I D C O M M A N D !
! ! !
! +---- Code = 2 (Failure) Null termination --+
+------- Channel = 0 (same as the command sent)
The remaining codes, 3 through 7, are used only as responses to a "G" poll
command. A 0 code can also be a response to a G poll. A 0 code means that
nothing is available for that channel: that is, no events worthy of notice have
taken place on the channel polled. This is the most common response to a G
command.
0x 00
! !
! +---- Code = 0 (Nothing available)
+------- Channel = x (same as the G command)
A code of 3 signifies a Link Status message. These messages are:
LINK STATUS MESSAGES
({n}) BUSY fm {call} via {digipeaters}
({n}) CONNECTED to {call} via {digipeaters}
({n}) LINK RESET fm {call} via {digipeaters}
({n}) LINK RESET to {call} via {digipeaters}
({n}) DISCONNECTED fm {call} via {digipeaters}
({n}) LINK FAILURE with {call} via {digipeaters}
CONNECT REQUEST fm {call} via {digipeaters}
({n}) FRAME REJECT (x y z) fm {call} via {digipeaters}
({n}) FRAME REJECT (x y z) to {call} via {digipeaters}
These messages should look familiar, since they are identical to the messages
displayed by the TNC in user mode. {n} is the channel number. Notice that the
channel number in the message is redundant information. The channel number may
be omitted from this message in a future release.
For instance, if I connect to you direct on channel 2, a poll of channel 2
(not necessarily the next one, depending on what else is going on) will return
the event:
02 03 28322920434F4E4E454354454420746F204B42354D55 00
! ! ( 2 ) C O N N E C T E D t o K B 5 M U !
! ! !
! +---- Code = 3 (Link Status) Null termination --+
+------- Channel = 2
Codes of 4 and 5 both signify a monitor header. This is a null-terminated
format message containing the
fm {call} to {call} via {digipeaters} ctl {name} pid {hex}
string that forms a monitor header. The monitor header is also identical to
the monitor header displayed in user mode. If the code was 4, the monitored
frame contained no information field, so the monitor header is all you get. If
you monitor KB6C responding to a connect request from me and then poll channel
0, you'll get:
0004666D204B42364320746F204B42354D552063746C2055612070494420463000
! ! f m K B 6 C t o K B 5 M U c t l U A p i d F 0 !
! ! !
! +---- Code = 4 (Monitor, no info) Null termination ----+
+------- Channel = 0 (Monitor info is always on channel 0)
If the code was 5, the monitored frame did contain an information field. In
this case, another G command to channel 0 will return the monitored information
with a code of 6. Since data transmissions must be transparent, the monitored
information is passed as a byte-count format transmission. That is, it is
preceded by a count byte (one less than the number of bytes in the field). No
null terminator is used in this case. Since codes 4, 5, and 6 pertain to
monitored information, they will be seen only on channel 0. If you hear KB6C
say "Hi" to NK6K, and then poll channel 0, you'll get:
0005666D204B42364320746F204E4B364B2063746C204930302070494420463000
! ! f m K B 6 C t o N K 6 K c t l I 0 0 p i d F 0 !
! ! ! ! !
! ! or whatever ----+-+ !
! ! !
! +---- Code = 5 (Monitor, info follows) Null termination ----+
+------ Channel = 0 (Monitor info is always on channel 0)
and then the very next poll to channel 0 will get:
00 06 02 48 69 0D
! ! ! H i CR
! ! ! !
! ! ! +---- (this is a data byte)
! ! +---- Count = 2 (three bytes of data)
! +------- Code = 6 (monitored information)
+---------- Channel = 0 (Monitor info is always on channel 0)
A code of 7 signifies connected information, so it will only be seen on a
connected channel 1 through 4. It is a byte-count format transmission, for
data transparency. If you're connected to me on channel 4 and I say "Hi", a
poll of channel 4 will return:
04 07 02 48 69 0D
! ! ! H i CR
! ! ! !
! ! ! +---- (this is a data byte)
! ! +---- Count = 2 (three bytes of data)
! +------- Code = 7 (connected information)
+---------- Channel = 4 (info was received on channel 4)
Chapter 7
Querying Channel Status: the L command
One of the most powerful features of the Host mode is the ability to ask the
TNC for a status report on a given channel. This report is similar to the
report given by the L command in user mode, but more extensive. To obtain the
Channel Status report, send an L command to the channel of interest. The TNC
will (barring error) respond with a code 1 packet. The information field of
this packet will contain six decimal number in ASCII delimited by spaces.
A typical Channel Status query:
01 01 00 4C
! ! ! L
! ! !
! ! +---- Count = 0 (one data byte)
! +------- Info/cmd = 1 (this is a command)
+---------- Channel = 1 (give me a report on channel 1)
A typical Channel Status report:
01 01 30 20 30 20 30 20 30 20 30 20 30 00
! ! 0 0 0 0 0 0 !
! ! !
! ! null termination ----+
! +------- Code = 1 (Success with info)
+---------- Channel = 1 (this is a report on channel 1)
Channel 0 does not have as much state information as a regular connectable
channel, so a Channel Status query to channel 0:
00 01 00 4C
! ! ! L
! ! !
! ! +---- Count = 0 (one data byte)
! +------- Info/cmd = 1 (this is a command)
+---------- Channel = 0 (give me a report on channel 0)
Will return a Channel Status report similar to this one.
00 01 30 20 33 00
! ! 0 3 !
! ! !
! ! +---- null termination
! +------- Code = 1 (Success with info)
+---------- Channel = 0 (this is a report on channel 0)
The interpretation of the returned information is as follows:
CHANNEL STATUS FORMAT
a b c d e f
a = Number of link status messages not yet displayed
b = Number of receive frames not yet displayed
c = Number of send frames not yet transmitted
d = Number of transmitted frames not yet acknowledged
e = Number of tries on current operation
f = Link state
Possible link states are:
0 = Disconnected
1 = Link Setup
2 = Frame Reject
3 = Disconnect Request
4 = Information Transfer
5 = Reject Frame Sent
6 = Waiting Acknowledgement
7 = Device Busy
8 = Remote Device Busy
9 = Both Devices Busy
10 = Waiting Acknowledgement and Device Busy
11 = Waiting Acknowledgement and Remote Busy
12 = Waiting Acknowledgement and Both Devices Busy
13 = Reject Frame Sent and Device Busy
14 = Reject Frame Sent and Remote Busy
15 = Reject Frame Sent and Both Devices Busy
NOTE 1: Only items a and b are displayed for channel 0.
NOTE 2: Only states 0 - 4 are possible if version 1 is in use.
How you will use the Channel Status report will depend on your application.
An interactive terminal program might simply display some or all of the
information and leave it at that. A mailbox program might want to wait for all
packets to be acknowledged before starting a timeout timer or before
disconnecting. A mail forwarder would want to make sure all data was
acknowledged before considering its task done. Any program might want to give
up if throughput is too low. These functions are easy to implement with Host
mode.
Chapter 8
Host Mode Error Recovery
What happens if something goes wrong on the computer-TNC link? Maybe there
is a loose wire, or maybe RF got into the RS-232 lines. Maybe it's just
Murphy. For whatever reason, the data on the line got corrupted. RS-232 links
are very reliable, so you may never see an error, but the application program
should be ready to cope with one.
The error recovery program must assume that the TNC is in a completely
unknown state. It might be expecting more bytes to fill a byte count (if bytes
coming from the computer were lost). It might be simply waiting for a
transmission, but the computer thought there was an error since data was lost
or corrupted on its way from the TNC. What we want to do is hit the TNC with a
stream of data that will eventually bring it into a known state. Preferably,
this process should generate little or no spurious data on the AX.25 link.
The first thing to do is dump any further data that may be coming from the
TNC. We don't know what it is, and so we can't use it. The possibility exists
that this is connected information we're dropping on the floor. This is just
too bad. There is nothing we can do.
Next, we just send ^A's one at a time until the TNC responds. The first few
^A's may go to fulfill a byte count that the TNC is waiting for. If this
happens to be a connected information transmission, these ^A's will go out on
the AX.25 link. Tough. When any outstanding byte count is fulfilled (no more
than 256 should be required), the following five ^A's will be seen as a command
on channel 1. This is why ^A is chosen: to make the TNC interpret the extra
transmission as a command.
01 01 01 01 01
! ! ! ^A ^A
! ! !
! ! +-- Count of two bytes.
! +----- This is a command.
+-------- Channel #1.
A command of "^A^A" doesn't mean anything, so the TNC should respond with a
failure message:
01 02 49 4E 56 41 4C 49 44 20 43 4F 4D 4D 41 4E 44 00
! ! I N V A L I D C O M M A N D !
! ! !
! +---- Failure message. Null termination --+
+------- Same channel as the command specified
We don't really care what the response is, though. It may not be exactly what
we expect. For instance, the first ^A might fulfill the byte count of a
garbled command. This would usually generate an error message of some other
type. All we need is to get the first response. Then we know that the TNC is
waiting for a command.
This implies that we have to wait between ^A's long enough to see if there is
a response yet. This can make the recovery process a slow one. For instance,
if the TNC spuriously receives 00 00 FF, it expects to see 256 data bytes
following, so we will have to send 256 ^A's before we get a response (which
will probably be a success message, since this is just a data transmission to
the TNC). Fortunately, this error recovery process is not required very often.
-EOF-