Features

Features

FlightScnr Pi shows live aircraft around your location on a circular radar, with rich flight details when you tap a plane. It combines FlightRadar24 (FR24), live positions from adsb.fi (free cloud feed - no local ADS-B dongle), optional local dump1090/readsb, Tomorrow.io weather, and optional AirLabs / FlightAware AeroAPI / OpenSky Network route enrichment. Optional LiveATC audio plays to a USB or Bluetooth speaker. Optional layers include wildfires and USGS earthquakes.

Settings, API keys, tracking, and updates are managed through the web portal. See Data Sources for the full source list.

Round touch display

The UI is designed for a 4″ round LCD with touch (default layout: 720×720).

Screen	How to open	What you see
Radar	Boot / home	Live aircraft, map background, sweep line, compass rose, range label, altitude tags; optional clock HUD
Flight / vessel detail	Tap traffic on radar	Airline logo or aircraft photo, route, type, altitude, speed, heading (vessel: name, type, photo); PREV / NEXT / RADAR footer; finger-scroll when content overflows
Fire detail	Tap a wildfire marker	Name, county, acres, containment, admin units (wrapped), and a location map; PREV / NEXT / RADAR footer
Earthquake detail	Tap a quake marker	Magnitude, depth, place, PAGER / tsunami when present; PREV / NEXT / RADAR footer
Tracked flight	Web portal → Track, or swipe right on radar	Route header with aircraft photo, progress bar, great-circle route map on the radar basemap (incl. long-haul framing), LIVE/ETA, vertical speed ticker; pin to keep screen open
Follow / Live	Swipe right again from Tracked	Live-centered map for the tracked aircraft (position source fallbacks); pin updates while the screen is open
Clock and current weather	Swipe down from radar	Time, date, current weather and conditions
Weather Forecast	Swipe right from clock	Multi-day forecast (Tomorrow.io)
Clock settings	Swipe left from clock	Clock format and related options on-device
About / details	Swipe up from radar	Version, network, API status, portal URL
Settings	Swipe left from About	Multi-page settings (see below): status, ATC, quiet hours, display, HUD, options, layers, theme, system
Wi‑Fi setup	Automatic when offline	QR code to join the FlightScnr setup hotspot, then finish on your phone
Safety disclaimer	Every boot, before radar	Required Accept gate; optional on-device Don't show again enables an eight-second countdown on later boots

Radar	Flight detail
Tracked flight	Follow / Live (placeholder)
Clock & weather	Earthquake detail (placeholder)
Fire detail (placeholder)	Settings list picker (placeholder)

Gestures and controls

• Tap an aircraft, vessel, fire, or earthquake marker → its detail screen. Tap an airport pin for a short ICAO / name / IATA callout (flights and fires win when overlapping)

• Two-finger pinch → zoom radar range in and out (requires multi-touch on X11; see Troubleshooting and Software Setup)

• Swipe between screens (see table above)

• Swipe left on radar → cycle Home ↔ saved favorite locations (up to 10). A brief name toast confirms the new center

• Swipe right on radar → Tracked (when a track is active), then again → Follow / Live

• Long-press then drag on the radar (~0.5 s still hold, then move) → pan the map to a new center. Release after moving to save; release without moving cancels

• Footer buttons appear per screen: flight/fire/quake detail (PREV / NEXT / RADAR), Tracked (PIN / RADAR), About and Settings (PREV / NEXT / RADAR), clock/forecast (RADAR)

• Breadcrumb tap (top label) navigates back one level

• Finger-drag scrolls long Settings, ATC / list pickers, and detail lists; overflowing pages show a thin right-edge scrollbar

• List pickers - multi-option Settings rows (favorites, range, map style, HUD position/style, quiet times, units, altitude/speed floors, traffic labels, ATC airport/channel, and more) open a scrollable overlay instead of tap-to-cycle

  

• Auto-return to clock when no aircraft are visible (optional, portal setting)

• Off-hours schedule can dim the panel, turn it off, or force the clock screen at night

• Settings navigation starts beside About: swipe up from Radar to About, then swipe left

• Secondary screens (flight/fire/quake detail, settings, etc.) show a perimeter timeout ring that counts down before returning to radar

Recenter the radar

After a long-press map pan (or Settings → Display → Click to Set Radar Center, which pans with tap-center to save / tap-rim to cancel), a Center saved dialog lets you:

• Update <favorite> - overwrite the active favorite location
• Save as Home - make it the home center
• Tap the rim - keep it as a one-off custom center

On-device Settings pages

Swipe up from Radar to About, then swipe left into Settings. Settings is a paged screen (page dots at the top; PREV / NEXT / RADAR footer):

Page	Contents
Main	Status hub - IP address, portal URL, CPU / RAM / temperature, latitude/longitude, and which API keys are present
ATC	LiveATC enable (unified power), volume, airport, channel, output (USB / Bluetooth), status; Play / Stop — airport/channel via list pickers
Quiet	LiveATC quiet-hours window (start / end)
Display	Facing calibrate, Click to Set Radar Center, compass, range rings, sweep, tag leaders, color by altitude, units, radar range, rotation, brightness
HUD	Radar clock HUD on/off, position, dark mode, opacity, and chime / tracked / military / earthquake voice volumes
Options	Traffic labels, favorite-location cycle, min/max altitude, aircraft/vessel min speed, basemap style, VFR opacity
Layers	Traffic mode, precipitation, wildfires, earthquakes, airport centerlines, airport icons, ground vehicles, auto-idle clock, alert toggles (military / emergency / hide non-alerted)
Theme	Accent color (RGB) and runway centerline color (RGB)
System	Relaunch app, Reboot, Shutdown (with confirm)

Flight-detail and clock timeouts are set from the web portal (Display & screens), not on-device.

Radar features

• Animated radar sweep with a configurable accent color (custom RGB for sweep, rings, and labels)

• Optional compass rose, range rings, and sweep line (toggle in portal)

• Facing direction - rotate the radar so “up” on the screen matches how the Pi is physically mounted (blips stay correct for non-north-up orientations)

• Map tile background - choose from:

  Id	Label
  dark	Dark: Carto
  osm	Dark: OSM
  stadia_dark	Dark: Stadia (needs STADIA_MAPS_API_KEY)
  black	Dark: Flat (solid black, no tiles)
  light	Light: Carto
  toner	Light: Toner (needs STADIA_MAPS_API_KEY)
  vfr	Light: VFR (FAA sectionals, US)
  streets	Street: Esri
  voyager	Street: Voyager (CARTO)
  satellite	Satellite: Esri

  Cached under /var/lib/flightscnr/maps/

Dark: Carto	Street: Voyager
Light: VFR	Dark: Flat (placeholder)
Dark: OSM (placeholder)	Dark: Stadia (placeholder)
Light: Carto (placeholder)	Light: Toner (placeholder)
Street: Esri (placeholder)	Satellite: Esri (placeholder)

• Optional precipitation overlay (LibreWXR, with RainViewer fallback)

  

• Optional airport centerlines and airport icons (OurAirports; skipped on VFR charts); tap an icon for a short callout

  

• Optional ground vehicles when ADS-B reports GRND/GVEH/SERV-type codes

• Aircraft-type icons (jet, turboprop, helicopter, military, light single/twin props, etc.) with altitude/speed tags - type→icon mappings expand with firmware releases (e.g. V10 / S2T)

• Optional tag leaders (“hockey sticks”) - diagonal leader + underline from callsign to blip, same color as the blip; only drawn when traffic labels are on (control is inert when labels are off)

  

• Optional color by altitude - ADS-B Exchange–style altitude color gradient

  

• Minimum altitude floor / ceiling and min-speed filters to declutter traffic

• Alert mode: highlight military aircraft, emergency squawks (7700/7600/7500), or a custom watch list; optionally hide non-alerted traffic. Paint priority: emergency solid red → watch aqua → military flash (watchlisted military pulses aqua↔red). A pulsing alert rim flash around the bezel signals when an alerted aircraft is in range

  

• Traffic labels: choose which tags are drawn - aircraft, marine, both, or off (Settings → Options, or the portal)

• Distance / speed units: nm+kts, mi+mph, km+kph, and mixed options

• Favorite locations - save up to 10 radar centers; cycle with swipe left on radar, or Settings → Options → Favorite Locations

  

Radar clock HUD

Optional frosted clock HUD on the radar (portal → Display & screens, or on-device Settings):

• Time, weather, wind, and color-coded US AQI at a glance. AQI comes from Open-Meteo, needs no API key, and is cached for about 30 minutes
• Position top or bottom; adjustable opacity
• Optional HUD dark mode - dark pill with light glyphs (default is light frosted glass)
• Optional hourly chime, tracked-flight enter-range sound, military-aircraft sound, and earthquake voice alert, each with its own enable switch and volume
• Tap a HUD audio icon (master, chime, alert, or ATC) to open its volume popover; drag the slider to set level. Master volume scales all HUD audio paths
• Long-press a HUD audio icon to mute or unmute that channel without changing its saved volume
• Sound alerts respect display off-hours and ATC quiet hours where applicable; preview controls can still be used for testing

·

Compass facing / orientation

By default the radar is north-up. If the display is mounted so the top of the screen does not face north, set a facing direction so aircraft and the compass rose match the real world.

Facing is the real-world direction at the top of the screen: 0 = north, 90 = east, 180 = south, 270 = west (any 0–359° value is allowed).

On the device

1. Swipe up → About → swipe left → Settings → Display → tap Facing
2. Traffic drawing and ADS-B refresh pause; drag around the screen to rotate the rose, crosshairs, and map
3. Tap center to save, or tap the rim to cancel

On the web portal

• Radar → Facing direction (degrees) → enter 0–359 → Save radar settings

Stored in /var/lib/flightscnr/round_touch_settings.json and survives updates.

Tracked flight and Follow

Pick any callsign in the web portal (or swipe right on radar when a track is active). The Tracked display shows:

• Origin → destination, airline / flight id, and aircraft type
• An aircraft photo (or airline wordmark) beside the header when one is available
• A progress bar with a moving plane icon and live stats (time remaining, distance, vertical speed)
• A compact great-circle route map under the stats - flown vs remaining path over the same basemap style as the radar (including long-haul routes). Changing radar map style refreshes the Track map too
• PIN to keep the screen open while you leave the portal

Swipe right again for Follow / Live: a live-centered map for that aircraft. Position fallbacks are ordered under portal → Position Sources. The live pin keeps updating while Follow is open (faster poll on that screen).

Flights not yet airborne can use AirLabs schedule data when configured. Route enrichment order is set under portal → Route Sources (or ROUTE_SOURCE_ORDER).

Aircraft photos and marine AIS

Flight detail and the Track screen can show a photo of the aircraft when one is available. Lookup order:

1. Airframe pin (manual / curated)
2. planespotters.net by ICAO hex
3. planespotters.net by registration
4. Wikimedia Commons airline + type (preferred branded match)
5. Wikimedia Commons generic type (flight detail only)

On the Track screen, generic type Commons photos are skipped so you do not get the wrong airline livery; airline+type matches are still allowed. Photographer credit is shown on screen when the source provides it.

Marine traffic uses live AIS from aisstream.io when enabled (portal → Radar → traffic mode, plus an API key). Vessels appear on the same radar as aircraft. Vessel detail photos are fetched from Wikimedia Commons by ship name / IMO when possible.

·

ATC audio

Optional LiveATC streams play through mpv to a USB or Bluetooth speaker:

• Enable and pick airport/channel in the portal (ATC Audio) or on-device (Settings → ATC)
• Pair a Bluetooth speaker on the portal (Bluetooth Speaker); the on-screen ATC page can reconnect quickly
• Channel lists load from a local seed, then refresh via LiveATC search (curl-cffi Cloudflare bypass)
• Playback can resume after reboot when it was left playing; quiet hours block auto-start/resume
• Disabling ATC or changing airport/channel stops the current stream (fixed in 2026.8.3.4)
• Requires: sudo apt install mpv bluez libspa-0.2-bluetooth pulseaudio-utils (also installed by install-pi.sh when available)

·

By default audio is gated to a USB (or selected Bluetooth) sink so the Pi does not open HDMI/headphone paths with no usable speaker. See .env.example (FLIGHTSCNR_REQUIRE_SPEAKER, FLIGHTSCNR_AUDIO_ALLOW_BUILTIN).

Safety disclaimer

The safety disclaimer is shown before any operational feature at every boot:

• Tap Accept to continue.
• On the physical display only, check Don't show again before accepting to remember the current disclaimer version.
• Later boots show Continuing in 8…1 with no Accept button and unlock automatically when the countdown ends.
• Unchecking the box during that countdown clears the remembered choice for the next boot.
• A disclaimer text/version change invalidates the saved choice.
• The web portal System card can clear saved acceptance, but cannot enable or restore it.

Update-available notices

The display checks for releases about every eight hours. When a newer release is found:

• The splash and About screens show the available version.
• Radar shows a dismissible Firmware Update Available bubble opposite the HUD (reappears after reboot until that version is installed or dismissed).
• Dismissal lasts for that release; a newer release makes the notice appear again.
• Dismissing also skips auto-install during off-hours for that version.

Install updates from the portal’s Updates card (Update Now, Later tonight, or off-hours auto-install). See Updates.

Wildfires

Optional wildfire markers on the radar:

Region	Source	API key?
California	CAL FIRE	No
Rest of USA / Canada	NIFC WFIGS (AirNow large-fire layer)	No
Outside USA / Canada	NASA FIRMS VIIRS NRT	Free MAP_KEY under portal → API Keys

Fire Details shows name, county, acres, containment, and admin units when the source provides them. Enable Show wildfires (Radar card or Settings → Layers). Tap a fire icon for its detail screen. Data refreshes every 15 minutes and immediately after recenter or boot.

·

Earthquakes

Optional USGS earthquake markers on the radar:

• Enable Show earthquakes (portal Radar card or Settings → Layers)
• Global M2.5+ epicenters from the USGS catalog — no API key
• Tap a marker for magnitude, depth, place, and PAGER / tsunami when present
• Refresh about every minute and on recenter; events older than about 36 hours are dropped
• Optional Earthquake alert voice (portal Display & screens, or Settings → HUD): once per new M3.0+ event in radar range. Not early warning — catalog events can be minutes old. Needs the layer on plus a USB or Bluetooth speaker; silent during quiet hours and display off-hours

·

Email alerts (optional)

Set an EMAIL address in /etc/flightscnr.env to receive email summaries for notable overhead flights (with an optional map link). Sender credentials use EMAIL_SENDER / EMAIL_PASSWORD; see .env.example. Leave EMAIL blank to disable.