FlightScnr Pi

A round 4″ touch display flight and marine tracker for Raspberry Pi. Dark radar UI, animated sweep, map tiles, gesture navigation, LiveATC audio, and a local web portal for setup — no SSH required for day-to-day use. Modeled after FlightScnr.

Display: Waveshare 4inch DSI LCD (C) (720×720) and the newer 4-DSI-TOUCH-C (same resolution; different bezel, fits the same housing). The new panel needs a different firmware overlay or it stays black — see Quick install and #207. On 4-DSI-TOUCH-C, the display power cable is mandatory (do not rely on DSI power alone).

FlightScnrPi Discord — community help, builds, and troubleshooting

Features

Live aircraft (and optional marine traffic) on a circular radar, with rich detail screens when you tap. Powered by FR24, adsb.fi, optional local dump1090/readsb, Tomorrow.io weather, optional precipitation from LibreWXR (RainViewer fallback), optional route enrichment, USGS earthquakes, and wildfire layers (CAL FIRE / NIFC / NASA FIRMS). Configure everything from the web portal. Full detail: Features wiki.

Current release: 2026.10.1.1 on main.

Screens

Radar home, flight detail, tracked flight with route map, Follow / Live map, clock faces (digital, analog, night altimeter, Flieger) plus moon and forecast, an airport METAR card, and a split-flap arrivals / departures board — swipe between them on the 720×720 round touch display. Swipe right on radar opens Tracked (when a track is active), then again for Follow / Live. Swipe left opens the arrivals board. Saved favorite locations open from the HUD Home icon or Settings → Options.

Weather providers

Tomorrow.io is the preferred source for current weather and daily forecasts. Open-Meteo automatically takes over when the Tomorrow.io key is missing, its portal switch is off, quotas are reached, or requests fail. No additional setting or Open-Meteo key is needed. Current weather and wind refresh at :01 and :31; daily forecasts at :01. Tomorrow.io resumes priority on the next allowed refresh. If both services fail, the display keeps its last readings.

Weather data sources are credited separately from the Tomorrow.io icon artwork. Open-Meteo data is CC BY 4.0, and its public API is for non-commercial use. This project remains CC BY-NC-SA 4.0; commercial use requires separate permission from Yash Mulgaonkar, the original author of FlightScnr_Pi.

Language and region

The clock, date, forecast, Tomorrow.io weather descriptions, portal settings overview, and Language & Region controls can use English, Dutch, German, French, Spanish, or Hungarian. English remains the safe default and per-message fallback. Choose a language and date order independently on-device under Settings → Display or in the web portal; System language detection is available as an explicit choice but is never selected automatically.

Translation catalogs are dependency-free, validated JSON shared by the Python display and browser portal. See the translation contributor guide to review a catalog or add another language.

Adding a language needs no code changes. Each language is a self-contained folder under flightscnr/i18n/locales/<locale>/ holding a manifest.json (locale code, native and English names, catalog revision, authors) and a messages.json. The loader discovers every folder under that directory at startup, so a new language is picked up automatically and appears in the on-device and portal pickers by its native name. To add one:

1. Copy the en folder to a new normalized locale tag, e.g. flightscnr/i18n/locales/pt-BR/.
2. Fill in the manifest names/authors and translate the values in messages.json, leaving the keys and {placeholders} unchanged.
3. That is all the wiring. Each pack is validated on load: placeholders must match English, missing keys fall back to English, and unknown or unsafe packs are skipped, so a partial or outdated translation can never break the UI.

The contributor guide has the full rules, review checklist, and version-compatibility contract.

Map layers

Eleven basemap styles: CARTO dark/light/Voyager (free CARTO_BASEMAPS_API_KEY), OSM dark, Dark Flat (solid black), Stadia dark + Toner (free STADIA_MAPS_API_KEY), Esri streets/satellite, free FAA VFR sectionals (US), and Nautical: Seamap (Open Waters Seamap depths and seamarks — not for navigation). Optional tag leaders, color by altitude, precipitation, airport overlays, wildfires, and earthquakes.

Radar clock HUD

Optional frosted HUD on the radar: time, weather, wind, and US AQI. Light or dark pill, adjustable opacity, and per-channel audio controls (chime, tracked, military, earthquake voice, ATC).

Aircraft photos & marine AIS

Flight detail can show aircraft photos (planespotters.net / Wikimedia). Optional marine AIS from aisstream.io puts vessels on the same radar, with ship photos from Wikimedia Commons. If that key is unset or the stream fails, positions fall back to Open Waters AIS (no key required). Note: aisstream.io is known to be unreliable — the fallback covers that, and the upstream status monitors are still worth a look before assuming a FlightScnr Pi bug.

ATC audio

Optional LiveATC streams to a USB or Bluetooth speaker — pick airport and channel on-device or in the portal.

Also included: scrollable list pickers for on-device settings, portal Route Sources / Position Sources, alert mode, facing / orientation, favorite locations (HUD Home icon), optional LoFi under LiveATC, a boot safety disclaimer, and portal OTA (Update Now, Later tonight, off-hours auto-install, Finish install, Repair & Update). See the Features wiki for the full list.

Documentation

Full guides live in the Wiki. Start there for build, install, features, and troubleshooting.

Upgrading from older builds: one Update Now is usually enough. Portal options also include Later tonight, Auto-install during off-hours, Finish install, and Repair & Update. If an OTA pulled a newer installer but could not run it (pre-re-exec path), the device auto-finishes install steps after restart — or use Finish install in the portal. If LightDM is switched to X11 for pinch-zoom, the Pi reboots automatically.

Stuck on 2026.8.5.x (Update fails silently): an older install step flipped permissions on scripts/release.sh, which used to block the update pull. That file is now frozen upstream, so pressing Update Now once more in the portal should work — no terminal needed. If it still fails (other local edits, corrupted git store), run on the Pi:

curl -fsSL https://raw.githubusercontent.com/yashmulgaonkar/FlightScnr_Pi/main/scripts/repair-ota.sh | bash

Use | bash -s -- --hard only if other local edits also block the pull.

Quick install

1. Gather parts and assemble the unit — see Hardware and Hardware Assembly.
2. Flash Raspberry Pi OS (64-bit, with desktop), then enable the matching Waveshare panel overlay in boot config.txt (/boot/firmware/config.txt on Bookworm+):

dtoverlay=vc4-kms-v3d

Use only one panel overlay. On 4-DSI-TOUCH-C, connect the display power cable — it is required (the panel will not run from the DSI ribbon alone). On Pi 5 / CM, if the screen stays blank, try the DSI0 form of the same overlay (see Software Setup). Thanks to @Matzebhv for the newer-panel overlay in #207.

Then:

git clone https://github.com/yashmulgaonkar/FlightScnr_Pi.git ~/FlightScnr_Pi
cd ~/FlightScnr_Pi
sudo bash install-pi.sh

The installer forces the desktop to X11 (needed for pinch-to-zoom) and reboots automatically when that switch is pending. It also enables the enclosure cooling fan via the kernel gpio-fan overlay (GPIO 14, on at 60°C), disables Wi‑Fi power save for kiosk reliability, and enables Bluetooth for speaker pairing.

3. Open the web portal at http://<hostname>.local and add API keys.

Step-by-step instructions: Software Setup.

Contributing

Contributions are welcome. If you find a bug, have an idea, or want to improve the project, open a pull request. For larger changes, opening an issue first is helpful so we can discuss the approach.

Language contributors should follow the translation catalog and native-review guide. Keep translation-only changes separate from runtime code so attribution and review stay clear.

Questions or setup help? Join the FlightScnrPi Discord:

Credits

• Parts of this repo are based on code by c0wsaysmoo, used with their prior written permission. Thank you!
• AIS WebSocket client design adapted from capsule-radar-ais (MIT).
• Aircraft photos courtesy of planespotters.net contributors (when credited on screen).
• Vessel photos from Wikimedia Commons contributors under their respective licenses.
• Precipitation radar tiles primarily from LibreWXR by Joshua Kimsey (public API api.librewxr.net), licensed under CC BY 4.0. Fallback: RainViewer. See flightscnr/display/round_touch/PRECIP_ATTRIBUTION.md.

Full asset attributions: Credits and License.

License

Firmware

Original application code, tools, and documentation in this repository are licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (LICENSE). Required attribution text is in NOTICE.

• Attribution: credit the author (Yash Mulgaonkar), link to https://github.com/yashmulgaonkar/FlightScnr_Pi and the license when you share or adapt this work.
• NonCommercial: you may not use this material for commercial purposes without separate permission.
• ShareAlike: adaptations must be released under the same license.

First-party source files include a copyright / SPDX / [AI-DIRECTIVE] header. Do not remove those headers. AI coding agents and forks should follow AGENTS.md (and .cursor/rules/license-attribution.mdc) so attribution and license terms stay intact.

Enclosure license

The 3D-printed enclosure is not part of this firmware repository. Its digital files and physical prints are governed by the license shown on the MakerWorld model page. There are two print profiles on the same model:

• Enclosure without speaker
• Enclosure with speaker

That content is published under a Standard Digital File License, which includes terms such as:

This user content is licensed under a Standard Digital File License.
You shall not share, sub-license, sell, rent, host, transfer, or distribute in any way the digital or 3D printed versions of this object, nor any other derivative work of this object in its digital or physical format (including - but not limited to - remixes of this object, and hosting on other digital platforms). The objects may not be used without permission in any way whatsoever in which you charge money, or collect fees.

Always read the full license on MakerWorld before downloading, printing, or sharing the enclosure design.

If you want to make your own analytics for your repos, click here.