Set up Synchronet as an AX.25 Packet Radio BBS

Sysops who are also amateur radio operators may wish to offer access to their Synchronet BBS via AX.25 packet radio. This article explains how to configure Synchronet to handle such connections.

AX.25 packet radio is a digital mode of communication often used by amateur radio operators. By connecting a device called a Terminal Node Controller (TNC) between a computer and a radio transceiver, one can transmit and receive digital data over the air. While faster and more efficient modes of digital communication do exist, AX.25 persists due to being robust, reliable, usable over great distances, and due to the proliferation of software and hardware that supports this standard.

The traffic of other protocols, including TCP/IP, can be encapsulated in AX.25 frames, however what this page will focus on is so-called “unproto” usage of AX.25, namely using the protocol as a means of passing arbitrary data between systems. A typical unproto session would involve a user accessing their TNC using a terminal emulator (SyncTERM, Minicom, Hyperterminal, etc.), issuing commands to have it connect to another station, then sending and receiving strings of ASCII text. The answering station may be attended by another operator at a keyboard, or by software monitoring the TNC for activity. For the caller, the experience is similar to (but slower than) calling a dial-up or Telnet BBS.

Many packet radio-based bulletin board systems already exist, and in fact most TNCs include a basic BBS in their firmware. Synchronet's many capabilities make it an ideal back-end for a packet radio BBS. Using the information on this page, you should be able to get your Synchronet BBS on the air.

Obviously you'll need a radio transceiver connected to an antenna system of some kind. You'll also need a TNC supporting the KISS protocol (more on that in a moment) and an up-to-date installation of Synchronet.

Before proceeding, consult your TNC's documentation and familiarize yourself with the procedures for placing it into (and getting it out of) KISS mode. Make note of the speed of communication between the TNC and the host computer, and understand the difference between this and the rate of over-the-air communications.

Confirm that the following files are present relative to the root directory of your Synchronet BBS installation:

• ctrl/kiss.ini
• exec/ax25tunnel.js
• exec/ax25shell.js
• exec/load/ax25defs.js
• exec/load/kissAX25lib.js

If any of the above files are missing, grab the latest copies from the Synchronet CVS.

AX.25 is the protocol spoken between packet radio stations. KISS (Keep It Simple, Stupid) is the protocol that your computer will use to talk to your TNC.

Most TNCs offer a terminal mode of operation, meaning that you the operator can access your TNC via a serial port, issue textual commands to it and view human-readable menus and responses. When calling packet radio bulletin board systems, this is the mode that you'll typically use. While most TNCs support the same commands and present information to the user in similar ways, no piece of software can reliably control every given model of TNC using these commands, or reliably parse the TNC's output.

KISS is a protocol that defines a standard for communication between software running on a host computer and a connected TNC. When software control and monitoring of a TNC is required, KISS is the most reliable and universal option. In KISS mode, the TNC is responsible for very few things. It listens for data inbound from your transceiver, demodulates it, verifies the checksums of inbound packets and discards them if necessary. When transmitting, the TNC watches for KISS frames from your computer, appends checksums to the AX.25 packets encapsulated therein, and then modulates the data onto an audio signal to be sent out over the air.

While a TNC in Host or BBS mode will often only support one connection at a time, KISS-mode TNCs operate on a connectionless basis, passing all AX.25 frames that they receive from the channel along to the host computer. This means that the host software can support concurrent AX.25 connections via a single TNC. Unnecessary? Sure, but it's still “better.”

KISS mode offers a lot of flexibility, and makes it very easy for software running on your computer to communicate with many different models of TNC. Unfortunately, it also places the burden of supporting the AX.25 protocol mostly on the host software. This means that support for the AX.25 protocol has to be provided by Synchronet itself. By way of a Javascript library and some supporting files, Synchronet now has full support for the KISS protocol and partial (let's say 90%) support for the AX.25 protocol. There are several things left to do before the protocol is fully implemented, so in the meantime such communication may be unreliable, especially when operating under less than ideal conditions. Your mileage may vary.

This is where you configure your TNC(s). You can define as many TNCs as you like by adding in a section for each of them as follows:

[TNC-Name]
callsign = <Callsign>
ssid = <Numeric SSID from 0 to 15>
serialPort = <Device name (Windows) or path (*nix)>
baudRate = <Numeric baud rate, eg. 9600>

The TNC name isn't terribly important, but you'll need to remember which names you chose for your TNCs once we get a bit farther along.

In most cases, the SSID can be set to 0 unless you intend to operate multiple TNCs on the same frequency using the same callsign.

Example 1:

[KPC3]
callsign = WD1CKS
ssid = 0
serialPort = COM4
baudRate = 9600

Example 2:

[AEA-PK232]
callsign = VE3XEC
ssid = 2
serialPort = /dev/ttyUSB0
baudRate = 9600

Since we're not allowed to use offensive language over the air, everything sent out to AX.25 clients by ax25tunnel.js passes through a censorship filter.

If your text directory does not already contain a file called badwords.can, you should create it and populate it with a line-by-line list of all of the fuck, shit, piss, etc. that you do not want your station to transmit over the air. Hell damn fart.

Okay, you're finally ready to go. Open a command prompt and navigate to your exec directory. Once there, type:

jsexec -l ax25tunnel.js <tnc1> <tnc2> <tnc3> etc.

Where <tnc1> etc. are the names of TNCs as defined in ctrl/kiss.ini. Example:

jsexec -l ax25tunnel.js KPC3 AEA-PK232

The AX.25 tunnel script (exec/ax25tunnel.js) should now be running. This script is responsible for monitoring your TNCs, handling connections from AX.25 clients and tunnelling traffic between them and the Packet-BBS service running on your BBS.

Hopefully in the near future this will be replaced by a similar script that will gate between AX.25 clients and the terminal server via Rlogin or, less preferably, Telnet. The Packet-BBS Service is intended only as a temporary solution.

Most of the support for the KISS and AX.25 protocols in Synchronet are provided by the following two files:

• exec/load/ax25defs.js

• exec/load/kissAX25lib.js

The latter is heavily commented, so if you wish to develop your own scripts to make use of Synchronet's packet radio support, start by reading that file. You may also wish to consult exec/ax25tunnel.js, exec/ax25call.js, and exec/examples/ax25monitor.js for some examples of how to use the objects and functions provided by kissAX25lib.js.

KISS-mode being what it is, most any KISS TNC should at the very least work on the server-side. kissAX25lib.js has been tested with the following TNCs:

• Kantronics KPC3+ Firmware rev. 9.1 (Client & Server)
• Kenwood TH-D7A / TASCO Radio Modem 09/15/99 2Chip version 2.00 (Client only - this KISS implementation is broken)
• AEA PK-232 (Client & Server)
• AEA PK-12 (Client & Server)
• MFJ-1278 (Client & Server)
• TAPR TNC 2 (Client & Server)

It, uh, works with most of them, but the library is not without its problems, especially when dealing with certain clients.

This is a real work in progress, so the answer to a lot of your questions might be “Yeah, I know - I'm working on it.” However, information about your experiences in using this software are welcome and will help to improve it. If you have any questions or anything to report, try the following:

• DOVE-Net: Send a message to echicken in the Synchronet Discussion or Ham Radio sub-boards
• IRC: Look for echicken in #synchronet or #hamradio on irc.synchro.net
• BBS: Contact echicken on bbs.electronicchicken.com

• howto index