Content-type: text/html Manpage of APRSDIGI

APRSDIGI

Section: Linux Programmer's Manual (8)
Updated: 28 November 2001
Index Return to Main Contents

NAME

aprsdigi - APRS(tm) digipeater

SYNOPSIS

aprsdigi [-CcDLMXv] [-n|s|e|w path] [-fF call] [-t tag] [-k secs] [-l logfile] [-i interval] [-p port:alias1,alias2...]

DESCRIPTION

Aprsdigi is a specialized Amateur Packet Radio (AX.25) UI-frame digipeater for the Automatic Position Reporting Systems, APRS(tm). It uses the Linux kernel AX.25 network stack as well as the SOCK_PACKET facility to listen for packets on one or more radio interfaces (ports) and repeat those packets -- with several possible modifications -- on the same or other interfaces.

Aprsdigi implements conventional packet radio AX.25 digipeating, in which a packet is digipeated if the next hop (non-repeated) digipeater ("via") callsign matches the AX.25 port's callsign and sub-station ID (SSID) or an alias callsign and SSID.

There are a number of extensions to conventional digipeating that have been proposed for use in the APRS community. Some of these features have been adopted by Terminal Node Controller (TNC) manufacturers, notably Paccomm and Kantronics. Aprsdigi implements most if not all of the commercialy adopted and proposed features. See the APRSdos README files for protocol documentation and "future feature" proposals. Specific features implemented by Aprsdigi include:

- Single-interface conventional UI-frame digipeating.
- Cross-interface digipeating (also known as routing or gatewaying): and one-to-many fanout.
- Substitution of a digipeated alias with the interface's callsign (typically used to substitute RELAY, WIDE: or TRACE aliases).
- WIDEn-n: flooding algorithim.
- TRACEn-n: route recording.
- Mic-Encoder(tm): support, including SSID-based digipeating, decompression of packets into the conventional APRS MIM format. (The Mic-Encoder compression is also used by other products such as the Kenwood TH-D7A, and TAPR PIC-Encoder).
- TheNet X1J4 node beacon text translation (removal of the lqTheNet X1J4 (alias)rq prefix from the btext).

GENERAL OPTIONS

-v: Produce verbose debugging output.
-T: Test mode: listen to my packets too. This mode is useful for off-air experimentation and configuration testing. Do not use it on-air.
-D: Suppress Duplicate packets. Remembers duplicate packets for the number of seconds give by the -k option and will not repeat them more than once. This reduces conjestion caused when several digipeaters that share a common flooding alias (e.g. WIDE) have overlapping footprints, causing geometric duplication of packets addressed via lqWIDE,WIDErq for example.
-L: Suppress Looping packets. Similar in function to duplicate packet suppression, but looks back through the list of already digipeated callsigns in the packet's digipeat list and kills any packets that list a callsign belonging to this aprsdigi. Note that only real callsigns are compared. Generic flooding aliases are not.
-V: Print program version and exit.
-n|s|e|w: Set North|South|East|West SSID directional path.
-d: Set SSID omnidirectional next-hops when operating in a non flooding network (e.g. when WIDEn-n is not an option).
-f: Set flooding alias. Use lq-f WIDErq to enable WIDEn-n flooding. Use -f multiple times to define several flooding aliases.
-F: Set flooding trace callsign. Use lq-F TRACErq to enable TRACE and TRACEn-n flooding. Use -F multiple times to define several trace aliases.
-k secs: Remember old packets for this long for duplicate packet detection. Default is 28.
-l file: Log digipeated packets to this file.

PER-INTERFACE OPTIONS

Put these options before each -p to set new values as needed. The values you set are remembered for subsequent -p's so options you want to set for all interfaces need only be specified once, before the first -p.

-C (-c): Do (not) perform callsign substitution. When enabled, aliases are replaced with the interface's callsign when repeated.
-M (-m): Do (not) perform Mic-E to MIM translation. When enabled, compressed Mic-E reports are expanded into one MIM-style position report packet and optionally a second telemetry packet if telemetry was supplied in the Mic-E packet.
-X (-x): Do (not) perform X1J4 translation. When enabled, the leading lqTheNet X1J4 (alias)rq text is removed when digipeated. This allows non-compliant APRS implementations to detect an APRS position report in an X1J4 beacon.
-i secs: Seconds between ID transmissions. Set to 0 to disable IDs on this interface. Default is 570 (9 minutes 30 seconds). IDs are only sent if the interface transmitted anything since the last ID. ID packets are addressed to the lqIDrq callsign, have no digipeat path, and list the callsign and aliases for the interface the ID is being transmitted on.
-t text: Text to append to received packets. Use -t - to reset to empty. Use this, for example, when gatewaying Mic-E packets from a voice repeater to the APRS net frequency to indicate where the report originated.
-p port:alias1,alias2,...: AX25 interface name (port) and optional list of aliases. The primary callsign is obtained from the interface's configuration. (See ifconfig(8)).

RUNTIME CONTROLS

aprsdigi responds to the following signals:

SIGUSR1: Print cumulative statistics. For each port, the following counters are displayed: packets received and how many of those where ignored, duplicates, loops, mic-E formatted; packets transmitted and how many of those where conventional digipeats, flooding digipeats (WIDEn-n), SSID-based digipeats, and IDs. If a log file was specified with the -l option, then the statistics are written to that file. Otherwise they are written to stderr.
SIGUSR2: Prints the statistics and then resets all counters to zero.

All other normal termination signals cause final statistics to print before aprsdigi exits.

MIC-E SSID-BASED ROUTING

SSID-based routing uses a non-zero sub-station ID in the destination callsign, an empty digipeater path, and the presence of a Mic-Encoder lqsignaturerq in the text of the packet to indicate that the APRS digipeater should repeat the packet after filling in an appropriate digipeater path. For example, a packet sent to lqT1QS4W-3rq would be repeated with a modifed destination of lqAPRS VIA WIDE3-3rq (in a network that supports WIDEn-n flooding). A packet sent to lqT1QS4W-11rq would be repeated to the West unproto path, as defined with the -w option. A table of SSID values and their paths follows:

SSID unproto path
---- ------------
0    none 
1    WIDE1-1
2    WIDE2-2
3    WIDE3-3
4    WIDE4-4
5    WIDE5-5
6    WIDE6-6
7    WIDE7-7
8    NORTH UNPROTO path
9    SOUTH UNPROTO path
10   EAST  UNPROTO path
11   WEST  UNPROTO path
12   NORTH UNPROTO path + WIDE
13   SOUTH UNPROTO path + WIDE
14   EAST  UNPROTO path + WIDE
15   WEST  UNPROTO path + WIDE

The theory behind Mic-Encoder digipeating is described in more detail in the APRSdos README, MIC-E.TXT. Basically, the idea is to minimize packet lengths on the voice frequency and to have the manager of the Mic-Encoder repeater gateway determine the most appropriate digipeat paths from the Mic-E gateway site.

Aprsdigi also fits into a non WIDEn-n network by using the same algorithm for selection of subset of digipeaters from a list supplied with the -d option as the MIC-E. That is, SSIDs of 1, 2 or 3 select that number of digipeaters from the first three digipeaters in the -d list. SSIDs of 4, 5, 6, or 7, start at the fourth digipeater in the list.

FLOODING ALIASES

APRS flooding (WIDEn-n) digipeating works by repeating any received packet whose next hop digipeater has a flooding alias (specified with the -f option), and the SSID is 1 or greater. The SSID is decremented by one, and the packet is repeated. Furthermore, to prevent broadcast storms, recently transmitted packets are remembered for a period of time specified by the -k option and are not repeated if they are heard within that time period.

Unlike conventional digipeating, in which the digipeater callsign/alias is flagged as lqrepeatedrq, the flooding mode does not do this. Once the SSID decrements to zero, then a flooding alias is treated just like any other alias, and does get marked as repeated upon transmission.

TRACE and TRACEn-n ALIASES

lqFloodingrq Trace aliases (TRACEn-n; -F option) are treated like flooding aliases with the addition that, besides decrementing the SSID, the current interface's callsign is inserted in front of the trace alias, providing a record-route function. lqPlainrq trace aliases (TRACE; also -F option) are simply substituted in the conventional ( -C ) manner.

MULTI PORT OPERATION

In single port operation, there is only one interface specified with -p. All packets are received and some are retransmitted on the same interface, depending on whether they match the criteria for retransmission after translation of the digpeater path from one of the APRS-specific formats:

- Mic-E TO-call SSID-based route.
- WIDEn-n/TRACEn-n flooding.

or a conventional next-hop (non-repeated) digipeater matching the callsign or one of the aliases for the interface.

The decision to transmit is made by matching the next hop callsign/alias with the table of callsigns and aliases you supply to -p.

In multi-port operation, this same technique simply extends to several interfaces. Besides each interface's unique callsign, you can give the same alias to several interfaces. This results in a one-to-many fanout which might be useful for dual frequency operation such as a general use APRS net frequency and an event-specific frequency.

By using different flags for Mic-E expansions, etc. you can tailor these fanouts differently on each of these interfaces, perhaps keeping Mic-E packets compressed on one frequency while decompressing them on another.

EXAMPLES

- Implementation of TRACE: Note that TRACEn-n vs. plain TRACE do different things: TRACEn-n *inserts* calls into the digipath while decrementing ssid, e.g.:

        RELAY*,TRACE3-3
        RELAY,N2YGK-7*,TRACE3-2
        RELAY,N2YGK-7,WB2ZII*,TRACE3-1
        RELAY,N2YGK-7,WB2ZII,N2MH-15*,TRACE3
        RELAY,N2YGK-7,WB2ZII,N2MH-15,WA2YSM-14*

- Kill looping packets (-L option):

        RELAY*,WIDE,WIDE,WIDE
        RELAY,N2YGK-7*,WIDE,WIDE
        RELAY,N2YGK-7,WIDE*,WIDE

Normally n2ygk-7 would respond to this, but, by finding one of mycall earlier in the path, I know to ignore it.

Following is a sample invocation of aprsdigi running on two ports. This is a contrived example that tries to show all the features.

aprsdigi \
   -v \
   -T \
   -n "N2YGK-2 WB2ZII WA2YSM-14" \
   -s "N2YGK-3 WB2ZII WA2JNF-4" \
   -e "N2YGK-3 WB2ZII KD1LY" \
   -w "N2YGK-2 WB2ZII N2MH-15" \
   -f "WIDE" \
   -F "TRACE" \
   -DLMC \
   -t " via 147.06 (WB2ZII/R)" \
   -psm0:RELAY,WIDE,TRACE \
   -mXc \
   -t - \
   -pax0:RELAY,WIDE,FOO,TRACE

Linux APRS(tm) digipeater
portions Copyright (c) 1996,1997,1999 Alan Crosswell, n2ygk@weca.org
Version: aprsdigi aprsdigi-2.0
This is free software covered under the GNU Public License.
There is no warranty.  See the file COPYING for details.

My interfaces:
Interface Callsign  Aliases...
sm0       N2YGK-2   RELAY     WIDE      TRACE    
ax0       N2YGK-3   RELAY     WIDE      FOO       TRACE    
My interface options:
Interface Flags    ID interval tag
sm0       CMx      570 (09:30)  via 147.06 (WB2ZII/R)
ax0       cmX      570 (09:30) (none)

My callsigns and aliases (routing table):
Callsign  Interfaces...
N2YGK-2   sm0      
RELAY     sm0       ax0      
WIDEn-n   sm0       ax0      
TRACEn-n  sm0       ax0      
N2YGK-3   ax0      
FOO       ax0      
SSID-based directional routing:

N:        N2YGK-2   WB2ZII    WA2YSM-14 
S:        N2YGK-3   WB2ZII    WA2JNF-4  
E:        N2YGK-3   WB2ZII    KD1LY     
W:        N2YGK-2   WB2ZII    N2MH-15   
keep dupes for: 28 seconds
log file: (none)
kill dupes: ON loops: ON  testing: OFF

BUGS

Aprsdigi: should not be confused with a Wes Johnson's DOS program of the same name.
This code has most recently been tested with the Linux 2.4.7 kernel.

Features planned but not yet implemented:

- UDP multicast interface.
- HOME routing as described in the APRSdos README, DIGIS.TXT.
- Compression.

FILES

/etc/ax25/axports

AUTHORS

Alan Crosswell, n2ygk@weca.org


APRS and the Mic-Encoder are Trademarks of APRS Engineering LLC.

This document was created by man2html, using the manual pages.
Time: 00:46:46 GMT, November 29, 2001