bandsaunter/packaging/bandsaunter.1

.\" Generated by packaging/make-man.py -- do not edit by hand.
.TH BANDSAUNTER 1 "2026-09-07" "bandsaunter 2026-09-07_04" "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 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.
.SS Dwell and recording
.TP
.B --record --record-seconds
Record for \[em] longest one signal may hold the receiver (0 = no limit) (s).
.br
Setting name \fBrecord_seconds\fR, default \fB30 s\fR.
.br
Accepts: at least 0.
.RS
.PP
How long one signal may keep the receiver before the sweep moves on. Set it to 0 and a transmission is followed until it actually ends, which is what you want for listening to conversations. Give it a number if you would rather sample a busy band widely than sit on the first station that comes up.
.RE
.TP
.B --hang --hang-seconds
Wait for quiet \[em] quiet time before the sweep resumes (s).
.br
Setting name \fBhang_seconds\fR, default \fB2 s\fR.
.br
Accepts: at least 0.
.RS
.PP
How much silence means 'they have finished talking'. People pause between sentences, and two people taking turns leave a gap every time the conversation changes hands; anything shorter than this is recorded straight through, so an exchange stays in one file. Raise it if conversations keep getting split into pieces, lower it if the scanner sits on dead air.
.RE
.TP
.B --max-record
Absolute limit \[em] ceiling on one capture, even when 'Record for' is 0 (s).
.br
Setting name \fBmax_record_seconds\fR, default \fB900 s\fR.
.br
Accepts: at least 0.
.RS
.PP
A safety stop. With no record limit set, a stuck transmitter or a continuously modulated data channel would record until the disk filled, and this is where that stops. Only worth changing if you are deliberately capturing something very long; 0 removes the stop entirely.
.RE
.TP
.B --min-record
Discard shorter than \[em] throw away captures shorter than this (s).
.br
Setting name \fBmin_record_seconds\fR, default \fB0.5 s\fR.
.br
Accepts: at least 0.
.RS
.PP
Recordings shorter than this are deleted instead of kept. A click of static or a passing car's ignition noise can hold the squelch open for a fraction of a second, and this is what keeps those out of the directory. Raise it if you are collecting lots of tiny useless files; lower it if you are chasing very short transmissions such as data bursts or single-word replies.
.RE
.TP
.B --revisit
Ignore again for \[em] hold-off before the same frequency can be recorded again (s).
.br
Setting name \fBrevisit_seconds\fR, default \fB8 s\fR.
.br
Accepts: at least 0.
.RS
.PP
After recording a frequency, ignore it for this long. One busy repeater can otherwise take over the whole scan, recorded again and again while everything else goes unheard. Lower it if you want everything from one channel; raise it if one talkative frequency is drowning out the rest of the band.
.RE
.PP
.SS Detection
.TP
.B -t --threshold
Squelch threshold \[em] margin over the noise before a signal counts as present (dB).
.br
Setting name \fBthreshold_db\fR, default \fB10 dB\fR.
.br
Accepts: at least 0.5.
.RS
.PP
How much louder than the background hiss something must be before the scanner stops on it. This is the squelch knob. Too low and it stops on noise; too high and it walks past quiet stations. If you are getting nothing at all, try lowering it a few dB; if you are recording static, raise it.
.RE
.TP
.B --dwell
Dwell per step \[em] how long the sweep listens at each tuner position (s).
.br
Setting name \fBdwell_seconds\fR, default \fB0.05 s\fR.
.br
Accepts: at least 0.005, at most 5.
.RS
.PP
How long the receiver listens at each tuning position while sweeping. A short dwell sweeps faster but can miss a transmission that starts and ends between visits; a long one hears more of what is there but goes round the band slowly. The default is a good compromise for voice traffic.
.RE
.TP
.B --resolution
Sweep resolution \[em] FFT bin width while sweeping (Hz).
.br
Setting name \fBresolution_hz\fR, default \fB3 kHz\fR.
.br
Accepts: at least 100.
.RS
.PP
How finely the sweep divides the spectrum when looking for signals. Finer resolution separates two stations sitting close together and finds weak narrow ones, but takes longer to compute. Worth making finer if you are scanning a crowded band of narrow channels.
.RE
.TP
.B --detector
Detector \[em] peak-hold catches bursts; averaging is quieter.
.br
Setting name \fBdetector\fR, default \fBpeak\fR.
.br
Accepts: one of: peak, avg.
.RS
.PP
How the sweep decides how strong each part of the band was. Peak-hold remembers the loudest instant, so it catches a transmission that starts and stops during the dwell, which is what you want for scanning. Averaging is quieter and steadier, and is better when you want a clean picture of the band rather than to catch every burst.
.RE
.TP
.B --detector-bias
Detector bias \[em] override the computed noise-peak offset (blank = automatic) (dB).
.br
Setting name \fBdetector_bias_db\fR, default \fBautomatic\fR.
.br
Accepts: at least 0.
.RS
.PP
A correction for the fact that peak-hold makes plain noise look stronger than it is, which would otherwise trigger the squelch on nothing. It is worked out automatically from the detector and the sweep settings, and there is normally no reason to set it by hand.
.RE
.TP
.B --squelch-margin
Squelch hysteresis \[em] how far below the threshold a signal may drop before it counts as gone (dB).
.br
Setting name \fBsquelch_margin_db\fR, default \fB3 dB\fR.
.br
Accepts: at least 0.
.RS
.PP
Once a signal has been found, it may drop this far below the squelch threshold before being counted as gone. Without it a station sitting exactly at the threshold would flicker on and off, chopping the recording into fragments. Raise it if recordings of weak stations keep breaking up.
.RE
.TP
.B --adaptive-floor / --no-adaptive-floor
Smooth the noise floor \[em] average the measured floor across sweeps.
.br
Setting name \fBadaptive_floor\fR, default \fByes\fR.
.RS
.PP
Learns what the background noise looks like across several sweeps rather than judging from one. It makes the squelch steadier, especially where the noise level varies across the band. Turn it off only if you are watching a band where the noise itself changes fast and you want the scanner to react immediately.
.RE
.TP
.B --max-detections
Signals per step \[em] how many separate signals one tuner position may report.
.br
Setting name \fBmax_detections_per_step\fR, default \fB4\fR.
.br
Accepts: at least 1.
.RS
.PP
The sweep can see several stations at once in the chunk of spectrum it is looking at, and this is how many of them it will queue up. Raise it in a crowded band where you are missing simultaneous transmissions; lower it if you would rather the scanner keep moving.
.RE
.TP
.B --probe
Probe length \[em] look at a signal for this long before choosing a demodulator (s).
.br
Setting name \fBprobe_seconds\fR, default \fB0.4 s\fR.
.br
Accepts: at least 0.05, at most 3.
.RS
.PP
Before recording, the scanner listens briefly to work out what kind of signal it is, so it can pick the right way to decode it. Longer is a more reliable guess but delays every recording slightly. The listen is not wasted: it is kept and played into the start of the recording.
.RE
.PP
.SS What counts as a signal
.TP
.B --require-signal / --keep-everything --no-require-signal
Check for content \[em] only keep captures that carry voice, CW or data.
.br
Setting name \fBrequire_signal\fR, default \fByes\fR.
.RS
.PP
Judge each capture and throw away anything that turns out to be noise, static or interference rather than a real transmission. This is the single setting that decides whether the recordings directory is full of things worth listening to or full of hiss. Turn it off only if you want everything that breaks squelch, however empty.
.RE
.TP
.B --accept
Record these \[em] which kinds of content are worth keeping.
.br
Setting name \fBaccept\fR, default \fBvoice, cw, digital\fR.
.br
Accepts: one of: voice, cw, digital, trunk, carrier, noise.
.RS
.PP
Which kinds of transmission are worth keeping: speech, Morse, data, trunking control channels, plain unmodulated carriers, and noise. Most people want voice, cw and digital. Add carrier if you are hunting beacons or interference sources, trunk if you are collecting control channels for a decoder, and noise only for diagnosing why nothing is being recorded.
.RE
.TP
.B --min-signal-score
Minimum confidence \[em] confidence needed to keep a capture.
.br
Setting name \fBmin_signal_score\fR, default \fB0.45\fR.
.br
Accepts: at least 0, at most 1.
.RS
.PP
How certain the content check must be before a recording is kept, from 0 to 1. Lower it if real transmissions are being discarded, since weak or noisy signals score lower. Raise it if borderline rubbish is still getting through.
.RE
.TP
.B --min-voice-score
Minimum speech score \[em] how speech-like audio must be to count as voice.
.br
Setting name \fBmin_voice_score\fR, default \fB0.45\fR.
.br
Accepts: at least 0, at most 1.
.RS
.PP
How speech-like audio has to sound before it is called voice. Speech has a pitch that moves and a rhythm of syllables; a steady tone or a hum does not. Lower it if quiet or distorted speech is being missed, raise it if music, hum or engine noise is being recorded as if it were someone talking.
.RE
.TP
.B --verify-every
Re-check every \[em] how often a live capture is re-examined (s).
.br
Setting name \fBverify_seconds\fR, default \fB1.5 s\fR.
.br
Accepts: at least 0.2.
.RS
.PP
How often a recording in progress is re-examined to see whether it is still carrying anything. Checking often releases the receiver quickly when a channel turns out to be holding static; checking rarely costs less processing.
.RE
.TP
.B --verify-max
Give up after \[em] how long a capture has to show any content (s).
.br
Setting name \fBverify_max_seconds\fR, default \fB6 s\fR.
.br
Accepts: at least 0.5.
.RS
.PP
How long a recording gets to prove it contains something. If nothing recognisable has appeared by then it is abandoned and deleted, and the sweep moves on rather than sitting on an open but empty channel.
.RE
.PP
.SS Trunking
.TP
.B --skip-control / --keep-control --no-skip-control
Skip trunk control channels \[em] spot a trunked system's control channel and move straight on.
.br
Setting name \fBskip_control\fR, default \fByes\fR.
.RS
.PP
Trunked radio systems -- the kind police, fire and large businesses use -- keep one frequency transmitting a data stream around the clock. It tells the radios which channel to jump to for each conversation; it carries no speech and it never goes quiet. To a scanner it looks like a very strong, very interesting signal, so without this setting the receiver parks on it, records the whole record limit of buzzing, and finds it again on the next sweep. With this on it is recognised within a second or two, named on screen, and skipped. Leave it on unless you are deliberately collecting control channel data to feed to a decoder.
.RE
.TP
.B --control-seconds
Control channel patience \[em] unbroken carrier a digital-voice look-alike must hold (s).
.br
Setting name \fBcontrol_seconds\fR, default \fB20 s\fR.
.br
Accepts: at least 1.
.RS
.PP
Only matters for P25, DMR and NXDN. On those systems the control channel and an ordinary digital conversation look identical for the first few seconds, and the only thing that tells them apart is that the conversation eventually pauses and the control channel never does. This is how long a signal has to keep going without a break before it is judged to be a control channel. Raise it if digital voice calls are being skipped by mistake; lower it if you are tired of waiting out control channels. It has no effect on the older Motorola and EDACS systems, which are recognised immediately from their symbol rate.
.RE
.TP
.B --lockout-control / --no-lockout-control
Lock out control channels \[em] add every control channel found to the lock-out list.
.br
Setting name \fBlockout_control\fR, default \fBno\fR.
.RS
.PP
Write each control channel into the lock-out list as it is found, so the scanner stops even looking at it. Skipping one already costs only a second or two, so this is worth turning on mainly if you scan the same band constantly and want the list built for you. With 'Remember lock-outs' also on, the entries are saved to your settings file and survive a restart.
.RE
.PP
.SS Receiver
.TP
.B -d --device
Device index \[em] which dongle to use when more than one is attached.
.br
Setting name \fBdevice_index\fR, default \fB0\fR.
.br
Accepts: at least 0.
.RS
.PP
Which receiver to use when more than one is plugged in. Run 'bandsaunter devices' to see the list and their numbers. With a single dongle this can be ignored.
.RE
.TP
.B --sample-rate
Sample rate \[em] capture rate; sets how much spectrum one step covers (Hz).
.br
Setting name \fBsample_rate\fR, default \fB2.048 MHz\fR.
.RS
.PP
How much spectrum the receiver takes in at once, which sets how much ground each step of the sweep covers. Higher covers the band in fewer steps but makes the computer work harder, and cheap dongles start dropping samples. 2.048 MS/s suits most machines; drop it if recordings sound wrong or the program warns about dropped samples.
.RE
.TP
.B -g --gain
Tuner gain \[em] gain in dB, or 'auto' for the tuner's own control (dB).
.br
Setting name \fBgain\fR, default \fBauto\fR.
.RS
.PP
How much the receiver amplifies. Automatic gain sounds convenient but tends to wind itself up during quiet moments and amplify noise until it breaks squelch. A fixed value is usually better for scanning: start around 30 and lower it if strong stations sound distorted, raise it if everything is too weak to hear.
.RE
.TP
.B --ppm
Frequency correction \[em] crystal error correction (ppm).
.br
Setting name \fBppm\fR, default \fB0 ppm\fR.
.RS
.PP
Cheap receivers are tuned by a crystal that is never exactly right, so every frequency reads slightly off, possibly by a few kilohertz at UHF. If stations consistently appear a little above or below where they should be, this corrects it. Leave at 0 unless you have measured the error.
.RE
.TP
.B --agc / --no-agc
RTL2832 AGC \[em] the demodulator chip's own automatic gain.
.br
Setting name \fBagc\fR, default \fBno\fR.
.RS
.PP
A second, separate automatic gain control inside the receiver chip, on top of the tuner gain. It is usually best left off, since two automatic gain controls fighting each other makes the squelch behave unpredictably.
.RE
.TP
.B --bias-tee / --no-bias-tee
Bias tee \[em] put DC on the antenna port to power an external amplifier.
.br
Setting name \fBbias_tee\fR, default \fBno\fR.
.RS
.PP
Sends power up the antenna cable, which is how mast-mounted amplifiers and some active antennas are fed. Leave it off unless you have such a device: switching it on with ordinary equipment attached can damage it.
.RE
.TP
.B --offset-tuning / --no-offset-tuning
Offset tuning \[em] shift the tuner's own local oscillator (E4000 tuners only).
.br
Setting name \fBoffset_tuning\fR, default \fBno\fR.
.RS
.PP
A trick for one older tuner chip, the E4000, that moves an artefact away from the middle of the picture. Modern dongles, including every R820T, ignore it. Leave it off unless you know you have that tuner.
.RE
.TP
.B --direct-sampling
Direct sampling \[em] HF reception below 24 MHz: auto, 0 off, 1 I branch, 2 Q branch.
.br
Setting name \fBdirect_sampling\fR, default \fBauto\fR.
.br
Accepts: one of: auto, 0, 1, 2.
.RS
.PP
How the receiver hears shortwave. These dongles cannot normally tune below about 24 MHz, but they can be persuaded to sample the antenna directly, which opens up everything beneath it: shortwave broadcast, amateur HF, marine. Automatic switches it on when you scan below 24 MHz and off again above. The Q branch is what almost all hardware uses.
.RE
.TP
.B --usable-fraction
Usable bandwidth \[em] fraction of the sample rate each step covers.
.br
Setting name \fBusable_fraction\fR, default \fB0.75\fR.
.br
Accepts: at least 0.1, at most 0.95.
.RS
.PP
The edges of what the receiver takes in are distorted by its own filtering, so only the middle portion is trusted. Lowering this uses less of each step and sweeps more slowly but avoids the poor edges; raising it covers ground faster at the cost of missing or mismeasuring signals near the edges.
.RE
.TP
.B --dc-guard
DC guard \[em] how far the local oscillator is parked below each step (Hz).
.br
Setting name \fBdc_guard_hz\fR, default \fB8 kHz\fR.
.br
Accepts: at least 0.
.RS
.PP
Every receiver of this type produces a spurious spike at the exact centre of where it is tuned, which would otherwise look like a station. The receiver is therefore deliberately parked slightly to one side. There is rarely a reason to change this.
.RE
.PP
.SS Output
.TP
.B -o --output
Output directory \[em] where recordings and logs are written.
.br
Setting name \fBoutput_dir\fR, default \fB~/bandsaunter\fR.
.RS
.PP
Where recordings, transcripts and logs are written. Everything the program produces goes here, so put it somewhere with room: audio adds up quickly, and raw IQ adds up very quickly.
.RE
.TP
.B --audio / --no-audio
Save audio \[em] write a WAV of the demodulated audio.
.br
Setting name \fBsave_audio\fR, default \fByes\fR.
.RS
.PP
Write the listenable audio file for each transmission. This is almost certainly what you want; turning it off leaves only the log and whatever other outputs are enabled, which is useful when you only care about what was active and when.
.RE
.TP
.B --iq --save-iq / --no-iq
Save raw IQ \[em] also write the raw complex samples and a SigMF sidecar.
.br
Setting name \fBsave_iq\fR, default \fBno\fR.
.RS
.PP
Also keep the raw radio samples, exactly as they came off the receiver, alongside the audio. These can be re-analysed or decoded later with other software, but they are enormous, many megabytes per second, so leave this off unless you have a specific use for them.
.RE
.TP
.B --iq-format
IQ format \[em] sample format for raw IQ files.
.br
Setting name \fBiq_format\fR, default \fBcf32\fR.
.br
Accepts: one of: cf32, cs16.
.RS
.PP
The number format for those raw files. cf32 is the easiest for other programs to read; cs16 is half the size for the same samples. Only matters if raw IQ is being saved.
.RE
.TP
.B --audio-rate
Audio rate \[em] preferred audio sample rate (Hz).
.br
Setting name \fBaudio_rate\fR, default \fB16 kHz\fR.
.br
Accepts: at least 4000.
.RS
.PP
The sample rate of the saved audio. Higher preserves more of the original sound at the cost of file size; the default is well matched to what a radio channel can actually carry, and to what speech recognisers expect.
.RE
.TP
.B --classify / --no-classify
Identify signals \[em] work out what kind of signal each capture is.
.br
Setting name \fBclassify\fR, default \fByes\fR.
.RS
.PP
Work out what each recording actually is, whether FM voice, AM, single sideband, Morse, a paging system or a digital voice mode, and write it into the log and the filename. Turning it off saves a little processing and leaves you to identify things by ear.
.RE
.TP
.B --images / --no-images
Decode pictures \[em] save SSTV, weather satellite and shortwave fax pictures as PNG.
.br
Setting name \fBdecode_images\fR, default \fByes\fR.
.RS
.PP
Three of the things a receiver can hear are pictures: the weather satellites on 137 MHz, amateur slow-scan television, and the shortwave weather fax stations. All three are images sent as sound, so they arrive in the same recordings everything else does. Each is recognised by its own header rather than guessed at, so this costs a moment per recording and finds nothing where there is nothing. What it does find is written as a PNG beside the audio.
.RE
.TP
.B --waterfall / --no-waterfall
Draw a waterfall \[em] picture every capture that produced no readable words.
.br
Setting name \fBwaterfall\fR, default \fByes\fR.
.RS
.PP
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 shows the shape of a signal rather than its meaning -- 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 -- so every capture that produced no readable words gets one drawn beside it as a PNG. Where the raw IQ was kept it draws the radio spectrum; otherwise the demodulated audio, and it says on the picture which it is.
.RE
.TP
.B --waterfall-min-chars
Words that count as readable \[em] a transcript shorter than this counts as no transcript.
.br
Setting name \fBwaterfall_min_chars\fR, default \fB5\fR.
.br
Accepts: at least 0, at most 200.
.RS
.PP
How much transcript counts as having read a capture. Under this, the recogniser found a word or two of nothing in particular, and a picture of the signal is worth more than the word.
.RE
.TP
.B --morse / --no-morse
Decode CW to text \[em] decode keyed carriers as Morse.
.br
Setting name \fBdecode_morse\fR, default \fByes\fR.
.RS
.PP
Turn keyed carriers into readable text, with the sending speed. Morse is still in daily use by amateurs and by beacons, and this saves you learning to read it by ear. It costs almost nothing when there is no Morse about. Every capture is tried once it has finished, whatever the modulation was called, because most of the Morse on the air is a repeater or a beacon giving its callsign in a burst of a second or two; a callsign read out of one goes to the same lookup and the same map as a spoken one.
.RE
.TP
.B --decode-data / --no-decode-data
Decode data signals \[em] read the packets out of anything carrying data.
.br
Setting name \fBdecode_data\fR, default \fByes\fR.
.RS
.PP
Read what a data signal actually says. A great deal of what a scanner finds is not speech: doorbells, tyre-pressure sensors, weather stations, remote controls, paging, packet radio. Each one is sliced into its pulses, the line code worked out from the pulse lengths alone, and the bits reported -- with the packet named where its framing says what it is, and the message printed in full where the protocol carries one. The check that keeps it honest is repetition: these transmitters send the same packet several times over, and bits that come back identical every time did not come from noise. Turn it off to save a little processing on a busy band.
.RE
.TP
.B --log-file
Log file \[em] name of the run log inside the output directory.
.br
Setting name \fBlog_file\fR, default \fBscan_log.jsonl\fR.
.RS
.PP
The name of the run log inside the output directory. It records every recording with its time, frequency, duration and identification, as JSON lines with a spreadsheet-friendly .csv alongside.
.RE
.PP
.SS Combining
.TP
.B --combine / --no-combine
Combine by frequency \[em] collect every transmission on one frequency into a single file.
.br
Setting name \fBcombine_by_frequency\fR, default \fBno\fR.
.RS
.PP
Instead of one file per transmission, keep one growing file per frequency, with each new transmission appended to it. This turns a scanner run into something you can play like a recording of that channel, rather than hundreds of fragments to click through.
.RE
.TP
.B --announce / --no-announce
Speak the time \[em] insert a spoken date and time before each transmission.
.br
Setting name \fBannounce_timestamps\fR, default \fByes\fR.
.RS
.PP
Speaks the date and time before each transmission in a combined file, so you can hear when something happened without watching a clock or reading filenames. It works with no extra software installed; installing espeak-ng makes the voice clearer.
.RE
.TP
.B --announce-frequency / --no-announce-frequency
Speak the frequency \[em] also read the frequency out with the timestamp.
.br
Setting name \fBannounce_frequency\fR, default \fBno\fR.
.RS
.PP
Also read out the frequency with the time. Useful when several nearby frequencies end up in the same combined file, or when you want a spoken record of what you were listening to.
.RE
.TP
.B --announce-engine
Speech engine \[em] which text-to-speech to use: auto, builtin, or a program name.
.br
Setting name \fBannounce_engine\fR, default \fBauto\fR.
.RS
.PP
Which voice does the speaking. Automatic uses the best available: espeak-ng if it is installed, otherwise a small built-in synthesiser that needs nothing at all. Set it to builtin to force the internal voice, or name another program.
.RE
.TP
.B --combine-tolerance
Same-frequency tolerance \[em] how far apart two receptions may be and still count as one frequency (Hz).
.br
Setting name \fBcombine_tolerance_hz\fR, default \fB6.25 kHz\fR.
.br
Accepts: at least 0.
.RS
.PP
How far apart two receptions may be and still be treated as the same frequency for combining. Transmitters drift and the measurement is never exact, so a little tolerance keeps one repeater in one file. Widen it if a single channel is being split across several files.
.RE
.TP
.B --keep-individual / --no-keep-individual
Keep separate files too \[em] also keep the one-file-per-transmission recordings.
.br
Setting name \fBcombine_keep_individual\fR, default \fBno\fR.
.RS
.PP
Keep the per-transmission files as well as the combined one. It costs twice the disk space, but means you can still pick out a single transmission without seeking through a long file.
.RE
.PP
.SS Transcription
.TP
.B --transcribe / --no-transcribe
Transcribe speech \[em] write out what was said in each voice transmission.
.br
Setting name \fBtranscribe\fR, default \fBno\fR.
.RS
.PP
Write out what was said in each voice transmission as a text file beside the recording, so a scan can be read rather than listened to, and searched with ordinary text tools. It needs a speech recogniser installed; the program says so plainly if none is present.
.RE
.TP
.B --transcribe-engine
Recogniser \[em] which speech recogniser to use, or auto.
.br
Setting name \fBtranscribe_engine\fR, default \fBauto\fR.
.RS
.PP
Which speech recogniser to use when more than one is installed. Automatic picks the best available. Radio audio is hard for these programs, and the whisper-based ones are noticeably better at it than the smaller alternatives.
.RE
.TP
.B --transcribe-model
Model \[em] model the recogniser should load.
.br
Setting name \fBtranscribe_model\fR, default \fBbase.en\fR.
.RS
.PP
How large a recognition model to load. Bigger models are more accurate and slower, and take more memory: tiny.en and base.en keep up comfortably on an ordinary machine, small.en and medium.en are better but heavier.
.RE
.TP
.B --transcribe-language
Language \[em] language to expect, or blank to detect it.
.br
Setting name \fBtranscribe_language\fR, default \fBen\fR.
.RS
.PP
The language to expect. Setting it is worth the trouble: on a short, noisy clip automatic detection often guesses wrong and returns confident nonsense in a language nobody was speaking. Leave it blank only if you genuinely do not know.
.RE
.TP
.B --transcribe-min
Skip clips shorter than \[em] do not bother transcribing very short captures (s).
.br
Setting name \fBtranscribe_min_seconds\fR, default \fB1 s\fR.
.br
Accepts: at least 0.
.RS
.PP
Do not bother transcribing captures shorter than this. Very short clips rarely contain a whole word and mostly produce noise or nothing, while still costing the processing.
.RE
.PP
.SS Callsigns
.TP
.B --callsign-lookup / --no-callsign-lookup --offline-callsigns
Look callsigns up \[em] ask the licence database who a callsign belongs to.
.br
Setting name \fBcallsign_lookup\fR, default \fByes\fR.
.RS
.PP
When someone gives their callsign, look it up and say who they are. The data is the FCC's own published licence register, which carries the licensee's name, the town they are licensed in and the coordinates that put them on the map. Only the callsign is sent, and each one is asked about once and then remembered, so this costs almost nothing. Turn it off if you would rather the scan reached the network for nothing at all -- callsigns are still picked out of the transcripts, and the prefix still says which country and which US district they belong to.
.RE
.TP
.B --kml
Map file \[em] KML map of where the stations heard are licensed (blank = none).
.br
Setting name \fBkml_file\fR, default \fBcallsigns.kml\fR.
.RS
.PP
The name of a map file, kept in the output directory, of everyone who identified themselves. Each station is one pin: the callsign, who holds the licence, where they are licensed, and every frequency and time you heard them. It is added to as the scan runs and again by later scans, so it builds up into a picture of what you can hear from where you are. KML is the format Google Earth uses; QGIS, Marble and OsmAnd read it too. Leave it blank if you do not want the map.
.RE
.PP
.SS Run control
.TP
.B --cycles
Stop after sweeps \[em] stop after this many full passes (0 = run until stopped).
.br
Setting name \fBmax_cycles\fR, default \fBno limit\fR.
.br
Accepts: at least 0.
.RS
.PP
Stop after this many complete passes through all the frequencies. Useful for a quick survey of what is active, or for a scripted run that must finish. 0 means keep going until you stop it.
.RE
.TP
.B --duration
Stop after time \[em] stop after this long (0 = run until stopped) (s).
.br
Setting name \fBmax_runtime_seconds\fR, default \fBno limit\fR.
.br
Accepts: at least 0.
.RS
.PP
Stop after this long, whatever the scan is doing. Handy for an unattended run, or for keeping a test short. 0 means no limit.
.RE
.TP
.B --lockout
Locked-out frequencies \[em] never stop on these frequencies.
.br
Setting name \fBlockout\fR, default \fB(none)\fR.
.RS
.PP
Frequencies the scan must never stop on. Every receiving setup has a few: a pager transmitter down the road, a nearby data link, or a spurious signal the receiver manufactures itself. Give several separated by commas, and a whole stretch of spectrum as a pair, such as 162.55M, 450M-455M.
.RE
.TP
.B --lockout-width
Lock-out width \[em] how wide a locked-out frequency is (Hz).
.br
Setting name \fBlockout_width\fR, default \fB12.5 kHz\fR.
.br
Accepts: at least 1.
.RS
.PP
How wide a single locked-out frequency is. A transmitter is never exactly on its nominal frequency, so the block covers a little either side. A lock-out written as a span ignores this and uses exactly the width you gave.
.RE
.TP
.B --quiet / --no-quiet
Quiet output \[em] print errors only.
.br
Setting name \fBquiet\fR, default \fBno\fR.
.RS
.PP
Print only errors. For running from a script or a scheduled job where the usual progress reporting would just fill a log file.
.RE
.TP
.B --save-lockouts / --no-save-lockouts
Remember lock-outs \[em] keep frequencies locked out during a scan.
.br
Setting name \fBsave_lockouts\fR, default \fByes\fR.
.RS
.PP
When you lock a frequency out during a scan, remember it for later runs instead of only the current one. Only the lock-out list is written back, so options you passed for one run stay one-off. Turn it off if you would rather the program never modified your settings file.
.RE
.TP
.B --plain / --no-plain
Plain display \[em] print one line per hit instead of the live display.
.br
Setting name \fBplain\fR, default \fBno\fR.
.RS
.PP
Print one line per recording instead of the live updating display. The live display needs a real terminal; plain output is what you want over a remote connection, when saving output to a file, or when feeding another program. It is chosen automatically when output is not going to a terminal.
.RE
.PP
.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 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
.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.
.SS Receiver
.TP
.B --device
Receiver \[em] which receiver to use, when more than one is plugged in.
.br
Setting name \fBdevice\fR, default \fB0\fR.
.br
Accepts: at least 0.
.TP
.B --gain
Gain \[em] tuner gain in dB, or automatic.
.br
Setting name \fBgain\fR, default \fBauto\fR.
.TP
.B --rate
Sample rate \[em] how fast to sample; two megasamples a second is the minimum (Hz).
.br
Setting name \fBrate\fR, default \fB2 MHz\fR.
.br
Accepts: at least 2e+06.
.TP
.B --at
Receiver at \[em] where the receiver is, as latitude,longitude (blank = work it out).
.br
Setting name \fBlocation\fR, default \fBblank\fR.
.TP
.B --simulate
Invent a sky \[em] fly imaginary aircraft past an imaginary receiver.
.br
Setting name \fBsimulate\fR, default \fBno\fR.
.RS
.PP
Turn this on to see what the whole thing does without hardware. Turn it off to hear real aircraft.
.RE
.TP
.B --near
Imaginary sky near \[em] where the simulated aircraft are flying.
.br
Setting name \fBnear\fR, default \fB47.55,-122.30\fR.
.PP
.SS Listening
.TP
.B --seconds
Listen for \[em] how long to listen before stopping (0 = until interrupted) (s).
.br
Setting name \fBseconds\fR, default \fBuntil stopped\fR.
.br
Accepts: at least 0.
.RS
.PP
Sixty seconds is enough to know whether aircraft are being heard. An evening of traffic wants no limit.
.RE
.TP
.B --frames
Show every frame \[em] print each frame as it arrives, rather than a running count.
.br
Setting name \fBframes\fR, default \fBno\fR.
.TP
.B --log / --no-log
Write the log \[em] write every frame to a file as it arrives.
.br
Setting name \fBlog\fR, default \fByes\fR.
.TP
.B --kml
Also write a KML \[em] write the flight paths for Google Earth as well.
.br
Setting name \fBkml\fR, default \fBno\fR.
.TP
.B --hold
Keep on screen for \[em] how long an aircraft stays on the display after its last frame (s).
.br
Setting name \fBhold\fR, default \fB45 s\fR.
.br
Accepts: at least 1.
.RS
.PP
Long enough that a gap in reception does not make rows jump about; short enough that the screen is the sky now.
.RE
.TP
.B --map
Draw when finished \[em] draw the map as soon as the listening stops.
.br
Setting name \fBdraw_after\fR, default \fBno\fR.
.PP
.SS Aircraft
.TP
.B --lookup / --no-lookup
Look the aircraft up \[em] ask the public registers who each aircraft is.
.br
Setting name \fBlookup\fR, default \fByes\fR.
.TP
.B --schedules
Schedule services \[em] which paid schedule services to ask, in order (blank = all with keys).
.br
Setting name \fBschedules\fR, default \fBblank\fR.
.RS
.PP
Leave it blank unless you want one service tried before another. With no keys set, nothing changes.
.RE
.TP
.B --recheck
Check the positions \[em] throw out positions the aircraft could not have been in.
.br
Setting name \fBrecheck\fR, default \fBno\fR.
.RS
.PP
Worth turning on for anything recorded before this version. Newer logs have the check applied as they are written, so it finds almost nothing.
.RE
.PP
.SS Animation
.TP
.B --out
Picture \[em] what kind of picture to draw.
.br
Setting name \fBpicture\fR, default \fBgif\fR.
.br
Accepts: one of: gif, mp4, png.
.RS
.PP
Start with gif. Use png when you want one picture to look at or send.
.RE
.TP
.B --seconds
Animation length \[em] how long the animation should run for (s).
.br
Setting name \fBlength\fR, default \fB30 s\fR.
.br
Accepts: at least 1.
.TP
.B --speed
Speed \[em] seconds of flying per second of animation (0 = fit to the length) (x).
.br
Setting name \fBspeed\fR, default \fBfit to the length\fR.
.br
Accepts: at least 0.
.TP
.B --fps
Frames a second \[em] how many frames of animation each second holds.
.br
Setting name \fBfps\fR, default \fB12\fR.
.br
Accepts: at least 1.
.TP
.B --width
Picture width \[em] how many pixels across the picture is (px).
.br
Setting name \fBwidth\fR, default \fB960 px\fR.
.br
Accepts: at least 160.
.TP
.B --trail
Trail \[em] how much of the path to leave behind each aircraft (0 = all of it) (s).
.br
Setting name \fBtrail\fR, default \fBthe whole path\fR.
.br
Accepts: at least 0.
.TP
.B --fade
Fade out over \[em] how long an aircraft takes to fade away once it has gone quiet (s).
.br
Setting name \fBfade\fR, default \fB20 s\fR.
.br
Accepts: at least 0.
.RS
.PP
Long enough to notice, short enough that a busy sky is not half ghosts.
.RE
.TP
.B --stale
Forget after \[em] stop drawing an aircraft this long after its last report (s).
.br
Setting name \fBstale\fR, default \fB300 s\fR.
.br
Accepts: at least 1.
.PP
.SS The map
.TP
.B --basemap / --no-basemap
Map underneath \[em] draw a real map under the flight paths.
.br
Setting name \fBbasemap\fR, default \fByes\fR.
.RS
.PP
Turn it off for a picture with nothing but the tracks on it, or where there is no network and no cached tiles.
.RE
.TP
.B --tiles
Tile server \[em] where the map tiles come from.
.br
Setting name \fBtile_url\fR, default \fBblank\fR.
.TP
.B --theme
Colour theme \[em] how the map looks: the colours, and whether the lines glow.
.br
Setting name \fBtheme\fR, default \fBnight\fR.
.br
Accepts: one of: night, digital, phosphor, amber, red.
.RS
.PP
night to read it, the others to look at it.
.RE
.TP
.B --map-brightness
Map brightness \[em] how bright the map under the aircraft is drawn, as a percentage (%).
.br
Setting name \fBmap_brightness\fR, default \fB70 %\fR.
.br
Accepts: at least 10, at most 100.
.RS
.PP
Turn it up until the coast and the roads are readable, and no further. On a vector theme it takes rather more turning up than on the default one.
.RE
.TP
.B --radius
Map radius \[em] how far around the receiver the map reaches (0 = fit whatever was heard).
.br
Setting name \fBradius\fR, default \fB100\fR.
.br
Accepts: at least 0.
.RS
.PP
Set it to what your aerial can really hear. Zero goes back to fitting whatever turned up, mistakes and all.
.RE
.TP
.B --airports / --no-airports
Mark the airports \[em] mark every aerodrome on the map, not only the ones flown between.
.br
Setting name \fBairports\fR, default \fByes\fR.
.RS
.PP
Turn it off for a picture with nothing but the aircraft on it, or where there is no network and nothing cached.
.RE
.TP
.B --rings / --no-rings
Range rings on the pictures \[em] faint discs at a quarter, a half and three quarters of the radius.
.br
Setting name \fBrings\fR, default \fByes\fR.
.RS
.PP
Turn it off for a picture with nothing on it but the aircraft and the ground.
.RE
.TP
.B --window-rings / --no-window-rings
Range rings in the window \[em] the same discs on the realtime display.
.br
Setting name \fBwindow_rings\fR, default \fByes\fR.
.RS
.PP
Turn it off if the window is busy enough already.
.RE
.PP
.SS Labels
.TP
.B --box-opacity
Box translucency \[em] how solid the card behind each information box is, as a percentage (%).
.br
Setting name \fBbox_opacity\fR, default \fB85 %\fR.
.br
Accepts: at least 0, at most 100.
.RS
.PP
Turn it up over a busy map and down over an empty one.
.RE
.TP
.B --labels / --no-labels
Label the aircraft \[em] write the callsign, height and speed beside each aircraft.
.br
Setting name \fBlabels\fR, default \fByes\fR.
.TP
.B --speed-unit
Speed in \[em] what to show speeds and distances in.
.br
Setting name \fBspeed_unit\fR, default \fBknots\fR.
.br
Accepts: one of: knots, mph, kph.
.RS
.PP
knots is what aviation uses and what the aircraft actually said. mph or kph if that is what means something to you.
.RE
.PP
.SS Effects
.TP
.B --pulse / --no-pulse
Pulsing aircraft \[em] swell each aircraft from bright to dim and back, over and over.
.br
Setting name \fBpulse\fR, default \fByes\fR.
.RS
.PP
Turn it off for a still picture, or if a moving screen in the corner of the room is a distraction.
.RE
.TP
.B --pulse-rate
Pulse takes \[em] how long one swell from dim to bright and back again takes (s).
.br
Setting name \fBpulse_rate\fR, default \fB2.2 s\fR.
.br
Accepts: at least 0.2, at most 30.
.RS
.PP
Two or three seconds reads as breathing. Under one is a strobe.
.RE
.TP
.B --echo / --no-echo
Echo circles \[em] rings travelling outward from each aircraft, growing and dimming.
.br
Setting name \fBecho\fR, default \fByes\fR.
.RS
.PP
Handsome on a quiet sky. Turn it off when a hundred aircraft are overhead.
.RE
.TP
.B --echo-every
Echo every \[em] how long between one ring leaving an aircraft and the next (s).
.br
Setting name \fBecho_every\fR, default \fB3 s\fR.
.br
Accepts: at least 0.3, at most 60.
.RS
.PP
Longer for a calmer picture, shorter for a busier one.
.RE
.TP
.B --echo-size
Echo reaches \[em] how far a ring gets from its aircraft before it has faded away (px).
.br
Setting name \fBecho_size\fR, default \fB46 px\fR.
.br
Accepts: at least 6, at most 400.
.RS
.PP
About forty on a nine-hundred-pixel picture. Scale it up with the width.
.RE
.PP
.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. That proves the
framing, the parity, the checksums and the arithmetic; it is not the same as
having held every one of these sensors.
.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
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 odd parity in the top bit
of every payload byte, which is twelve to fourteen bits of check.
.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 Afterwards
When the listening stops, two tables. The first is about reception \[em] who,
how often, how well \[em] and is the one to look at when something is missing:
these transmit on a fixed cycle, so a gap of thirty seconds from a sensor that
sends every sixteen means half of them are being missed, and that is an aerial
problem rather than a weather one. 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.
.SS Receiver
.TP
.B --device
Receiver \[em] which receiver to use, when more than one is plugged in.
.br
Setting name \fBdevice\fR, default \fB0\fR.
.br
Accepts: at least 0.
.TP
.B --gain
Gain \[em] tuner gain in dB, or automatic.
.br
Setting name \fBgain\fR, default \fBauto\fR.
.RS
.PP
Leave it automatic first. If a sensor you know is there never appears, try 40 or so.
.RE
.TP
.B --rate
Sample rate \[em] how fast to sample; a quarter of a megasample is the minimum (Hz).
.br
Setting name \fBrate\fR, default \fB250 kHz\fR.
.br
Accepts: at least 250000.
.TP
.B --frequency --freq
Sensors on \[em] where the sensors transmit (Hz).
.br
Setting name \fBfrequency\fR, default \fB433.92 MHz\fR.
.br
Accepts: at least 3e+08, at most 1e+09.
.TP
.B --offset
Tuning offset \[em] how far to one side of the sensors to tune, if at all (Hz).
.br
Setting name \fBoffset\fR, default \fBstraight at them\fR.
.br
Accepts: at least 0.
.RS
.PP
Leave it at zero. It is worth trying a quarter of the sample rate only if the diagnosis shows bursts that will not slice.
.RE
.TP
.B --simulate / --no-simulate
Invent a garden \[em] put imaginary sensors on an imaginary fence.
.br
Setting name \fBsimulate\fR, default \fBno\fR.
.RS
.PP
Turn this on to see what the whole thing does without hardware. Turn it off to hear real sensors.
.RE
.PP
.SS Listening
.TP
.B --seconds
Listen for \[em] how long to listen before stopping (0 = until interrupted) (s).
.br
Setting name \fBseconds\fR, default \fBuntil stopped\fR.
.br
Accepts: at least 0.
.TP
.B --log / --no-log
Write a log \[em] write every message down as it arrives.
.br
Setting name \fBlog\fR, default \fByes\fR.
.TP
.B --messages / --no-messages
Print every message \[em] one line per message instead of a table that updates in place.
.br
Setting name \fBmessages\fR, default \fBno\fR.
.TP
.B --diagnose / --no-diagnose
Say what is arriving \[em] print what each second of band looked like at every stage.
.br
Setting name \fBdiagnose\fR, default \fBno\fR.
.RS
.PP
Turn this on when sensors you know are there are not appearing. The line of pulse lengths is the useful part: a real message has two or three lengths in it and nothing in between.
.RE
.TP
.B --hold
Keep on screen for \[em] how long a sensor stays on the display after its last message (s).
.br
Setting name \fBhold\fR, default \fB1800 s\fR.
.br
Accepts: at least 1.
.PP
.SS Sensors
.TP
.B --units
Show readings in \[em] metric or imperial, for the display and the export.
.br
Setting name \fBunits\fR, default \fBmetric\fR.
.br
Accepts: one of: metric, imperial.
.TP
.B --only-named / --all-sensors
Only named sensors \[em] ignore sensors that have not been given a name.
.br
Setting name \fBonly_named\fR, default \fBno\fR.
.RS
.PP
Leave it off until you have named things, or there will be nothing to name.
.RE
.TP
.B --unknown / --no-unknown
Show unreadable models \[em] list sensors whose messages framed correctly and were not understood.
.br
Setting name \fBunknown\fR, default \fByes\fR.
.PP
.SS Afterwards
.TP
.B --report / --no-report
Report at the end \[em] print what each sensor said when the listening stops.
.br
Setting name \fBreport\fR, default \fByes\fR.
.TP
.B --csv / --no-csv
Also write a spreadsheet \[em] write the readings as CSV beside the log.
.br
Setting name \fBcsv\fR, default \fBno\fR.
.PP
.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/*.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
.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 .
.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.