2665a17a22
Four things asked for in turn, landing together because they run through the same files. THE MAPS. The tiles were already cached and always had been -- a second evening on the same view was measured at nought network requests -- but the work done on them was not. Every window open decoded forty PNGs and resampled a megapixel and a half into this program's own projection, for an answer that cannot have changed, because a coastline does not move. The finished map is kept beside the tiles now: 0.61 seconds become 0.01, byte for byte identical, two hundred kilobytes a view. Both windows and both kinds of still picture get it, all four reaching the ground through one function. A map with squares missing is deliberately not kept, since caching a hole would keep it for a month and the point of calling a partial map provisional is that it is asked for again. And because this adds a disk consumer, the whole cache is now pruned to four hundred megabytes, least recently *used* first: a tile fetched a year ago and looked at last night is the receiver's own neighbourhood, and discarding that to keep last week's holiday is the wrong way round. THE LOOKUPS. APRS and FT8 now ask who each station is licensed to. Every other mode that hears a callsign already did -- speech transcripts, Morse idents, the recording browser -- and all five resolve through one file, so a callsign heard on two bands is asked about once. The rules for finding the licensed callsign inside a heard one are now in one place rather than per band, because getting them wrong is silent: a register asked about W1AW-9 returns nothing, which looks exactly like a station that is not licensed. An SSID, a rover suffix, a guest prefix, a digipeater alias and an unspelled hash all come off or are refused. The bug worth recording is that the first cut of this did the lookups and threw them away. The book has to be told to save and was not, so every evening would have asked the register about the same net again -- which is the one thing caching them was for, and is invisible from inside a single run because the answers are all in memory while it lasts. Caught by looking at the file on disk rather than at the display. There is a test for each side of it now, and a register of which modules resolve callsigns at all, which fails when a new one starts so that somebody has to decide whether it should. THE REGISTER. c in saunterbrowse opens everything ever looked up: sixty-odd callsigns and sixteen hundred aircraft here, every field of each in two columns because a licence has a dozen and a screen is wider than it is tall. tab switches, / searches every field rather than the name -- the question is usually "who was in Arizona" rather than "which callsign" -- and g opens the place in a browser. Only the coordinates go into that link: a map does not need to be told whose licence it is looking at, and the link is the one part of this that leaves the machine. A headless box, which is the normal case for a receiver, gets the coordinates printed instead. Callsigns no register could place are kept rather than dropped, because "asked about, and in no register reachable from here" is a fact about a station. THE FRONT OF IT. A title screen for each program: five rows of blocks cut by hand, a figlet dependency to draw eleven letters being the largest thing that would then be in the requirements, coloured blue to red across the width, which is the ramp every waterfall here already uses because it is what a spectrum looks like. The interesting part is where it does not appear -- everything here can be piped into something else and a banner in the middle of that is corruption rather than decoration, so anything that is not a terminal gets nothing, --help is untouched because it is drawn after parsing, --no-splash turns it off for a run and BANDSAUNTER_NO_SPLASH=1 for good. And the address. INSTALL.md said "git clone <the repository>" for a long time: a placeholder in the first command anybody types, unnoticed because nothing reads install instructions except somebody installing, who then cannot. It is filled in, along with the readme, the metadata, both manuals and the Homepage field of all three packages. The tile server's User-Agent pointed at a topic listing on somebody else's site for want of an address of its own; the usage policy of that service asks for one naming the application and giving somewhere to look it up, so an operator with a question about the traffic has somebody to ask, and now it gives the real one. Seven tests so the placeholder cannot come back, verified by putting it back and watching two of them fail. One thing forced by all this: the keys page in saunterbrowse was exactly as tall as an eighty-by-twenty-four terminal, so the register entry pushed "q quit" off the bottom. A test caught it. Home and End have merged into the Page Up line, which were always the same thought. THE WINDOWS. They open maximised now, this being a map and the thing anybody wants more of being map; f goes to true full screen and back, and is written along the top of the screen because a window with no frame is one somebody has to know a key to get out of. Maximised rather than frameless by default, because the title bar is where the band and the frequency are written. And a map made bigger now gets a sharper map, which it did not. The window only ever re-examined the ground when the view left the box that had been fetched, so a window opened at its default size and taken to the whole screen kept the map it started with until an aircraft wandered far enough to move it -- on a quiet band, a long time to look at a blurred coastline. Measured before it was believed: 1100 to 1920 asked for nothing and stretched a 1364-pixel map across 1920, then across 3840. It now compares map pixels per degree in hand against what the view wants, and asks when it is being blown up by more than fifteen per cent. That comparison has to be per degree rather than pixel against pixel, which a surviving mutation was what established: the fetched box is a quarter wider than the view, so a map with exactly as many pixels as the window is wide has only four fifths of them on the screen. The two ways of measuring agree everywhere except a narrow band, and the realistic case sits inside it. There is a test pinning that case now. Asking is safe at any size, because the request is keyed on the window's dimensions: once answered, nothing more is asked, which is what stops a window larger than the tile budget can cover from asking all evening. The braille, while this was open. The banners were blocks in capitals; they are braille in mixed case, two dots wide and four tall to a character, which is eight times the detail and is what makes room for two heights of letter at once -- a five-row block font has no second height to spend, so the name came out shouted. Two attempts failed first: thin one-dot strokes came out as confetti, because braille dots render as dots and a one-dot stroke reads as a dotted line rather than a line. What worked was cutting the font small, at cap height seven where there is only one way to draw each letter, and doubling it. Coloured deep blue through cyan to a cool white, which is deliberately not the waterfall ramp the rest of the program draws in: that one has to run to red because it stands in for a spectrum, and a title screen stands in for nothing. One hundred and four new tests. Full suite 2892 passed. Built as 2026-09-24_01. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016PsWPTweCT6pwxKngvVxcg
2126 lines
98 KiB
Python
Executable file
2126 lines
98 KiB
Python
Executable file
#!/usr/bin/env python3
|
|
"""Generate the bandsaunter manual page from the settings table.
|
|
|
|
The settings are described in exactly one place -- bandsaunter/settings.py --
|
|
so the manual cannot drift from the program. Every setting appears here with
|
|
its command-line flag, its default, and the plain-language guidance that says
|
|
what it is and when someone would change it.
|
|
"""
|
|
import sys
|
|
from datetime import date
|
|
from pathlib import Path
|
|
|
|
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
|
|
|
|
import bandsaunter # noqa: E402
|
|
from bandsaunter import settings as st # noqa: E402
|
|
from bandsaunter.config import ScanConfig # noqa: E402
|
|
|
|
|
|
def esc(text: str) -> str:
|
|
"""Escape for troff: a leading dot or apostrophe is a request."""
|
|
out = text.replace("\\", "\\e")
|
|
return "\n".join(("\\&" + ln if ln[:1] in (".", "'") else ln)
|
|
for ln in out.split("\n"))
|
|
|
|
|
|
def settings_section() -> list[str]:
|
|
out = []
|
|
defaults = ScanConfig()
|
|
for group in st.GROUPS:
|
|
out.append(f'.SS {esc(group)}')
|
|
for s in st.in_group(group):
|
|
flags = " ".join(s.flags)
|
|
if s.off_flags:
|
|
flags += " / " + " ".join(s.off_flags)
|
|
shown = st.format_value(s, getattr(defaults, s.key))
|
|
unit = f" ({s.unit})" if s.unit and s.kind not in ("bool",) else ""
|
|
out.append('.TP')
|
|
out.append(f'.B {esc(flags)}')
|
|
out.append(f'{esc(s.label)} \\[em] {esc(s.help)}{esc(unit)}.')
|
|
out.append('.br')
|
|
out.append(f'Setting name \\fB{esc(s.key)}\\fR, '
|
|
f'default \\fB{esc(shown)}\\fR.')
|
|
accepts = s.describe_range()
|
|
if accepts:
|
|
out.append('.br')
|
|
out.append(f'Accepts: {esc(accepts)}.')
|
|
if s.guidance:
|
|
# Indented to the entry it belongs to, not back out to the
|
|
# left margin, so an entry reads as one block.
|
|
out.append('.RS')
|
|
out.append('.PP')
|
|
out.append(esc(s.guidance))
|
|
out.append('.RE')
|
|
out.append('.PP')
|
|
return out
|
|
|
|
|
|
def aircraft_section() -> list[str]:
|
|
"""Every ADS-B option, from the same table the menu and flags come from."""
|
|
from bandsaunter import aircraft as air
|
|
|
|
return options_section(air)
|
|
|
|
|
|
def weather_section() -> list[str]:
|
|
"""Every weather option, from the same table."""
|
|
from bandsaunter import weather as wx
|
|
|
|
return options_section(wx)
|
|
|
|
|
|
def aprs_section() -> list[str]:
|
|
"""Every APRS option, from the same table again."""
|
|
from bandsaunter import aprs as ap
|
|
|
|
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.
|
|
|
|
Written out rather than described in prose, so that an option added to
|
|
the program cannot quietly fail to appear in its manual. Both sections
|
|
describe their options in the same shape, so this does not need to know
|
|
which one it has been handed.
|
|
"""
|
|
out = []
|
|
defaults = air.defaults()
|
|
for group in air.OPTION_GROUPS:
|
|
out.append(f'.SS {esc(group)}')
|
|
for o in air.in_group(group):
|
|
flags = " ".join(o.flags)
|
|
if o.off_flags:
|
|
flags += " / " + " ".join(o.off_flags)
|
|
shown = air.format_option(o, getattr(defaults, o.key))
|
|
unit = f" ({o.unit})" if o.unit and o.kind != "bool" else ""
|
|
out.append('.TP')
|
|
out.append(f'.B {esc(flags) if flags else esc(o.key)}')
|
|
out.append(f'{esc(o.label)} \\[em] {esc(o.help)}{esc(unit)}.')
|
|
out.append('.br')
|
|
out.append(f'Setting name \\fB{esc(o.key)}\\fR, '
|
|
f'default \\fB{esc(shown) if shown else "blank"}\\fR.')
|
|
accepts = o.describe_range()
|
|
if accepts:
|
|
out.append('.br')
|
|
out.append(f'Accepts: {esc(accepts)}.')
|
|
if o.guidance:
|
|
out.append('.RS')
|
|
out.append('.PP')
|
|
out.append(esc(o.guidance))
|
|
out.append('.RE')
|
|
out.append('.PP')
|
|
return out
|
|
|
|
|
|
HEAD = r'''.\" Generated by packaging/make-man.py -- do not edit by hand.
|
|
.TH BANDSAUNTER 1 "{date}" "bandsaunter {version}" "User Commands"
|
|
.SH NAME
|
|
bandsaunter \- scan, record and identify radio signals with an RTL-SDR
|
|
.SH SYNOPSIS
|
|
.B bandsaunter
|
|
.RI [ command ]
|
|
.RI [ options ]
|
|
.br
|
|
.B bandsaunter scan
|
|
.BI \-r " RANGE"
|
|
.RI [ options ]
|
|
.br
|
|
.B bandsaunter
|
|
.RI "(no arguments: interactive menus)"
|
|
.SH DESCRIPTION
|
|
.B bandsaunter
|
|
sweeps any set of frequency ranges with an RTL-SDR receiver, stops on
|
|
signals that rise above the background noise, records them, and works out
|
|
what kind of signal each one was. Morse is decoded to text and speech can be
|
|
transcribed.
|
|
.PP
|
|
Ranges are given by hand or chosen from a built-in US band plan. There is no
|
|
limit on how many may be scanned at once.
|
|
.PP
|
|
Captures that turn out to be noise, static or interference are discarded
|
|
rather than saved, so what ends up on disk is transmissions rather than hiss.
|
|
This is the behaviour of
|
|
.B \-\-require\-signal
|
|
and it is on by default.
|
|
.PP
|
|
Every setting can be given as a command-line option, set in the menus, or
|
|
saved to a settings file; the three are the same list, described under
|
|
.B SETTINGS
|
|
below.
|
|
.SH COMMANDS
|
|
.TP
|
|
.B scan
|
|
Run a scan. Without
|
|
.B \-r
|
|
or
|
|
.B \-b
|
|
the interactive menus open instead.
|
|
.TP
|
|
.B bands
|
|
Browse the built-in US band plan: amateur, marine, aviation, public service,
|
|
business, railroad, GMRS/FRS, CB, ISM, weather, and more.
|
|
.TP
|
|
.B config
|
|
Show or change the saved settings.
|
|
.B "config KEY=VALUE"
|
|
sets one and saves it,
|
|
.B "config \-\-show"
|
|
prints them all,
|
|
.B "config \-\-describe KEY"
|
|
explains one in full, and
|
|
.B "config \-\-edit"
|
|
opens the menus.
|
|
.TP
|
|
.B transcribe
|
|
Transcribe existing recordings, or list which speech recognisers are
|
|
installed with
|
|
.BR \-\-engines .
|
|
.TP
|
|
.B waterfall
|
|
Draw a waterfall for every recording in a directory that produced no
|
|
readable words. See
|
|
.B WATERFALLS
|
|
below.
|
|
.TP
|
|
.B devices
|
|
List attached receivers.
|
|
.TP
|
|
.B profiles
|
|
List saved profiles.
|
|
.TP
|
|
.B adsb
|
|
Listen to aircraft on 1090 MHz and write down everything they say. See
|
|
.B AIRCRAFT
|
|
below.
|
|
.TP
|
|
.B flights
|
|
Read an ADS-B log back: the report, the map for Google Earth and the
|
|
animation. See
|
|
.B AIRCRAFT
|
|
below.
|
|
.TP
|
|
.B weather
|
|
Listen to the AcuRite weather sensors on 433.92 MHz, and name them as they
|
|
arrive. See
|
|
.B WEATHER SENSORS
|
|
below.
|
|
.TP
|
|
.B readings
|
|
Read a weather log back: the report, and a spreadsheet. See
|
|
.B WEATHER SENSORS
|
|
below.
|
|
.TP
|
|
.B sensors
|
|
List every weather sensor heard, and give them names.
|
|
.TP
|
|
.B aprs
|
|
Listen to the APRS channel on 144 MHz: positions, weather, messages, objects
|
|
and telemetry from amateur stations. See
|
|
.B APRS
|
|
below.
|
|
.TP
|
|
.B packets
|
|
Read an APRS log back: the report, a spreadsheet and a map. See
|
|
.B APRS
|
|
below.
|
|
.TP
|
|
.B analyze
|
|
Identify a signal in an already-recorded file, decode Morse from it, or write
|
|
out the picture it turns out to be.
|
|
.SH OPTIONS
|
|
.TP
|
|
.BI \-r " RANGE\fR, \fP" \-\-range " RANGE"
|
|
A frequency range to sweep, such as
|
|
.IR 144M\-148M .
|
|
Repeatable, and a comma-separated list is accepted. See
|
|
.B ENTERING FREQUENCIES
|
|
below.
|
|
.TP
|
|
.BI \-b " KEY\fR, \fP" \-\-band " KEY"
|
|
A band-plan preset, such as
|
|
.IR gmrs " or " marine\-vhf .
|
|
Repeatable.
|
|
.B bandsaunter bands
|
|
lists them.
|
|
.TP
|
|
.BI \-\-mode " MODE"
|
|
Force one demodulator for every range: nfm, wfm, am, usb, lsb, cw or raw.
|
|
Without this each range is demodulated according to what the signal turns out
|
|
to be, which is normally what you want.
|
|
.TP
|
|
.BI \-p " NAME\fR, \fP" \-\-profile " NAME"
|
|
Start from a saved profile instead of the saved default settings.
|
|
.TP
|
|
.BI \-\-save\-profile " NAME"
|
|
Save the settings this run would have used, under that name, and exit.
|
|
.TP
|
|
.B \-\-save
|
|
Save the settings this run would have used as the new defaults, and exit.
|
|
.TP
|
|
.B \-\-no\-config
|
|
Ignore the saved settings file and start from the built-in defaults.
|
|
.TP
|
|
.B \-\-simulate
|
|
Use a synthetic receiver instead of real hardware. Everything else behaves
|
|
normally, so the program can be tried out with no dongle attached.
|
|
.TP
|
|
.B \-\-dry\-run
|
|
Print the sweep plan \[em] every tuner step and how long a pass will take \[em]
|
|
and exit without receiving anything.
|
|
.TP
|
|
.B \-\-keep\-carriers
|
|
Also record steady unmodulated carriers, which are otherwise discarded as
|
|
having no content. Useful for beacon hunting or for tracking down a source of
|
|
interference.
|
|
.SH SETTINGS
|
|
Each of these can be given as a command-line option, changed in the menus
|
|
under
|
|
.BR "bandsaunter config" ,
|
|
or written into the settings file. The command line wins for one run; the
|
|
settings file is what every run starts from.
|
|
'''
|
|
|
|
TAIL = r'''.SH ENTERING FREQUENCIES
|
|
Frequencies may be written with a unit or without:
|
|
.IR 146.52M ", " "146.52 MHz" ", " 146520k ", " 146520000 .
|
|
A bare number under 10000 is read as megahertz, since that is how people
|
|
write frequencies.
|
|
.PP
|
|
A range is a pair:
|
|
.IR 144M\-148M ", " 144\-148M " (the unit carries over), " "144M to 148M" ", "
|
|
.IR 144M..148M .
|
|
A single frequency on its own is treated as a narrow range around it.
|
|
.PP
|
|
A step and a demodulator may be attached:
|
|
.I 144M\-148M/25k@nfm
|
|
sweeps in 25 kHz steps and demodulates narrowband FM.
|
|
.PP
|
|
Several may be given at once, separated by commas, and
|
|
.B \-r
|
|
may be repeated. There is no limit on how many ranges a scan may cover.
|
|
.SH BAND PLAN
|
|
.B bandsaunter bands
|
|
lists over a hundred presets from the US band plan, each carrying the right
|
|
step size and demodulator for that service, so
|
|
.B "\-b gmrs"
|
|
is enough to scan GMRS properly.
|
|
.PP
|
|
Presets that stand for several others expand automatically:
|
|
.I all\-cw
|
|
sweeps every Morse segment of every amateur band, and
|
|
.IR 2m\-complete ", " 70cm\-complete
|
|
and their like sweep a whole amateur band end to end rather than one segment
|
|
of it.
|
|
.PP
|
|
The same plan names what is heard. Beside every frequency on the display,
|
|
and in the line\-per\-hit output, is the band it falls in: a signal at
|
|
421 MHz is labelled
|
|
.IR "70 cm Amateur" ,
|
|
one at 462.5625 MHz is
|
|
.IR "GMRS / FRS" ,
|
|
and 162.55 MHz is
|
|
.IR "NOAA Weather Radio" .
|
|
Where several allocations overlap, the narrowest wins, because it says the
|
|
most \[em] 146.52 MHz is named as the 2 m simplex calling channel rather than
|
|
as the whole 2 m band. The name is written into each recording's sidecar as
|
|
well, so it stays with the capture.
|
|
.SH LOCK-OUTS
|
|
Every receiving setup has a few frequencies not worth stopping on: a pager
|
|
transmitter down the road, a nearby data link, or a spurious signal the
|
|
receiver manufactures itself. Locking one out makes the scan skip it.
|
|
.PP
|
|
Pressing
|
|
.B l
|
|
during a scan locks out whatever is being received. Unless
|
|
.B \-\-no\-save\-lockouts
|
|
is given, it is written back to the settings file the run started from, so it
|
|
stays locked out on later runs. Only the lock-out list is written back \[em]
|
|
options given on the command line for a single run stay one-off.
|
|
.PP
|
|
Lock-outs can also be given directly, several at a time, as single
|
|
frequencies or as spans:
|
|
.PP
|
|
.RS
|
|
.EX
|
|
bandsaunter scan \-r 144M\-148M \-\-lockout "162.55M, 450M\-455M"
|
|
.EE
|
|
.RE
|
|
.PP
|
|
A single frequency is widened by
|
|
.BR \-\-lockout\-width ;
|
|
a span is used exactly as written.
|
|
.PP
|
|
Two runs never write anything back.
|
|
.B \-\-no\-config
|
|
has no settings file to write to, since the point of it is to leave the saved
|
|
settings alone; and
|
|
.B \-\-simulate
|
|
is looking at an invented band, whose frequencies would be nonsense in a real
|
|
settings file. Both still lock out for the run in hand, and say so.
|
|
.SH THE LIVE DISPLAY
|
|
The display is redrawn in place several times a second, so it has to fit the
|
|
window. On a short terminal the optional parts are given up in order \[em] the
|
|
spectrum row, then the list of recorded signals, then the key hints, and last
|
|
of all the receiver panel, which says nothing that changes. What is never
|
|
given up is the sweep line and, while one is running, the recording.
|
|
.PP
|
|
Resizing the window redraws everything from a blank screen. The frame that was
|
|
on it was drawn for a window that no longer exists, and the text above it has
|
|
been reflowed by the terminal in any case, so what was printed before the scan
|
|
started \[em] the sweep plan and the settings summary \[em] scrolls away at that
|
|
point.
|
|
.PP
|
|
.B \-\-plain
|
|
prints one line per hit instead and needs none of this, which is what to use
|
|
when the output is going into a pipe or a log.
|
|
.SH KEYS DURING A SCAN
|
|
.TP
|
|
.B q
|
|
Stop.
|
|
.TP
|
|
.B p
|
|
Pause and resume.
|
|
.TP
|
|
.B s
|
|
Abandon this recording and resume sweeping.
|
|
.TP
|
|
.B l
|
|
Lock out this frequency, now and in future runs.
|
|
.TP
|
|
.B "+ \fRand\fB \-"
|
|
Raise or lower the squelch threshold by 1 dB.
|
|
.SH OUTPUT
|
|
Recordings are named
|
|
.IR frequency \-\- date _ time \- modulation .wav ,
|
|
with the frequency padded to four digits so that an ordinary directory
|
|
listing sorts by frequency. Beside them are the run log, as JSON lines and as
|
|
CSV, and optionally a transcript per recording and the raw samples.
|
|
.PP
|
|
With
|
|
.B \-\-combine
|
|
every transmission on one frequency is appended to a single growing file for
|
|
that frequency, with a spoken date and time before each one, so a scan can be
|
|
played back as a recording of that channel rather than clicked through as
|
|
hundreds of fragments.
|
|
.SH TRUNKED SYSTEMS
|
|
Police, fire and large business radio in the US mostly runs on
|
|
.IR trunked
|
|
systems. Instead of giving each department its own frequency, the system owns
|
|
a pool of channels and hands one out for each conversation as it happens. To
|
|
make that work, one frequency in the pool is given over entirely to a data
|
|
stream that runs day and night, telling every radio in the fleet where to go
|
|
next. That frequency is the
|
|
.IR "control channel" .
|
|
.PP
|
|
A control channel is the worst thing a scanner can find. It is loud, it is
|
|
perfectly steady, it never stops, and there is nothing on it to listen to \[em]
|
|
just a harsh buzz. A scanner without special handling parks on it for the
|
|
whole record limit, saves the file, and then finds it again on the next sweep,
|
|
for as long as it is left running.
|
|
.PP
|
|
bandsaunter recognises one from the shape of the signal, names the system on
|
|
screen, deletes what it captured and moves on, usually within a second or
|
|
two. What it looks for is a constant\-envelope data stream that never pauses,
|
|
at a symbol rate belonging to a known trunking standard:
|
|
.RS
|
|
.PP
|
|
3600 baud two\-level \[em] Motorola SMARTNET / SmartZone (Type I and II).
|
|
.br
|
|
9600 baud two\-level \[em] EDACS and ProVoice.
|
|
.br
|
|
1200 baud two\-level \[em] MPT\-1327.
|
|
.br
|
|
4800 baud four\-level \[em] P25 or DMR Tier III.
|
|
.br
|
|
2400 baud four\-level \[em] NXDN and NEXEDGE.
|
|
.RE
|
|
.PP
|
|
The first two are recognised at once: nothing else transmits at those rates
|
|
without pausing. The others share their shape with an ordinary digital voice
|
|
call on the same system, so they are only called a control channel once the
|
|
carrier has run unbroken for
|
|
.B \-\-control\-seconds
|
|
(20 s by default) \[em] long enough that a real conversation would have taken
|
|
a breath. Raise that figure if digital voice calls are being skipped by
|
|
mistake.
|
|
.PP
|
|
Being inside a band where trunking is common raises confidence but is never
|
|
required: trunking is licensed on business pairs all over the spectrum.
|
|
.PP
|
|
Use
|
|
.B \-\-keep\-control
|
|
to record control channels anyway, which is what you want if you are feeding
|
|
them to a decoder. Use
|
|
.B \-\-lockout\-control
|
|
to have each one written into the lock\-out list as it is found, so the
|
|
scanner stops looking at it at all; with
|
|
.B \-\-save\-lockouts
|
|
on, that list survives a restart.
|
|
.SH TRANSCRIPTS
|
|
Anything the content check identifies as voice is passed to a speech
|
|
recogniser, and the words are written to a
|
|
.I _transcription.txt
|
|
beside the recording. Only voice: running a recogniser over Morse or a data
|
|
burst costs seconds and produces nothing.
|
|
.PP
|
|
One transcript per transmission, and none is ever overwritten \[em] the
|
|
timestamp is part of the name, so two overs on one frequency cannot land on
|
|
the same file.
|
|
.PP
|
|
With
|
|
.B \-\-combine
|
|
there is one recording per frequency, so there is one transcript per
|
|
frequency, and each over is appended to it with the time it was heard. An
|
|
unattended receiver keeps adding to that file night after night rather than
|
|
starting it over.
|
|
.PP
|
|
A capture with nothing recognisable in it produces no file at all, rather
|
|
than a directory of placeholders. No voice-activity filter runs inside the
|
|
recogniser \[em] one throws away the single-word overs between transmissions,
|
|
which on a scanner are the replies worth having. Instead the whole capture is
|
|
asked once whether anything in it rises above its own noise, and refused
|
|
before a recogniser sees it if nothing does. That check can veto a capture
|
|
but never trim one, so a short reply in the middle of a quiet channel
|
|
survives it.
|
|
.PP
|
|
.BR saunterbrowse (1)
|
|
reads these back, and lists any callsigns it finds in them with the licence
|
|
they belong to.
|
|
.PP
|
|
A callsign in a transcript is not written the way it is printed. A recogniser
|
|
has never heard of the phonetic alphabet: it writes what the words sounded
|
|
like, breaks the callsign wherever the speaker paused, joins the words back
|
|
up, hyphenates them, or drops a hesitation into the middle of the run. So
|
|
"KU 0W", "kilo uniform zero whiskey", "Whiskey\-One\-Alpha\-Whiskey",
|
|
"WhiskeyOneAlphaWhiskey" and "whiskey one alpha, uh, whiskey" are all read
|
|
back as the callsigns they are, and "alfa", "juliett" and "whisky" count
|
|
alongside the official spellings.
|
|
.PP
|
|
Two shapes are recognised. An amateur callsign is a prefix, a district digit
|
|
and a suffix; everything else the FCC licenses is written the other way
|
|
round, the letters first and then the digits, so WQVF960 and WXG204 are read
|
|
as the GMRS and business licences they are.
|
|
.PP
|
|
Nothing is joined across a slash: a suffix says where the station is, not
|
|
what it is called, so
|
|
.I W1AW/B
|
|
is W1AW.
|
|
.SH WATERFALLS
|
|
Most of what a scanner records cannot be turned into words: a data burst, a
|
|
keyed carrier, a pager, a control channel, a stretch of something
|
|
unidentified. A waterfall says something about every signal there is,
|
|
because it shows the shape of the thing rather than its meaning \[em] how
|
|
wide it is, how long it lasted, whether it was keyed, swept, hopping or
|
|
steady, and whether it was one signal or three side by side.
|
|
.PP
|
|
So every capture that produced no readable words is drawn beside the audio
|
|
as a PNG: no voice, or voice the recogniser came back from with fewer than
|
|
.B \-\-waterfall\-min\-chars
|
|
characters, which is what a recogniser handed something that is not speech
|
|
reliably does. Time runs down the picture and frequency across it, with the
|
|
frequency scale on top, the seconds down the left and a caption underneath
|
|
saying what the capture was.
|
|
.PP
|
|
A capture with Morse in it is never counted as readable, however long the
|
|
transcript. A station identifying itself in CW over an FM carrier is
|
|
transcribed as a string of digits, one per tone, which clears any bar and
|
|
says nothing; the ident is in the Morse text and the signal is only visible
|
|
as a picture.
|
|
.PP
|
|
The caption also says what the picture is *of*, and that matters. Where the
|
|
raw IQ was kept this draws the radio spectrum around the tuned frequency,
|
|
which is the waterfall an operator would have been watching. Where only the
|
|
audio was kept \[em] the usual case, since IQ is off by default \[em] it
|
|
draws the demodulated audio instead: after an FM detector the frequency axis
|
|
is no longer radio frequency, and a picture that did not say so would be a
|
|
lie told in a convincing font.
|
|
.PP
|
|
.B bandsaunter waterfall
|
|
does the same for a directory already recorded, drawing only what cannot be
|
|
read unless
|
|
.B \-\-all
|
|
is given, and skipping what it has already drawn unless
|
|
.B \-\-redraw
|
|
is.
|
|
.B \-\-check\-morse
|
|
runs the CW decoder over the recordings it was about to skip, for sidecars
|
|
written before the decoder could hear an ident over an FM carrier, and draws
|
|
\[em] and records the ident in \[em] the ones that have one.
|
|
.SH CW AND IDENTIFICATION
|
|
Every capture is offered to a CW decoder once it has finished, whatever the
|
|
classifier made of it. Most of the Morse on the air is not a conversation:
|
|
it is a repeater, a beacon or an unattended transmitter saying who it is and
|
|
stopping, which is four to six characters and over in a second or two. That
|
|
burst is a fraction of a capture named after whatever filled the rest of it,
|
|
so waiting for the label to say "CW" missed it.
|
|
.PP
|
|
Nor does that station key its carrier. On the land-mobile bands the carrier
|
|
stays up and the ident is an audio tone keyed inside it, which a detector
|
|
looking for a keyed carrier sees as a carrier that never stops. So the
|
|
recorded audio is searched as well, a few seconds at a time, because the
|
|
decoder takes its tone and its key-down threshold from the whole of whatever
|
|
it is handed: a half-minute recording with five seconds of keying in the
|
|
middle measures both from the other twenty-five. A mark far longer than any
|
|
dash is read as the transmission the ident was sent over rather than as a
|
|
character the window sliced, which is what used to take the first and last
|
|
letter of every such ident \[em] and with them the callsign, one word with no
|
|
gap in it to survive the drop.
|
|
.PP
|
|
A reading made only of one-element characters is refused. E and T are the
|
|
only two, so a decode of nothing but those can hardly be wrong \[em] there is
|
|
nothing in it to get wrong \[em] and no station has ever identified itself
|
|
that way.
|
|
.PP
|
|
Short is therefore the normal case rather than the awkward one. A decode of
|
|
two or three characters is believed on its timing alone \[em] every element
|
|
within a third of a unit of one or three, every character resolving to
|
|
something in the table, and the keyed tone standing at least 20 dB above the
|
|
rest of its band. That last one is what separates an ident from a blip: with
|
|
four elements the dot length is fitted to those very elements, so noise lands
|
|
on the grid as neatly as keying does, and only the tone tells them apart. One
|
|
keyed element is refused, because a single pulse is an E or a T whether a
|
|
person sent it or the squelch opened on a click.
|
|
.PP
|
|
The other half of a short decode is knowing what was cut off. A capture opens
|
|
when the squelch does, which is in the middle of an element as often as not,
|
|
and half a character is not a smaller reading of what was sent \[em] it is a
|
|
different one, and a K with its first dash missing is an A. So the character
|
|
at a sliced end is dropped, and so is the rest of the word it was in, because
|
|
what is left of that word can read as a whole one:
|
|
.I K1AA
|
|
caught halfway through is
|
|
.IR K1A ,
|
|
which belongs to somebody else. The full text is still reported; it is the
|
|
identification that is held to the stricter standard.
|
|
.PP
|
|
What survives goes to the same callsign lookup and the same map as a spoken
|
|
one. Word gaps in Morse are not joined across, because the sender chose them:
|
|
.I "KU0W K"
|
|
is a station signing off, not a callsign one letter longer.
|
|
.SH DECODING DATA
|
|
A great deal of what a scanner finds is not speech. Doorbells, tyre\-pressure
|
|
sensors, weather stations, remote controls, paging and packet radio all carry
|
|
words or numbers that a receiver can read, and
|
|
.B bandsaunter
|
|
reads them.
|
|
.PP
|
|
Whatever the modulation, a data signal comes down to the same shape once it
|
|
has been sliced: a train of alternating runs whose lengths carry the
|
|
information. On\-off keying gives that directly \[em] the carrier is up or it is
|
|
down \[em] and two\-level FSK gives the same thing from the discriminator, one
|
|
tone or the other. So both are reduced to runs and everything after that is
|
|
shared.
|
|
.PP
|
|
What the runs mean is the line code, and it is worked out from the runs alone
|
|
rather than being configured:
|
|
.TP
|
|
.B PWM
|
|
The pulse carries the bit and the gap or the period holds still. Nearly every
|
|
cheap 433 MHz remote, and everything built on an EV1527 or PT2262.
|
|
.TP
|
|
.B PPM
|
|
The pulse holds still and the gap carries the bit. The other half of the same
|
|
market.
|
|
.TP
|
|
.B Manchester
|
|
Every bit is a transition in the middle of its own period, so runs come in
|
|
only two lengths.
|
|
.TP
|
|
.B NRZ
|
|
The level is held for as many symbol periods as there are bits. What a framed
|
|
protocol sits on top of.
|
|
.PP
|
|
Four\-level FSK \[em] C4FM, as P25, DMR and NXDN use it \[em] is recognised as
|
|
such and read as symbols rather than being sliced down the middle, which would
|
|
give bits that mean nothing. Where a frame sync word appears the system is
|
|
named outright.
|
|
.SH PROTOCOLS THAT CAN BE READ IN FULL
|
|
Two carry their own framing and checksums, so a frame either passes or it does
|
|
not, and one that passes is not a guess.
|
|
.TP
|
|
.B POCSAG
|
|
Paging, at 512, 1200 or 2400 baud. The rate is not announced anywhere in the
|
|
signal, so all three are tried and the one whose sync word appears is the
|
|
right one. Each codeword is checked, and a single bit error is corrected,
|
|
against the BCH code the standard puts there for the purpose. The address, the
|
|
function letter and the message text are all reported.
|
|
.TP
|
|
.B "AX.25 / APRS"
|
|
Amateur packet on 1200 baud AFSK. The frame check has to come out right before
|
|
a frame is reported at all. The sender's callsign, the digipeater path and the
|
|
payload are shown \[em] and the callsign goes onto the map with the rest.
|
|
.SH BELIEVING A DECODE
|
|
A decoder that always returns something is worse than useless: noise sliced at
|
|
a threshold produces runs, and runs produce bits. Three things guard against
|
|
that.
|
|
.PP
|
|
The runs have to quantise to the line code's own grid, and a decode whose runs
|
|
are scattered is thrown away. Most of the bursts in a capture have to decode
|
|
the same way, because a data signal is data all the way through and one lucky
|
|
window among eight is a coincidence. And, much the strongest, the packet has
|
|
to repeat \[em] these transmitters send the same thing three to ten times over,
|
|
and bits that come back identical every time did not come from noise.
|
|
.PP
|
|
A bare reading with none of that behind it, where the runs merely happened to
|
|
land on a grid, is reported as nothing at all rather than as a bit string with
|
|
a low number beside it that somebody will read anyway.
|
|
.PP
|
|
A decode that does have repeats or a checksum behind it outranks the content
|
|
check: a burst of keying demodulated as FM audio is a buzz, and the speech
|
|
detector likes a buzz, but a frame whose own checksum came out right is not a
|
|
statistic.
|
|
.SH PICTURES
|
|
Three of the things a receiver can hear are images rather than sounds. All
|
|
three are analogue, all three encode brightness as a frequency, and all three
|
|
arrive as the audio the scanner already records \[em] so they are looked for in
|
|
every recording and written out as PNG beside it.
|
|
.TP
|
|
.B SSTV
|
|
Slow-scan television, on 14.230 MHz and 144.5 MHz and wherever else amateurs
|
|
send it. A transmission opens with a VIS header that says which mode follows,
|
|
and that header is what is looked for: no header, no picture. Martin M1 and
|
|
M2, Scottie S1, S2 and DX, and Robot 36 and 72 are decoded, in colour.
|
|
.TP
|
|
.B "APT"
|
|
The NOAA weather satellites on 137 MHz, which spend a fifteen-minute pass
|
|
sending one continuous picture. A 2400 Hz tone carries the brightness, two
|
|
lines a second, 2080 words to a line, with both of the satellite's sensors in
|
|
every line. The whole frame is written, and each sensor again on its own.
|
|
.TP
|
|
.B "HF fax"
|
|
The weather charts the shortwave stations have sent for decades, in single
|
|
sideband between 2 and 20 MHz. A transmission opens with a phasing signal \[em]
|
|
twenty or so lines that are black but for a pulse at the start of each \[em] and
|
|
that is what says where a line begins and how long one is.
|
|
.PP
|
|
None of the three is guessed at, which is what makes it safe to try them on
|
|
every recording: each is recognised by a header or a phasing signal that
|
|
nothing else on the air sends. A decoder without one draws static beautifully,
|
|
and a directory of beautifully rendered static is worse than an empty one.
|
|
.PP
|
|
A picture keeps its capture whatever the content check made of it. A satellite
|
|
is a steady tone with a wobble on it and an SSTV transmission is a whistle:
|
|
neither is speech and neither has symbol structure, so both were being thrown
|
|
away as "no signal content" having already been recognised.
|
|
.PP
|
|
Pictures take minutes rather than seconds \[em] two minutes for SSTV, fifteen for
|
|
a satellite pass \[em] so
|
|
.B \-\-record
|
|
has to be long enough or what arrives is the top of one. A partial picture is
|
|
kept and labelled as partial rather than discarded.
|
|
.PP
|
|
.BR saunterbrowse (1)
|
|
marks these in the list and gives the path of the file.
|
|
.PP
|
|
GRIB, which is sometimes asked about in the same breath, is not a modulation:
|
|
it is the binary format the weather models are published in, and it travels by
|
|
satellite data link and by e-mail rather than as something a receiver can
|
|
demodulate. Where a decoded byte stream begins with its magic number it is
|
|
named as such; nothing here fetches or renders one.
|
|
.SH AIRCRAFT
|
|
.B bandsaunter adsb
|
|
parks the receiver on 1090 MHz and reads the Mode S extended squitter that
|
|
every airliner overhead broadcasts twice a second: the aircraft's address, its
|
|
callsign, its altitude, its position and its speed, unencrypted, to nobody in
|
|
particular.
|
|
.PP
|
|
It is a command of its own because ADS-B does not fit through the scanner. The
|
|
signalling is a megabit a second, which needs at least two megasamples a second
|
|
of raw receiver output; the scan path decimates everything to a channel twelve
|
|
and a half kilohertz wide long before any decoder sees it.
|
|
.PP
|
|
Every frame carries a 24-bit checksum, so there is no threshold here and
|
|
nothing to disbelieve: a frame either passes or is dropped. A position takes
|
|
two frames \[em] the encoding sends a fraction of a zone, and one frame alone is
|
|
ambiguous by hundreds of miles \[em] so an aircraft is placed once an even and an
|
|
odd frame have both arrived, about a second apart.
|
|
.PP
|
|
An aircraft is overhead for four minutes and then gone, so everything heard is
|
|
written down as it arrives: a JSON Lines log, one object per frame, in
|
|
.I adsb_<time>.jsonl
|
|
in the output directory, with the raw hexadecimal of every frame kept beside
|
|
what was read out of it \[em] the frame is the evidence and the rest of the line
|
|
is an opinion about it. The log is flushed as it is written, because a
|
|
listening session ends with control-C. Beside it goes a readable report, one
|
|
block per aircraft.
|
|
.PP
|
|
.B \-\-frames
|
|
prints each frame as it arrives instead of a running count,
|
|
.B \-\-no\-log
|
|
listens without writing anything down,
|
|
.B \-\-kml
|
|
writes the flight paths for Google Earth and
|
|
.B \-\-map
|
|
draws the animation when the listening stops.
|
|
.B \-\-simulate
|
|
flies six imaginary aircraft past an imaginary receiver \[em] real frames, real
|
|
checksums, the same decoder \[em] for trying all of this without an aerial;
|
|
.BI \-\-near " LAT,LON"
|
|
says where they are flying. An aerial cut for 1090 MHz makes the difference
|
|
between hearing the airport and hearing the county; the whip supplied with a
|
|
dongle is a quarter of the length it wants.
|
|
.SS While it listens
|
|
The screen is a live board of what is overhead: one line per aircraft, in the
|
|
order they were first heard, with everything the frames have said \[em] callsign,
|
|
address, height with an arrow for climb or descent, ground speed, track as
|
|
degrees and a point of the compass, position \[em] and a counter that climbs as
|
|
frames arrive. Height is coloured low warm to high cold, and the age of the
|
|
last frame green, then yellow, then red.
|
|
.PP
|
|
An aircraft that has not been heard from for
|
|
.B \-\-hold
|
|
seconds is removed from the board and everything below it moves up: the board
|
|
is the sky now, not a list of everything ever heard. Nothing is lost by it, as
|
|
the log holds every frame and the report at the end lists every aircraft.
|
|
.PP
|
|
The registers are asked while the listening runs, so the registration, type,
|
|
operator and route appear on the line as the answers arrive. A narrow terminal
|
|
drops the columns a website supplied and keeps the ones only the aircraft can
|
|
give.
|
|
.B \-\-frames
|
|
prints the raw stream instead, and output that is not a terminal gets a plain
|
|
running count rather than a display that redraws four times a second.
|
|
.PP
|
|
.BI \-\-speed\-unit " knots|mph|kph"
|
|
changes what speeds are shown in: the heading on the live display, the speed
|
|
written beside every aircraft on the map, and the speeds in the report. The
|
|
distances move with it \[em] nautical miles with knots, statute miles with miles
|
|
an hour, kilometres with km/h \[em] so that one picture never carries two
|
|
different miles. The log always holds knots, because that is what the aircraft
|
|
broadcast: the recording stays the thing that arrived and the conversion
|
|
happens at the moment of showing it to somebody.
|
|
.SS A window, while it happens
|
|
.B \-\-window
|
|
opens a window instead of drawing a table in the terminal: a real map with the
|
|
aircraft moving on it as the frames arrive, and beside each one a box giving
|
|
its type and registration, who operates it, where it came from and where it is
|
|
going \[em] each end with its country's flag \[em] its height and rate of climb,
|
|
its speed and heading, how far away it is
|
|
and on what bearing, its position, how many frames it has sent and how long
|
|
ago the last one was. The boxes are placed so that they cover neither each
|
|
other nor another aircraft, and long names are folded rather than allowed to
|
|
stretch one \[em] a route between two airports under their full names runs to
|
|
sixty characters, and breaks at the arrow so that the two ends of the flight
|
|
stay whole.
|
|
.PP
|
|
A box keeps its place for as long as that place still works and is moved only
|
|
when an aircraft or another box genuinely takes it, which is about a third as
|
|
many moves as laying every box out afresh each frame. The moves that are left
|
|
are eased over about half a second rather than jumped, since a box that
|
|
teleports reads as a different box, and the window redraws at thirty frames a
|
|
second for as long as anything is moving and drops back to five when it
|
|
stops. That is affordable because the ground is dimmed once and kept: cutting
|
|
the view out of the fetched map and looking every level up in the palette is
|
|
most of a tenth of a second over two megapixels, and nothing about it changes
|
|
between frames unless the view, the window, the brightness or the map itself
|
|
has. What the next box is laid out against is the place a moving box is
|
|
going to, not the place it has reached, as otherwise its neighbours would
|
|
move as well and move back when it arrived; and a box in motion is drawn over
|
|
the ones standing still, so that it stays readable while it crosses them.
|
|
.PP
|
|
.B d
|
|
cycles how much each box says, for a busy sky;
|
|
.B t
|
|
turns the trails off,
|
|
.B g
|
|
the map underneath,
|
|
.B [
|
|
and
|
|
.B ]
|
|
its brightness,
|
|
.B +
|
|
and
|
|
.B \-
|
|
the range, and
|
|
.B q
|
|
closes it. Closing the window leaves exactly the files a passive capture
|
|
leaves, because it is the same code with a different thing watching it: the
|
|
receiver runs on its own thread, so a slow repaint cannot cost a frame.
|
|
.PP
|
|
Qt is asked for and not required \[em] PyQt6, PyQt5, PySide6 and PySide2 are
|
|
all tried. Without any of them this window is the only thing lost, and the
|
|
program says how to get one rather than failing.
|
|
.SS From the menus
|
|
Running
|
|
.B bandsaunter
|
|
with no arguments and choosing
|
|
.B 5
|
|
.RB ( "Aircraft (ADS-B)" )
|
|
does all of this without a command line. Every option is listed on one screen
|
|
with a line saying what it does;
|
|
.BI ? N
|
|
explains one at length, including the flag it corresponds to,
|
|
.B p
|
|
starts a passive capture,
|
|
.B r
|
|
opens the window,
|
|
.B m
|
|
draws a map from any log in the recordings directory, and
|
|
.B s
|
|
saves the options to
|
|
.IR ~/.config/bandsaunter/aircraft.yaml .
|
|
.SS Not a scan
|
|
The band plan lists 1090 MHz because that is where ADS-B is, but sweeping it
|
|
records the bursts as clicks in a WAV file and decodes nothing: the signalling
|
|
is a megabit a second and the scan path is twelve and a half kilohertz wide.
|
|
Both the scanner and the menus say so when a sweep is pointed at 1090 MHz or
|
|
at the 978 MHz UAT band, rather than letting it run silently. Scanning it
|
|
anyway is a fair thing to want if what you are after is the raw spectrum;
|
|
.B \-\-save\-iq
|
|
keeps the samples.
|
|
.SS Who the aircraft is
|
|
The frames say an address, not a registration. Two registers are asked \[em]
|
|
adsbdb for the airframe and the route, then hexdb \[em] and the answers are
|
|
cached for a month. Nothing is sent to either but the address or the callsign
|
|
that was heard on the air.
|
|
.PP
|
|
What can be answered without asking anybody is answered without asking. The
|
|
address block says which country registered the aircraft, fixed by treaty, and
|
|
the first three letters of an airline callsign are its ICAO designator.
|
|
.B \-\-no\-lookup
|
|
stops at that.
|
|
.PP
|
|
A callsign is a flight number rather than a leg. An airline runs the same
|
|
number over several legs in a day and a register holds one route for it, so an
|
|
aircraft crossing Arizona is quite often handed a half-hour hop between two
|
|
airports in Texas; the two registers routinely disagree about the same flight
|
|
number, and both are snapshots years old. Nothing on the air settles it, as
|
|
ADS-B carries no origin or destination: an aircraft broadcasts who and where
|
|
it is, not where it is going.
|
|
.PP
|
|
So a route the aircraft cannot be flying is left off the map and out of the
|
|
window \[em] the two ends are known, and an aircraft on a route is never much
|
|
further along it than the route is long \[em] and written in the report with a
|
|
note saying so, since it is what the register holds for that flight number and
|
|
worth having. Where a source lists a whole day's stops rather than a leg, the
|
|
aircraft's own position picks the leg out; where no leg fits, none is claimed.
|
|
.SS Schedule services
|
|
Knowing the leg for certain needs live schedule data, which none of the free
|
|
sources carry. Four commercial services are wired up and all four are
|
|
optional: FlightAware AeroAPI, Flightradar24, OAG and Cirium. Each holds the
|
|
timetable and the day's movements, so each can say which leg of a flight
|
|
number was in the air at the moment an aircraft was overhead. Where one
|
|
answers, its leg is used; where none does, the free databases answer as they
|
|
always did, and a program with no keys set behaves exactly as before.
|
|
.PP
|
|
Keys are read from the environment rather than the settings file, because a
|
|
settings file is meant to be copied between machines and pasted into a message
|
|
asking for help, and an API key is not.
|
|
.PP
|
|
.nf
|
|
BANDSAUNTER_AEROAPI_KEY FlightAware AeroAPI
|
|
BANDSAUNTER_FR24_TOKEN Flightradar24
|
|
BANDSAUNTER_OAG_KEY OAG Flight Info
|
|
BANDSAUNTER_CIRIUM_APP_ID Cirium (FlightStats), with
|
|
BANDSAUNTER_CIRIUM_APP_KEY
|
|
.fi
|
|
.PP
|
|
.BI \-\-schedules " NAMES"
|
|
picks which to ask and in what order, comma separated, from
|
|
.BR flightaware ", " flightradar24 ", " oag " and " cirium ;
|
|
the default asks every one that has its key. A service with no key is skipped
|
|
rather than asked and refused. The callsign and the moment are all that is
|
|
sent.
|
|
.PP
|
|
Each reader was written from its service's published response shape and
|
|
tested against that shape; none has been run against a live service, since
|
|
each wants a paid account. So each is written to find what it recognises and
|
|
return nothing otherwise: a service that has changed since costs a route
|
|
rather than a scan, and the free databases pick the question back up.
|
|
.SS The moving map
|
|
.B bandsaunter flights
|
|
reads a log back \[em] the newest one in the output directory unless told
|
|
otherwise \[em] prints the report and draws the whole evening as a map with the
|
|
clock running.
|
|
.PP
|
|
Every frame of the animation is a moment: each aircraft is drawn where it
|
|
actually was then, interpolated between the position reports either side of it
|
|
and dead-reckoned from its last known speed and heading where none arrived, so
|
|
an aircraft crossing the picture in ten seconds took the twenty minutes the
|
|
data says it took. An aircraft not heard from for
|
|
.B \-\-stale
|
|
seconds stops being drawn rather than being flown on by guesswork.
|
|
.PP
|
|
.BI \-\-speed " X"
|
|
is seconds of flying per second of animation;
|
|
.BI \-\-seconds " N"
|
|
works that out from how long the animation should run instead.
|
|
.B \-\-out
|
|
takes a
|
|
.IR .gif ,
|
|
an
|
|
.I .mp4
|
|
where ffmpeg is installed, or a
|
|
.I .png
|
|
for the whole evening in one picture. Altitude is the colour, low warm to high
|
|
cold. The GIF is written from first principles \[em] a palette, an LZW stream
|
|
and frame differencing \[em] so nothing but numpy is needed to draw one.
|
|
.PP
|
|
Beside each aircraft goes its flight level and speed, its type and
|
|
registration, and the two ends of its route, each with a small flag of the
|
|
country the airport is in. The flags are twelve pixels by eight and come from
|
|
a table rather than a network: at that size a flag is the arrangement that
|
|
makes one recognisable rather than a rendering of the real thing. A country
|
|
not in the table is named by its two letters instead, since a flag that is
|
|
nearly another country's is worse than none. Where a route arrives as nothing
|
|
but a pair of airport codes the country comes from the code, the first letter
|
|
or two of an ICAO code being a region.
|
|
.SS How far the map reaches
|
|
The picture is framed on the receiver rather than on whatever was heard. An
|
|
aerial reaches a hundred miles on a good day and a position that decoded
|
|
wrongly can land anywhere on Earth, so a map drawn to fit everything heard is
|
|
drawn to fit the mistakes: the aircraft come out a pixel wide in the middle of
|
|
an empty continent.
|
|
.PP
|
|
.BI \-\-radius " MILES"
|
|
is how far the map reaches, in the same unit as the speeds, and defaults to a
|
|
hundred; zero goes back to fitting whatever turned up. The centre is the
|
|
median of everything heard \[em] a receiver hears aircraft all round it, and a
|
|
median cannot be dragged anywhere by a handful of bad positions \[em] or
|
|
.BI \-\-at " LAT,LON"
|
|
says where the receiver is, which is worth doing to keep the same frame every
|
|
night. Positions outside the radius are left off the drawing, one at a time
|
|
rather than one aircraft at a time, so a single bad fix in the middle of a
|
|
real flight does not take the flight with it. Nothing is dropped from the log.
|
|
.SS Positions that never happened
|
|
A position is sent as half a position \[em] an even frame and an odd one \[em] and
|
|
the pair only means anything while the aircraft has not moved between them.
|
|
Logs written before this version paired them however old they were, so an even
|
|
frame kept from ten minutes ago decoded against a fresh odd one to a place on
|
|
the wrong side of the world and wrote it down as confidently as a real one.
|
|
.PP
|
|
.B \-\-recheck
|
|
reads such a log back and keeps, for each aircraft, the longest run of
|
|
positions that could describe one aeroplane. It is deliberately not a forward
|
|
walk dropping whatever disagrees with the last position kept: one bad fix then
|
|
becomes the reference and it is the truth that gets discarded. Nothing in the
|
|
log is changed.
|
|
.PP
|
|
An aircraft that goes quiet for five minutes and is heard again a long way off
|
|
is an aeroplane rather than an error, and is not second-guessed; the radius is
|
|
what keeps those off the picture. New logs need none of this, as the decoder
|
|
now refuses a stale pair, a position that is not on Earth, and one the
|
|
aircraft could not have reached, as the frames arrive.
|
|
.SS The ground under it
|
|
A real map is drawn under the aircraft: standard {z}/{x}/{y} raster tiles,
|
|
OpenStreetMap by default, fetched the first time an area is drawn and
|
|
reprojected from Web Mercator onto the picture, inverted and dimmed so the
|
|
aircraft stay the brightest thing on it. The tiles are decoded here, from
|
|
zlib and the five row filters the PNG specification defines, with no imaging
|
|
library.
|
|
.PP
|
|
Tiles are cached in
|
|
.I ~/.cache/bandsaunter/tiles
|
|
and never fetched twice, every request identifies this program in its
|
|
User-Agent, and the attribution the tiles require is written onto the picture
|
|
\[em] a GIF travels without the readme that would otherwise carry it.
|
|
.PP
|
|
The finished map is cached as well, in
|
|
.IR ~/.cache/bandsaunter/ground .
|
|
The tiles always were, so a second evening on the same view has never touched
|
|
the network, but it still cost decoding forty PNGs and resampling a megapixel
|
|
and a half into this program's own projection every time a window opened, for
|
|
an answer that cannot have changed. On a hundred-and-fifty-mile view that is
|
|
0.61 seconds become 0.01. Both windows and both kinds of still picture share
|
|
it. A map with squares missing is not kept, since caching a hole would keep it
|
|
for a month. The whole cache is pruned to four hundred megabytes whenever a
|
|
map is written, least recently used first.
|
|
.PP
|
|
The zoom is chosen from how wide the picture is, not from the area alone, so a
|
|
map asked for at 1920 pixels fetches finer tiles than the same map asked for
|
|
at 960. Half again over the width is fetched deliberately and averaged down,
|
|
since a downscaled tile is sharp and an upscaled one is not.
|
|
.PP
|
|
The window fetches a little more world than it shows so that panning does not
|
|
leave the ground blank, and fetches that bigger piece at the bigger piece's
|
|
own size, so what is shown comes out pixel for pixel with the screen. At 1920
|
|
by 1080 and a hundred-mile radius the tiles hold about 1.6 times the pixels
|
|
the window wants. A drawing is capped at a couple of hundred tiles, which at
|
|
3840 by 2160 is reached: there the zoom has stopped climbing and the map is
|
|
enlarged after all, and a smaller radius buys the detail back.
|
|
.PP
|
|
The window opens maximised \[em] this is a map, and the thing anybody wants
|
|
more of is map. Un-maximising gives back a usable window, the restored size
|
|
being set before it maximises rather than left to the toolkit to guess.
|
|
.B f
|
|
goes to true full screen and back to maximised, and is written along the top of
|
|
the screen because a window with no frame is one somebody has to know a key to
|
|
get out of. Maximised rather than full screen by default, because the title bar
|
|
is where the band and the frequency are written.
|
|
.PP
|
|
A window made bigger fetches a sharper map. The map underneath is fetched for
|
|
the size of the window at the time, and a map of the right piece of world goes
|
|
on being one however far it is then stretched, so nothing else notices. A
|
|
window opened at its default size and taken to the whole screen used to keep
|
|
the map it started with until an aircraft wandered far enough to move the view
|
|
out of the fetched box. It now compares map pixels per degree in hand against
|
|
what the view wants and asks for a better one when it is being blown up by more
|
|
than fifteen per cent \[em] per degree rather than in raw pixels, because the
|
|
fetched box is a quarter wider than the view, so a map with as many pixels as
|
|
the window is wide has only four fifths of them on the screen. The request is
|
|
keyed on the window's size, so once answered nothing more is asked, which is
|
|
what stops a window larger than the tile budget can cover from asking all
|
|
evening.
|
|
.PP
|
|
Resizing the window is the demanding case: a wider picture picks a sharper
|
|
zoom and a hundred tiles that have never been on this disk are asked for at
|
|
once, whereupon a busy server refuses some of them. A tile that does not
|
|
arrive leaves its square of the canvas black, and black is not neutral here
|
|
\[em] the brightness is inverted on the way in, so the darkest possible square
|
|
came out as the brightest thing on the picture, dragged the floor of the map's
|
|
own contrast down with it, and stayed there for the life of the view. Instead
|
|
the missing squares are asked for again at once, and only those, the rest
|
|
being on the disk by then; whatever is still missing is drawn as bare ground
|
|
and left out of the reckoning when the darkest and brightest of the map are
|
|
worked out; and the map is kept as provisional rather than as the last word,
|
|
asked for again half a minute later, four attempts in all, each retrying its
|
|
own misses once, so a square gets eight chances before one that will not come
|
|
is accepted as one that is not there.
|
|
.PP
|
|
The politeness pause between requests is paid only on a tile that had to be
|
|
fetched. Paid on every tile, as it had been, it put twenty-six seconds of
|
|
sleeping into redrawing a view whose tiles were all in hand.
|
|
.PP
|
|
.B \-\-no\-basemap
|
|
draws the tracks on their own,
|
|
.BI \-\-tiles " URL"
|
|
points at another server, and where there is no network and nothing cached
|
|
the picture falls back to the plain grid.
|
|
.PP
|
|
An aircraft that goes quiet fades rather than vanishing: taking it off the
|
|
picture between one frame and the next says it stopped existing, and fading it
|
|
says it stopped talking, which is what happened. It fades where it was last
|
|
actually seen and never along a reckoned track, since the reason for giving up
|
|
on it is that where it would be by now is a guess.
|
|
.BI \-\-fade " SECONDS"
|
|
is how long that takes, and zero takes it away at once.
|
|
.PP
|
|
The map is averaged down to the size of the picture rather than point-sampled,
|
|
so lettering and roads stay whole, and the window fetches enough pixels to
|
|
cover its margin at full detail rather than enlarging what it has.
|
|
.BI \-\-map\-brightness " PERCENT"
|
|
is how far up its range the map is drawn: dark enough that the aircraft stay
|
|
the brightest thing on the picture, light enough that a coastline can be made
|
|
out, and which way to err depends on the screen.
|
|
.PP
|
|
Every aerodrome under the picture is marked, not only the ones being flown
|
|
between \[em] a receiver hears aircraft over its own county, and the county's
|
|
airports say where on the map you are looking. They come from the same map
|
|
data the tiles are drawn from, asked once per area and kept for a month.
|
|
.B \-\-no\-airports
|
|
turns that off. They are drawn magenta, which nothing else on the picture is:
|
|
the old amber sat sixteen units of CIELAB from the altitude ramp's yellow,
|
|
which is to say it was the same colour, and an aeroplane low over a field was
|
|
drawn in the field's own colour. The ramp already spends red, amber, green,
|
|
cyan and violet on height; magenta is what it leaves free, and is what an
|
|
aeronautical chart marks an aerodrome in anyway.
|
|
.SS What is beside each aircraft
|
|
Its height in feet with the unit on it, rounded to the twenty-five feet Mode S
|
|
reports altitude in, so that a moment interpolated between two reports stops
|
|
claiming to know the height to the foot; its speed; what sort of aircraft it
|
|
is; its type and registration; and the two ends of the route, each with the
|
|
flag of the country its airport is in. The country of registration gets a flag
|
|
too, from the register where one answered and otherwise from the address
|
|
block, so it is there for an aircraft no register has heard of.
|
|
.PP
|
|
What sort of aircraft it is comes from two places. Every identification
|
|
message carries three bits under its type code saying what is transmitting
|
|
\[em] light, small, large, high vortex, heavy, high performance, rotorcraft,
|
|
and under another type code glider, airship, parachutist, ultralight, drone,
|
|
spacecraft, or a vehicle on the ground \[em] and that is the only word about
|
|
what an aircraft is that needs no register. Which list the three bits index
|
|
depends on the type code, and zero means the aircraft declined to say, which
|
|
is answered with nothing rather than a guess.
|
|
.PP
|
|
Whether it is military comes off no air at all, as no aircraft broadcasts it
|
|
and a tanker calls itself heavy exactly as an airliner does. It is read from
|
|
the address instead, since states set aside blocks of their national range for
|
|
their armed forces. A state can fly a military aircraft on a civil address
|
|
whenever it likes, so this finds nobody who does not want to be found, and the
|
|
table holds the allocations a receiver in the ordinary world hears rather than
|
|
every one that exists.
|
|
.PP
|
|
A label keeps its place for as long as that place still works and is moved
|
|
only when something takes it, which is about half as many moves as deciding
|
|
afresh every frame; the moves that are left are eased over about half a second
|
|
of playback rather than jumped, and what the next label is laid out against is
|
|
where a moving one is going rather than where it has reached. A still picture
|
|
has no frame before it and places its labels exactly as it always did. The
|
|
whole box fades with its aircraft: an indexed picture cannot blend, so the row
|
|
grey and all twelve flag colours have dimmed copies at each fade step.
|
|
.SS What is on the picture besides the aircraft
|
|
The line from an information box to the aircraft it belongs to is dashed and
|
|
is its own colour, in the window and in the animated pictures alike. Drawn in
|
|
the aircraft's own colour it came out the same colour as that aircraft's
|
|
trail, and a straight solid line running out of an aeroplane in the colour of
|
|
the path behind the aeroplane reads as more path, which on a busy picture is a
|
|
heading nobody flew. The animation had no such line at all until now, so a
|
|
label pushed out into one of the outward rings by a crowd had nothing tying it
|
|
to the aeroplane it was about.
|
|
.PP
|
|
A red flag stands where the receiver is, on the window and on the animated
|
|
pictures alike, taken from the coordinates in the settings. The foot of the
|
|
pole is the position and the pennant flies up and to the right of it, so that
|
|
nothing the flag is made of covers the place it points at. It is pure red in
|
|
every theme, that being the one mark on the picture whose meaning must not
|
|
change with the colours as well as the red furthest from every altitude
|
|
colour. It is drawn only where the receiver was actually told where it is: a
|
|
middle worked out from whatever flew past is not a place anybody is standing.
|
|
.SS The options menu
|
|
The aircraft options are in six groups \[em] receiver, listening, aircraft,
|
|
animation, the map, and labels \[em] rather than in one list, thirty-three of
|
|
them on a screen being a wall rather than a menu. A number opens a group;
|
|
inside it a number changes an option and
|
|
.BI ? N
|
|
explains one at length. The numbers are the option's place in the whole list,
|
|
so the same number means the same option wherever it is typed. Typing a name
|
|
instead goes straight to that option, and part of a name lists everything it
|
|
could mean; a name that matches exactly wins outright, so "speed" reaches the
|
|
setting called speed rather than that one and every other whose description
|
|
mentions the word.
|
|
.SS The card behind a box
|
|
.BI \-\-box\-opacity " PERCENT"
|
|
is how solid the card behind each information box is. The words beside an
|
|
aircraft are readable over water and not over a city, so a card goes behind
|
|
them: at nothing they sit straight on the map and at the whole way the map
|
|
does not show through at all. An indexed picture cannot blend, so in the
|
|
animation this darkens the ground under the box instead, which leaves the
|
|
coastline faintly visible through it. The animated pictures had no card at all
|
|
before, so nothing is what they used to look like.
|
|
.PP
|
|
The flag marking the receiver is drawn after everything else on both pictures
|
|
\[em] after the aircraft, their trails and their boxes \[em] since it says
|
|
where the receiver is standing and that is the one mark that must not end up
|
|
behind an aeroplane that happened to fly over it. A vector theme's halo cannot
|
|
cover it either, a halo only ever going on the ground, the grid and the
|
|
background.
|
|
.SH AIRCRAFT OPTIONS
|
|
Every option the ADS-B side takes, in the six 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.
|
|
.AIRCRAFT_OPTIONS_HERE
|
|
.SS Pulsing and echoes
|
|
.B \-\-pulse
|
|
swells each aircraft from bright to dim and back. At the top of the swell it
|
|
burns: drawn in a set of peak colours and wearing a halo grown out of its own
|
|
shape, which is what a phosphor does when the beam sits in one place a little
|
|
too long. The halo is the aeroplane itself spread outward a pixel at a time
|
|
rather than a circle drawn round it, so the glow has the shape of the thing
|
|
casting it, and it goes only where the picture was still empty.
|
|
.PP
|
|
.B \-\-echo
|
|
sends a ring travelling outward from each aircraft, growing and dimming as it
|
|
goes \[em] what a radar repeater does, and what the eye reads as this thing is
|
|
transmitting, which is exactly what an aeroplane on this picture is doing
|
|
twice a second. One ring at a time per aircraft.
|
|
.PP
|
|
.BI \-\-pulse\-rate " SECONDS" ,
|
|
.BI \-\-echo\-every " SECONDS"
|
|
and
|
|
.BI \-\-echo\-size " PIXELS"
|
|
set the rest. The two times are seconds of watching rather than of flying, so
|
|
a pulse looks the same whatever speed an evening is being run through. Each
|
|
aircraft is offset by its own address, so a sky full of them swells and rings
|
|
separately rather than beating as one, and an aeroplane keeps its own rhythm
|
|
from one drawing of the same log to the next. Only an aircraft still being
|
|
heard pulses: one that has gone quiet is fading, and a thing that is fading
|
|
and beating at once says two contradictory things about itself.
|
|
.PP
|
|
The window can blend and its swell is continuous. The animation cannot, a GIF
|
|
being indexed colour, so there the swell is the handful of steps a palette
|
|
allows \[em] which family of colours the aeroplane is drawn from, and how far
|
|
its halo reaches.
|
|
.SS Range rings
|
|
.B \-\-rings
|
|
puts faint discs at a quarter, a half and three quarters of the radius,
|
|
concentric on the receiver and each labelled with its distance. They are
|
|
translucent and they stack, so the ground inside the innermost is lifted three
|
|
times, the next twice and the outer once; what that gives is a sense of how
|
|
far away a thing is without measuring anything, an aircraft two shades in
|
|
being about halfway to the edge of what this receiver hears. An indexed
|
|
picture cannot blend, so translucent there means moving the ground under the
|
|
disc a step or two up its own ramp of shades, which keeps the coastline and
|
|
the roads visible through it.
|
|
.PP
|
|
They need a receiver position and a radius and are not drawn without both.
|
|
.B \-\-window\-rings
|
|
is the same thing on the realtime window, kept as a separate setting because
|
|
a picture is studied and a window is glanced at.
|
|
.SS Themes
|
|
.BI \-\-theme " NAME"
|
|
changes the window and the animated pictures together, since both read their
|
|
colours out of the same palette.
|
|
.B night
|
|
is the default: a night-blue ground with height as colour, low warm to high
|
|
cold, which is what every other aircraft map does and is the easiest to read.
|
|
.BR digital ", " phosphor ", " amber " and " red
|
|
are the screens the phrase "air defence display" calls to mind \[em] a black
|
|
tube, one phosphor, and thin bright vector lines with a halo round them.
|
|
.PP
|
|
Three things follow from having one colour to spend, and they are constraints
|
|
rather than decoration. Height becomes brightness, since hue is no longer
|
|
free: low is dim and high burns. The map underneath is drawn at about
|
|
two-fifths of the brightness asked for, because a tinted photograph of a
|
|
county behind the vectors is the one thing that stops a vector display looking
|
|
like one. And a country is named in two letters rather than drawn as a flag,
|
|
a flag being half a dozen colours.
|
|
.PP
|
|
A vector display draws by holding a beam on the phosphor, which spreads the
|
|
light a little and keeps glowing after the beam has gone, so a line on one of
|
|
those screens is a bright core inside a halo. The window does that by laying
|
|
the same line down two or three times, wider and fainter each pass, and the
|
|
core last. The animation cannot blend at all, a GIF being indexed colour, so
|
|
it dilates what it has drawn and fills the halo with the dimmed copy of the
|
|
colour underneath: an aeroplane glows into the colour its own trail is drawn
|
|
in, which is the colour a phosphor would have spread into. The halo goes over
|
|
the map, the grid and the background and over nothing else that was drawn.
|
|
.SH METERS AND SENSORS
|
|
Two things on the ISM bands are worth naming rather than reporting as
|
|
hexadecimal.
|
|
.PP
|
|
The Itron ERT modules fitted to electricity, gas and water meters across North
|
|
America broadcast their reading every thirty seconds or so on 902-928 MHz, in
|
|
the clear, so that a van can drive past and read a street. The message says
|
|
which meter, what kind, what the register reads and whether the tamper
|
|
switches have been tripped, and carries a sixteen-bit BCH check.
|
|
.PP
|
|
The AcuRite 433.92 MHz outdoor sensors sold with every consumer weather
|
|
station send temperature, humidity, battery state and a channel letter every
|
|
sixteen seconds, with a checksum and four parity bits.
|
|
.PP
|
|
Neither is guessed at: nothing is reported that has not satisfied its own
|
|
checksum. Both are implemented from their published descriptions and checked
|
|
against frames built from the same descriptions, which proves the framing and
|
|
the arithmetic and is not the same as having held a meter.
|
|
.SH THE MAP
|
|
A callsign is looked up in the FCC's published licence data, which gives the
|
|
licensee, the town, and coordinates. They arrive from three directions and
|
|
all three end up in the same place: spoken and transcribed, sent in Morse, or
|
|
carried in the header of an APRS packet. None of the last two involves a
|
|
speech recogniser, so a machine with none installed still builds a map. Those go into a
|
|
KML file in the output directory \[em]
|
|
.I callsigns.kml
|
|
unless
|
|
.B \-\-kml
|
|
names another \[em] which opens in Google Earth,
|
|
.BR qgis (1),
|
|
.BR marble (1)
|
|
and OsmAnd.
|
|
.PP
|
|
One placemark per station, not one per transmission: the same repeater heard
|
|
twenty times in an evening is one operator, and twenty pins on the same
|
|
rooftop would say less than one. Each pin carries the callsign, the licensee,
|
|
where they are licensed, and every frequency and time you heard them.
|
|
.PP
|
|
The file is added to, by this scan and by later ones, so it builds up into a
|
|
picture of what the aerial can actually reach rather than a snapshot of one
|
|
evening.
|
|
.PP
|
|
Only the callsign is sent, and each is asked about once and then remembered
|
|
under
|
|
.IR ~/.cache/bandsaunter/ ,
|
|
so a net recorded night after night is looked up once.
|
|
.B \-\-no\-callsign\-lookup
|
|
stops it contacting anything at all; callsigns are still found, and the
|
|
prefix still says which country and which US district they belong to. Setting
|
|
.B \-\-kml
|
|
to nothing turns the map off.
|
|
.PP
|
|
US amateur licence records are public by law and include the licensee's
|
|
address. That is what is written.
|
|
.SH HF RECEPTION
|
|
These receivers cannot normally tune below about 24 MHz. Below that they can
|
|
sample the antenna directly instead, which opens up shortwave: broadcast,
|
|
amateur HF, marine, aviation. It is switched on automatically when a scan
|
|
goes below 24 MHz. A direct connection to a suitable antenna is needed; the
|
|
whip supplied with most dongles will hear very little.
|
|
.SH SINGLE SIDEBAND
|
|
Single sideband is the one mode where tuning must be exact: its demodulator
|
|
is a filter that opens at the suppressed carrier, so tuning to the middle of
|
|
the voice discards its lower half and shifts the rest. bandsaunter measures
|
|
where the carrier is rather than assuming, and identifies upper from lower
|
|
sideband by which way the signal's energy leans, so
|
|
.B \-\-mode usb
|
|
is not needed. The frequency in the filename is the carrier \[em] the
|
|
frequency to dial into a radio.
|
|
.SH WEATHER SENSORS
|
|
A consumer weather station is two things. The display on the kitchen wall is
|
|
one of them; the other is a plastic box on a fence post that says what it can
|
|
see every sixteen seconds, in the clear, on 433.92 MHz, to anyone who happens
|
|
to be listening.
|
|
.B bandsaunter weather
|
|
reads the box.
|
|
.PP
|
|
It is a mode of its own, like the aircraft one, and for the same reason: it
|
|
does not fit through the scanner. A sensor message is a burst of a carrier
|
|
switched on and off, a fifth of a second long, and the scan path is a squelch
|
|
and a recorder \[em] it would record the bursts as clicks in a WAV file and
|
|
decode nothing.
|
|
.SS What it reads
|
|
Five families, each with its own framing and its own check.
|
|
.TP
|
|
.B "Tower 592TXR / 06002RM"
|
|
Seven bytes: temperature and humidity.
|
|
.TP
|
|
.B "5-in-1 06014RM / VN1TXC"
|
|
Eight bytes, in two kinds sent alternately: wind speed with wind direction and
|
|
rainfall, or wind speed with temperature and humidity. It has more to say than
|
|
fits in one message, so the display keeps the newest value of each quantity
|
|
rather than the newest message.
|
|
.TP
|
|
.B "Lightning 6045M"
|
|
Nine bytes: temperature, humidity, the cumulative strike count, and how far
|
|
off the storm is. A bit set when the detector believes it is being interfered
|
|
with is shown too, because a strike count that climbs while it is set is not
|
|
lightning.
|
|
.TP
|
|
.B 609TXC
|
|
Five bytes: temperature and humidity.
|
|
.TP
|
|
.B 606TX
|
|
Four bytes: temperature, and nothing else at all.
|
|
.PP
|
|
Battery state comes from all of them. The Atlas, the 986 and 515 fridge
|
|
thermometers, the 00275rm room monitor and the 899 standalone rain gauge are
|
|
on the same band and are not decoded; a message from one whose framing happens
|
|
to match is reported as an unknown message type with its identity and nothing
|
|
else, rather than guessed at.
|
|
.PP
|
|
These formats are implemented from their published descriptions and are
|
|
checked against frames built from the same descriptions, which proves the
|
|
framing, the parity, the checksums and the arithmetic and proves nothing about
|
|
anything a description and an implementation of it both get wrong. The tower
|
|
sensor is additionally checked against messages recovered from real hardware,
|
|
byte for byte.
|
|
.SS Naming a sensor
|
|
A sensor broadcasts an identity, and that identity is a number that came out
|
|
of a hat in a factory \[em] or a different number out of the same hat the next
|
|
time the batteries were changed. It tells one sensor from another and is no
|
|
use at all for telling which is which.
|
|
.PP
|
|
It is shown in both bases. These identities are bit fields with the channel
|
|
packed above them, so this prints them in hexadecimal where that shape shows,
|
|
while rtl_433 and everything built on it prints them in decimal: 3935 and
|
|
14645 are the same sensor. Anyone arriving with a list of their own already
|
|
has it in decimal, so
|
|
.B bandsaunter sensors
|
|
puts the two side by side and either may be typed at
|
|
.BR \-\-name .
|
|
An identity that is a valid number in both bases is reported as ambiguous
|
|
rather than resolved by guesswork.
|
|
.PP
|
|
So press
|
|
.B n
|
|
while listening. The display comes down, the sensors are listed with numbers,
|
|
you pick one and type a name, and it goes back up. The receiver keeps running
|
|
throughout: a slow typist loses a few seconds of weather and nothing else.
|
|
That is the moment it is possible to do \[em] the sensor is on the screen
|
|
saying 3.1 degrees, and the person watching is the one who knows that the cold
|
|
one is the shed.
|
|
.PP
|
|
Names can also be given with
|
|
.BI \-\-name " ID=NAME"
|
|
on
|
|
.B "bandsaunter weather"
|
|
or
|
|
.BR "bandsaunter sensors" ,
|
|
before or after anything has been heard: a name given before the sensor has
|
|
ever been received waits under its identity alone, because nothing yet knows
|
|
which model it is, and moves across the moment the first message arrives. They
|
|
live in
|
|
.I sensors.yaml
|
|
beside the settings, are written the moment they are given rather than when
|
|
the program exits, and are written to a neighbouring file which is renamed
|
|
over the old one, so a machine losing power halfway through leaves either the
|
|
old names or the new ones and never half of each. Nothing is ever dropped for
|
|
being stale.
|
|
.SS Why nothing false gets through
|
|
433 MHz is a crowded band \[em] doorbells, car keys, tyre-pressure sensors,
|
|
garage doors \[em] and a decoder that looks at every bit offset of every burst
|
|
will find a message in noise if it is allowed to. Four things stop it.
|
|
.PP
|
|
The three newer models carry an eight-bit sum plus even parity in the top bit
|
|
of every payload byte, which is twelve to fourteen bits of check. Even and not
|
|
odd: that one bit of convention was wrong here and the cost was that nothing
|
|
decoded at all, every other check in the format passing and saying so.
|
|
.PP
|
|
The two older models carry one byte of check between them, which is one false
|
|
message in two hundred and fifty-six, so those two are only believed when the
|
|
same message arrives twice. It costs nothing: these sensors send everything
|
|
three times in a row, for exactly this reason.
|
|
.PP
|
|
Nothing outside what the hardware can report is accepted \[em] no temperature
|
|
beyond \-40 to 70 \[de]C, no humidity above 100 per cent, no wind the
|
|
anemometer cannot physically produce.
|
|
.PP
|
|
And a message must sit where a message sits. A seven-byte message read out of
|
|
the front of a real eight-byte one is made of that message's own payload
|
|
bytes, whose parity is already correct, so the parity bits contribute nothing
|
|
and one byte of sum is all that is left. Corroboration does not help either,
|
|
the copies of a message being identical. What gives that window away every
|
|
time is that it ends a whole byte before the burst does.
|
|
.SS Getting it off the air
|
|
The receiver is tuned straight at 433.92 MHz, at 250 kS/s, with the tuner's own
|
|
gain control doing its job and the RTL2832's digital AGC left off, which is
|
|
what the established tools for this band do.
|
|
.PP
|
|
The digital AGC is off because it pumps: it winds the gain up through the
|
|
silence between one burst and the next, lifting the noise towards the signal
|
|
and squeezing the difference this depends on. It matters here in a way it does
|
|
not for aircraft, where a frame is found by correlating a preamble over a few
|
|
microseconds rather than by comparing a burst with the quiet around it.
|
|
.PP
|
|
.B \-\-offset
|
|
tunes to one side of the sensors and shifts them back in software, which
|
|
avoids the spike every RTL-SDR puts at whatever it is tuned to. It is off by
|
|
default: the spike is a steady addition to the envelope and the burst rises
|
|
clear of it, while a filter narrow enough to reject the spike is narrow enough
|
|
to lose a transmitter that has drifted. At the default sample rate it does
|
|
nothing whatever it is set to, there being nothing after the mixer narrower
|
|
than the band.
|
|
.PP
|
|
Finding the bursts is done in two passes, and the reason is having more than
|
|
one sensor. The first pass asks only where anything is happening at all, and
|
|
asks it against the noise: the bottom fifth of a second, which is noise
|
|
however busy the rest was. Whatever clears that is grouped into regions, and
|
|
the second pass re-thresholds each region against its own high and low, so
|
|
every sensor is sliced at its own amplitude. One threshold per second, set
|
|
halfway between the noise and the loudest thing in it, is the obvious way to
|
|
write this and is wrong: a sensor on the windowsill and a sensor at the end of
|
|
the garden differ by forty decibels, so the far ones fall below it and vanish,
|
|
and vanish only while the near one is transmitting.
|
|
.PP
|
|
Slicing the envelope into bits never measures anything against a clock, and
|
|
assumes as little as it can about how a bit is drawn. Not which of the pulse
|
|
and the gap carries the bit; not whether the gap is the complement of the
|
|
pulse or a fixed spacer, since a 220 microsecond pulse against a 200
|
|
microsecond spacer is the longer of the two and reads as the wrong bit; and
|
|
not which of long and short means one; and not which end of a byte goes down
|
|
the air first. The same burst is read half a dozen ways and the checksums say
|
|
which reading it was, at most one of them being able to satisfy one. There is
|
|
a fingerprint for the last of those: reversing the bits of a byte does not
|
|
change how many are set, so parity survives it and a sum does not, and a
|
|
message read from the wrong end shows every parity holding and every checksum
|
|
failing. A transmitter running ten per cent fast is therefore read
|
|
correctly and never noticed, which matters: these are unlocked and drift with
|
|
the temperature, and an outdoor sensor in January is not the one that was on
|
|
the fence in July.
|
|
.SS How well each sensor is heard
|
|
Three columns say so, and they answer different halves of the question.
|
|
.TP
|
|
.B signal
|
|
How far the sensor's burst stood above the noise, in decibels, coloured red
|
|
below 14, amber below 22 and green above. A ratio of two amplitudes off the
|
|
same receiver in the same second and nothing more \[em] not a power at the
|
|
aerial, which an RTL-SDR cannot give, having no reference level and, on
|
|
automatic gain, no fixed gain either. What a ratio is good for is comparing
|
|
one sensor with another, watching one over an evening, and pointing an aerial.
|
|
Use a fixed
|
|
.B \-\-gain
|
|
if the figures are to be compared between one run and the next. It is on the
|
|
live display as well, and kept there on a narrow terminal, because watching a
|
|
number climb while moving a whip about is the most useful thing it does.
|
|
.TP
|
|
.B every
|
|
The average wait between messages.
|
|
.TP
|
|
.B heard
|
|
What share of what the sensor sent is arriving. These transmit on a fixed
|
|
cycle, so the shortest wait ever seen between two of a sensor's messages is
|
|
that cycle, and the average wait is the cycle divided by the share getting
|
|
through; one over the other is the share, without needing to know the model or
|
|
how often it is supposed to speak.
|
|
.PP
|
|
The two are worth reading together and can disagree usefully. A strong signal
|
|
with a low share is interference or a collision rather than a range problem; a
|
|
weak signal at a hundred per cent is a sensor at the edge that is getting
|
|
through anyway.
|
|
.SS Afterwards
|
|
When the listening stops, two tables. The first is about reception and is the
|
|
one to look at when something is missing. The second is the first, last,
|
|
lowest and highest of everything each sensor reported.
|
|
.PP
|
|
There is no average, deliberately. These arrive every sixteen seconds when the
|
|
sensor is in range and not at all when it is not, and rain and cold both
|
|
shorten the range of a 433 MHz transmitter, so the mean of what was received
|
|
is the mean of a sample whose gaps are themselves the weather. A bearing gets
|
|
no lowest or highest either: north is 0 and also 360.
|
|
.PP
|
|
.B \-\-csv
|
|
writes a column per quantity and a row per reading, with the sensor's name in
|
|
the second column and the unit in the heading rather than beside every number.
|
|
.B "bandsaunter readings \-\-csv"
|
|
does the same to an old log, and takes
|
|
.BI \-\-sensor " NAME"
|
|
to narrow it to one sensor.
|
|
.PP
|
|
The log keeps the raw bytes of every message underneath whatever was made of
|
|
them, because the message is the evidence and the rest of the line is an
|
|
opinion about it. Readings are converted once, on the way in, to Celsius,
|
|
kilometres an hour, millimetres and kilometres \[em] different models report
|
|
in different units \[em] so
|
|
.B \-\-units imperial
|
|
changes only what is shown, and can be changed afterwards on an old log.
|
|
.SS Without a sensor
|
|
.B \-\-simulate
|
|
puts six sensors on a fence that does not exist, one of every model,
|
|
transmitting real messages with real checksums, keyed on and off as a real one
|
|
does, through the real filter, the real slicer and the real decoders. Nothing
|
|
touches the receiver.
|
|
.SS If nothing is heard
|
|
.B "bandsaunter weather \-\-diagnose"
|
|
is the answer to this, because "nothing was heard" is four different faults
|
|
wearing the same coat and they want four different answers. It prints each
|
|
second of band taken apart stage by stage: the noise level, the level a burst
|
|
has to clear, the loudest thing in the block, and then every burst found with
|
|
the lengths of its pulses and gaps and whatever was made of them.
|
|
.TP
|
|
.B "peak barely above noise, no bursts"
|
|
Nothing is arriving, which is an aerial. These are a few milliwatts; a
|
|
quarter-wave whip for 433.92 MHz is 17 cm of wire, which is the stock
|
|
telescopic aerial collapsed to about that, and indoors behind a wall with the
|
|
dongle in the back of a machine is usually the problem. Try
|
|
.B \-\-gain 40
|
|
if the automatic gain control is not finding them.
|
|
.TP
|
|
.B "peak well above noise, no bursts"
|
|
Something is there and did not group into a burst, usually a transmitter that
|
|
is on continuously rather than keyed. Not one of these.
|
|
.TP
|
|
.B "bursts whose pulse lengths are not two or three clean groups"
|
|
The receiver is hearing it and the slicing is wrong. A real message shows two
|
|
or three lengths with nothing in between; a smear means noise is being sliced
|
|
as signal, or two sensors are transmitting over each other.
|
|
.TP
|
|
.B "clean pulse lengths, nothing framed"
|
|
The radio is fine and the message is from a model this does not read. Under it
|
|
comes the closest thing to a message that was found, which of its checks held,
|
|
and the bytes themselves in hexadecimal. Which check fails says what kind of
|
|
fault it is: a sum that holds while a parity does not is a different thing
|
|
from neither holding. That line and the pulse lengths above it are between
|
|
them everything needed to add a format.
|
|
.TP
|
|
.B "framed, but needs the same message twice"
|
|
It was read correctly and arrived once. The two older models are believed only
|
|
on a second copy, so this wants a stronger signal.
|
|
.PP
|
|
When the listening stops it says which of those five it was, once, rather than
|
|
on every quiet second.
|
|
.PP
|
|
.BI \-\-save\-iq " FILE"
|
|
writes the raw samples alongside, for anything the diagnosis cannot settle. It
|
|
is 2 MB a second at the default rate, so bound it with
|
|
.BR \-\-seconds ;
|
|
sixty seconds is plenty, every sensor reporting at least twice in that. The
|
|
settings it was taken at are written beside it, a file of raw samples with no
|
|
record of its sample rate being unreadable by anything.
|
|
.PP
|
|
.BI \-\-from\-iq " FILE"
|
|
reads one back instead of the receiver, so a recording made where the aerial is
|
|
can be worked on anywhere. Everything downstream of the dongle is the real
|
|
thing, which is what tells a receiver problem and a decoder problem apart: a
|
|
capture that yields nothing on replay yields nothing for anybody, and one that
|
|
yields readings on replay and not on the air is a setting.
|
|
.SH WEATHER OPTIONS
|
|
Every option the weather 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.
|
|
.WEATHER_OPTIONS_HERE
|
|
.SH APRS
|
|
One channel, one frequency, everybody: 144.390 MHz across North America and a
|
|
different number in every other region, carrying position reports, weather,
|
|
messages, objects and telemetry from every amateur station within earshot, and
|
|
from every hilltop digipeater repeating them onward \[em] which is most of what
|
|
will actually be heard.
|
|
.PP
|
|
A mode of its own for the same reason the other two are: a scan stops on a
|
|
signal, records it and moves on, and this is a two-second transmission every
|
|
few minutes from a hundred stations sharing one frequency. A sweep catches
|
|
whichever one happened to key up while it was pointed there.
|
|
.PP
|
|
Unlike the others it is a conversation rather than a broadcast, so what is
|
|
shown is not only who is out there but what was said. And nothing here needs
|
|
naming: a station broadcasts a callsign issued by a government, which is
|
|
already the name.
|
|
.SS Which channel
|
|
The frequency is agreed between amateurs rather than allocated, so it differs
|
|
by region and there is no way to discover it from the air: on the wrong one
|
|
there is silence, not a bad signal. That is the one fault that looks exactly
|
|
like a dead aerial and is not, so it is the first thing to settle.
|
|
.B \-\-region
|
|
covers north-america (144.390), europe (144.800), australia (145.175), japan,
|
|
brazil and thailand, and
|
|
.B \-\-frequency
|
|
takes a number for anything else.
|
|
.PP
|
|
.BI \-\-find\-channel " [SECONDS]"
|
|
listens on each region's channel in turn \[em] twenty seconds each unless told
|
|
otherwise \[em] and prints what was on each, then says which to use. It
|
|
answers the one question about APRS that cannot be answered on any single
|
|
frequency, because the answer is a frequency. A quiet channel is not proof of
|
|
an empty one, a fixed station beaconing every half hour, so what it finds is
|
|
traffic and what it misses is only the absence of traffic while it listened;
|
|
it says as much when every channel comes back silent.
|
|
.PP
|
|
In the menus the channel is on the front page rather than a level down among
|
|
the gain and the sample rate, being the setting that decides whether anything
|
|
is heard at all.
|
|
.B c
|
|
lists the regions with their frequencies and also takes a number in megahertz
|
|
for a channel that is no region's;
|
|
.B f
|
|
runs the search and offers to adopt whichever channel had the most on it.
|
|
.SS What it reads
|
|
Positions, uncompressed and compressed into thirteen characters of base-91;
|
|
Mic-E, which every Kenwood and Yaesu mobile sends; weather, attached to a
|
|
position or without one; messages, acknowledgements, rejections and bulletins;
|
|
objects and items; status reports; telemetry; and third-party traffic relayed
|
|
in from another network, credited to whoever originally sent it. Riding in the
|
|
comment: course and speed, altitude, transmitter power and antenna height,
|
|
pre-computed range, direction-finding reports and the precision extension.
|
|
.PP
|
|
Mic-E deserves a note, being a quarter of everything on the channel and the
|
|
least readable thing in amateur radio. In 1995 the destination address of an
|
|
APRS frame carried nothing but the word "APRS", and somebody noticed that six
|
|
bytes is exactly enough for a latitude \[em] so a Mic-E packet puts the
|
|
latitude, the north/south bit, the east/west bit, a hundred degrees of
|
|
longitude and a three-bit status message into the callsign it is addressed to.
|
|
It is also why APRS fits in a two-second transmission.
|
|
.SS Refusing to guess
|
|
A packet whose format does not match what its first character promised comes
|
|
back as unparsed with its text kept, rather than as a position. Thirteen
|
|
characters of a malformed uncompressed position are perfectly good base-91, so
|
|
a decoder that tries one format and falls back to the other does not fail on a
|
|
bad packet \[em] 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, so the rule is read rather than
|
|
guessed at.
|
|
.SS Getting it off the air
|
|
APRS is Bell 202: 1200 Hz for a mark and 2200 Hz for a space, twelve hundred a
|
|
second, inside an ordinary FM transmission. Two correlators, one at each tone,
|
|
and the difference between them \[em] a correlator rather than a frequency
|
|
discriminator, the tones being less than an octave apart and radio audio
|
|
distorted enough that instantaneous frequency wanders.
|
|
.PP
|
|
De-emphasis is turned off, which matters and is easy to miss: voice FM lifts
|
|
the high frequencies on transmit and drops them again on receive, and packet
|
|
radio takes its audio from the discriminator before that happens. Dropping the
|
|
highs would take four decibels off the 2200 Hz tone and leave the 1200 Hz one
|
|
alone, which is exactly the difference being measured.
|
|
.PP
|
|
The soft symbol is sampled once a bit, at an instant held in the middle of the
|
|
bit by a loop nudged at every zero crossing, and that loop carries its phase
|
|
from one block of audio to the next \[em] a packet is most of a second and a
|
|
block is about one, so frames straddling the boundary are most of them. Then
|
|
NRZI, where a zero is a change of tone and a one is no change, which makes the
|
|
whole thing immune to being wired up backwards; then HDLC framing with its bit
|
|
stuffing; then sixteen bits of CRC, and nothing without a correct one is
|
|
reported. That last is what makes it safe to leave running for hours with the
|
|
squelch open.
|
|
.SS A window, while it happens
|
|
.B \-\-window
|
|
opens the same map the aircraft use, with stations on it instead of
|
|
aeroplanes: a real map underneath, an information box beside each station, a
|
|
leader line to the mark it belongs to, range rings around the aerial and a
|
|
flag where it stands.
|
|
.PP
|
|
The one difference from the aircraft map is that nothing fades. An aeroplane
|
|
that stops transmitting has flown out of range, and drawing it an hour later
|
|
where it was would be drawing something that is certainly not there; a fixed
|
|
amateur station that stops transmitting is still exactly where it was,
|
|
beaconing every half hour, so the gaps are silence rather than absence. The
|
|
picture accumulates instead, and an evening of listening fills a map.
|
|
.PP
|
|
Marks are drawn by what they are \[em] something moving as a body with a
|
|
stalk pointing where it is going, and anything fixed as a diamond, which is
|
|
the one shape on the picture with no front \[em] and coloured off the same
|
|
altitude ramp the aircraft use, that being the one set of colours every theme
|
|
defines, so a digipeater stays distinguishable from a car on all five.
|
|
.PP
|
|
The box says what the station is, where it is in figures, how far off and in
|
|
which bearing, what it is doing if it is moving, its altitude, its weather, its
|
|
status, the digipeaters it came through, how many packets and how many arrived
|
|
directly, and how strongly. The mark shows where a station is and the figures
|
|
are what gets written down \[em] and where a station blanked its minutes, the
|
|
figures are the only place that shows. Boxes are placed where they cover nothing else and glide when their
|
|
station moves; where there is no room for one the mark is still drawn, and the
|
|
most recently heard get the boxes.
|
|
.PP
|
|
The same keys as the aircraft map:
|
|
.B d
|
|
for how much each box says,
|
|
.B t
|
|
trails,
|
|
.B g
|
|
the map underneath,
|
|
.B [
|
|
and
|
|
.B ]
|
|
its brightness,
|
|
.B +
|
|
and
|
|
.B \-
|
|
the range,
|
|
.B f
|
|
true full screen, and
|
|
.B q
|
|
to quit.
|
|
.PP
|
|
The window measures in whatever unit is being shown.
|
|
.B \-\-units " imperial"
|
|
puts statute miles round the rings, along the scale at the bottom and on
|
|
.B \-\-radius
|
|
itself;
|
|
.B \-\-units " metric"
|
|
puts kilometres on all three. The rings are drawn at the distance they are
|
|
labelled \[em] the outermost at
|
|
.B \-\-radius " 100"
|
|
in imperial stands seventy-five statute miles from the flag, measured on the
|
|
ground, rather than seventy-five kilometres with miles written beside it. A
|
|
ring is what a distance gets judged against by eye, so one labelled in a unit
|
|
it was not drawn in is a wrong answer given confidently.
|
|
.PP
|
|
.BI \-\-at " LAT,LON"
|
|
puts the red flag on the map, centres the range rings and gives every station a
|
|
distance and a bearing. Left unset, whatever the aircraft side was told is used
|
|
instead \[em] one aerial on one roof does not move because the receiver was
|
|
pointed at a different band \[em] and which was used is said out loud, an
|
|
inherited position being a convenience right up until somebody has moved and
|
|
changed only one of them.
|
|
.SS Afterwards
|
|
Three tables. Stations heard is about the band and the aerial: where each was,
|
|
how far off, how many packets, how many of those arrived directly rather than
|
|
through a digipeater, and how strongly. What they said is the weather, the
|
|
speeds and the status lines. What passed between them is the messages, in
|
|
order, which is the only part of APRS that is a conversation.
|
|
.PP
|
|
.BI \-\-at " LAT,LON"
|
|
turns on the distance and bearing columns.
|
|
.B \-\-direct\-only
|
|
leaves out anything relayed, which is a much shorter list and the honest
|
|
measure of what an aerial can reach.
|
|
.B \-\-csv
|
|
writes a row per packet and
|
|
.B \-\-kml
|
|
a pin per station with a line for anything that moved; both can be made later
|
|
from a log with
|
|
.BR "bandsaunter packets" ,
|
|
which also takes
|
|
.BI \-\-station " CALL"
|
|
to narrow either to one callsign.
|
|
.PP
|
|
The log keeps the whole AX.25 frame in hexadecimal under whatever was made of
|
|
it, because the list of APRS formats is still growing and a packet this
|
|
version cannot read should be on the disk in full for a version that can.
|
|
.SS If nothing is heard
|
|
Check the region first: it is the one fault that looks like a dead aerial and
|
|
is not. Then give it time \[em] a fixed station beacons every twenty or thirty
|
|
minutes and a mobile every minute or two, so five minutes of an ordinary
|
|
suburb might be three packets. A quarter-wave whip for 144 MHz is 49 cm, which
|
|
is longer than the aerial most dongles ship with.
|
|
.B \-\-packets
|
|
shows each frame as it arrives, which is what to watch while moving an aerial
|
|
about.
|
|
.SS Who each station is
|
|
An APRS callsign is issued by a government, so unlike a weather sensor it can
|
|
be looked up: the name on the licence, the town, and the licensed position,
|
|
which is a street address where a beacon only gives a grid square. The SSID
|
|
comes off first \[em] W1AW\-9 is the ninth radio W1AW runs, and no register
|
|
has heard of it \[em] and objects are not looked up at all, an object being a
|
|
marker placed on behalf of something with no licence of its own.
|
|
.PP
|
|
Nothing waits: the lookup runs on its own thread and the name appears in a
|
|
later frame, because a table that stopped for a network request would stop for
|
|
every new station on a busy channel. A station the register cannot know still
|
|
says where it is from, the country coming out of the callsign's own structure
|
|
with no network at all.
|
|
.PP
|
|
Answers are kept in
|
|
.I ~/.cache/bandsaunter/callsigns.json
|
|
for a month, and that file is shared with every other part of this program
|
|
that resolves a callsign, so the same net logged night after night is asked
|
|
about once.
|
|
.B \-\-no\-lookup
|
|
turns the network off and leaves the country and district, which cost nothing.
|
|
.SH APRS OPTIONS
|
|
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 Who each station is
|
|
Every FT8 exchange is two callsigns and a callsign is issued by a government,
|
|
so both are looked up \[em] the station being answered may never transmit
|
|
within earshot and is still one this receiver knows about. The licensed
|
|
callsign is found inside the heard one: ET3RFG/R is ET3RFG operating away from
|
|
home, DL/G4ABC is G4ABC as a guest, and a hashed <...> is not asked about
|
|
because there is nothing to ask. Those rules are shared with APRS rather than
|
|
written twice, getting them wrong being silent: a register asked about W1AW\-9
|
|
returns nothing, which looks exactly like a station that is not licensed.
|
|
.PP
|
|
Nothing waits on the network \[em] a slot has to be decoded in well under
|
|
fifteen seconds or the next one is missed \[em] and answers are kept in
|
|
.I ~/.cache/bandsaunter/callsigns.json
|
|
for a month, in the same file every other part of this program uses. The
|
|
databases are United States registers, so the DX that makes this mode worth
|
|
listening to comes back unlisted, and the country beside it comes out of the
|
|
callsign's own structure with no network at all.
|
|
.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 THE TITLE SCREEN
|
|
Drawn on startup in braille, two dots wide and four tall to a character, which
|
|
is eight times the detail a block gives and is what makes room for capitals and
|
|
lowercase at the same height \[em] a five-row block font has no second height
|
|
to spend, so the name comes out shouted. Coloured in a gradient from deep blue
|
|
through cyan to a cool white across the width \[em] deliberately not the
|
|
waterfall ramp the rest of the program draws in, which carries on through green
|
|
and yellow to red because it stands in for a spectrum and has to mean
|
|
something. Under it, who conceived the program and what wrote it.
|
|
.PP
|
|
The font is twelve letters cut by hand at cap height seven and then doubled,
|
|
because a stroke two dots thick reads as a line where one dot thick reads as a
|
|
dotted line.
|
|
.PP
|
|
It never appears where it would be in the way. Everything here can be piped
|
|
into something else, and a banner in the middle of that is corruption rather
|
|
than decoration, so anything that is not a terminal gets nothing at all. It is
|
|
drawn after the arguments are parsed, so
|
|
.B \-\-help
|
|
and a bad argument say their piece without one over the top.
|
|
.B \-\-no\-splash
|
|
turns it off on a terminal too, and
|
|
.B BANDSAUNTER_NO_SPLASH=1
|
|
turns it off for good.
|
|
.SH FILES
|
|
.TP
|
|
.I ~/.config/bandsaunter/config.yaml
|
|
The settings every run starts from.
|
|
.TP
|
|
.I ~/.config/bandsaunter/aircraft.yaml
|
|
The aircraft options, as saved from the menus.
|
|
.TP
|
|
.I ~/.config/bandsaunter/weather.yaml
|
|
The weather options, as saved from the menus.
|
|
.TP
|
|
.I ~/.config/bandsaunter/sensors.yaml
|
|
What each weather sensor is called. The only file here holding anything a
|
|
person typed; safe to edit by hand.
|
|
.TP
|
|
.I ~/.config/bandsaunter/aprs.yaml
|
|
The APRS options, as saved from the menus.
|
|
.TP
|
|
.I ~/.config/bandsaunter/*.yaml
|
|
Named profiles.
|
|
.TP
|
|
.IR adsb_ * .jsonl
|
|
Every ADS-B frame heard in one listening session, with a
|
|
.I .txt
|
|
report and any picture drawn from it beside it.
|
|
.TP
|
|
.IR weather_ * .jsonl
|
|
Every weather sensor message heard in one listening session, with a
|
|
.I .csv
|
|
of the readings beside it where one was asked for.
|
|
.TP
|
|
.IR aprs_ * .jsonl
|
|
Every APRS packet heard in one listening session, with a
|
|
.I .csv
|
|
and a
|
|
.I .kml
|
|
beside it where they were asked for.
|
|
.TP
|
|
.I ~/bandsaunter/
|
|
Where recordings, transcripts and logs are written, unless
|
|
.B \-\-output
|
|
says otherwise. Chosen on first run.
|
|
.TP
|
|
.IR ... _data.txt
|
|
What a data capture said, where anything was decoded.
|
|
.TP
|
|
.I ~/bandsaunter/callsigns.kml
|
|
The map of stations heard, added to as scans run.
|
|
.TP
|
|
.I ~/.cache/bandsaunter/callsigns.json
|
|
Licence lookups already made, so they are not repeated.
|
|
.TP
|
|
.I /etc/modprobe.d/blacklist-rtlsdr.conf
|
|
Written by the package to keep the DVB-T television driver from claiming the
|
|
receiver.
|
|
.SH ENVIRONMENT
|
|
.TP
|
|
.B BANDSAUNTER_CONFIG_DIR
|
|
Where settings and profiles live, instead of
|
|
.IR ~/.config/bandsaunter .
|
|
.TP
|
|
.B BANDSAUNTER_LIBRTLSDR
|
|
Path to a particular librtlsdr shared library, when the system one is not the
|
|
one wanted.
|
|
.TP
|
|
.B BANDSAUNTER_DRIVER_MESSAGES
|
|
Set to 1 to let the receiver driver print its own chatter, which is
|
|
suppressed by default because it draws over the live display.
|
|
.TP
|
|
.B BANDSAUNTER_VENDOR_DIR
|
|
Where a packaged speech recogniser is installed. Default
|
|
.IR /usr/lib/bandsaunter/vendor .
|
|
.TP
|
|
.B BANDSAUNTER_MODEL_DIR
|
|
Where packaged recognition models are installed. Default
|
|
.IR /usr/share/bandsaunter/models .
|
|
.TP
|
|
.B BANDSAUNTER_ENGINE_OUTPUT
|
|
Set to 1 to let the speech recogniser print its own progress.
|
|
.SH EXAMPLES
|
|
.TP
|
|
.B bandsaunter
|
|
Interactive menus: pick bands, change settings, start scanning.
|
|
.TP
|
|
.B bandsaunter scan \-b 2m \-b 70cm \-\-record 0 \-\-hang 6
|
|
Scan two amateur bands, following each conversation to its end and allowing
|
|
six seconds of silence between overs.
|
|
.TP
|
|
.B bandsaunter scan \-b marine\-vhf \-\-combine \-\-transcribe
|
|
Scan marine VHF, keeping one growing file per channel with spoken timestamps,
|
|
and write out what was said.
|
|
.TP
|
|
.B bandsaunter scan \-r 14.0M\-14.35M
|
|
Scan the 20 metre amateur band. Direct sampling switches on by itself.
|
|
.TP
|
|
.B bandsaunter scan \-b all\-cw \-\-decode\-morse
|
|
Sweep every Morse segment of every amateur band and decode what is heard.
|
|
.TP
|
|
.B bandsaunter scan \-b gmrs \-\-plain \-\-duration 3600
|
|
Scan GMRS for an hour with line-per-hit output, suitable for a log file or a
|
|
remote session.
|
|
.TP
|
|
.B bandsaunter config threshold_db=12
|
|
Raise the squelch threshold and save it as the new default.
|
|
.SH EXIT STATUS
|
|
0 on success, 1 for a bad option or an unusable configuration, 2 when the
|
|
receiver could not be opened.
|
|
.SH SEE ALSO
|
|
.BR saunterbrowse (1)
|
|
\[em] browse and play back what a scan collected: the recordings list, their
|
|
transcripts and their identifications, on one screen.
|
|
.PP
|
|
.BR rtl_test (1),
|
|
.BR rtl_sdr (1),
|
|
.BR espeak-ng (1)
|
|
.PP
|
|
The README shipped with the package covers the same ground at greater length,
|
|
including why the detection thresholds are what they are.
|
|
.SH COPYING
|
|
Copyright \(co 2026 The Dust Council.
|
|
.PP
|
|
This program is free software: you can redistribute it and/or modify it under
|
|
the terms of the GNU General Public License as published by the Free Software
|
|
Foundation, either version 3 of the License, or (at your option) any later
|
|
version. It is distributed in the hope that it will be useful, but WITHOUT ANY
|
|
WARRANTY \[em] without even the implied warranty of MERCHANTABILITY or FITNESS
|
|
FOR A PARTICULAR PURPOSE. See the GNU General Public License for the full
|
|
terms, in
|
|
.I /usr/share/doc/bandsaunter/copyright
|
|
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 HOMEPAGE
|
|
.I https://frostwarning.com/git/dustcouncil/bandsaunter
|
|
.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
|
|
driver on install, but the module must be unloaded once with
|
|
.B "rmmod dvb_usb_rtl28xxu"
|
|
or the dongle replugged.
|
|
'''
|
|
|
|
|
|
def main() -> int:
|
|
out = [HEAD.format(date=date.today().isoformat(),
|
|
version=bandsaunter.__version__)]
|
|
out += settings_section()
|
|
out.append(TAIL)
|
|
text = "\n".join(out)
|
|
text = text.replace(".AIRCRAFT_OPTIONS_HERE",
|
|
"\n".join(aircraft_section()))
|
|
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")
|
|
target.write_text(text)
|
|
print(target)
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|