dustcouncil/bandsaunter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Listen to FT8: fifteen seconds of everybody at once

Browse source 
A new section, alongside the aircraft, the weather sensors and APRS.

FT8 is the odd one out among the things this program listens to, and the
reason is worth stating because it shapes everything below.  Every station on
the band transmits in the same quarter-minute slots, on the same dial
frequency, fifty hertz wide each, stacked across three kilohertz of audio.
One receiver parked on one frequency therefore hears the whole band's worth of
stations at once -- and hears most of them well below the noise, because half
of what is sent is error-correcting code.  That is the entire trick: a rate of
about one half buys a mode that decodes twenty-odd decibels under what an
operator can hear.  A receiver that took the loudest tone of each symbol and
hoped would decode almost nothing, which is why the tone detector reports how
confident it is bit by bit rather than what it thinks it heard.

Written from first principles except for two tables.  The checksum, the
belief propagation over the sparse graph, the Costas sync search, the
waterfall, the soft-bit metric, and the seventy-seven bits that hold two
callsigns and a grid square are all here.  The generator and the parity-check
matrix are not: they cannot be derived, being the code itself rather than
consequences of anything, so they are taken from ft8_lib under its MIT licence
with the attribution it asks for, and said so in the readme, the manual and
the file.  No decoding logic came with them.  That the two agree -- and they
are not derivable from one another, the generator's parity half running to
fifty-odd bits a row against the sparse matrix's six or seven -- is a test
rather than an assumption.

Tested against the air, not against itself.  Eleven off-air recordings with
published decodes: ninety-seven of a hundred and fifty messages, no false
decodes, timing within a hundredth of a second, frequency within a hertz,
signal reports within half a decibel on average.  The third not decoded are
the weakest in each slot; a mature decoder subtracts what it has decoded and
looks again in the remainder, and does ordered-statistics decoding where
belief propagation fails, and neither is built here.  What is here decodes
nothing that other receivers did not also hear, which is the property that
matters in a log.  Ten whole codewords lifted off the air are in the tests as
a permanent fixture, so the recordings can go missing and the regression
cannot.

Three things that looked like bugs and were not, and three that were.  The
half-second timing discrepancy was the convention: a transmission is 12.64
seconds in a slot of fifteen and everybody starts half a second in, so
lateness is reported against that.  Synthetic signals at known offsets proved
the clock self-consistent before anything was changed.  The signal reports
were twenty-one decibels optimistic because those recordings have a receiver
passband above three kilohertz, putting a whole-band median twelve to sixteen
decibels below the real noise floor -- so noise is now measured beside the
signal, and in the tone that was actually sent rather than the loudest of
eight, the largest of eight noisy numbers being well above their mean even
with no signal at all.  And the test transmitter was thirteen decibels
pessimistic, scaling its noise into a fifty-hertz reference instead of the
sampled bandwidth, which made the decoder look deaf when it was the test
signal that had been quietly attenuated.

The real bug the simulator caught was a one-block timestamp error: samples
were dated a block earlier than they were taken, which slid every slot slice a
second late and cut the first half-second -- three symbols, part of the
opening Costas array -- off every transmission on the band.  One decode a slot
became six.

Reachable both ways, as everything here is.  Twenty-one options, every one of
them a command-line flag and a line in the menu, both built from one table so
they cannot disagree -- and a test that says so, since an option in no group
would be settable from the command line and invisible in the menu.  The band
list says which channels a plain dongle can reach and which need an
upconverter, because almost all the activity is on shortwave and finding that
out by listening to silence for ten minutes is the wrong way to learn it.  The
default is two metres, which a plain dongle can hear.

--grid turns decodes into geography: every CQ says where it is, so each gets a
distance and a bearing and the furthest is named.  --adif writes the log in
the form every amateur logging program imports, marked as heard rather than
worked, because nothing here transmits and an ADIF that let a logging program
treat these as contacts would put claims into somebody's log that they cannot
make.

One bug shipped and found by being used rather than by being tested: the
line that opens the receiver called a function this program has never had.
Every test reached it through the simulator, which takes the other branch, so
the one line that matters to somebody with an aerial was the one line never
run.  There is now a check that every name these modules import actually
exists -- it names the missing one rather than failing somewhere downstream --
and two that say a receiver which cannot be opened is reported rather than
raised, and that nothing claims to be listening before there is one.  It had
been announcing the frequency first, so a dongle that would not open read as
listening that had gone wrong.

Ninety-six new tests.  Full suite 2781 passed.  Built as 2026-09-21_04.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016PsWPTweCT6pwxKngvVxcg
This commit is contained in:
The Dust Council 2026-09-21 16:09:57 -07:00
parent e203b3e581
commit 93120b80a6
14 changed files with 4247 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

202
packaging/bandsaunter.1
View file

@ -1,5 +1,5 @@
.\" Generated by packaging/make-man.py -- do not edit by hand.
.TH BANDSAUNTER 1 "2026-09-21" "bandsaunter 2026-09-21_03" "User Commands"
.TH BANDSAUNTER 1 "2026-09-21" "bandsaunter 2026-09-21_04" "User Commands"
.SH NAME
bandsaunter \- scan, record and identify radio signals with an RTL-SDR
.SH SYNOPSIS
@ -2958,6 +2958,196 @@ Also write a map \[em] write the stations and their tracks for Google Earth.
.br
Setting name \fBkml\fR, default \fBno\fR.
.PP
.SH FT8
Fifteen seconds of everybody at once. Every station on the band transmits in
the same quarter-minute slots, on the same dial frequency, fifty hertz wide
each, stacked across three kilohertz of audio \[em] so one receiver parked on
one frequency hears the whole band's worth of stations at the same time, and
hears most of them well below the noise.
.PP
Half of what is transmitted is error-correcting code, and that is the trick:
it is what buys a mode that decodes twenty-odd decibels under what an operator
can hear. A receiver that took the loudest tone of each symbol and hoped would
decode almost nothing, which is why the tone detector reports how confident it
is bit by bit rather than what it thinks it heard.
.SS What it needs
The clock has to be right to a second or two. The slots are quarter-minutes of
UTC and every station on earth agrees about which one it is. A receiver a
second out still decodes; one a slot out hears every transmission split across
two captures and decodes none of them. This is the one failure that looks
exactly like a dead band, so the display and the report both say so when
nothing arrives.
.PP
Almost all the activity is on shortwave, which a plain receiver of this kind
cannot reach. The default is therefore the two-metre channel at 144.174 MHz,
which it can. All thirteen channels are in the list and the shortwave ones
work through an upconverter or a receiver in direct sampling mode; the menu
says which is which rather than leaving somebody to find out by listening to
silence.
.SS What comes out
.BI \-\-grid " SQUARE"
is what turns decodes into geography: every station calling CQ says where it
is, so with your own square filled in each gets a distance and a bearing and
the furthest heard is named. Three tables afterwards \[em] stations heard,
calling CQ, and who was working whom.
.PP
.B \-\-adif
writes the log again in the form every amateur logging program imports,
marked as heard rather than worked. Nothing here transmits, so nothing here is
a contact, and an ADIF that let a logging program treat these as worked would
put claims into somebody's log that they cannot make.
.SS How well it works
Checked against eleven off-air recordings with published decodes, which is the
only honest way to test a decoder: an encoder tested against its own decoder
agrees with it about anything they are both wrong about. Ninety-seven of a
hundred and fifty messages, with no false decodes; timing within a hundredth
of a second, frequency within a hertz, signal reports within half a decibel on
average. The third not decoded are the weakest in each slot: a mature decoder
subtracts what it has decoded and looks again in the remainder, which is not
built here.
.SH FT8 OPTIONS
Every option the FT8 side takes, in the five groups the menu shows them in.
Each is a flag here and a line in the menu, and both come from one table in
the program, so they cannot disagree.
.SS Receiver
.TP
.B --device
Receiver \[em] which receiver to use, when more than one is plugged in.
.br
Setting name \fBdevice\fR, default \fB0\fR.
.br
Accepts: at least 0.
.TP
.B --gain
Gain \[em] tuner gain in dB, or automatic.
.br
Setting name \fBgain\fR, default \fBauto\fR.
.TP
.B --rate
Sample rate \[em] how fast to sample; 96 kS/s is the least that holds the channel (Hz).
.br
Setting name \fBrate\fR, default \fB240 kHz\fR.
.br
Accepts: at least 96000.
.TP
.B --band
Band \[em] which FT8 channel to listen on.
.br
Setting name \fBband\fR, default \fB2m\fR.
.br
Accepts: one of: 160m, 80m, 60m, 40m, 30m, 20m, 17m, 15m, 12m, 10m, 6m, 2m, 70cm.
.TP
.B --frequency --freq
Dial frequency \[em] the dial frequency, if you want one the band list does not have (Hz).
.br
Setting name \fBfrequency\fR, default \fB144.174 MHz\fR.
.br
Accepts: at least 100000, at most 2e+09.
.TP
.B --simulate / --no-simulate
Simulate \[em] invent a band instead of using a receiver.
.br
Setting name \fBsimulate\fR, default \fBno\fR.
.PP
.SS Listening
.TP
.B --seconds
Listen for \[em] how long to listen; zero means until stopped (s).
.br
Setting name \fBseconds\fR, default \fBuntil stopped\fR.
.br
Accepts: at least 0.
.TP
.B --slots
Or this many slots \[em] stop after this many fifteen-second slots; zero means no limit.
.br
Setting name \fBslots\fR, default \fBno limit\fR.
.br
Accepts: at least 0.
.TP
.B --log / --no-log
Write a log \[em] keep every decode in a file.
.br
Setting name \fBlog\fR, default \fByes\fR.
.TP
.B --decodes-seen / --no-decodes-seen
Print each decode \[em] a line per decode instead of a table that refreshes.
.br
Setting name \fBdecodes_seen\fR, default \fBno\fR.
.TP
.B --hold
Keep on display for \[em] how long a station stays on the table after its last decode (s).
.br
Setting name \fBhold\fR, default \fB3600 s\fR.
.br
Accepts: at least 1.
.PP
.SS Decoding
.TP
.B --lowest
Search from \[em] the lowest audio frequency to look for signals at (Hz).
.br
Setting name \fBlowest\fR, default \fB200 Hz\fR.
.br
Accepts: at least 0.
.TP
.B --highest
Search to \[em] the highest audio frequency to look for signals at (Hz).
.br
Setting name \fBhighest\fR, default \fB3 kHz\fR.
.br
Accepts: at least 100.
.TP
.B --most
Candidates per slot \[em] how many possible transmissions to try to decode each slot.
.br
Setting name \fBmost\fR, default \fB300\fR.
.br
Accepts: at least 1.
.TP
.B --rounds
Repair passes \[em] how many passes of error correction to make before giving up.
.br
Setting name \fBrounds\fR, default \fB30\fR.
.br
Accepts: at least 1.
.PP
.SS Showing
.TP
.B --grid
Aerial at \[em] your own grid square, so distances can be worked out.
.br
Setting name \fBgrid\fR, default \fBnot set, so no distances\fR.
.TP
.B --units
Show readings in \[em] metric or imperial, for the display and the export.
.br
Setting name \fBunits\fR, default \fBmetric\fR.
.br
Accepts: one of: metric, imperial.
.TP
.B --calls-only / --no-calls-only
Callsigns only \[em] leave out free text and telemetry.
.br
Setting name \fBcalls_only\fR, default \fBno\fR.
.PP
.SS Afterwards
.TP
.B --report / --no-report
Report at the end \[em] print the tables when the listening stops.
.br
Setting name \fBreport\fR, default \fByes\fR.
.TP
.B --csv / --no-csv
Also write a CSV \[em] a spreadsheet of every decode beside the log.
.br
Setting name \fBcsv\fR, default \fBno\fR.
.TP
.B --adif / --no-adif
Also write an ADIF \[em] the log again, in the form logging programs read.
.br
Setting name \fBadif\fR, default \fBno\fR.
.PP
.SH FILES
.TP
.I ~/.config/bandsaunter/config.yaml
@ -3090,6 +3280,16 @@ terms, in
or at
.UR https://www.gnu.org/licenses/
.UE .
.PP
One file is not original work.
.I ft8tables.py
holds the two fixed tables that define the FT8 error-correcting code, taken
from ft8_lib (https://github.com/kgoba/ft8_lib), MIT licensed, copyright 2018
K\[u0101]rlis Goba, which took them in turn from WSJT\-X. They are reproduced
under the MIT terms and that file carries the attribution they ask for. They
are there because they cannot be derived: everything else about FT8 here is
worked out from first principles, but those two tables are the code itself,
chosen once by its designers and published. No decoding logic was taken.
.SH BUGS
The DVB-T television driver claims these dongles on sight. If the receiver
cannot be opened, that is almost always why: the package blacklists the

70
packaging/make-man.py
View file

@ -77,6 +77,13 @@ def aprs_section() -> list[str]:
return options_section(ap)
def ft8_section() -> list[str]:
"""Every FT8 option, from the same table again."""
from bandsaunter import ft8
return options_section(ft8)
def options_section(air) -> list[str]:
"""One section's options, written out from the table the program uses.
@ -1792,6 +1799,58 @@ Every option the APRS side takes, in the four groups the menu shows them in.
Each is a flag here and a line in the menu, and both come from one table in
the program, so they cannot disagree.
.APRS_OPTIONS_HERE
.SH FT8
Fifteen seconds of everybody at once. Every station on the band transmits in
the same quarter-minute slots, on the same dial frequency, fifty hertz wide
each, stacked across three kilohertz of audio \[em] so one receiver parked on
one frequency hears the whole band's worth of stations at the same time, and
hears most of them well below the noise.
.PP
Half of what is transmitted is error-correcting code, and that is the trick:
it is what buys a mode that decodes twenty-odd decibels under what an operator
can hear. A receiver that took the loudest tone of each symbol and hoped would
decode almost nothing, which is why the tone detector reports how confident it
is bit by bit rather than what it thinks it heard.
.SS What it needs
The clock has to be right to a second or two. The slots are quarter-minutes of
UTC and every station on earth agrees about which one it is. A receiver a
second out still decodes; one a slot out hears every transmission split across
two captures and decodes none of them. This is the one failure that looks
exactly like a dead band, so the display and the report both say so when
nothing arrives.
.PP
Almost all the activity is on shortwave, which a plain receiver of this kind
cannot reach. The default is therefore the two-metre channel at 144.174 MHz,
which it can. All thirteen channels are in the list and the shortwave ones
work through an upconverter or a receiver in direct sampling mode; the menu
says which is which rather than leaving somebody to find out by listening to
silence.
.SS What comes out
.BI \-\-grid " SQUARE"
is what turns decodes into geography: every station calling CQ says where it
is, so with your own square filled in each gets a distance and a bearing and
the furthest heard is named. Three tables afterwards \[em] stations heard,
calling CQ, and who was working whom.
.PP
.B \-\-adif
writes the log again in the form every amateur logging program imports,
marked as heard rather than worked. Nothing here transmits, so nothing here is
a contact, and an ADIF that let a logging program treat these as worked would
put claims into somebody's log that they cannot make.
.SS How well it works
Checked against eleven off-air recordings with published decodes, which is the
only honest way to test a decoder: an encoder tested against its own decoder
agrees with it about anything they are both wrong about. Ninety-seven of a
hundred and fifty messages, with no false decodes; timing within a hundredth
of a second, frequency within a hertz, signal reports within half a decibel on
average. The third not decoded are the weakest in each slot: a mature decoder
subtracts what it has decoded and looks again in the remainder, which is not
built here.
.SH FT8 OPTIONS
Every option the FT8 side takes, in the five groups the menu shows them in.
Each is a flag here and a line in the menu, and both come from one table in
the program, so they cannot disagree.
.FT8_OPTIONS_HERE
.SH FILES
.TP
.I ~/.config/bandsaunter/config.yaml
@ -1924,6 +1983,16 @@ terms, in
or at
.UR https://www.gnu.org/licenses/
.UE .
.PP
One file is not original work.
.I ft8tables.py
holds the two fixed tables that define the FT8 error-correcting code, taken
from ft8_lib (https://github.com/kgoba/ft8_lib), MIT licensed, copyright 2018
K\[u0101]rlis Goba, which took them in turn from WSJT\-X. They are reproduced
under the MIT terms and that file carries the attribution they ask for. They
are there because they cannot be derived: everything else about FT8 here is
worked out from first principles, but those two tables are the code itself,
chosen once by its designers and published. No decoding logic was taken.
.SH BUGS
The DVB-T television driver claims these dongles on sight. If the receiver
cannot be opened, that is almost always why: the package blacklists the
@ -1944,6 +2013,7 @@ def main() -> int:
text = text.replace(".WEATHER_OPTIONS_HERE",
"\n".join(weather_section()))
text = text.replace(".APRS_OPTIONS_HERE", "\n".join(aprs_section()))
text = text.replace(".FT8_OPTIONS_HERE", "\n".join(ft8_section()))
text = text.replace("\n\n", "\n") # troff dislikes blank lines
target = Path(sys.argv[1] if len(sys.argv) > 1
else Path(__file__).parent / "bandsaunter.1")