Synchronet v3.15b-Win32 (upgrade) has been released (Oct-2011).

DokuWiki just upgraded to the latest. You must now have an account on Vertrauen to edit the wiki.

You can donate to the Synchronet project using PayPal.

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.

Overview

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 the more basic usage of AX.25, namely using the protocol as a means of passing arbitrary data between systems. A typical 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.

Several 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.

Requirements

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
  • exec/load/callsign.js

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

KISS Mode, AX.25 and Synchronet

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 via a radio.

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, while also taking the memory limitations of 1980s-era TNCs out of the equation.

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 supports the KISS and AX.25 protocols.

Configuring and Enabling Packet Radio Support for Synchronet

Edit ctrl/kiss.ini

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>
; Optional values
;port = <0 - 15, the radio port number on a multiport TNC>
;timeout = <Time to wait while reading a packet from the TNC, in milliseconds>
;txDelay = <Time between transmitter keydown and packet transmit, in milliseconds>
;persistence = <CSMA persistence, between 0 and 1>
;slotTime = <CSMA slot time, in milliseconds>
;txTail = <Obsolete>
;fullDuplex = <1 or 0>
;setHardware = <Consult your TNC documentation; don't include this value unless you have to>

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

Create/Edit text/badwords.can (Optional)

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.

Prepare the AX.25 Command Shell

The AX.25 command shell (exec/ax25shell.js) is a custom user interface geared toward packet radio users. It is not recommended for use by clients connecting by other means.

To have your BBS launch this command shell when an AX.25 client connects, make a copy of exec/logon.js and place it in your mods directory. Edit mods/logon.js, and add the following code to the top of the file:

if(console.terminal == "AX25") {
	bbs.exec("?ax25shell.js");
	bbs.hangup();
	exit();
}

By launching the shell in this manner, you can bypass any modules in your login sequence that are not appropriate for AX.25 clients (lightbar menus, etc.), and also avoid setting an alternate command shell for those users who also connect over the internet via telnet, SSH or rlogin.

Launch the AX.25 Tunnel

Now that you're ready to go, open a command prompt and navigate to your exec directory. Once there, type:

jsexec -l ax25tunnel.js

The AX.25 tunnel script (exec/ax25tunnel.js) should now be running. This script is responsible for monitoring your TNCs (as defined in ctrl/kiss.ini,) handling connections from AX.25 clients and tunnelling traffic between them and the terminal server of your BBS (via RLOGIN.)

Mapping User Accounts to Callsigns

exec/ax25tunnel.js matches the callsign and SSID of an inbound AX.25 link to a user account on the BBS whenever possible. It does this by comparing the combined callsign and SSID (eg. “VE3XEC0”, or “VA7RRX2”) against the Chat Handle fields of all users on the BBS until a match is found. If an existing user of your BBS wishes to link their callsign to their account, all you'll need to do is add the callsign+SSID pair that they'll be connecting from to the Chat Handle field of their account.

If no match for the callsign and SSID can be found in the system when a client connects, an account will be created for them (populated with data from various online callsign databases if possible) and they will be logged in automatically.

Libraries

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.

Compatibility

KISS-mode being what it is, most any KISS TNC should at the very least work on the server-side.

Synchronet's KISS support has just been rewritten. Notes about testing with specific hardware will appear here once testing has been done. Please feel free to contribute your own notes.

Support

You can blame me (echicken) for Synchronet's AX.25 support. I'm eager to hear about your experiences with 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

See Also


In Other Languages
Translations of this page: