Repository navigation
Code tour
About 5,000 lines in three languages, each chosen for where it has to run: shell for anything that configures a Debian machine, Python with nothing but the standard library for the server, and plain browser JavaScript with no build step for the wall.
No dependencies to install beyond what Raspberry Pi OS already has. That is a deliberate constraint: an installer that needs pip install on a Pi has one more way to fail two years from now.
install.sh the menu-driven installer (also the uninstaller)
bin/zenithboard the whole command line
bin/zenithboard-demo a fake sky, for working without hardware
lib/*.sh one module per subject, sourced by both install.sh and bin/zenithboard
flightinfo/server.py the wall's web server and all its lookups
flightinfo/static/ the wall itself: app.js, flap.js, scene.js, shapes, CSS
flightinfo/aircraft.py reading aircraft.json
flightinfo/social.py social sharing: the service that picks an aircraft and posts it to Bluesky
flightinfo/telegram.py Telegram messages (0.99.6): the crossings and the emergency squawks, to the owner's own chat
flightinfo/social_card.py the split-flap picture with its map (Pillow)
flightinfo/post_lang.py the posts' language (0.51.0): the catalogue, CLDR's plurals, numbers, dates and countries, the templates
flightinfo/console.py the web console's side of the server (0.39.0): sign-in, sessions, pairing, jobs
flightinfo/console_actions.py the fixed list of what the console may run, read by the server and the root helper
systemd/ the unit files
tools/ maintenance scripts (type-list refresh, demo photos, checkers), social-render.js (the dot-matrix picture)
tests/ the whole suite
docs/wiki/ the source of this wiki
| Module | Holds |
|---|---|
common.sh |
cfg_get / cfg_set, the default for every setting, the whiptail helpers (wt_menu, wt_input, wt_msg), validation, service checks |
versions.sh |
Every pinned version and download URL, plus ZB_VERSION. The one file to edit when a provider moves a file |
adsb.sh |
The decoder and the sharing services, the single-MLAT rule |
adsbxstats.sh |
ADSB Exchange's stats package (0.52.0, optional): on by their script with the packages it adds noted, off by their uninstaller and back to what was there, the link to their map |
flightinfo.sh |
Installing and configuring the wall |
gain.sh |
The gain steps, reading stats.json, the advice, the 24-hour log, the menu |
reliability.sh |
Both watchdogs, persistent logs, the health screen |
patches.sh |
Debian security fixes by themselves: the one apt rule it writes, and taking it back |
security.sh |
zenithboard security: reads the running Pi, one line per fact, each WARN with its fix |
stats.sh |
The 15-minute statistics sample, the day files of aircraft seen, the farthest aircraft asked of the wall (stats_farthest_sample), pruning, and the terminal view with its sparkline |
network.sh |
Fixed address, DHCP, net status
|
wifi.sh |
Radio, country, scan, connect, forget, the boot-time re-apply |
ddns.sh |
DuckDNS, No-IP, FreeDNS |
logs.sh |
Size, review, cap, clean, the daily clean-up |
uat.sh |
The optional 978 MHz receiver (United States) |
update.sh |
Updating everything, or one component |
Two conventions throughout: a menu's back entry is always the single word back, and no module reads a setting directly — it goes through cfg_get, so a missing key falls back to the default in common.sh.
One file, read top to bottom in five parts:
-
Config and geometry —
load_config,radius_to_km,haversine_km,bearing_deg. -
Building the picture —
merge_aircraftjoins 1090 MHz and UAT,build_planesturns raw aircraft into what the wall shows: distance, airline from the callsign, type name, route, photo. -
The lookups —
ThrottledLookupand the route, photo and aircraft functions. See Routes, photos and data. -
The farthest aircraft (0.22.0) —
FarthestTrackerkeeps the day's farthest position,farthest_watchfeeds it every five seconds while statistics are on,nearest_cityreadsdata/cities100k.tsv,describe_farthestnames the record with the same route check as the wall (checked_route), andread_farthestreads back what the statistics timer wrote. -
The server —
Handlerserves/, the static files,/api/planesand/api/config.public_configdecides what the browser is allowed to know, which is where the antenna's exact position is held back.
VERSION near the top must match ZB_VERSION in lib/versions.sh; a test enforces it.
| File | Does |
|---|---|
app.js |
The grid geometry, the layout, polling, cycling, the settings panel |
flap.js |
The split-flap board: the letter drum and the rolling animation |
scene.js |
The animated sky scene and the side views, used when there is no photo |
shapes.js |
Aircraft seen from above, drawn as dots |
flags.js |
Registration prefix to country, maker to country, and the flags themselves at 11 x 7 dots. No manufacturer mark is ever drawn |
stats.html, stats.css, stats.js
|
The /stats page: four headline numbers, the two farthest aircraft in words (farthestLine), and three charts from /api/stats, one series each, following the device's light or dark setting |
i18n.js, i18n.css, i18n/<lang>/*.json
|
The pages' languages (0.47.0): t() and tn() with the English as key, the catalogues, the flag and the list at the top, the first visit's choice. tools/i18n.py finds the keys, checks the catalogues and makes the review sheets (docs/translations/) |
console.webmanifest, console-icon-*.png, console-sw.js
|
The console as an app (0.53.0): the manifest, the icons (tools/make_console_icons.js draws them from shapes.js and font5x7.js), a service worker that keeps nothing |
console.html, console.css, console.js
|
The web console (0.39.0): one section at a time, the wizard, Activity, pairing a phone with a QR code (vendor/qrcode.js, MIT). Reads /console/api/*
|
font5x7.js, format.js
|
The dot font, and formatting numbers in metric, imperial or aviation units |
The constants at the top of app.js — GW, GH, SIL_BOX, PHOTO_BOX — are the layout. Change one and tests/test_layout.js will tell you whether the settings gear still fits. See The wall.
| Unit | Does | When |
|---|---|---|
zenithboard-flightinfo.service |
The wall's server | Always |
zenithboard-wifi.service |
Re-applies the Wi-Fi country and on/off choice | At boot |
zenithboard-data-refresh.service + .timer
|
Refreshes the aircraft-type list | Monthly |
zenithboard-ddns.service + .timer
|
Updates your dynamic-DNS host | 30 s after boot, then every 5 min |
zenithboard-netwatch.service + .timer
|
The network watchdog | Every 2 min, if on |
zenithboard-logs-clean.service + .timer
|
Deletes log messages older than 7 days | Daily, if on |
zenithboard-gain-log.service + .timer
|
One gain measurement into the 24-hour CSV | Every 15 min, if on |
zenithboard-console.path + .service
|
The web console's root helper (tools/console_run.py): runs the jobs the console dropped, from its fixed list |
When a job appears, if the console is on |
The watchdog timers are oneshot services fired by a timer rather than long-running daemons: a crashed check cannot take the watchdog down with it, since the next tick starts a fresh one.
Direction
Getting started
How it works
- Architecture
- Configuration reference
- Command reference
- The wall
- Statistics
- Social sharing
- Telegram
- Web console
Running it
Working on it