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.

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
Fire detail	Tap a wildfire marker	Name, county, acres, containment, and a location map; 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, LIVE/ETA, vertical speed ticker; pin to keep screen 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

Gestures and controls

• Tap an aircraft, vessel, or fire marker → its detail screen
• Two-finger pinch → zoom radar range in and out (requires multi-touch; see Troubleshooting)
• Swipe between screens (see table above)
• 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 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 picker, and detail lists
• 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. Radar swipe-left is reserved for future apps.
• Secondary screens (flight/fire 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, volume, airport, channel, output (USB / Bluetooth), status; Play / Stop
Quiet	LiveATC quiet-hours window (start / end)
Display	Facing calibrate, Click to Set Radar Center, compass, range rings, sweep, units, radar range, rotation, brightness
HUD	Radar clock HUD on/off, position, dark mode, opacity, and chime / tracked / military sound volumes
Options	Traffic labels, favorite-location cycle, min/max altitude, aircraft/vessel min speed, map style, VFR opacity
Layers	Traffic mode, precipitation, wildfires, airport centerlines, airport icons, ground vehicles, auto-idle clock
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
• Map tile background - dark / light / Voyager CARTO street maps, or free FAA VFR sectionals (US); cached under /var/lib/flightscnr/maps/

· ·

• Optional precipitation overlay (LibreWXR, with RainViewer fallback)
• Optional airport centerlines and airport icons (OurAirports; skipped on VFR charts)
• 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
• 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. 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 on-device under 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, and military-aircraft sound, 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; 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

Pick any callsign in the web portal (or swipe right on radar when a track is active). The 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 (dark / light / Voyager / VFR). Changing radar map style refreshes the Track map too
• PIN to keep the screen open while you leave the portal

Flights not yet airborne can use AirLabs schedule data when configured. Route enrichment can also fall back to FlightAware and OpenSky (order configurable via 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.
• Dismissal lasts for that release; a newer release makes the notice appear again.

Install updates from the portal’s Updates card.

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, and containment 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.

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.