aprx(8) System Manager's Manual aprx(8)
NAME
Aprx-2 - An APRS iGate application with integrated Digipeater.
SYNOPSIS
aprx [-d[d[d]]] [-e] [-i] [-v] [-V] [-l syslogfacilityname] [-f
/etc/aprx.conf]
DESCRIPTION
The aprx program is a special purpose Ham-radio application supplying
infrastructure services for APRS protocol use.
A more detailed manual is available at:
http://ham.zmailer.org/oh2mqk/aprx/aprx-manual.pdf
FEATURES
The Aprx begun as a receive-only APRS iGate application with minimum
system support technology requirements. This version has also multi-
port digipeater support, transmit iGate, and experimental D-PRS-to-APRS
RF/Rx-iGate.
• The Aprx does not require machine to have any other software in it,
than things in UNIX standard libc. In particular no special AX.25
libraries at all, nor widgets or even C++ runtime.
• Important goal has been to keep R/W memory footprint as small as
possible, and on general purpose i386 Linux a single radio port
iGate+digipeater is now around 250 kB of R/W memory allocations.
• Any UNIX (and UNIX like) platform should work for the Aprx, or be
trivially ported.
• The Aprx can listen "TNC2 monitor" and "KISS" speaking TNCs on any
serial ports.
• For Aprx the serial port can be ordinary host computer port, a USB
serial port, or remote port on a remote server behind the internet,
like cisco router AUX ports (port 4001, TCP STREAM without TELNET
escapes.)
• The Aprx does not require machine to have AX.25 protocol support
internally! (Thus this works also on e.g. Solaris and BSD machines
without PF_AX25 sockets.)
• On Linux machine with kernel internal AX.25 protocol support, the
Aprx can listen on it with promiscuous mode and in order to use
that, the Aprx must be started as root user, and be configured to
list interface callsigns that APRS packets are coming in. The AX.25
socket listening is not in itself configurable, it is always exists
in Linux systems, and related configuration parameters are ignored
in other platforms. This socket listening does not need auxiliary
"libax25" to function.
• The Aprx program can be run without root privileges at least against
remote serial port servers. One must change local serial port own-
ership or access-groups (if any are used) to userid that runs the
program and possibly do several changes of file paths in configura-
tion file beginning with its location (startup parameter). How that
is done is up to the user or system integrator of this program.
• The Aprx connects with one callsign-ssid pair to APRS-IS core for
all received radio ports.
• The Aprx Rx-iGate knows that messages with following tokens in AX.25
VIA fields are not to be relayed into APRS-IS network:
RFONLY, NOGATE, TCPIP, TCPXX
• The Aprx Rx-iGate knows that following source address prefixes are
bogus and thus messages with them are to be junked:
WIDE, RELAY, TRACE, TCPIP, TCPXX, NOCALL, N0CALL
• The Aprx Rx-iGate Drops all query messages ("?").
• The Aprx Rx-iGate opens up all 3rd party messages ("}"), and checks
the internal data if it is OK to be gated out to APRS-IS.
• The Aprx has built-in "Erlang monitor" mechanism that telemeters
each receiving interface to APRS-IS. It can also syslog the inter-
face specific channel occupancy, and optionally can output to STD-
OUT.
• The Aprx (since version 1.91) can do digipeater functions.
• The Aprx (since version 1.99) does have experimental D-STAR D-PRS to
APRS gateway functionality. See the aprx-manual.pdf for details.
• The Aprx can be run on systems without writable storage, even with
very little memory, like on NSLU2, and OpenWrt platforms. The
experiments have shown that a single radio Tx-iGate+digipeater works
with less than 300 kB of writable RAM for the Aprx itself. Addi-
tional memory is necessary for operating system services of TCP/IP
networking, and serial port drivers.
OPTIONS
The aprx has following runtime options:
-i Keep the program foreground without debugging outputs.
-d Turn on verbose debugging, outputs data to STDOUT.
-dd the "more debug" mode shows also details of network interaction
with the APRS-IS network service.
-ddd the "even more debug" mode shows also detail classification of
every kind of frame received in KISS variants.
-e Erlang output prints 10 minute and 60 minute traffic accumula-
tion byte counts, and guestimates on channel occupancy, alias
"Erlang". These outputs are sent to STDOUT, which system opera-
tor may choose to log elsewere. This is independent if the "-l"
option below.
-f /etc/aprx.conf
Configuration file, given path is built-in default, and can be
overridden by the program runner.
-l syslogfacilityname
Defines syslog(3) facility code used by the erlang reporter by
defining its name. Default value is: NONE, and accepted values
are: LOG_DAEMON, LOG_FTP, LOG_LPR, LOG_MAIL, LOG_NEWS, LOG_USER,
LOG_UUCP, LOG_LOCAL0, LOG_LOCAL1, LOG_LOCAL2, LOG_LOCAL3,
LOG_LOCAL4, LOG_LOCAL5, LOG_LOCAL6, LOG_LOCAL7. That list is
subject to actual facility code set in the system, and in any
case if you specify a code that is not known, then the program
will complain during the startup, and report it. This is inde-
pendent of the "-e" option above.
-v Verbose logging of received traffic to STDOUT. Lines begin with
reception timestamp (UNIX time_t seconds), then TAB, and either
data as is, or with prefix byte: "*" for "discarded due to data
content", or possibly "#" for "discarded due to APRS-IS being
unreachable".
-V Print source version compiled to this binary, and exit.
DEBUGGING SYSTEM
Use parameter set -ddv (or -dddv) to test new configuration by running
it synchronously to console.
NORMAL OPERATION
Running the aprx program without any of option flags: -d, -v, or -e
reads possibly given configuration, then automatically backgrounds the
process, and writes pidfile. When the process whose number written in
pidfile is then sent a SIGTERM signal, it automatically shuts down
itself, and removes the pidfile. The pidfile can be runtime configured
with the -f /etc/aprx.conf file, and it has default name of:
/var/run/aprx.pid.
CONFIGURATION FILE
The configuration file is used to setup the program to do its job.
You can construct following configurations:
• A receive-only iGate server.
• A digipeater with bi-directional iGate server.
• A single radio digipeater. (The most common type of digipeater.)
• A multi-interfaced digipeater relaying traffic in between multiple
radios. (On same or on separate frequencies.)
• A viscuous digipeater, which relays a packet it heard from viscuous
source after the viscuous delay, unless it was heard more times than
only once, or it was heard from non-viscuous source before the vis-
cuous one was digipeated. This allows of making fill-in digipeaters
that will not digipeat the packet, if that same packet was heard
twice or more before the viscuos delay expired.
In the configuration file a line ending backslash (\) character con-
catenates next input line into itself. Combined result can be up to
8000 bytes long. This combination can be a bit surprising:
#beacon .... long text \
continuation
results in single long input line that begins with '#' (it is comment)
and all continuations following it have been folded in. Presented line
number of combined continuation is the line number of the last line
segment in this type of multi-line input.
In the configuration file there is special treatment for quoted
strings. They are stripped of the outer quotes, and "\" character is
processed within the source string to produce an output string. The
escapes are:
\n Produces newline character (Control-J) on the output string.
\r Produces carriage return character (Control-M) on the output
string.
\\ Places a back-slash on the output string.
\" Places a double-quote on the output string.
\' Places a single-quote on the output string.
\xHH Lower-case "x" precedes two hex digits which ensemble is then
converted to a single byte in the output string.
The complex encodings are for possible initstrings of the external
devices, and in particular for initstrings even a nul byte ( \x00 ) is
supported.
A configuration token without surrounding quotes does not understand
the backslash escapes.
#
# Sample configuration file for the APRX -- an Rx-only APRS iGate with
# Digipeater functionality.
#
#
# Simple sample configuration file for the APRX-2
#
# This configuration is structured with Apache HTTPD style tags
# which then contain subsystem parameters.
#
#
# For simple case, you need to adjust 4 things:
# - Mycall parameter
# - Select correct type of interface (ax25-device or serial-device)
# - Optionally set a beacon telling where this system is
# - Optionally enable digipeater with or without tx-igate
#
#
#
# Define the parameters in following order:
# 1) <aprsis> ** zero to many
# 2) <logging> ** zero or one
# 3) <interface> ** one to many
# 4) <beacon> ** zero to many
# 5) <telemetry ** zero to many
# 6) <digipeater> ** zero to many (at most one for each Tx)
#
#
# Global macro for simplified callsign definition:
# Usable for 99+% of cases.
#
mycall N0CALL-1
#
# Global macro for simplified "my location" definition in
# place of explicit "lat nn lon mm" at beacons. Will also
# give "my location" reference for "filter m/100".
#
#myloc lat ddmm.mmN lon dddmm.mmE
<aprsis>
# The login parameter:
# Station call-id used for relaying APRS frames into APRS-IS.
# Use this only to define other callsign for APRS-IS login.
#
#login OTHERCALL-7 # login defaults to $mycall
#
# The passcode parameter:
# Unique code for your callsign to allow transmitting packets
# into the APRS-IS.
#
passcode -1
# APRS-IS server name and portnumber.
# Every reconnect does re-resolve the name to IP address.
# Some alternates are shown below, choose something local to you.
#
server rotate.aprs2.net 14580
#server noam.aprs2.net 14580
#server soam.aprs2.net 14580
#server euro.aprs2.net 14580
#server asia.aprs2.net 14580
#server aunz.aprs2.net 14580
# Some APRS-IS servers tell every about 20 seconds to all contact
# ports that they are there and alive. Others are just silent.
# Recommended value 3*"heartbeat" + some -> 120 (seconds)
#
#heartbeat-timeout 0 # Disabler of heartbeat timeout
# APRS-IS server may support some filter commands.
# See: http://www.aprs-is.net/javAPRSFilter.aspx
#
# You can define the filter as single long quoted string, or as
# many short segments with explaining comments following them.
#
# Usability of these filters for a Tx-iGate is dubious, but
# they exist in case you for example want to Tx-iGate packets
# from some source callsigns in all cases even when they are
# not in your local area.
#
#filter "possibly multiple filter specs in quotes"
#
#filter "m/100" # My-Range filter
#filter "f/OH2XYZ-3/50" # Friend-Range filter
</aprsis>
<logging>
# pidfile is UNIX way to tell that others that this program is
# running with given process-id number. This has compiled-in
# default value of: pidfile /var/run/aprx.pid
#
#pidfile /var/run/aprx.pid
# rflog defines a rotatable file into which all RF-received packets
# are logged.
#
#rflog /var/log/aprx/aprx-rf.log
# aprxlog defines a rotatable file into which most important
# events on APRS-IS connection are logged, namely connects and
# disconnects.
#
#aprxlog /var/log/aprx/aprx.log
# erlangfile defines a mmap():able binary file, which stores
# running sums of interfaces upon which the channel erlang
# estimator runs, and collects data.
# Depending on the system, it may be running on a filesystem
# that actually retains data over reboots, or it may not.
# With this backing store, the system does not loose cumulating
# erlang data over the current period, if the restart is quick,
# and does not stradle any exact minute.
# (Do restarts at 15 seconds over an even minute..)
# This file is around 0.7 MB per each interface talking APRS.
# If this file is not defined and can not be created,
# internal non-persistent in-memory storage will be used.
#
# Built-in default value is: /var/run/aprx.state
#
#erlangfile /var/run/aprx.state
# erlang-loglevel is config file edition of the "-l" option
# pushing erlang data to syslog(3).
# Valid values are (possibly) following: NONE, LOG_DAEMON,
# LOG_FTP, LOG_LPR, LOG_MAIL, LOG_NEWS, LOG_USER, LOG_UUCP,
# LOG_LOCAL0, LOG_LOCAL1, LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4,
# LOG_LOCAL5, LOG_LOCAL6, LOG_LOCAL7. If the parameter value is
# not acceptable, list of accepted values are printed at startup.
#
#erlang-loglevel NONE
# erlanglog defines a rotatable file into which erlang data
# is written in text form.
#
#erlanglog /var/log/aprx/erlang.log
# erlang-log1min option logs to syslog/file also 1 minute
# interval data from the program. (In addition to 10m and 60m.)
#
#erlang-log1min
</logging>
# *********** Multiple <interface> definitions can follow *********
# ax25-device Lists AX.25 ports by their callsigns that in Linux
# systems receive APRS packets. If none are defined,
# or the system is not Linux, the AX.25 network receiver
# is not enabled. Used technologies need at least
# Linux kernel 2.4.x
#
# tx-ok Boolean telling if this device is able to transmit.
#
#<interface>
# ax25-device $mycall # Either $mycall macro, or actual callsign
# #tx-ok false # transmitter enable defaults to false
# #telem-to-is true # set to false to disable
#</interface>
# The TNC serial options. Parameters are:
# - /dev/ttyUSB1 -- tty device
# - 19200 -- baud rate, supported ones are:
# 1200, 2400, 4800, 9600, 19200, 38400, ...
# - 8n1 -- 8-bits, no parity, one stop-bit,
# no other supported modes
# - "KISS" - plain basic KISS mode
# - "XORSUM" alias "BPQCRC" - KISS with BPQ "CRC" byte
# - "SMACK" alias "CRC16" - KISS with real CRC
# - "FLEXNET" - KISS with real CRC
# - "TNC2" - TNC2 monitor format
# - "DPRS" - DPRS (rx) Gateway
#
#<interface>
# serial-device /dev/ttyUSB0 19200 8n1 KISS
# #callsign $mycall # Either $mycall macro, or actual callsign
# #tx-ok false # transmitter enable defaults to false
# #telem-to-is true # set to false to disable
#</interface>
#
#<interface>
# serial-device /dev/ttyUSB1 19200 8n1 TNC2
# #callsign $mycall # Either $mycall macro, or actual callsign
# #tx-ok false # TNC2 monitor can not have transmitter
# #telem-to-is true # set to false to disable
#</interface>
#
#<interface>
# serial-device /dev/ttyUSB1 19200 8n1 DPRS
# callsign dprsgwcallsign # must define actual callsign
# #tx-ok false # DPRS monitor can not do transmit
# #telem-to-is true # set to false to disable
#</interface>
#
# *********** Multiple <beacon> definitions can follow *********
<beacon>
#
# Beacons are sent out to radio transmitters AND/OR APRSIS.
# Default is "both", other modes are settable.
#
#beaconmode { aprsis | both | radio }
#
# Beacons are sent from a circullar transmission queue, total cycle time
# of that queue is 20 minutes by default, and beacons are "evenly"
# distributed along it. Actual intervals are randomized to be anything
# in between 80% and 100% of the cycle-size / number-of-beacons.
# First beacon is sent out 30 seconds after system start.
# Tune the cycle-size to be suitable to your number of defined beacons.
#
#cycle-size 20m
#
#
# Basic beaconed thing is positional message of type "!":
#
#beacon symbol "R&" lat "0000.00N" lon "00000.00E" comment "Rx-only iGate"
#beacon symbol "R&" $myloc comment "Rx-only iGate"
#
# Following are basic options:
# 'symbol' no default, must be defined!
# 'lat' coordinate latitude: ddmm.mmN (no default!)
# 'lon' coordinate longitude: dddmm.mmE (no default!)
# '$myloc' coordinate values taken from global 'myloc' entry,
# and usable in place of explicit 'lat'+'lon'.
# 'comment' optional tail part of the item, default is nothing
#
# Sample symbols:
# R& is for "Rx-only iGate"
# I& is for "Tx-iGate"
# /# is for "Digipeater"
# I# is for "Tx-iGate + Digipeater"
#
# Additional options are:
# 'srccall' parameter sets claimed origination address.
# 'dstcall' sets destination address, default "APRXnn"
# 'interface' parameter picks an interface (must be "tx-ok true" type)
# 'via' sets radio distribution pattern, default: none.
# 'timefix' On APRS messages with HMS timestamp (hour:min:sec), the
# system fixes appropriate field with transmit time timestamp.
#
# Message type is by default '!', which is positional no timestamp format.
# Other possible formats are definable with options:
# 'type' Single character setting type: ! = / @
# 'item' Defines a name of Item (')') type beacons.
# 'object' Defines a name of Object (';') type beacons.
#
# 'file' option tells a file at which a _raw_ APRS message content is
# expected to be found as first line of text. Line ending newline
# is removed, and no escapes are supported. The timefix is
# available, though probably should not be used.
#
# 'exec' option defines program path for a program whose stdout is
# read up to first newline (which must be present), and then
# transmit as beacon content. No format helpers are supplied,
# although 'timefix' can be used.
# 'timeout' option is associated with 'exec', and defines when the
# exec must by latest produce the output, or the subprogram
# execution is killed. Default value is 10 seconds.
#
# The parameter sets can vary:
# a) 'srccall nnn-n dstcall "string" symbol "R&" lat "ddmm.mmN" lon "dddmm.mmE" [comment "any text"]
# b) 'srccall nnn-n dstcall "string" raw "string"'
#
# The a) form flags on some of possible syntax errors in parameters.
# It will also create only "!" type messages. The dest parameter
# defaults to "APRS", but can be used to give other destinations.
# The via parameter can be used to add other keywords, like "NOGATE".
#
# Writing correct RAW format beacon message is very hard,
# which is evidenced by the frequency of bad syntax texts
# people so often put there... If you can not be persuaded
# not to do it, then at least VERIFY the beacon result on
# web service like findu.com, or aprs.fi
#
#beacon file /tmp/wxbeacon.txt
#beacon srccall N0CALL-3 raw "!0000.00NR00000.00E&aprx - an Rx-only iGate"
#beacon srccall N0CALL-3 raw "!0000.00NI00000.00E&aprx - an iGate"
#beacon srccall $mycall symbol "R&" lat "0000.00N" lon "00000.00E" \
comment "aprx - an Rx-only iGate"
#beacon srccall $mycall symbol "I&" lat "0000.00N" lon "00000.00E" \
comment "aprx iGate"
</beacon>
# *********** <telemetry> definition(s) follow *********
#
# The system will always send telemetry for all of its interfaces
# to APRSIS, but there is an option to define telemetry to be sent
# to radio channel by using following sections for each transmitter
# that is wanted to send out the telemetry.
#
# transmitter - callsign referring to <interface>
# via - optional via-path, only 1 callsign!
# source - one or more of <interface> callsigns for which
# the telemetry transmission is wanted for
#
#<telemetry>
# transmitter $mycall
# via TRACE1-1
# source $mycall
#</telemetry>
# *********** <digipeater> definition(s) follow *********
#
# The digipeater definitions tell transmitters that receive
# AX.25 packets from possibly multiple sources, and then what
# to do on the AX.25 headers of those messages.
#
# There is one transmitter per digipeater -- and inversely, there
# can be at most one digipeater for each transmitter.
#
# In each digipeater there is at least one <source>, usually same
# as the transmitter.
#
#<digipeater>
# transmitter $mycall
# #ratelimit 60 120 # default: average 60 packets/minute,
# # burst max 120 packets/minute
# #srcratelimit 10 20 # Example: by sourcecall:
# # average 10 packets/minute,
# # burst max 20 packets/minute
#
# <source>
# source $mycall
# # ratelimit 60 120 # default: average 60 packets/minute,
# # # burst max 120 packets/minute
# # viscous-delay 0 # no viscous delay for RF->RF digipeat
# # ratelimit 120 # default: max 120 packets/minute
# </source>
#
# #<source> # Adding APRSIS source makes this tx-igate
# # source APRSIS
# # ratelimit 60 120 # default: average 60 packets/minute,
# # # burst max 120 packets/minute
# # relay-type third-party # Must define this for APRSIS source!
# # viscous-delay 5 # Recommendation: 5 seconds delay to give
# # # RF delivery time make itself known.
# # filter t/m # Tx-iGate only messages sent to me by APRSIS
# #</source>
#
#</digipeater>
GLOBAL MYCALL PARAMETER
In majority of usage models, system needs single configured callsign.
This is set by using the mycall configuration option, and latter
referred to in configurations as $mycall parameter in place of call-
signs.
GLOBAL MYLOC PARAMETER
Usually multiple beacons, and simple filter rules are wanted to be
using same reference coordinate for this system. This is set by using
the myloc configuration option, and latter referred to in configura-
tions as $myloc parameter in place of "lat nn lon mm" coordinate pair
of beacons.
APRSIS SECTION FOR APRSIS CONNECTIVITY
Settings in the <aprsis> section define connectivity with the APRS-IS
network service.
Necessary option is server, and others are optional.
Available options are:
login $mycall
The APRSIS network login. Defaults to the mycall configuration
entry.
passcode -1
Defining a small integer in range of 0 to 32767 authenticating
your login to APRS-IS server. Ask for assistance from your
APRS-IS managers, or calculate it yourself with aprspass pro-
gram. (Web search engines do find several of them.)
server server-name 14850
Define which APRS-IS is being connected to. Multiple defini-
tions are used in round-robin style, if the connection with the
previous one fails for some reason.
filter 'filter specs in quotes' # comments
Set filter adjunct definitions on APRS-IS server. Multiple
entries are catenated together in entry order, when connecting
to the server.
LOGGING SECTION
The <logging> section defines miscellaneous file names and options for
state tracking and logging use.
pidfile /var/run/aprx.pid
The pidfile is UNIX way to tell that others that this program
is running with given process-id number. This has compiled-in
default value of: pidfile /var/run/aprx.pid
rflog /var/log/aprx/aprx-rf.log
The rflog defines a rotatable file into which all RF-received
packets are logged. There is no default.
aprxlog /var/log/aprx/aprx.log
The aprxlog defines a rotatable file into which most important
events on APRS-IS connection are logged, namely connects and
disconnects. There is no default.
erlangfile /var/run/aprx.state
The erlangfile defines a mmap():able binary file, which stores
running sums of interfaces upon which the channel erlang esti-
mator runs, and collects data. Depending on the system, it may
be running on a filesystem that actually retains data over
reboots, or it may not. With this backing store, the system
does not loose cumulating erlang data over the current period,
if the restart is quick, and does not stradle any exact minute.
This file is around 0.7 MB per each interface talking APRS. If
this file is not defined and can not be created, internal non-
persistent in-memory storage will be used. Built-in default
value is: /var/run/aprx.state
erlang-loglevel NONE
The erlang-loglevel is config file edition of the "-l" option
pushing erlang data to syslog(3). Valid values are (possibly)
following: NONE, LOG_DAEMON, LOG_FTP, LOG_LPR, LOG_MAIL,
LOG_NEWS, LOG_USER, LOG_UUCP, LOG_LOCAL0, LOG_LOCAL1,
LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4, LOG_LOCAL5, LOG_LOCAL6,
LOG_LOCAL7. If the parameter value is not acceptable, list of
accepted values are printed at startup.
erlanglog /var/log/aprx/erlang.log
The erlanglog defines a rotatable file into which erlang data
is written in text form. There is no default.
erlang-log1min
The erlang-log1min option logs to syslog/file also 1 minute
interval data from the program. (In addition to 10m and 60m.)
Default is off.
INTERFACE SECTIONS FOR RADIO PORTS
The <interface> sections define connections to radio modems. Several
different styles are available:
• Local serial ports in the machine (device-serial /dev/ttyS0 speed
encapsulation)
• Local USB serial ports in the machine (device-serial /dev/ttyUSB0
speed encapsulation)
• Remote served serial ports over a TCP stream. Implemented to talk
with Cisco AUX ports on "range 4000" (TCP STREAM, no TELNET escapes)
(tcp-device 12.34.56.78 4001 encapsulation)
• Linux internal AX.25 network attached devices (ax25-device CALL-
SIGN-1) are only available when running on a Linux system. On a non-
Linux system it connects to a null interface, never getting anything
and can always sink everything.
The serial port name tells what kind of port is in question, and while
port baud-rate (9600) and character settings (8n1) must always be set,
they are ignored for the remote connection.
Following speed modes are available:
1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600,
115200, 230400, 460800, 500000, 576000
Likely available speeds are in bold, other supported values are listed
in italics.
Following encapsulation modes are available:
TNC2 is capable only to monitor the packets reported by TNC2 type
debug output, and Rx-iGate, but they are not acceptable as
source for a <digipeater>.
DPRS is special mode for gateway from D-STAR D-PRS to APRS. This
must always have a callsign definition for the gateway.
KISS Basic KISS encapsulation. No checksums. Will autodetect
(sometimes) packets with SMACK or FLEXNET characteristics.
SMACK Stuttgart Modified Amateurradio-CRC-KISS, which runs CRC-16
checksum on KISS datastream much in the same way as HDLC has
CCITT-CRC checksum on it.
FLEXNET FLEXNET which runs a CRC checksum of its own polynomial on
KISS datastream much in the same way as HDLC has CCITT-CRC
checksum on it.
BPQCRC XOR "checksum" on dataframes. Also known as "XKISS", and
"XORSUM". This detects single bit failure, but weakly any
multibit failures. Extra 0x00 bytes have no effect on check-
sum, etc.
On <kiss-subif tncid> sub-options the parameter is tncid, which sets up
KISS multiplexer parameter so that subsequent options applies only on
designated KISS sub-port.
The callsign option sets port specific callsign when relaying to APRS-
IS.
The telem-to-is true option can be used to disable (by explicitly set-
ting it to 'false') radio interface telemetry transmission to APRS-IS.
By default it is on. This is separate from <telemetry> sections, which
send telemetry to RF interfaces.
<interface>
serial-device /dev/ttyUSB1 19200 8n1 KISS
tx-ok false # receive only (default)
callsign OH2XYZ-R2 # KISS subif 0
initstring "...." # initstring option
timeout 900 # 900 seconds of no Rx
</interface>
<interface>
serial-device /dev/ttyUSB1 19200 8n1 SMACK
tx-ok false # receive only (default)
callsign OH2XYZ-R2 # KISS subif 0
initstring "...." # initstring option
timeout 900 # 900 seconds of no Rx
</interface>
<interface>
serial-device /dev/ttyUSB2 19200 8n1 KISS
initstring "...."
timeout 900 # 900 seconds of no Rx
<kiss-subif 0>
callsign OH2XYZ-2
tx-ok true # This is our transmitter
</kiss-subif>
<kiss-subif 1>
callsign OH2XYZ-R3 # This is receiver
tx-ok false # receive only (default)
</kiss-subif>
</interface>
<interface>
tcp-device 172.168.1.1 4001 KISS
tx-ok false # receive only (default)
callsign OH2XYZ-R4 # KISS subif 0
initstring "...." # initstring option
timeout 900 # 900 seconds of no Rx
</interface>
<interface>
ax25-device OH2XYZ-6 # Works only on Linux systems
tx-ok true # This is also transmitter
</interface>
<interface> # RX-IGATE ONLY, NOT USABLE AS DIGIPEATER SOURCE
serial-device /dev/ttyUSB1 19200 8n1 TNC2
callsign OH2XYZ-R6 # TNC2 has no sub-ports
initstring "...." # initstring option
timeout 900 # 900 seconds of no Rx
</interface>
BEACON DEFINITIONS
The beacons are defined using <beacon> configuration sections.
Because classical beacon definitions are highly error-prone, this pro-
gram has a new way to define them:
• The new way to define beacons:
beacon symbol "R&" lat "0000.00N" lon "00000.00E" \
comment "aprx - iGate"
• Semi-clasical definition of raw APRS packet:
beacon raw "!0000.00NR00000.00E&aprx - iGate"
• Load beacon text from a file, path data is configurable:
beacon file /path/to/file
• Run a program to produce beacon data in raw format:
beacon exec /path/to/file timeout 10
The fields and parameters:
interface An optional "interface" parameter tells that this beacon
shall be sent only to interface whose callsign is named.
Default is to send to all interfaces that have "tx-ok true"
setting.
type An optional one character string parameter, with one of
following contents: "!", "=", "/", "@", ";" and ")".
srccall An optional "srccall" parameter tells callsign which is
claimed as this particular beacon source. It must be valid
AX.25 callsign in text format. When this "srccall" parame-
ter is not given, value of "mycall" configuration entry is
used.
dstcall An optional "dstcall" parameter has built-in software ver-
sion dependent value, but it can be used to define another
value.
via An optional "via" parameter defaults to nothing, but can be
used to define additional "VIA" path tokens, for example:
"WIDE1-1".
item An optional "item" parameter is for defining a name for an
item type APRS packet.
object An optional "object" parameter is for defining a name for
an object type APRS packet.
symbol A mandatory "symbol" parameter is two character code, which
for Rx-only iGate is pair: "R&"
lat This mandatory parameter defines latitude coordinate (that
is: north/south.) It is expected to be of format:
"ddmm.mmN" where "dd" defines two digits of degrees of lat-
itude, and "mm.mm" defines two digits + decimal dot + two
digits of minutes of latitude. Then comes literal "N" or
"S" indicating hemisphere.
lon This mandatory parameter defines longitude coordinate (that
is: east/west.) It is expected to be of format:
"dddmm.mmE" where "ddd" defines three digits of degrees of
longitude, and "mm.mm" defines two digits + decimal dot +
two digits of minutes of longitude. Then comes literal "E"
or "W" indicating hemisphere.
comment This optional parameter defines commentary text tail on the
beacon packet. If you need characters outside US-ASCII
character set, use of UTF-8 encoded UNICODE character set
is recommended.
raw This alternate format defines whole APRS packet content in
raw text format. Currently this type of packets are not
validated for syntax at all!
file This alternative way defines path to a file with single
text line defining content of raw message data.
exec This alternative mode runs designated program, and waits
for at most a timeout number of seconds (default 10) for
the program to produce the result.
timeout This is optional parameter for exec allowing altered time-
out (number of seconds) for waiting the program to respond.
Default is 10 seconds.
The type/symbol/lat/lon/comment-format supports only a few types of
APRS packets. It splits input into small slices that are possible to
validate in detail. (See "DEBUGGING SYSTEM" above.)
RF-TELEMETRY
The aprx system will always send telemetry for all of its interfaces to
APRSIS, but there is an option to define telemetry to be sent to radio
channel by using following sections for each transmitter that is wanted
to send out the telemetry.
The parameters of <telemetry> configuration section are:
transmitter A mandatory callsign referring to an interface.
via An optional via-path parameter. Only 1 callsign!
source One or more of interface callsigns for which the telemetry
transmission is made.
DIGIPEATER
The aprx is possible to configure as a AX.25 digipeater with APRS
twists. This is done with <digipeater> configuration section and its
subsections.
There can be at most one <digipeater> definition per each transmit
capable interface in the system. On a system with multiple transmit-
ters, this means there can be multiple digipeaters, each with different
behaviour rules.
Minimalistic setup for a digipeater will be as follows:
<digipeater>
transmitter $mycall
<source>
source $mycall
</source>
</digipeater>
In minimalistic approach the system does digipeating of packets heard
on the $mycall interface back to same interface. Single requirement is
that the <interface> block has tx-ok true setting on it.
In more complicated approaches it is possible to define multiple
sources for packets:
• Multiple device ports.
• APRSIS pseudoport, which creates the Tx-iGate functionality.
<digipeater> options
Main-level <digipeater> options are:
• transmitter defines which interface the digipeater will output to.
• <trace> and <wide> sub-options are explained below.
• <source> sub-option is explained below.
<trace> and <wide> sub-options
The <trace> sub-option has priority over the <wide> sub-option, other-
wise they are configured the same way.
The <trace> sub-option defines which AX.25 address contained keywords
are treated with APRS "New-N paradigm" rules in a way where each pro-
cessing node always marks its transmitter callsign on the transmitted
AX.25 packet address header.
The <wide> sub-option defines which AX.25 address contained keywords
are treated with APRS "New-N paradigm" rules in a way where processing
node does not mark its transmitter callsign on the transmitted AX.25
packet address header.
Available parameters are:
keys A string of comma-separated set of string tokens:
keys "TRACE,WIDE"
Alternative form for this entry is:
keys "TRACE"
keys "WIDE"
maxdone Defines maximum number of redistribution hops that these key-
words can have completed when reaching here. If accounting
finds more done, the system will just drop the packet instead
of digipeating it onwards.
maxreq Defines maximum number of redistribution hops that these key-
words can define. If accounting finds more requested, the
system will just drop the packet instead of digipeating it
onwards.
<source> sub-options
Primary definer option is source which gives callsign of an <interface>
from which the AX.25 packets are received for this <source> block.
Available relay-type modes on <source> definitions are:
digipeater Normal AX.25 digipeater behaviour with APRS New-N para-
digm support. This is default mode.
directonly Digipeat only directly heard packets. Useful for systems
that are designated as "fill-in". See also "vis-
cous-delay".
third-party Special mode for Tx-iGate.
The ratelimit defines two parameters: average and limit number of pack-
ets sent in 60 seconds. Its definitions can be both in <digipeater>
and in digipeater's <source> sections, and therefore you can limit each
individual source to a max accepted rate as well as define separate
rate limits for the transmitter.
The viscous-delay defines a number of seconds from 0 (default) maximum
of 9 that the source will put the message on duplicate detector delay
processing. All occurrances of same packet per duplicate detector dur-
ing that time will be accounted on duplicate detection, and if at the
end of the delay period there are more than one hit, the packet is dis-
carded. Use delay of 0 seconds for normal digipeater, 5 seconds for a
fill-in, or a Tx-iGate.
A javAPRSSrvr filter-adjunct style rules are possible with the filter
options. When you want multiple filters, use multiple options with
associated parameters:
filter t/m # APRS messaging type packets
filter a/la/lo/la/lo # APRS positional packets within this area
Also negative filters are possible (prefixed with minus character),
which upon match cause rejection of the packet. Filters are evaluated
in definition order, and first matching one will terminate the evalua-
tion. When no filters are defined, everything is passed thru. When
any filter is defined, only those matching non-negative filters are
passed thru, and no default "pass everything else" behaviour exists.
Supported "adjunct filters" are following:
A/latN/lonW/latS/lonE
Area filter, defined as area enclosing within latS/latN and
lonW/lonE. Latitude and longitude are entered as degrees and
decimals.
B/call1/call2...
Budlist filter. Supports *-wildcards.
D/digi1/digi2...
Not supported at APRX internal filters
E/call1/call2/...
Not supported at APRX internal filters
F/call/dist_km
Great-circle distance in kilometers from friend's coordinates.
No wildcarding.
(TODO: check that it really works!)
M/dist The range around my location filter requires that you have
defined also the "myloc" configuration entry. It defines
acceptance of positions and messages with senders within dist
kilometers of the "myloc" position.
O/object1/obj2...
Object name filter. Supports *-wildcards.
P/aa/bb/cc...
Prefix filter.
Q/con/ana
The Q-construct filter is not supported.
R/lat/lon/dist
Range filter. Latitude and longitude are in degrees and deci-
mals. Distance is in kilometers. No wildcards.
S/pri/alt/over
Symbol filter
T/..../call/km
Type filter. Couple possible usages:
-t/c Everything except CWOP
t/*/OH2RDY/50 Everything within 50 km of OH2RDY's last
known position
Type code characters are:
* An "all" wild-card.
C A CWOP.
I An ITEM.
M A MESSAGE.
N A NWS message.
O An OBJECT.
Q A QUERY.
S A STATUS response.
T A TELEMETRY packet or parameter message.
U A USERDEF message.
W A WX data packet
U/unproto1/unproto2...
Filters by value in destination address field, supports wild-
card.
The <trace> and <wide> sub-options exist also within each <source>.
Where such occur, the <source> specific <trace> sub-option trumps the
definition on <digipeater> level, and same with <wide> sub-options.
This allows things like overriding flooding control keywords on source
basis, should such be necessary.
A set of regex-filter rules can be used to reject packets that are not
of approved kind. Available syntax is:
regex-filter source RE
source address field
regex-filter destination RE
destination address field
regex-filter via RE
any via path field
regex-filter data RE
payload content
The regex-filter exists as ad-hoc method when all else fails.
NOTES: ERLANG
The Erlang is telecom measurement of channel occupancy, and in this
application sense it does tell how much traffic there is on the radio
channel.
Most radio transmitters are not aware of all transmitters on channel,
and thus there can happen a collision causing loss of both messages.
The higher the channel activity, the more likely that collision is.
For further details, refer to statistical mathematics books, or perhaps
on Wikipedia.
In order to measure channel activity, the aprx program suite has these
built-in statistics counter and summary estimators.
The Erlag value that the estimators present are likely somewhat under-
estimating the true channel occupancy simply because it calculates
estimate of channel bit transmit rate, and thus a per-minute character
capacity. It does not know true frequency of bit-stuffing events of
the HDLC framing, nor each transmitter pre- and port frame PTT times.
The transmitters need to stabilize their transmit oscillators in many
cases, which may take up to around 500 ms! The counters are not aware
of this preamble-, nor postamble-times.
The HDLC bit stuffing ratio is guessed to be 1:1.025 (1 extra bit every
5 bytes)
NOTES: PROGRAM NAME
Initially this program had name aprsg-ng, which was too close to
another (a less low-tech C++ approach) program had.
BUGS/WARTS
The Erlang-monitor mechanisms are of rudimentary quality, and can seri-
ously underestimate the channel occupancy by ignoring pre- and postam-
ple transmissions, which can be as high as 50 centiseconds for pream-
ple, and 20 centiseconds for postample! When entire packet takes 50
centiseconds, such preample alone doubles channel occupancy. A 6pack
protocol on serial link (instead of KISS) could inform receiver better
on carrier presense times, however even that underestimates RF power
presense (RSSI) signal. (6pack is not supported.)
On serial lines supports really only 8n1 mode, not at all like: 7e1.
On the other hand, there really is no sensible usage for anything but
8n1...
SEE ALSO
Couple web sites:
http://www.aprs2.net/,
http://www.aprs-is.net/,
http://wiki.ham.fi/Aprx.en,
http://ham.zmailer.org/oh2mqk/aprx/aprx-manual.pdf
aprx-stat(8)
AUTHOR
This little piece was written by Matti Aarnio, OH2MQK during a dark and
rainy fall and winter of 2007-2008 after a number of discussions grum-
bling about current breed of available software for APRS iGate use in
Linux (or of any UNIX) platforms. Fall and winter 2009-2010 saw
appearance of digipeater functionality.
Principal contributors and test users include: Pentti Gronlund, OH3BK,
Reijo Hakala, OH1GWK. Debian packaging by Kimmo Jukarinen, OH3GNU.
Testing of SMACK variant of KISS by Patrick Hertenstein, DL1GHN. The
beacon exec functionality prototype by Kamil Palkowiski SQ8KFH.
2.08 - 2014 March 11 aprx(8)