APRS iGate properties

This document exists also in Finnish; Tästä dokumentista on myös suomenkielinen versio: APRS iGaten ominaisuudet

APRS iGate is an application that listens on APRS packets heard by the radio, and relays them to the APRS-IS network on the internet. There is also a possibility of bi-directional gatewaying of some frames from the APRS-IS network to the radio channel(s).

Typically the APRS iGate is not a APRS digipeater, rather a separate application. The iGate does however typically receive packets from the Digipeater in same machine.

For GW operators

APRS-IS connection

APRS-IS documentation on web: http://www.aprs-is.net/ , so called "Tier-2" APRS-network is on top of the APRS-IS network: http://www.aprs2.net/

Connection to APRS-IS in Finland is preferably done on one of following addresses:

1. igates.aprs.fi
2. finland.aprs2.net
3. rotate.aprs.net

list is given in decreasing order of preference.

Recommended port number in both cases is TCP/14580, which permits the user to define a filter to select what packets the APRS-IS will send to this APRS iGate for possible relaying to radio network(s).

Properties of RX-iGate

Anybody can implement an Rx-only iGate without any sort of licenses anywhere where the permitted radio amateur operations include APRS.

Having real callsign and passcode for the APRS-IS connection lets received packets to be relayed back to radio frequency, should it become necessary at some point, but that is not mandatory. That is, any uniqueue identifier in place of callsign will work, and '-1' is acceptable for passcode.

Such gateway can use simple rules listed below in the "for gw coders" part in order to drop away packets that must not be relayed to APRS-IS. Everything else they will always send to APRS-IS.

Properties of Rx/Tx-iGate

Transmitting iGate does need at least licensed radio amateur to be its owner and operator! Such may need also automated (transmitting)station permits.

First of all: APRS-IS→RF iGate's purpose is not to be publisher of its builder's ego, and jammer of the radio channel used by mobile stations.

Second of all: Typical ADSL link is about (or at least) 1000 times speedier, than the 1200 bps radio channel! Be very careful when doing transmitting iGate's!

Third of all: Powerful transmitter on high tower can be heard at surprising large area!

Jamming the radio channel is to be avoided at all cost, and therefore a bi-directional iGate needs following special properties in addition to what Rx-only iGate has:

1. Minimal distribution
2. Strict filtering
3. Channel busyness awareness
4. Backoff to keep away from radio when the channel keeps busy

Specifically:

• Do not use WIDEn-N at all, if possible, or use it with minimal (like WIDE1-1) redistribution.
  • If the iGate is located so that it can not be heard widely, defining VIA-path with nearest APRS-digipeater callsign is useful: OH1GW-15>APRS,OH1DIG-15
• Do not gate positions to radio channel that are more than 100 km away of your position.
• Do not gate non-position packets to radio channel if you have not heard position packet for the source in last 30 minutes ( = keep track of sources within your filter range )
  • If your software can not do this tracking, relay no non-position packets.
• Limit number of packets gated to radio channel so that your iGate will not be consuming more than about 20% of channel activity time in one and in five minute time periods.
  • If your software can not do this limiting, monitor its behaviour otherwise, and use other methods to limit the number of messages being relayed.

Beacons

At present (fall 2007) the APRS-IS network has sharp traffic spikes at every 10 minute mark, and lesser peaks at every 5 minute mark in between them. This is mainly because of some popular software do schedule various beacons at specific wall-clock times, and not e.g. randomly varying 7-9 minutes since previous beacon set. Also when there are multiple beacons to be sent, they should be evenly distributed on that interval, instead of being sent in a rapid burst. This applies both on beacons sent to APRS-IS, and sent directly over radio.

While original idea of beacons has been that there anybody arriving to area should receive full tactical awareness with listening the channel for 10 minutes, the time period should be prolonged at some places, and/or messages be prioritized so that on a busy channel some less important beacons are not sent at all.

For GW coders

APRS-IS connection

APRS-IS documentation on web: http://www.aprs-is.net/ , so called "Tier-2" APRS-network is on top of the APRS-IS network: http://www.aprs2.net/

Connection to APRS-IS in Finland is preferably done on one of following addresses:

1. igates.aprs.fi
2. finland.aprs2.net
3. rotate.aprs.net

list is given in decreasing order of preference.

In every cases, each time the connection is being formed, the name must be resolved to IP address(es), and no permanent caching of the address shall be used. There are multiple servers behind these names, and for load balance the connection must be done with carefully randomized address selection. (Some operating systems want to sort the addresses by some unknown criteria, or possibly cache the lookup results. Both are bad ideas in this application!)

Recommended port number in both cases is TCP/14580, which permits the user to define a filter to select what packets the APRS-IS will send to this APRS iGate for possible relaying to radio network(s).

After the formation of the TCP connection to APRS-IS server, the login procedure is:

user <iGate-callsign> pass <passcode>

Giving software version:

user <iGate-callsign> pass <passcode> vers <program_name_and_version_text>

With a filter (not needed in receive-only iGate):

user <callsign> pass <passcode> vers <version> filter <filter_specifiers>

For example:

user OH9XYZ-13 pass 12944 vers mysoft 0.0.1 filter a/72/16/58/34 p/OF/OG/OH/OI/OJ

• This validation procedure is described at page: http://www.aprs-is.net/ServerCmds.htm
• Filters are explained at page: http://www.aprs-is.net/javAPRSSrvr/javaprsfilter.htm
• Passcode calculation is not explained in any public document, only in source-codes of some programs...

In network traffic from APRS-IS to iGate, the protocol is "line oriented text", and lines beginning with "#"-character are comments, heartbeat, etc. line noise without predefined form. They can be ignored, but they are useful for observing connection being alive.

At any given time there must be only one TCP connection to APRS-IS network servers (no connections to multiple servers, nor multiple connections to same server), but it is useful to monitor line health (with possible heartbeat, for example), and when necessary, close pre-existing connection and initiate a new one.

Even when radio networks have no local APRS events, aforementioned APRS-IS system use javAPRSSrvr software, which chimes "heartbeats" to each TCP connection about every 20 seconds. If a monitored TCP connection has not received anything for 120 seconds, connection close and reconnect are in order. The iGate should then detect and recover internet connectivity problems in timely fashion.

Note: Not all APRS-IS server software supply such heartbeat at all!

Other means for similar approach is to use filter to request wider area object feed, and just hope for the best that there won't ever be prolonged silent period. (This can be used even for receive-only iGates, that otherwise discard everything that the APRS-IS server tells.)

Third way would be to use operating system level functions, like TCP-Keepalive, however its reactive time scale is in 30-90 minutes, which may be far too long.

If connection formation fails, it is generally not a good idea to try immediately again, but rather try some 15-30 seconds before next attempt. This will avoid program spinning very fast in place, when connection setup failure is fast.

Properties of RX-iGate

Creators of the APRS-IS system wrote a Gating criteria, here the issue is being elaborated a bit more.

All packets sent to APRS-IS network are text lines ending with CR/LF character pair. If the packet received from radio has CR or LF characters, the packet is to be cut at first such character, and always a CF/LF pair is appended for transmission to the APRS-IS.

All packets received from radio are to be relayed to APRS-IS as is with a few exceptions:

• (note the possibility for zero-bytes in packets! although most C-codes do not support them in reality!)
• All packet headers are to be converted into so called TNC2-form (KISS frames, and PK232 format), which is:
  SOURCE-1>DESTIN-2,PATH*,PATH2:payload_data_content.
  • If the packet does not have VIA fields, it will simplify into:
    SOURCE-5>DESTIN-6:payload_data_content.
  • If SSID is zero, it will not be presented in text format (no DESTIN-0).
  • A star following the SSID value denotes "has-been-digipeated" bit being set, and it must be preserved exactly as it was received from radio.
• Packets with VIA-path containing TCPIP, or TCPXX shall not be relayed to APRS-IS.
• Packets with VIA-path containing RFONLY or NOGATE shall not be relayed to APRS-IS.
  • Usage of these keywords can limit the packet to either the APRS-IS network, or the radio network
• Packets with data content beginning with character '}' (ASCII code 125) are so called 3rd-party frames, and can be multiply nested:
  • ADDR>ADDR:}ADDR2>ADDR2:}ADDR3>ADDR3:data
  • The packet is reprocessed from following the payload leading '}' character following all rules listed above.
• Packets with data beginning with character '?' (so called generic query) shall not be relayed to APRS-IS.
• Packets being relayed to APRS-IS network get ",qAR,IGATECALL-SSID" appended to outermost address before first ':' character.
• Advanced iGate may also monitor recently received packets from both the radio, and from APRS-IS, and determine when a packet has already been received "very recently", and not to relay such. A possible mechanism for such duplicate detection is below.

Properties of RX/TX-iGate

First of all: APRS-IS→RF iGate's purpose is not to be publisher of its builder's ego, and jammer of the radio channel used by mobile stations.

Creators of the APRS-IS system wrote a Gating criteria, here the issue is being elaborated a bit more.

Jamming the channel is to be avoided at all cost, and therefore a bi-directional iGate needs following special properties in addition to what Rx-only iGate has:

Effective filtering of traffic to be relayed from the internet to the radio channel:

• Packets with ",qAX," in outermost path are not to be relayed to radio — "sender of this packet has not identified itself with proper pass-code to APRS-IS, and therefore is possibly not licensed radio amateur."
  • Possibly other Q Construct codes also forbid the relaying.
  • However not all APRS-IS systems produce those qAX-codes, while they do produce TCPXX VIA-field in same situations.
• Not relaying to radio packets that have been heard from radio or been relayed to radio within last 60 seconds (see the duplicate detection above)
• Not relaying to radio any packets that are far from iGate local area
  • Using area-filters: only stations within 50 km, not from further away! (In very low traffic areas possibly 100 or 200 km)
  • Not using prefix-filters! Not all OH-stations!
• Primarily relaying only packets with positional data
• APRS Messaging packet passing is more complicated issue...
• Using minimum possible paths for relayed packets, preferrably only "WIDE" (alias WIDE1-1).
  • For example a WIDE2-2 at Jyväskylä does flood the traffic (with a little bit of 2m tropo) from Helsinki to Oulu (whole southern half of Finland)
• Not relaying to radio packets with VIA-path having any of: TCPXX, NOGATE, or RFONLY (Note: TCPIP is permitted!)
• After all other filters, limiting the number of transmitted packets to something sensible per 60 seconds interval. This is a fail-safe to prevent radio channel from being jammed by the packet transmits.
• Alternative approach is to monitor radio channel signal activity (from RSSI of radio + own transmits), and if it exceeds some treshold, limiting own transmits: 1 minute window permits total activity seconds to be up to 50%, as long as simultaneous 5 minute window has accumulated usage level below 33%.

Packets from the APRS-IS to radio are to be relayed in so called "3rd party" format.

For example iGaten OH4ZZZ-5 relays a packet:

"OH2XYZ-11>APZYXW-4,RELAY*,WIDE,qAR,OH1YYY-3:>packet  "

reformats it like this for transmit to radio:

"OH4ZZZ-5>APZ123,WIDE2-2:}OH2XYZ-11>APZYXW-4,TCPIP,OH4ZZZ-5*:>packet  "

where APX123 is a destination address used by the iGate software, WIDE2-2 is path that is being used, and OH4ZZZ-5 is iGate's callsign, which is repeated both in AX.25 header, and within packet content. The TCPIP within the "inner" packet path tells, that it came from APRS-IS. The original via-path of the packet is discarded in order to shrink the packet.

Duplicate detection

In order that the iGate shall not unnecessarily relay packets (to radio in particular), it can have an in-memory collection of recently received packets, and compare that to new candidate packet.

Duplicate detection picks following bits off the packet:

• innermost AX.25 source address with SSID value (and without the VIA-path)
• innermost AX.25 destination address without SSID value
• datafield content with possible trailing CR, LF and whitespace characters removed

If same packet is seen within 30-60 seconds, it need not to be relayed again.

This comparison can be done with a checksum tracking to reduce memory requirements. A good quality checksum function produces low number of collisions in between dissimilar packets, algorithm selection is left for implementers choice. (Note: 60 seconds by 140 bytes/sec = 8400 bytes, which is infinitesimal memory amount in an embedded computer that can talk via TCP/IP to the internet, thus possibly the comparison is to be done against a "comparison copy" and not a checksum.)

Every packet is always relayed without altering the number of whitespace characters at its tail.

Example: Following packets produce same comparison/checksum:

"OH2XYZ-11>APZYXW:>packet"
"OH2XYZ-11>APZYXW-4,RELAY,WIDE:>packet  "
"OH1YYY>APRS,WIDE:}OH2XYZ-11>APZYXW-4,TCPIP,OH1YYY*:>packet  "

Beacons

At present (fall 2007) the APRS-IS network has sharp traffic spikes at every 10 minute mark, and lesser peaks at every 5 minute mark in between them. This is mainly because of some popular software do schedule various beacons at specific wall-clock times, and not e.g. randomly varying 7-9 minutes since previous beacon set. Also when there are multiple beacons to be sent, they should be evenly distributed on that interval, instead of being sent in a rapid burst. This applies both on beacons sent to APRS-IS, and sent directly over radio.

While original idea of beacons has been that there anybody arriving to area should receive full tactical awareness with listening the channel for 10 minutes, the time period should be prolonged at some places, and/or messages be prioritized so that on a busy channel some less important beacons are not sent at all.

February 2008: The APRS-IS core overload every 5 minutes appears to be due to CWOP (Citizens Weather Observer Program) whose windows software is pushing measurement data in every 5 minutes at precise minute, and most of those windows machines are in NTP time sync, so it really hits core network hard. To add insult on the injury, that software is also ignoring the directive of "re-resolve and randomize server IP addresses every time doing reconnect".