Flight Radar

A live aircraft tracker for the ESP-Mosaico 480 × 480 touch display. It loads nearby ADS-B positions from adsb.lol, plots aircraft by bearing and distance, and shows flight details when an aircraft is tapped.

Release status

This is an experimental preview, not a navigation or flight-safety tool. The firmware builds successfully. Metric conversion, route/selection logic, label layout and audio regression checks pass. Earlier native simulator checks passed; the submission-time replay rerun was blocked by a compiler warning in the shared graphics library, so that full rerun is not claimed as passing. Installation through Vibe Mode, live airport routes, cached reopening and the metric data page were verified on hardware before the 0.1.1 version bump. DKH1136's route and metric readout loaded and played on the device, and the user confirmed it was clear. The 0.1.1 package has not been separately flashed. External data and speech services may be unavailable or incomplete. This release uses adsb.lol, not Flightradar24, and does not claim equivalent aircraft coverage.

Use

1. Configure and connect Wi-Fi in Vibe Mode. The app reuses that saved network; credentials are not stored in this project.
2. Start Flight Radar and wait for the status to change from CONNECTING to LIVE.
3. Drag the radar to move its geographic center. Tap + to zoom in or - to zoom out around that center (50, 100, 200 or 450 kilometres). The top-right range button also cycles through the four ranges. The top-left coordinates update as you drag; releasing fetches flights around the new center. Flight labels grow at every zoom step, up to four times their overview size at the 50 km setting. Labels near the right edge move to the left of their aircraft. Zoomed views keep non-overlapping labels visible even in busy areas.
4. Tap an aircraft to open a full-screen route card and hear “from … to …” with the airport, city, and country, followed by the last reported ground speed in km/h, altitude in metres, direction in degrees and distance from the current radar centre in kilometres. Tap FLIGHT DATA below the callsign for large metric values, aircraft type and registration; SHOW AIRPORTS returns to the route. Data remains visible when airports are unavailable. Tap HEAR FLIGHT DETAILS for a new readout using the latest received values, the large < BACK> button to return, or swipe right across the card. Flight selection happens on release, so dragging across an aircraft pans instead of selecting it. Long city/country names scroll; airport names wrap across lines. If speech cannot load, VOICE FAILED / RETRY lets you try again. RETRY ROUTE retries a failed airport lookup. The selected card stays open even when its aircraft temporarily disappears from the live feed. Recently received callsigns survive blank feed updates for two minutes. Reopening a successfully loaded flight uses its published route for up to ten minutes, labeled CACHED PUBLISHED ROUTE, without another route request. A changed callsign starts a fresh lookup; the app does not guess missing routes.
5. Tap the top-left coordinates to refresh immediately. Live data also refreshes every 15 seconds.
6. Tap the yellow center marker for the assumed address/area, coordinates and current radius. Tap < BACK or swipe right to return.
7. Tap HOME to recenter on the internet-based location estimate, keeping the current zoom. LOCATING... means lookup is pending; RETRY LOCATION retries a failed lookup. Panning while a lookup is pending does not snap the view back when its result arrives; Home remains available afterward.

The initial fallback center is Shanghai (31.2304, 121.4737). Change CONFIG_FLIGHT_RADAR_LATITUDE and CONFIG_FLIGHT_RADAR_LONGITUDE with menuconfig for another location. The tracker shows up to the 32 nearest aircraft with positions seen during the previous minute. ADS-B coverage varies by location.

An empty radar does not prove that no aircraft are nearby. In Shanghai, tests on 1 October 2026 returned no aircraft within 50 km from the current feed even when the user could see nearby traffic in Flightradar24. Other tested anonymous feeds did not establish better local coverage. Zooming out may show aircraft in areas with receiver coverage, but cannot recover observations missing from the provider. The simulator cover uses sample aircraft and is not evidence of local live coverage.

At startup the device requests its own public-IP location over HTTPS from ipwho.is. No API key or Wi-Fi credentials are sent. A valid response establishes the session's Home coordinates and city, region and country. It is a city-level internet estimate, not GPS or a verified street address; VPNs, carrier routing and ISP gateways can put it in another city. The service has no availability guarantee. Failed lookup does not turn the Shanghai fallback into a claimed user location.

LIVE describes the aircraft feed, not location accuracy. Both the query and display use the same center and radius; replies for an earlier view are ignored. The location card marks Home as IP ESTIMATE / NOT GPS. Other centers show coordinates without inventing an address. Only the exact Shanghai fallback has an offline nearby-area label from OpenStreetMap via Photon. Opening the location card makes no additional network request.

Data is provided by adsb.lol under the Open Data Commons Open Database License. The public service is suitable for personal use and may require coordination for production use.

Airport itineraries come from the provider's published VRS standing-data records, not the failing location-based route endpoint. They are published schedules, not live-confirmed destinations: diversions or schedule changes may differ. Stopovers are shown as VIA airport codes. Flights without a callsign or published route remain unavailable; the app does not invent their airports.

Temporary route network/server failures get at most two attempts, separated by half a second. Missing records are not retried automatically. Rate limits pause requests to that service for a minute, while cached routes remain available. Map requests are spaced by at least five seconds and use the latest browsed view. Route and voice loading leave the loading state after 25 seconds; a late valid response can still recover the card. Messages distinguish missing flight IDs, missing published routes, network failures, invalid responses, timeouts and rate limits.

Flight values follow the provider's ADS-B field definitions: ground speed is not airspeed; barometric altitude is used when available, otherwise geometric altitude is explicitly labelled. Neither is height above the ground. Direction uses ground track, with reported heading as a fallback. Missing or invalid fields display -- and are spoken as unavailable, not zero. Distance is from the browsed radar centre, which may differ from Home. All displayed, spoken and simulator-exported distances use kilometres. Range queries are converted only at the provider boundary, and returned aircraft are filtered to the exact metric radius shown on screen.

English flight speech uses Baidu Translate's online voice endpoint. It requires internet access and is not an offline or guaranteed-availability service. Route text appears before speech finishes loading. Audio is converted to the speaker's 24 kHz mono format; announcements are limited to 60 seconds. When the route provider has no result, available telemetry can still be spoken without inventing airports.

Sound effects use short electronic pulses: a quiet scan ping, a double-pulse flight-selection confirmation and a crisp zoom tick. A sharp, briefly frequency-modulated metallic attack gives way to a steady tone and fast decay, without ascending melodies. The file edges fade to silence to avoid clicks. Flight speech stops other sounds when its announcement starts.

Developer build

From the workspace root:

python3 mosaico.py game run --project projects/flight_radar
python3 mosaico.py game run --project projects/flight_radar --headless --frames 120 \
  --replay projects/flight_radar/tests/range-cycle.replay.json
python3 mosaico.py game build --project projects/flight_radar
python3 mosaico.py iris system-update --project projects/flight_radar
python3 projects/flight_radar/tests/check.py

The regression check requires a C compiler and FFmpeg. It checks sound-effect format, duration, silent endpoints, amplitude headroom and embedded asset integrity; it also checks audio conversion at 16/24/44.1 kHz, stereo-to-mono, pitch/duration, 35-second readouts, invalid data and short buffers, then replays flight selection, back navigation, the complete range cycle and the location card, drag/zoom/recenter and swipe-back. It also checks stale-view rejection, date-line/polar panning, IP response validation and failed location retry. The simulator's Home location is a deterministic fixture, not a lookup. It also covers identity/route cache expiry, changed callsigns, bounded retry policy, timeout recovery and native failure-screen rendering. The Host-only FLIGHT_RADAR_SIM_ROUTE_ERROR can simulate missing, busy or timeout. Metric conversion and speech checks cover missing/invalid fields, valid zeroes, ground status, geometric-altitude fallback and refreshed readouts. The telemetry replay exercises switching between the data and airport pages and going Back.

The simulator uses deterministic sample flights so visual and touch checks are repeatable. Firmware uses the live feed. One response is capped at 256 KB; reduce the range in unusually dense airspace if the status changes to STALE.

License

The Flight Radar application code, visual design, and generated sound effects are available under Apache-2.0.