bandsaunter/packaging/make-man.py

#!/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


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 devices
List attached receivers.
.TP
.B profiles
List saved profiles.
.TP
.B analyze
Identify a signal in an already-recorded file, or decode Morse from it.
.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.
.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
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 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
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 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 FILES
.TP
.I ~/.config/bandsaunter/config.yaml
The settings every run starts from.
.TP
.I ~/.config/bandsaunter/*.yaml
Named profiles.
.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 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("\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())