Read the APRS channel: who is out there, and what they said

A third section, alongside the aircraft and the weather sensors, and for the
same reason as both: a scan stops on a signal, records it and moves on, while
APRS is a two-second transmission every few minutes from a hundred stations
sharing one frequency.  A sweep catches whichever happened to key up as it
passed.  `bandsaunter aprs` parks on the channel and catches all of them;
`bandsaunter packets` reads a log back.

Four layers, three of them new.

The link layer was already here, opportunistically, in the generic decoder --
a correlator, NRZI, HDLC and a checksum, run on whatever a scan happened to
record.  It is now a receiver.  What had to change is the state that survives
a block boundary: the tail of the audio so the correlators see no edge, the
phase of the sampling loop so a bit is not lost where one block meets the
next, the tone the line was last at, and the bits themselves.  A packet is
most of a second and a block is about one, so frames straddling the boundary
are not an edge case, they are most of them.

Above that, the APRS information field, which is not one format but about
twenty, chosen by the first character and accreted over thirty years.
Positions uncompressed and compressed; Mic-E, which every Kenwood and Yaesu
mobile sends and which hides the latitude inside the destination callsign
because in 1995 those six bytes were carrying the word "APRS" and nothing
else; weather with a position and without; messages, acknowledgements,
rejections and bulletins; objects and items; status; telemetry; third-party
traffic, credited to whoever originally sent it rather than to the gateway.
Course and speed, altitude, power and antenna height, range and the precision
extension, all of which ride in the comment.  Every one has a writer beside
its reader, so a packet goes in and the same packet comes out.

Above that the section: a registry of who is out there and what each last
said of each kind, distances and bearings from --at, a log keeping the whole
frame under whatever was made of it, a spreadsheet, a map, and a channel full
of stations that are not there for --simulate.

One rule is worth naming because it is the difference between a decoder and a
liar.  A packet whose format does not match what its first character promised
comes back as unparsed with its text intact.  Thirteen characters of a
*malformed* uncompressed position are perfectly good base-91, so trying one
format and falling back to the other does not fail on a bad packet -- it
succeeds, as a confident and completely different place, usually a thousand
miles away.  The specification makes the two unambiguous, a leading digit
always meaning uncompressed, and the rule is read rather than guessed at.

Two faults found by building it, both by measurement rather than by reading
the code again.  The framer handed back frames it had already reported,
because it trimmed its buffer to before them rather than after -- every packet
counted twice, for ever, which only shows up once the same signal is read
across more than one block.  And the invented channel truncated a
transmission at the end of the block it began in rather than carrying the
remainder over, which was invisible for as long as the simulated clock
advanced in exact seconds and put every transmission at a block boundary; the
moment it was paced against a real clock, nothing decoded at all.

204 new tests against seven deliberately broken builds, one of which survived
until a test was written for the case it actually breaks.  Full suite 2597
passed.  Built as 2026-09-20_02.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016PsWPTweCT6pwxKngvVxcg

INSTALL.md

@@ -10,9 +10,10 @@ If you are on Debian, Ubuntu or Mint, [build the package](#a-debian-ubuntu-mint-
 
 **You can try the whole program before buying or plugging in a receiver.**
 `--simulate` runs the scanner against a synthetic band, `bandsaunter adsb
---simulate` flies imaginary aircraft past an imaginary receiver, and
-`bandsaunter weather --simulate` puts six weather sensors on a fence that does
-not exist. None of the three needs
+--simulate` flies imaginary aircraft past an imaginary receiver, `bandsaunter
+weather --simulate` puts six weather sensors on a fence that does not exist,
+and `bandsaunter aprs --simulate` fills a channel with amateur stations that
+are not there. None of the four needs
 hardware or a network.
 
 ---
@@ -120,6 +121,8 @@ bandsaunter adsb --simulate --seconds 30
 bandsaunter flights                # draws what the last command heard
 bandsaunter weather --simulate --seconds 60
 bandsaunter readings --csv         # turns what it heard into a spreadsheet
+bandsaunter aprs --simulate --seconds 120
+bandsaunter packets --kml          # turns what it heard into a map
 ```
 
 With a receiver plugged in:
@@ -229,6 +232,13 @@ read the output. `--save-iq FILE` keeps the raw samples (2 MB a second, so
 bound it with `--seconds 60`) and `--from-iq FILE` reads one back, so a
 recording made where the aerial is can be worked on anywhere.
 
+**APRS needs nothing extra either** — no network, no key, no package beyond
+the table above. The only thing that decides whether you hear it is the aerial
+and whether a digipeater is in range: a quarter-wave whip for 144 MHz is 49 cm,
+which is longer than the one most dongles ship with. Check `--region` before
+anything else, because on the wrong channel there is silence rather than a bad
+signal. `bandsaunter aprs --simulate` runs the whole thing without an aerial.
+
 **Aircraft and callsign lookups need no installation**, only a network. They
 ask public registers about a callsign or a 24-bit address and cache the
 answers for a month; `--no-lookup` turns them off, and what the address and