Repository navigation
Routes photos and data
The wall knows four things the radio does not tell it: which airline a callsign belongs to, what the aircraft model is, where the flight is going, and what the aircraft looks like. Three of those come from the internet, which raises a question the design has to answer: what happens to a wall whose Pi cannot reach the internet? The answer throughout is it shows less, it never stalls and it never shows something wrong.
| What | Source | Needs internet |
|---|---|---|
| Airline name | Built-in list of about 90 major airlines; beyond it, the name the route answer carries (since 0.17.0) | No for the list; the rest rides on the route lookup |
| Aircraft model name |
types.json, refreshed monthly |
Only for the refresh |
| Registration and model, when the decoder does not know them | tar1090's database on the Pi if data localdb on (0.26.0, off by default), then adsbdb.com, then hexdb.io
|
No for tar1090's; yes for the others |
| Route (from → to) | adsbdb.com by callsign, with hexdb.io as a second opinion | Yes |
| Photo | Planespotters by ICAO hex | Yes |
| Silhouette | Drawn in code from the aircraft type | No |
adsbdb's answer for a callsign names the airline as well as the airports ("airline": {"name": "easyJet", "icao": "EZY", ...}). Since 0.17.0 the wall keeps that name for the callsign's three-letter prefix, so the next EZY flight is labelled EASYJET even though easyJet is not in the built-in list. Three rules keep it honest: the built-in list wins when it knows the prefix (its names are the short ones a sign needs); the names live in memory only, since the wall server writes nowhere, and are learned again after a restart from the first route lookup; and with routes switched off nothing is learned, because nothing is asked. Corporate suffixes such as Inc. or AG are dropped before display, and the dot font drops accents as it does for airports.
The route answer names the airline of a flight it knows. Business jets, charters and some airlines' second companies fly with a callsign whose route nobody publishes, so their rows had no airline: the owner's zenithboard stats gaps of 14 November 2026 listed forty such three-letter prefixes over twenty-eight days, JFA on 31 aircraft, VJT on 19, WMT on 17.
sudo zenithboard config-set AIRLINE_LOOKUP 1 (menu 2 The wall → 4 Photos, routes, aircraft names → 5; 0 turns it off; zenithboard status says which) makes the wall ask adsbdb's airline endpoint for the three letters alone: api.adsbdb.com/v0/airline/JFA answers Jetfly Aviation.
-
One question per three letters, at most one every 1.5 seconds, through
ThrottledLookuplike every other lookup. A name is kept thirty days, a designator adsbdb does not know is asked again after seven. In memory only: the wall server writes nowhere, so a restart asks again, a few dozen questions over the following hours. -
What leaves the Pi: the three letters of the callsign, nothing else. With the setting off, nothing.
-
Only an airline's callsign (three letters, then a digit) is asked. A registration flown as a callsign (
GABCD) also starts with three letters, and would be named after a stranger. -
Only the name is taken. The country adsbdb gives is the designator's, not always the operator's (it says Canada for
VJT, VistaJet's Maltese certificate), so the flag stays the one of the aircraft's registration. -
The built-in list wins, then the route answer, then this. adsbdb's names are kept by volunteers and some are old. The owner's forty prefixes were read one by one on 14 November 2026:
-
thirty-one right (
JFAJetfly Aviation,KLCKLM Cityhopper,GACGlobeAir,LXALuxaviation,FJOFlexjet Operations Malta,RUKRyanair UK,DLAAir Dolomiti,EFWBA Euroflyer,LHXCity Airlines,NJUNetJets UK,PVDPadaviation…); -
three wrong, now in the built-in list under their right names, with or without the setting:
JAFcame back as Jetairfly, TUI fly Belgium's former name;PTNas a Brazilian airline, where the aircraft over Moselle are Platoon Aviation's;OCNas O Air, where they are Discover Airlines' (1.1.1); -
two never asked and left bare (1.1.1):
OOMandECAcome back as Zoom Airlines and Eurocypria Airlines, which are not the aircraft heard today, and their right name was not found. No name rather than a wrong one; -
four unknown to adsbdb:
KMM,LUA,HBJ,FJDstay bare.
A name you find wrong, or one you know for those six, is worth an issue: it goes into the built-in list.
-
thirty-one right (
-
An answer that is not one name (two companies under the same letters, a name of more than sixty characters, an answer about other letters) names nothing.
From the owner's log of 17 to 19 November 2026, thirty posts without a route (each post says why in zenithboard logs social):
| How many | Why | What can be done |
|---|---|---|
| 13 | neither adsbdb nor hexdb knows the callsign: business jets, charters, air taxis (NetJets, Global Jet, Jetfly…) | nothing: nobody publishes these routes |
| 6 | both answers are another flight under the same callsign (UAL3907: Hong Kong → Guam and Brussels → Newark, over the Moselle heading south) | nothing: they are rightly refused rather than shown wrong |
| 5 | not an airline callsign (a registration such as 3AMSR, or none) | nothing: routes are looked up for airline callsigns |
| 6 | the answer was still on its way | fixed in 1.2.2: an aircraft back over the antenna did not wait for it, the two-minute wait being timed from its first passage ever |
Every outside lookup goes through ThrottledLookup, and the rule is absolute: the display loop never waits for the network. A lookup that is not answered yet returns nothing, the wall draws the row without it, and the answer appears on a later pass. At most one request leaves every 1.5 seconds, however many aircraft are overhead.
Answers are cached, and so are the failures — a missing answer that was not cached would be asked again every few seconds for as long as that aircraft is in range:
| Case | Asked again after |
|---|---|
| A route was found | 12 hours |
| The callsign is not in the database | 2 hours |
| No answer at all (error, timeout, no internet) | 1 minute |
Twelve hours is not about load. A callsign is reused: today's AF1234 and tomorrow's AF1234 need not be the same route.
A very busy sky (0.99.14). At most 60 lookups wait their turn (20 for hexdb's second opinion). One more is not asked yet and not counted as a failure: it is asked on the wall's first pass after the next request leaves, once the queue has room, rather than a minute later as if the service had not answered. The answers kept are capped at 1000 per service; when the cap is passed, the oldest answers are forgotten down to 900 (asked again if that aircraft comes back), never a lookup still waiting for its answer. Until 0.99.14 the whole cache was emptied at once, lookups still waiting included, which were then asked a second time.
The route databases know callsigns, not flights. A callsign is reused for the return leg, and reassigned over time. Ask about one and you may get yesterday's route, or the same route backwards.
So the answer is checked against the aircraft in front of you before it is shown. An answer is dropped when:
- origin and destination are the same airport — East Midlands → East Midlands was a real sighting;
- the aircraft is more than 120 km from the straight line between the two airports, or more than 20 % of the route length when that is further;
- the aircraft is heading more than 100° away from the destination, which usually means the callsign's other direction.
A blank route row is better than a wrong one.
When adsbdb's answer is dropped, or since 0.99.3 when adsbdb does not know the callsign at all, hexdb.io is asked once as a second opinion, and the wall takes the first leg of that route the aircraft can actually be on. If hexdb is unreachable, nothing is shown and nothing wrong is remembered. hexdb gives each airport a name and no town, so the town is taken from the name (0.25.3): what is in brackets and the words Airport, International and the like go (Turin Airport (Caselle Airport) → Turin), and a name that opens on a city far from the airport gives way to the town by it, within 30 km, from the GeoNames list shipped with ZenithBoard (Brussels South Charleroi Airport → Charleroi; Brussels is 45 km away), while a name that opens on the town by the airport is that town alone (0.25.4: Amsterdam Airport Schiphol → Amsterdam; Palma de Mallorca stays whole). The small words of a town's name are written as the town writes them (Palma de Mallorca, not adsbdb's Palma De Mallorca).
Since 0.99.3 a post that goes out without a route says why, in zenithboard logs social: social: posted RYR73JA (rule) (no route: adsbdb did not know the callsign, hexdb did not know the callsign): …. The reasons are did not know the callsign, did not answer (timeout, refusal), gave a route this aircraft cannot be on, was not asked (too many lookups at once), and since 0.99.4 answer still on its way (N lookups queued) — the service waits two minutes for the lookups, then posts with what is known (EJU81FR, 29 October 2026, went out before hexdb's Brussels → Nice) — and not an airline callsign or no callsign: registrations such as T7NYD and aircraft without a callsign are never looked up. Before it, a post with an empty route row left no trace: on 29 October 2026 the owner's RYR73JA went out without Charleroi → Turin, which adsbdb gave half an hour later, and nothing said whether adsbdb did not know it yet or was never asked.
What leaves the Pi for a route. Showing a route means asking for it: the radio does not carry it. Only the callsign goes out (to adsbdb, then to hexdb in the two cases above), and the code of an airport when hexdb's answer needs its position. A callsign is broadcast in the clear by the aircraft and shown on every public flight map; the receiver's position, radius and address never leave. sudo zenithboard routes off stops all of it, and the route rows stay empty.
The airport positions used for these checks are never displayed. They exist only to judge plausibility, and are fetched once per airport and kept until the next restart.
When the decoder does not know an airframe, the wall asks adsbdb for its registration and model; when adsbdb answers unknown aircraft, it asks hexdb.io once, the same service that gives the second opinion on routes. Found on a real post: TF-AKE (4CC54B), an Air Atlanta Icelandic cargo 747, unknown to adsbdb, known to hexdb. When neither knows it, the posts' pictures leave no blank row: the rows below move up.
From a real post: EWG8QR, 9H-EWG (4D2087), a Eurowings A320, went out with no registration and no model. adsbdb answered unknown aircraft and hexdb n/a; the database of tar1090, the receiver map, knew it (4D2087 → 9H-EWG, A320).
tar1090's installer keeps that database on the card, in /usr/local/share/tar1090/git-db/db, and updates it when tar1090 updates. sudo zenithboard data localdb on (menu 2 The wall → 4 Photos, routes, aircraft names → 4) makes the wall read it first, before adsbdb and hexdb, which are then asked only for what it does not know. Off by default; off goes back to the decoder, adsbdb and hexdb alone.
- Nothing is downloaded and nothing leaves the Pi for it.
- The database is in files named after the first characters of the hex code (
4.jsfor 4D2087), gzip'd JSON. The wall reads the one it needs, keeps four in memory (about 25 MB at most) and remembers 4 000 answers. - Another folder:
sudo zenithboard config-set LOCAL_DB_DIR /path/to/db. With no such folder,onsays so and changes nothing. -
zenithboard data statusnames its version (theversionfile next todb).
Looked up by the aircraft's ICAO hex, which is a far better key than a callsign: it identifies the airframe. Credited to the photographer on screen, with the photo itself a link to its page on Planespotters, and optional — zenithboard photos off. Since 0.24.5, as Planespotters' photo API terms require (read 19 October 2026), the tablet loads each picture straight from the address the API gives, unchanged; the Pi keeps no picture and remembers the API's answer 24 hours at most. Until 0.24.4 the Pi fetched the pictures and served them to the tablet from a memory cache, which those terms rule out. The tablet therefore needs internet to show photos. The terms also rule out posting a photo elsewhere: social sharing never does.
With no photo available, the corner shows an animated sky scene with a side view of the matching model, rather than an empty box. Most aircraft have no photo on a quiet night, so this is the normal case rather than the fallback.
zenithboard photos test makes one real request and tells you whether this Pi can reach the service at all. It is the right command when the corner is always a drawing.
types.json turns an ICAO type code into a readable name and picks the silhouette. It is refreshed monthly by a timer; zenithboard data update does it now, zenithboard data status says when it last happened, and zenithboard data auto off stops it. An out-of-date list costs you nothing but the newest models' names.
Worth reporting, with the callsign and the time. The plausibility rules are deliberately loose — a real flight can be diverted 100 km off its line — so an answer that is wrong but geometrically possible will get through. Those are the cases that improve the filter.
Direction
Getting started
How it works
- Architecture
- Configuration reference
- Command reference
- The wall
- Statistics
- Social sharing
- Telegram
- Web console
Running it
Working on it