Configuring an AX.25 port

From LinuxHam
Jump to: navigation, search

Each of the AX.25 applications read a particular configuration file to obtain the parameters for the various AX.25 ports configured on your Linux machine. For AX.25 ports the file that is read is the /etc/ax25/axports file. You must have an entry in this file for each AX.25 port you want on your system.

Creating the AX.25 network device

The network device is what is listed when you use the `ifconfig' command. This is the object that the Linux kernel sends and receives network data from. Nearly always the network device has a physical port associated with it, but there are occasions where this isn't necessary. The network device does relate directly to a device driver.

In the Linux AX.25 code there are a number of device drivers. The most common is probably the KISS driver, but others are the SCC driver(s), the Baycom driver and the soundmodem driver.

Each of these device drivers will create a network device when it is started.

Creating a 6PACK device

Kernel Compile Options:

Amateur Radio support  --->
    [*] Amateur Radio support
    --- Packet Radio protocols
    <*>   Amateur Radio AX.25 Level 2 protocol
    ...
    AX.25 network device drivers  --->
    --- AX.25 network device drivers
    ...
    <*> Serial port 6PACK driver
    ...

6PACK is a protocol that is supported by some TNCs as an alternative to KISS. It is used in a similar fashion to the KISS driver, using the slattach command instead of kissattach.

A mini HOWTO on the 6PACK driver is included in the kernel source code as the file /usr/src/linux/Documentation/networking/6pack.txt.

Creating a Baycom device

Kernel Compile Options:

Amateur Radio support  --->
    [*] Amateur Radio support
    --- Packet Radio protocols
    <*>   Amateur Radio AX.25 Level 2 protocol
    ...
    AX.25 network device drivers  --->
    --- AX.25 network device drivers
    ...
    <?> BAYCOM ser12 fullduplex driver for AX.25
    <?> BAYCOM ser12 halfduplex driver for AX.25
    <?> BAYCOM picpar and par96 driver for AX.25
    <?> BAYCOM epp driver for AX.25
    ...

Thomas Sailer, despite the popularly held belief that it would not work very well, has developed Linux support for Baycom modems. His driver supports the Ser12 serial port, Par96 and the enhanced PicPar parallel port modems. Further information about the modems themselves may be obtained from the Baycom Web site.

Your first step should be to determine the i/o and addresses of the serial or parallel port(s) you have Baycom modem(s) connected to. When you have these you must configure the Baycom driver with them.

The Baycom driver creates network devices called: bc0, bc1, bc2 etc. when it is configured.

The sethdlc utility allows you to configure the driver with these parameters, or, if you have only one Baycom modem installed you may specify the parameters on the insmod command line when you load the Baycom module.

For example, a simple configuration. Disable the serial driver for COM1: then configure the Baycom driver for a Ser12 serial port modem on COM1: with the software DCD option enabled:

# setserial /dev/ttyS0 uart none
# insmod hdlcdrv
# insmod baycom mode="ser12*" iobase=0x3f8 irq=4

Par96 parallel port type modem on LPT1: using hardware DCD detection:

# insmod hdlcdrv
# insmod baycom mode="par96" iobase=0x378 irq=7 options=0

This is not really the preferred way to do it. The sethdlc utility works just as easily with one device as with many.

The sethdlc man page has the full details, but a couple of examples will illustrate the most important aspects of this configuration. The following examples assume you have already loaded the Baycom module using:

# insmod hdlcdrv
# insmod baycom

or that you compiled the kernel with the driver inbuilt.

Configure the bc0 device driver as a Parallel port Baycom modem on LPT1: with software DCD:

# sethdlc -p -i bc0 mode par96 io 0x378 irq 7

Configure the bc1 device driver as a Serial port Baycom modem on COM1:

# sethdlc -p -i bc1 mode "ser12*" io 0x3f8 irq 4

Configuring the AX.25 channel access parameters

The AX.25 channel access parameters are the equivalent of the KISS ppersist, txdelay and slottime type parameters. Again you use the sethdlc utility for this.

Again the sethdlc man page is the source of the most complete information but another example of two won't hurt:

Configure the bc0 device with TxDelay of 200 mS, SlotTime of 100 mS, PPersist of 40 and half duplex:

  1. sethdlc -i bc0 -a txd 200 slot 100 ppersist 40 half

Note that the timing values are in milliseconds.

Configuring the Kernel AX.25 to use the Baycom device

The Baycom driver creates standard network devices that the AX.25 Kernel code can use. Configuration is much the same as that for a PI or PacketTwin card.

The first step is to configure the device with an AX.25 callsign. The ifconfig utility may be used to perform this.

  1. /sbin/ifconfig bc0 hw ax25 VK2KTJ-15 up

will assign the Baycom device bc0 the AX.25 callsign VK2KTJ-15. Alternatively you can use the axparms command, you'll still need to use the ifconfig command to bring the device up though:

  1. ifconfig bc0 up
  2. axparms -setcall bc0 vk2ktj-15

The next step is to create an entry in the /etc/ax25/axports file as you would for any other device. The entry in the axports file is associated with the network device you've configured by the callsign you configure. The entry in the axports file that has the callsign that you configured the Baycom device with is the one that will be used to refer to it.

You may then treat the new AX.25 device as you would any other. You can configure it for TCP/IP, add it to ax25d and run NET/ROM or ROSE over it as you please.

Creating a YAM device

Kernel Compile Options:

Amateur Radio support  --->
    [*] Amateur Radio support
    --- Packet Radio protocols
    <*>   Amateur Radio AX.25 Level 2 protocol
    ...
    AX.25 network device drivers  --->
    --- AX.25 network device drivers
    ...
    <?> YAM driver for AX.25
    ...

YAM is Yet Another Modem, a 9600 baud modem designed by Nico Palermo. Information on the Linux driver can be found at http://www.teaser.fr/~frible/yam.html while general information on the modem can be found at http://www.microlet.com/yam/

Creating a PI card device

Kernel Compile Options:

General setup  --->
    [*] Networking support
Network device support  --->
    [*] Network device support
    ...
    [*] Radio network interfaces
    [*] Ottawa PI and PI/2 support for AX.25

The PI card device driver creates devices named `pi[0-9][ab]'. The first PI card detected will be allocated `pi0', the second `pi1' etc. The `a' and `b' refer to the first and second physical interface on the PI card. If you have built your kernel to include the PI card driver, and the card has been properly detected then you can use the following command to configure the network device:

# /sbin/ifconfig pi0a hw ax25 VK2KTJ-15 up

This command would configure the first port on the first PI card detected with the callsign VK2KTJ-15 and make it active. To use the device all you now need to do is to configure an entry into your /etc/ax25/axports file with a matching callsign/ssid and you will be ready to continue on.

The PI card driver was written by David Perry.

Creating a PacketTwin device

Kernel Compile Options:

General setup  --->
    [*] Networking support
Network device support  --->
    [*] Network device support
    ...
    [*] Radio network interfaces
    [*] Gracilis PackeTwin support for AX.25

The PacketTwin card device driver creates devices named `pt[0-9][ab]'. The first PacketTwin card detected will be allocated `pt0', the second `pt1' etc. The `a' and `b' refer to the first and second physical interface on the PacketTwin card. If you have built your kernel to include the PacketTwin card driver, and the card has been properly detected then you can use the following command to configure the network device:

# /sbin/ifconfig pt0a hw ax25 VK2KTJ-15 up

This command would configure the first port on the first PacketTwin card detected with the callsign VK2KTJ-15 and make it active. To use the device all you now need to do is to configure an entry into your /etc/ax25/axports file with a matching callsign/ssid and you will be ready to continue on.

The PacketTwin card driver was written by Craig Small, VK2XLZ.

Creating a generic SCC device

Kernel Compile Options:

General setup  --->
    [*] Networking support
Network device support  --->
    [*] Network device support
    ...
    [*] Radio network interfaces
    [*] Z8530 SCC KISS emulation driver for AX.25

Joerg Reuter, DL1BKE, has developed generic support for Z8530 SCC based cards. His driver is configurable to support a range of different types of cards and present an interface that looks like a KISS TNC so you can treat it as though it were a KISS TNC.

Obtaining and building the configuration tool package

While the kernel driver is included in the standard kernel distribution, Joerg distributes more recent versions of his driver with the suite of configuration tools that you will need to obtain as well.

You can obtain the configuration tools package from: Joerg's web page, ftp://db0bm.automation.fh-aachen.de/incoming/dl1bke, ftp://insl1.etec.uni-karlsruhe.de/pub/hamradio/linux/z8530, ftp://ftp.ucsd.edu/hamradio/packet/tcpip/linux, or ftp://ftp.ucsd.edu/hamradio/packet/tcpip/incoming.

You will find multiple versions, choose the one that best suits the kernel you intend to use: z8530drv-2.4a.dl1bke.tar.gz for 2.0.* kernels and z8530drv-utils-3.0.tar.gz for 2.1.6 or later kernels.

The following commands were what I used to compile and install the package for kernel version 2.0.30:

# cd /usr/src
# gzip -dc z8530drv-2.4a.dl1bke.tar.gz | tar xvpofz -
# cd z8530drv
# make clean
# make dep
# make module         # If you want to build the driver as a module
# make for_kernel     # If you want the driver to built into your kernel
# make install

After the above is complete you should have three new programs installed in your /sbin directory: gencfg, sccinit and sccstat. It is these programs that you will use to configure the driver for your card.

You will also have a group of new special device files created in your /dev called scc0-scc7. These will be used later and will be the `KISS' devices you will end up using.

If you chose to 'make for_kernel' then you will need to recompile your kernel. To ensure that you include support for the z8530 driver you must be sure to answer `Y' to: `Z8530 SCC kiss emulation driver for AX.25' when asked during a kernel `make config'.

If you chose to 'make module' then the new scc.o will have been installed in the appropriate /lib/modules directory and you do not need to recompile your kernel. Remember to use the insmod command to load the module before your try and configure it.

Configuring the driver for your card

The z8530 SCC driver has been designed to be as flexible as possible so as to support as many different types of cards as possible. With this flexibility has come some cost in configuration.

There is more comprehensive documentation in the package and you should read this if you have any problems. You should particularly look at doc/scc_eng.doc or doc/scc_ger.doc for more detailed information. I've paraphrased the important details, but as a result there is a lot of lower level detail that I have not included.

The main configuration file is read by the sccinit program and is called /etc/z8530drv.conf. This file is broken into two main stages: Configuration of the hardware parameters and channel configuration. After you have configured this file you need only add:

# sccinit

into the rc file that configures your network and the driver will be initialized according to the contents of the configuration file. You must do this before you attempt to use the driver.

Configuration of the hardware parameters

The first section is broken into stanzas, each stanza representing an 8530 chip. Each stanza is a list of keywords with arguments. You may specify up to four SCC chips in this file by default. The #define MAXSCC 4 in scc.c can be increased if you require support for more.

The allowable keywords and arguments are:

chip the chip keyword is used to separate stanzas. It will take anything as an argument. The arguments are not used.
data_a this keyword is used to specify the address of the data port for the z8530 channel `A'. The argument is a hexadecimal number e.g. 0x300
ctrl_a this keyword is used to specify the address of the control port for the z8530 channel `A'. The arguments is a hexadecimal number e.g. 0x304
data_b this keyword is used to specify the address of the data port for the z8530 channel `B'. The argument is a hexadecimal number e.g. 0x301
ctrl_b this keyword is used to specify the address of the control port for the z8530 channel `B'. The arguments is a hexadecimal number e.g. 0x305
irq this keyword is used to specify the IRQ used by the 8530 SCC described in this stanza. The argument is an integer e.g. 5
pclock this keyword is used to specify the frequency of the clock at the PCLK pin of the 8530. The argument is an integer frequency in Hz which defaults to 4915200 if the keyword is not supplied.
board the type of board supporting this 8530 SCC. The argument is a character string. The allowed values are:
PA0HZP the PA0HZP SCC Card
EAGLE the Eagle card
PC100 the DRSI PC100 SCC card
PRIMUS the PRIMUS-PC (DG9BL) card
BAYCOM BayCom (U)SCC card
escc this keyword is optional and is used to enable support for the Extended SCC chips (ESCC) such as the 8580, 85180, or the 85280. The argument is a character string with allowed values of `yes' or `no'. The default is `no'.
vector this keyword is optional and specifies the address of the vector latch (also known as "intack port") for PA0HZP cards. There can be only one vector latch for all chips. The default is 0.
special this keyword is optional and specifies the address of the special function register on several cards. The default is 0.
option this keyword is optional and defaults to 0.

Example configurations

Some example configurations for the more popular cards are as follows:

BayCom USCC

chip    1
data_a  0x300
ctrl_a  0x304
data_b  0x301
ctrl_b  0x305
irq     5
board   BAYCOM
#
# SCC chip 2
#
chip    2
data_a  0x302
ctrl_a  0x306
data_b  0x303
ctrl_b  0x307
board   BAYCOM

PA0HZP SCC card

chip 1
data_a 0x153
data_b 0x151
ctrl_a 0x152
ctrl_b 0x150
irq 9
pclock 4915200
board PA0HZP
vector 0x168
escc no
#
#
#
chip 2
data_a 0x157
data_b 0x155
ctrl_a 0x156
ctrl_b 0x154
irq 9
pclock 4915200
board PA0HZP
vector 0x168
escc no

DRSI SCC card

chip 1
data_a 0x303
data_b 0x301
ctrl_a 0x302
ctrl_b 0x300
irq 7
pclock 4915200
board DRSI
escc no

If you already have a working configuration for your card under NOS, then you can use the gencfg command to convert the PE1CHL NOS driver commands into a form suitable for use in the z8530 driver configuration file.

To use gencfg you simply invoke it with the same parameters as you used for the PE1CHL driver in NET/NOS. For example:

# gencfg 2 0x150 4 2 0 1 0x168 9 4915200

will generate a skeleton configuration for the OptoSCC card.

Channel Configuration

The Channel Configuration section is where you specify all of the other parameters associated with the port you are configuring. Again this section is broken into stanzas. One stanza represents one logical port, and therefore there would be two of these for each one of the hardware parameters stanzas as each 8530 SCC supports two ports.

These keywords and arguments are also written to the /etc/z8530drv.conf file and must appear after the hardware parameters section.

Sequence is very important in this section, but if you stick with the suggested sequence it should work okay. The keywords and arguments are:

device this keyword must be the first line of a port definition and specifies the name of the special device file that the rest of the configuration applies to. e.g. /dev/scc0
speed this keyword specifies the speed in bits per second of the interface. The argument is an integer: e.g. 1200
clock this keyword specifies where the clock for the data will be sourced. Allowable values are:
dpll normal halfduplex operation
external MODEM supplies its own Rx/Tx clock
divider use fullduplex divider if installed.
mode this keyword specifies the data coding to be used. Allowable arguments are: nrzi or nrz
rxbuffers this keyword specifies the number of receive buffers to allocate memory for. The argument is an integer, e.g. 8.
txbuffers this keyword specifies the number of transmit buffers to allocate memory for. The argument is an integer, e.g. 8.
bufsize this keyword specifies the size of the receive and transmit buffers. The arguments is in bytes and represents the total length of the frame, so it must also take into account the AX.25 headers and not just the length of the data field. This keyword is optional and default to 384
txdelay the KISS transmit delay value, the argument is an integer in ms.
persist the KISS persist value, the argument is an integer.
slot the KISS slot time value, the argument is an integer in ms.
tail the KISS transmit tail value, the argument is an integer in ms.
fulldup the KISS full duplex flag, the argument is an integer. 1==Full Duplex, 0==Half Duplex.
wait the KISS wait value, the argument is an integer in ms.
min the KISS min value, the argument is an integer in s.
maxkey the KISS maximum keyup time, the argument is an integer in s.
idle the KISS idle timer value, the argument is an integer in s.
maxdef the KISS maxdef value, the argument is an integer.
group the KISS group value, the argument is an integer.
txoff the KISS txoff value, the argument is an integer in ms.
softdcd the KISS softdcd value, the argument is an integer.
slip the KISS slip flag, the argument is an integer.

Using the driver

To use the driver you simply treat the /dev/scc* devices just as you would a serial tty device with a KISS TNC connected to it. For example, to configure Linux Kernel networking to use your SCC card you could use something like:

# kissattach -s 4800 /dev/scc0 VK2KTJ

You can also use NOS to attach to it in precisely the same way. From JNOS for example you would use something like:

attach asy scc0 0 ax25 scc0 256 256 4800

The sccstat and sccparam tools

To assist in the diagnosis of problems you can use the sccstat program to display the current configuration of an SCC device. To use it try:

# sccstat /dev/scc0

you will displayed a very large amount of information relating to the configuration and health of the /dev/scc0 SCC port.

The sccparam command allows you to change or modify a configuration after you have booted. Its syntax is very similar to the NOS param command, so to set the txtail setting of a device to 100mS you would use:

# sccparam /dev/scc0 txtail 0x8

Creating a BPQ ethernet device

Kernel Compile Options:

General setup  --->
    [*] Networking support
Network device support  --->
    [*] Network device support
    ...
    [*] Radio network interfaces
    [*] BPQ Ethernet driver for AX.25

Linux supports BPQ Ethernet compatibility. This enables you to run the AX.25 protocol over your Ethernet LAN and to interwork your linux machine with other BPQ machines on the LAN.

The BPQ network devices are named `bpq[0-9]'. The `bpq0' device is associated with the `eth0' device, the `bpq1' device with the `eth1' device etc.

Configuration is quite straightforward. You firstly must have configured a standard Ethernet device. This means you will have compiled your kernel to support your Ethernet card and tested that this works. Refer to the Ethernet-HOWTO for more information on how to do this.

To configure the BPQ support you need to configure the Ethernet device with an AX.25 callsign. The following command will do this for you:

# /sbin/ifconfig bpq0 hw ax25 vk2ktj-14 up

Again, remember that the callsign you specify should match the entry in the /etc/ax25/axports file that you wish to use for this port.

Configuring the BPQ Node to talk to the Linux AX.25 support

BPQ Ethernet normally uses a multicast address. The Linux implementation does not, and instead it uses the normal Ethernet broadcast address. The NET.CFG file for the BPQ ODI driver should therefore be modified to look similar to this:

LINK SUPPORT

        MAX STACKS 1
        MAX BOARDS 1

LINK DRIVER E2000                    ; or other MLID to suit your card

        INT 10                       ;
        PORT 300                     ; to suit your card

        FRAME ETHERNET_II

        PROTOCOL BPQ 8FF ETHERNET_II ; required for BPQ - can change PID

BPQPARAMS                            ; optional - only needed if you want
                                     ; to override the default target addr

        ETH_ADDR  FF:FF:FF:FF:FF:FF  ; Target address

Creating the /etc/ax25/axports file

The /etc/ax25/axports is a simple text file that you create with a text editor. The format of the /etc/ax25/axports file is as follows:

portname  callsign  baudrate  paclen  window  description

where:

callsign is the AX.25 callsign you want to assign to the port.
baudrate is the speed at which you wish the port to communicate with your TNC.
paclen is the maximum packet length you want to configure the port to use for AX.25 connected mode connections.
window is the AX.25 window (K) parameter. This is the same as the MAXFRAME setting of many TNC's.
description is a textual description of the port.

In my case, mine looks like:

radio    VK2KTJ-15       4800        256     2       4800bps 144.800 MHz
ether    VK2KTJ-14       10000000    256     2       BPQ/ethernet device

Remember, you must assign unique callsign/ssid to each AX.25 port you create. Create one entry for each AX.25 device you want to use, this includes KISS, Baycom, SCC, PI, PT and Soundmodem ports. Each entry here will describe exactly one AX.25 network device. The entries in this file are associated with the network devices by the callsign/ssid. This is at least one good reason for requiring unique callsign/ssid.

Configuring AX.25 routing

You may wish to configure default digipeaters paths for specific hosts. This is useful for both normal AX.25 connections and also IP based connections. The axparms command enables you to do this. Again, the man page offers a complete description, but a simple example might be:

# /usr/sbin/axparms -route add radio VK2XLZ VK2SUT

This command would set a digipeater entry for VK2XLZ via VK2SUT on the AX.25 port named radio