Documentation Index
Alphabetic Index
XRPi Documentation - Interfaces
WA8DED Emulation Interface
Introduction
XRPi can emulate a WA8DED TNC, in both normal mode and "host" mode. This can be used for both manual operations and application support, just like a real TNC. Many applications are capable of using WA8DED host mode.
.------. .-------------.
| XRPi |------RS232-------| Application |
'------' '-------------'
(e.g. BBS or Hyperterm)
The application may be located on the same machine as XRPi, connected to it either via a pair of "virtual" COM ports, or via a pair of "real" COM ports interconnected with a null-modem cable. Alternatively, the application may be located on a separate machine, using an RS232 null-modem cable to interconnect the machines.
In "normal" TNC mode, the "user" (usually a sysop) interacts with XRPi via the application, which is usually a dumb terminal such as HyperTerm.
.------. .-----------.
| XRPi |------RS232-------| HyperTerm |<--User
'------' '-----------'
But in "host" mode, the user interacts with the APPLICATION, which is usually a BBS, via XRPi:
.------. .-----.
User -->| XRPi |------RS232-------| BBS |
'------' '-----'
Configuring XRPi To Support Applications Using WA8DED Hostmode
- Decide how to interconnect the application and XRPi. You can use either a pair of real COM ports and a null-modem cable, or a virtual com port driver such as Com0Com.
- If using the latter, install it on the PC (if it isn't already installed) and note the numbers of the two COM ports it provides. You may need to adjust one or both of them to a convenient number for your application. Ensure that "Baud Rate Emulation" and "Enable Buffer Overrun" are checked on both sides.
- In XROUTER.CFG specify an interface similar to this...
INTERFACE=x TYPE=ASYNC COM=/dev/ttyUSB18 PROTOCOL=DEDHOST APPLNUM=3 CHANNELS=4 SPEED=9600 FLOW=0 MTU=256 ENDINTERFACE
"x" represents the interface number.
COM is the number of one of the real or virtual COM ports used to connect with the application. XRPi can use COM numbers up to COM32.
CHANNELS specifies the max no. of host channels the interface will provide (between 1 and 32). The total number of host channels available to be shared between all applications is 64. If XRPi cannot allocate the requested number of channels it will fail to start. (In versions up to 200e the number of channels was specified by INTNUM. This is now deprecated.)
MTU must be 256
APPLNUM (1-16???) specifies which application will be using this interface. Corresponds to "n" in APPL=n (see below).
SPEED is the serial baud rate . Don't use too low a speed, otherwise badly-written applications may lose sync due to the time it takes for a poll to reach XRPi and the reply to reach the application. Speeds of 9600 and above should be OK.
FLOW must always be set to 0 or 4. Setting FLOW to any value other than 0 or 4 may cause the application or XRPi to hang. FLOW=4 is a special case which forces the WA8DED emulator to default to host mode (see later).
Don't use CHANNEL, IOADDR, or INTNUM keywords.
Don't try to attach any PORTs to this interface, as they are not required.
- In XROUTER.CFG add an APPL=n block, to specify the application's callsign, alias, Netrom quality and visibility. The "n" parameter must match the APPLNUM specified in the INTERFACE block.
For example:
APPL=3 APPLNAME=BBS APPLCALL=GB7PZT APPLALIAS=PZTBBS APPLQUAL=100 APPLFLAGS=4 ENDAPPL
The application definition (APPL) block should contain one or more of the following keywords:
APPLNAME is the nickname or shortcut by which the application is accessed from the XRPi's command line. In the example above, if a user types "BBS" at the command prompt, they will be connected to the application.
APPLCALL is the AX25 layer 2 callsign which the application will use. If specified, the application will accept AX25 L2 connects to this callsign, subject to the setting of APPLMASK (see below).
APPLALIAS is the AX25 layer 2 "alias" for use by the application. If specified, the application will accept AX25 L2 connects to this callsign, subject to the setting of APPLMASK (see below).
APPLQUAL (0-255) is the Net/Rom quality to broadcast. If a non-zero value is specified here, the APPLCALL will be included in Net/Rom nodes broadcasts and the application will be connectible at AX25 layer 4. The higher the quality, the further the node entry will propogate.
APPLFLAGS defaults to 0 if omitted. A value of 4 instructs XRPi to send "Connected to (applcall)" to the user upon connection to an application. This may be omitted if the application sends its own "Connected to" message.
All fields within an application definition block are optional - you may have for instance choose to have an APPLNAME but no APPLCALL, meaning the application could only be reached by typing the applname at the command prompt. Or you could have an APPLCALL but no APPLNAME, in which case the application would be directly connectible, but wouldn't be reachable from a command line shortcut.
- In XROUTER.CFG set the APPLMASK on each PORT that you wish the application to appear on. The application will only monitor traffic and send UNPROTOs on the ports which have the application enabled via the APPLMASK.
The APPLMASK parameter specifies which applications will be directly connectible on a port. The default is 255, which allows all applications. The value is made up by adding together the following numbers:
1 - Enable Application 1 2 - Enable Application 2 4 - Enable Application 3 8 - Enable Application 4 16 - Enable Application 5 32 - Enable Application 6 64 - Enable Application 7 128 - Enable Application 8 Example: APPLMASK=5 (enable applications 1 and 3)
If you want an application to be directly connectible on a port, it must have either an APPLCALL or an APPLALIAS (or both), and the corresponding bit in that port's applmask must be set.
- Finally, configure the application to use WA8DED hostmode on the other of the chosen COM port pair, with the same baud rate as specified in the INTERFACE block.
Default Mode
The default mode (host mode / terminal mode) is controlled by the FLOW parameter in the INTERFACE definition block. With FLOW=0, XRPi's WA8DED emulation starts in non-host ("terminal") mode because most applications expect it that way, therefore it allows them to sync up quickly.
However, some applications may expect the TNC to be in host mode, and may fail to sync if FLOW=0. In this case, setting FLOW=4 forces the WA8DED "TNC" to start in host mode.
This control is not a panacea. For example, If XRPi is stopped and restarted while an application is running in hostmode, everything should quickly sync up again if FLOW=4. But this setting may prevent the application from syncing up from cold.
Starting / Stopping Applications
Where possible, XRPi should be started before the application, and stopped after it, because some applications malfunction if they don't see the expected responses when they start up and shut down.
If an application doesn't close down "cleanly", it may take a while to resync when it restarts. This is normal.
Hidden Applications
If you have an application that only makes outgoing connections, you can omit the APPL block altogether. The application will still work, but it won't accept incoming connects.
Known Issues
- FBB 16-bit versions 700g and 700i use 100% CPU when configured for WA8DED hostmode. The BBS seems to work OK despite this. Although this is not an XRPi issue, we are looking at ways to fix the problem.
- WinFBB v701-35 often reports "Error initialising WA8DED Driver" and fails to communicate with XRPi after that. It usually boots cleanly if stopped and restarted. The best setting for FLOW is 0.
- With WinFBB v701-35, the sysop is able to open a gateway connection to XRPi's command processor and make outgoing connections. However, whilst incoming connections are accepted, WinFBB only sends the SID [FBB-701-ABFHMR$] and nothing else. It doesn't respond to any command.
- If XRPi is stopped and restarted within a short time, WinFBB v701-35 will resync cleanly. However, if too long an interval elapses before XRPi restarts, WinFBB goes into meltdown and will never resync.
- Although WinFBB 701-35 appears to run in DED mode, it doesn't run properly, and is therefore unusable as a BBS in this mode.
- If Com0Com is used without the "enable buffer overrun" option checked, closing the application may sometimes cause XRPi to hang until the application is restarted.
Breaking out of host mode
If the emulator is inadvertently switched into, or left in, host mode it can be easily be returned to terminal mode using Hyperterm as follows:
- Send ctrl-a's slowly (1 or 2 per sec) until "INVALID COMMAND" appears (it may take up to 256 ctrl-a's to make this happen, but usually it will take a lot less). Stop sending ctrl-a's as soon as the response appears. If you inadvertently send one or two too many, *slowly* send up to 4 more ctrl-a's and the message should appear again.
- Send
JHOST0 (there will be no response)
- Send <esc> and it should display the "* " to indicate that it is in command mode.
TROUBLESHOOTING
- XRPi reports "All Host Ports in use" upon first attempt to connect to DEDHOST application:
- The APPLNUM in the INTERFACE definition block does not match the application number specified in the APPL definition block.
- Application frequently loses sync:
- Serial port baud rate too low?
If the baud rate is too low, the data may take too long to propogate back and forth between XRPi and the application, causing the application to think it has lost sync. Good applications would adjust their polling rate according to the baud rate. Unfortunately some don't!
- Serial port baud rate too high?
If the baud rate is too high the serial line may drop characters, causing loss of sync. Another, more likely, issue is that with high baud rates the "timeout" between the application sending a poll and expecting a reply may be too short for a multitasking operating system, even though it is OK for a firmware TNC.
- FLOW not set to 0 or 4
- The PC is too busy.
Unlike a real TNC, XRPi does not have sole use of the processor. Other processes may "steal" processor time, causing a delay in responding to the application's polls. In most cases this shouldn't happen, but some applications poll too fast. The only solution is to avoid running processor-hungry applications on the same PC.
- Excessive tracing on XRPi's console.
Writing characters to the console is very CPU-intensive, so having MON ON can cause delays in the poll-response cycle if the amount of trace traffic is heavy. Turning MON OFF or tracing fewer ports at once should alleviate the problem.
- Serial port baud rate too low?
- XRPi hangs when application is stopped:
- XRPi's RS232 output buffer is full and something is preventing it from emptying.
- If using Com0Com virtual com port emulator, check the "Enable buffer overrun" boxes
- Use FLOW=0.
- XRPi's RS232 output buffer is full and something is preventing it from emptying.
- Application won't sync if XRPi is stopped and restarted
- XRPi's DEDHOST emulation starts in non-host mode because most applications expect it that way. This allows them to sync up quickly when they are started AFTER xr32. However, if XRPi is restarted while the application is running, the application won't know that XRPi is back in non-host mode, and will fail to sync.
- Can't connect to application on port N / Can't monitor port N
- The port's APPLMASK is not set correctly (see above for description of APPLMASK)
- There is a bug in early versions - Although up to 16 applications are allowed, if APPLNUM is more than 8, the application cannot be connected to.
- The port's APPLMASK is not set correctly (see above for description of APPLMASK)
- Application is monitoring port N uncesessarily.
The default APPLMASK setting for each port allows access to, and monitoring by, all applications. If you wish to suppress connections and monitoring on a particular port, you must set APPLMASK accordingly. To suppress all applications, set the port's APPLMASK to 0.
Miscellany
Random factoids...
- Uplinks and downlinks to DEDHOST applications show as link type "DED" on XRPi's "Users" display.
Using WA8DED TNC Emulation in Terminal Mode
XRPi's WA8DED emulator starts up in "terminal" mode (i.e. not host mode) and may be therefore tested or used in this mode using Hyperterm or any other dumb terminal. Wherever possible, the emulator behaves the same as a "real" WA8DED TNC, as detailed below:
In normal mode, commands and information are sent from the terminal to the emulator in the form of lines. Lines may be up to 256 characters long, including the terminating CARRIAGE RETURN. If the 256th character entered is not a CARRIAGE RETURN, it will be discarded and a BELL character will be output to the terminal. BACKSPACE and DELETE may be used to remove single characters from the line. The entire line may be permanently backspaced out by entering a CONTROL-U or CONTROL-X.
Lines which begin with an ESCAPE character (echoed as '* ') are interpreted as commands. Lines without a leading ESCAPE character are sent as information.
Most commands consist of a single letter. Some commands have an optional parameter. The number of spaces (if any) between the command and any parameter is not important. If a command is issued with no parameter, the current value of that command's parameter is displayed. Unless a parameter is returned, commands do not normally return any acknowledgement.
By default, XRPi's WA8DED emulator provides the operator with five virtual TNC channels, numbered 0 to 4 (The actual number may be altered between 1 and 32using the CHANNELS= keyword in the supporting INTERFACE). The terminal is logically attached to only one of these channels at a time, selected by the 'S' command.
Channel 0 is reserved for unproto transmissions and monitoring. This channel does not support connections. Information sent on channel 0 is always unproto. The unproto path may be set by issuing a 'C' command when channel 0 is selected.
Channels other than 0 support connections, but are unproto if they are not currently connected. Outgoing connect requests may be issued on any unconnected channel (other than channel 0), while incoming connect requests will use the first available channel (provided the maximum number of connections set by the 'Y' command will not be exceeded).
Information received on a connected channel that is not currently selected will remain queued there until that channel is selected. The 'L' command may be used to determine the channel(s) where stored information is located. Information for transmission is sent only to the currently selected channel. When a connection is ended, received information will remain queued until it has been displayed.
Frame monitoring is controlled by the 'M' command. The command parameter determines the types of frames monitored, and is a list of desired frames chosen from the letters in the following table:
LTR FRAME
--- -----
N None
I I frames
U UI frames
S Supervisory frames
C Monitor while connected
+ Call signs to be included (maximum of 8)
- Call signs to be excluded (maximum of 8)
The '+' and '-' parameters may not be used together. If either is used, it must be the last parameter (followed by one to eight callsigns, if applicable). If no list of callsigns is specified to be included or excluded, all callsigns will be candidates for monitoring. Entering a '+' or '-' with no callsigns will empty the list.
An asterisk displayed after a callsign in the digipeater list indicates the frame was transmitted by that station. The control field displayed will be one of the following:
NAME DESCRIPTION
---- -----------
RRa - Receive Ready
RNRa - Receive Not Ready
REJa - Reject
UI - Unnumbered Information
DM - Disconnected Mode
SABM - Connect Request
DISC - Disconnect Request
UA - Unnumbered Acknowledge
FRMR - Frame Reject
Iab - Information
?ccH - Unknown
a = Next expected frame number (0 - 7)
b = Frame number of this frame (0 - 7)
cc = Hexadecimal value
In addition, one of the following characters will be displayed, reflecting the protocol version, command/response bits, and the poll/final bit:
(blank) = version 1 frame without poll/final bit
! = version 1 frame with poll/final bit
^ = version 2 command frame without poll bit
+ = version 2 command frame with poll bit
- = version 2 response frame with final bit
v = version 2 response frame without final bit
The protocol identifier field is displayed in hexadecimal
An unattended mode, controlled by the 'U' command, provides for sending user supplied text to a connecting station, and then allows that station to leave a brief message. This mode can operate on all channels simultaneously, but in no way limits the operator's ability to interact with one of the connected channels or the ability to make outgoing connect requests.
When unattended mode is enabled, link status messages are queued to the associated channel and not output to the terminal unless that channel is currently selected. Link status messages will therefore be displayed in chronological order with the information from that channel.
In addition, text supplied by the user with the 'U' command will be sent to any station that connects. If channel 0 is left selected, stations may then connect and leave messages on channels 1 - 4
(limited by the 'Y' parameter, of course). The 'L' command may be used to determine if messages have been left on any channel. Selecting a channel containing messages will cause all link status and information from that channel to be displayed. If xon/xoff handshaking is enabled, CONTROL-S and CONTROL-Q may be used to regulate the output to the terminal to allow comfortable reading.
COMMAND SUMMARY
(In terminal mode all commands are preceded by ESCAPE character)
COMMAND PARAMETER DESCRIPTION
------- --------- -----------
A (1) 0 Auto linefeed disabled
1 Auto linefeed enabled
* C Cs1 [Cs2 ... Cs9] Connect path (0=unproto path)
* D Disconnect
E (1) 0 Echo input disabled
1 Echo input enabled
* I Cs Tnc source callsign
JHOST (0) 0 Terminal mode enabled
1 Host mode enabled
K (0) 0 Timestamp disabled
1 Timestamp status messages
2 Timestamp monitoring & status
L [0-n] Display channel status
M (IU) NIUSC+- Monitor mode
S (0) 0-n Select channel (0=unproto)
U (0) 0 [text] Unattended mode disabled
1 [text] Unattended mode enabled
V (0) Displays the software version
Y (4) 0-n Maximum incoming connections
Z (3) 0 Flow disabled, xon/off disabled
1 Flow enabled, xon/off disabled
2 Flow disabled, xon/off enabled
3 Flow enabled, xon/off enabled
(0) Default values are shown in parentheses
n Number of channels, as specified by CHANNELS keyword
* These commands are applicable to each connection channel
COMMAND DESCRIPTION
The 'A' (AutoLF) command is used to enable or disable the automatic insertion of LINEFEED characters after CARRIAGE RETURN characters to the terminal.
The 'C' (Connect) command is used on channels other than 0 to initiate a link connection. A 'C' command issued when channel 0 is selected sets the unproto path. If digipeaters are specified, 'v' or 'via' is not required (but is allowed) between the destination callsign and the digipeater callsigns, and callsigns must be seperated by spaces. Note that on channels > 0 this command ignores the destination path and only allows connect to the node. The default unproto address for channel 0 is "CQ".
The 'D' (Disconnect) command is used to initiate a link disconnection. If there is unsent or unacknowledged information remaining, the disconnect request frame will not be sent until all information has been transmitted and acknowledged. No additional information will be received after the 'D' command has been issued. A second 'D' command may be entered to force the transmission of the disconnect request frame before all information has been sent and acknowledged. A 'D' command issued during the establishment of a link or after a disconnect request frame has been transmitted will cause an immediate return to the disconnected state.
The 'E' (Echo) command is used to enable or disable the echoing of input (commands and information) to the terminal.
The 'I' (Ident) command is used to set and display the TNC source callsign. The initial value is the APPLCALL. If no APPL block was defined, the initial value is all blanks. Changing the TNC source callsign on a connected channel is not permitted. If the tnc source callsign is left blank, the tnc will not allow connect commands or unproto transmissions. The callsign stored in channel 0 is used to initialize each connection channel upon power up or disconnection.
The 'JHOST' command is used to switch between terminal and host modes. A later section is devoted to host mode operation.
The 'K' command controls the time stamping of status messages and monitored frames.
The 'L' (LinkStatus) command is used to display the link status of one or all channels. Information displayed includes the connection path and the number of receive frames not yet displayed, number of send frames not yet transmitted, number of transmitted frames not yet acknowledged, and the current retry count. A '+' character preceeding the channel number indicates the currently selected channel. Operation of this command when host mode is enabled is somewhat different, and is described in a later section.
The 'M' (Monitor) command is used to set the frame monitoring mode. The command parameter determines the types of frames monitored, and is a list of desired frames chosen from the letters in the following table:
LTR FRAME
--- -----
N None
I I frames
U UI frames
S Supervisory frames
C Monitor while connected
+ Call signs to be included (maximum of 8)
- Call signs to be excluded (maximum of 8)
The '+' and '-' parameters may not be used together. If either is used, it must be the last parameter (followed by one to eight callsigns, if applicable). If no list of callsigns is specified to be included or excluded, all callsigns will be candidates for monitoring. Entering a '+' or '-' with no callsigns will clear the list.
The 'U' (Unattended) command is used to enable or disable unattended modes.
The 'V' (Version) command just displays the software version. In this respect it behaves like TheFirmware instead of WA8DED.
The 'Y' command is used to set the maximum number of connections that may established by incoming requests. This command has no effect on the operators ability to initiate outgoing connection requests.
The 'Z' command is used to enable or disable flow control and xon/xoff handshaking to the terminal. If flow control is enabled, output to the terminal will be inhibited while entering commands or information. If flow control is disabled, output to the terminal will not be restricted. Flow control and xon/xoff handshaking should be disabled during periods in which the tnc is operated without a terminal, to avoid suspending output which will consume buffers. If xon/xoff handshaking is enabled, terminal scrolling may be stopped and started using CONTROL-S and CONTROL-Q characters. Flow control and xon/xoff handshaking are not performed when host mode is enabled.
The '@' command is a software maintenance command. A parameter of 'B' will display the number of free buffers.