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

Cover every option in the help, the manual and the readme, and say what to install

Browse source 
An audit rather than a feature, prompted by wanting this fit to hand to
somebody else.

Five options had no command-line flag written down in the table the manual
is generated from -- location, hold, schedules, tile_url and speed_unit --
so five flags that exist were missing from the manual.  Four of them did
exist under other names and are now recorded; hold had no flag at all and
has one.

Four switches could be turned off from the command line and not back on:
--no-lookup, --no-basemap, --no-airports and --no-labels had no positive
halves, so an option turned off in the saved settings could not be turned on
again for one run.  All four now have both.

And adsb, which opens the window and draws a map when it stops, could not be
given any of the settings that decide what those look like: no --at, no
--radius, no --tiles, no --map-brightness, no --width, --fps, --trail,
--fade, --stale, --airports or --labels.  It takes all of them now.

The manual had no list of the aircraft options at all -- the ADS-B sections
were hand-written prose -- so five of them appeared nowhere in it.  It now
generates an AIRCRAFT OPTIONS section from the same table the menu and the
flags come from, and the readme carries a table of all thirty-four with
their flags and defaults.  Three tests hold the three of them together: one
that every option records its flag, one that every flag the table claims
actually exists on a command, and one that the readme names them all.

The installing instructions now list every dependency rather than only the
optional ones: the four Python packages with their names in Debian, Fedora
and Arch, and librtlsdr, which is a C library and therefore the one thing
pip cannot bring and a virtual environment cannot supply.  What reaches a
network is written down too -- which host, when, and which file it is cached
in -- since somebody installing this on a metered or air-gapped machine has
to be able to see that nothing is fetched behind their back.  build-repo.sh
needs dpkg-dev and apt-utils, which a minimal system does not have, and now
says so.

Verified rather than asserted: a clean virtual environment, pip install from
this tree, and a real log read back through the installed command.  It pulls
seven wheels rather than the four the page claimed, the other three being
what Rich brings with it.

Also: matplotlib is gone from the readme's dependency table, nothing having
imported it; ffmpeg and Qt are in it, both having been missing; ffmpeg is a
Suggests on the package; and resume.sh is ignored.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016PsWPTweCT6pwxKngvVxcg
This commit is contained in:
The Dust Council 2026-09-06 14:12:33 -07:00
parent 6d2436cde1
commit 8ed01f991f
16 changed files with 1012 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

101
README.md
View file

@ -111,9 +111,16 @@ be built.
| **required** | Rich | `python3-rich` | `python3-rich` | `python-rich` | menus and the live display |
| **required** | PyYAML | `python3-yaml` | `python3-pyyaml` | `python-yaml` | settings file and profiles |
| *recommended* | eSpeak NG | `espeak-ng` | `espeak-ng` | `espeak-ng` | clearer spoken timestamps |
| *optional* | Qt | `python3-pyqt6` | `python3-pyqt6` | `python-pyqt6` | the realtime aircraft window |
| *optional* | ffmpeg | `ffmpeg` | `ffmpeg` | `ffmpeg` | writing `.mp4` instead of `.gif` |
| *optional* | rtl-sdr tools | `rtl-sdr` | `rtl-sdr` | `rtl-sdr` | `rtl_test` and friends for diagnosis |
| *optional* | a speech recogniser | **pip only** | **pip only** | AUR | transcribing speech to text |
| *optional* | Matplotlib | `python3-matplotlib` | `python3-matplotlib` | `python-matplotlib` | nothing yet; reserved for plots |
**Only `librtlsdr` cannot come from pip.** It is a C library, so no virtual
environment brings it with it, and it is the one thing you have to install
from your distribution by hand. Everything that does not touch the hardware
works without it — reading logs, drawing maps, decoding recordings, the
simulated sky — and anything that does says so plainly rather than failing.
Two notes on the optional ones:
@ -1069,11 +1076,27 @@ brightest red there is and the one furthest from every altitude colour in
every theme. A softer red sat close enough to a low aeroplane on the default
map, and to a mid-altitude one on the red theme, to be taken for one.
**Nothing is ever drawn over the flag.** It goes down after everything else on
both pictures — after the aircraft, their trails and their boxes — because 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. The halo of a vector
theme cannot cover it either: a halo only ever goes on the ground, the grid
and the empty background.
The flag is drawn **only where the receiver was actually told where it is**.
Without a position the middle of the picture is worked out from whatever flew
past, which is not a place anybody is standing, and a flag on it would say
that somebody is.
**`--box-opacity PERCENT`** (85 by default) 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 0 they sit straight on the map
and at 100 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, where a flat wash would
not. The animated pictures had **no card at all** before this, so `0` is what
they used to look like.
**Range rings** put 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
@ -1632,6 +1655,82 @@ rings meet the nearer wins, which is what happens on the tube as well. It
costs about 55 ms a frame at 1400×1258, and the default theme skips the pass
entirely.
## Every ADS-B option
Thirty-four of them, in the six groups the menu shows. Each is a flag on the
command line and a line in `bandsaunter` → 5, and both are generated from one
table in the source, so they cannot disagree. `man bandsaunter` has the long
form of every one.
**receiver**
| option | flag | default | what it does |
| --- | --- | --- | --- |
| Receiver | `--device` | `0` | which receiver to use, when more than one is plugged in |
| Gain | `--gain` | `auto` | tuner gain in dB, or automatic |
| Sample rate | `--rate` | `2 MHz` | how fast to sample; two megasamples a second is the minimum |
| Receiver at | `--at` | — | where the receiver is, as latitude,longitude (blank = work it out) |
| Invent a sky | `--simulate` | `no` | fly imaginary aircraft past an imaginary receiver |
| Imaginary sky near | `--near` | `47.55,-122.30` | where the simulated aircraft are flying |
**listening**
| option | flag | default | what it does |
| --- | --- | --- | --- |
| Listen for | `--seconds` | `until stopped` | how long to listen before stopping (0 = until interrupted) |
| Show every frame | `--frames` | `no` | print each frame as it arrives, rather than a running count |
| Write the log | `--log` `--no-log` | `yes` | write every frame to a file as it arrives |
| Also write a KML | `--kml` | `no` | write the flight paths for Google Earth as well |
| Keep on screen for | `--hold` | `45 s` | how long an aircraft stays on the display after its last frame |
| Draw when finished | `--map` | `no` | draw the map as soon as the listening stops |
**aircraft**
| option | flag | default | what it does |
| --- | --- | --- | --- |
| Look the aircraft up | `--lookup` `--no-lookup` | `yes` | ask the public registers who each aircraft is |
| Schedule services | `--schedules` | — | which paid schedule services to ask, in order (blank = all with keys) |
| Check the positions | `--recheck` | `no` | throw out positions the aircraft could not have been in |
**animation**
| option | flag | default | what it does |
| --- | --- | --- | --- |
| Picture | `--out` | `gif` | what kind of picture to draw |
| Animation length | `--seconds` | `30 s` | how long the animation should run for |
| Speed | `--speed` | `fit to the length` | seconds of flying per second of animation (0 = fit to the length) |
| Frames a second | `--fps` | `12` | how many frames of animation each second holds |
| Picture width | `--width` | `960 px` | how many pixels across the picture is |
| Trail | `--trail` | `the whole path` | how much of the path to leave behind each aircraft (0 = all of it) |
| Fade out over | `--fade` | `20 s` | how long an aircraft takes to fade away once it has gone quiet |
| Forget after | `--stale` | `300 s` | stop drawing an aircraft this long after its last report |
**the map**
| option | flag | default | what it does |
| --- | --- | --- | --- |
| Map underneath | `--basemap` `--no-basemap` | `yes` | draw a real map under the flight paths |
| Tile server | `--tiles` | — | where the map tiles come from |
| Colour theme | `--theme` | `night` | how the map looks: the colours, and whether the lines glow |
| Map brightness | `--map-brightness` | `70 %` | how bright the map under the aircraft is drawn, as a percentage |
| Map radius | `--radius` | `100` | how far around the receiver the map reaches (0 = fit whatever was heard) |
| Mark the airports | `--airports` `--no-airports` | `yes` | mark every aerodrome on the map, not only the ones flown between |
| Range rings on the pictures | `--rings` `--no-rings` | `yes` | faint discs at a quarter, a half and three quarters of the radius |
| Range rings in the window | `--window-rings` `--no-window-rings` | `yes` | the same discs on the realtime display |
**labels**
| option | flag | default | what it does |
| --- | --- | --- | --- |
| Box translucency | `--box-opacity` | `85 %` | how solid the card behind each information box is, as a percentage |
| Label the aircraft | `--labels` `--no-labels` | `yes` | write the callsign, height and speed beside each aircraft |
| Speed in | `--speed-unit` | `knots` | what to show speeds and distances in |
**Where they live.** Saved with `s` in the menu to
`~/.config/bandsaunter/aircraft.yaml`, which is plain YAML you can edit or
copy between machines. API keys are deliberately **not** kept there — see
[Knowing the leg for certain](#knowing-the-leg-for-certain).
## Meters and weather sensors
Two things on the ISM bands are worth naming rather than reporting as hex.