Tuesday, May 9, 2017

Important Hints to iGate developers

By connorgoodwolf - Own work, CC BY-SA 4.0
There are a lot of APRS iGate implementations out there, and new ones are popping up every few months these days. A lot of the new ones are made for various microcontroller chips and development boards (Arduino, ESP8266 and friends). Some are made for SDR sticks, some are built in mobile phone applications. Many of them reduce the amount of hardware needed to run an iGate by fully removing the need for a TNC, a full-blown computer, or an actual amateur radio transceiver.

Very cool stuff!

It would seem like writing an iGate would be very easy: receive packets off the air, put them in TNC2 format, and pass them to the APRS-IS servers over TCP (specifications: connecting, design, details). But it turns out that there are quite a few things that can go wrong in the implementation, and in fact, some things seem to be going wrong the same way fairly often. Some bugs are fairly common and some seem to pop up in multiple different iGates, old and new.

Currently the most popular ones are due to the false assumption that all packets are either plain 7-bit English ASCII text with no NUL bytes or other binary stuff, or some specific Unicode encoding such as UTF-8. These assumptions lead to the packets getting truncated at the first NUL (binary 0) byte, or otherwise modified in a way that scändic and øthér ïnternátiønal characters get mutilated if they don't happen to use the same encoding. Sometimes a truncation of a packet at the first NUL may lead to the packet being concatenated together with the next packet.

I get to decode the corrupted packets on aprs.fi, and I also get to process the corrupted ones in the aprsc APRS-IS server software which is fairly common these days. If the bugged packets are not detected and handled, there usually are some folks complaining to me about the odd results, since they are often received from aprsc and viewed on aprs.fi.

I can't blame the authors of the new applications – I have to admit that APRS documentation is not great, and it's easy to stumble across the same bugs if you haven't fixed them once before.

Every now and then I spend an evening trying to identify some of these bugs in the APRS-IS client applications and file bug tickets to the software authors. Last night I filed 3 packet corruption bug reports on Github for 3 different iGate applications. These are not the first ones, I've probably filed 30 in the past. It's not hard to spot these once you know what to look for.

I'd like to take this chance to thank to all the authors who fix the bugs in a timely manner and release the fixed versions!

Based on this experience I wrote a little document listing common iGate bugs: IGATE-HINTS.md. It'd be great if all APRS software authors could glance through it and make sure these bugs are not present in their own software. If you spot someone writing a new iGate, please pass on the link to the new author – hopefully these bugs will then be avoided right from the beginning.

Unfortunately some buggy iGate applications are orphaned and no longer developed. A few of those applications are fairly popular, too. It'd be great for the network if iGate operators could gradually upgrade to applications which still get updates, and don't exhibit any of the packet-corrupting bugs.

A lot of iGates are also not getting updated, even though they run software which would have updates available. Some iGate operators feel that the iGates work, sort of, since most packets go through them just fine, most of the time. I think I'll try to make aprs.fi highlight some of the more common issues on the station info page in the future.

If you know a little Python or C, and you've got a little extra time, let me know – there are some bugs out there in the Open Source Land which could use a helping hand.