Aircraft Radar (ADS B)

Aircraft Radar (ADS-B) Engine

The aircraft tracking engine in ESP-MeteoPlaneRadar streams live transponder telemetry from global ADS-B networks, processes situational airspace data in real time, and renders high-precision vector graphics on the display.

---

📡 ADS-B Telemetry Data Source

The device fetches live flight records from the adsb.fi Open Data API:

https://opendata.adsb.fi/api/v3/lat/{latitude}/lon/{longitude}/dist/{nautical_miles}

• Update Interval: Configurable (default: 5–10 seconds).
• Network Protocol: Secure TLS with HTTP/1.1 keep-alive connection reuse to minimize handshake latency and memory fragmentation.
• Fields Processed: ICAO 24-bit address (hex), callsign (flight), aircraft registration (r), ICAO type (t), latitude/longitude coordinates, altitude (alt_baro / alt_geom), ground speed (gs), track heading (track), vertical speed (baro_rate), and squawk code (squawk).

---

🚀 Airspace Capacity: 250 Aircraft Tracking

Starting with version v1.5.8, the aircraft tracking buffer was expanded to 250 simultaneous targets:

1. PSRAM Memory Footprint

Because the ESP32-S3 module features 8 MB of Octal PSRAM, aircraft structures (~76 bytes per track) are allocated in external PSRAM. Tracking 250 aircraft takes less than 20 KB of memory, leaving ample space for dual 480x480 framebuffers and radar tile caches.

2. Intelligent Distance-Based Retention

The upstream adsb.fi API returns aircraft sorted in ascending order of longitude (from west to east).

When querying a wide airspace (such as a 250 km radius covering Slovakia and Central Europe), a naive linear parser would fill up with western targets and terminate before parsing eastern aircraft.

ESP-MeteoPlaneRadar solves this with a dynamic distance-sorted insertion algorithm:

• As aircraft records stream into the JSON parser, the geometric distance to your home coordinates is calculated in real time.
• If the buffer reaches 250 aircraft and a new target is closer than the most distant target currently tracked, the distant target is swapped out.
• This guarantees 100% full 360-degree coverage without geographic bias.

---

🎨 Altitude Color Scale

Aircraft markers, flight tags, and trajectory vectors are color-coded based on barometric flight levels:

Altitude Range (Meters)	Flight Level (FL / Feet)	Color	Visual Indicator
Ground / Taxi	Surface (0 ft)	Gray	Ground traffic / parked at gates
0 – 1,000 m	Surface to FL030 (~3,300 ft)	Green	Approach / departure low altitude
1,000 – 3,000 m	FL030 to FL100 (~10,000 ft)	Cyan	Initial climb / descent vector
3,000 – 6,000 m	FL100 to FL200 (~20,000 ft)	Blue	Mid-altitude regional transit
6,000 – 10,000 m	FL200 to FL330 (~33,000 ft)	Magenta	High-altitude cruise / jet airways
10,000 m+	FL330+ (> 33,000 ft)	Orange / Red	Commercial long-haul jet cruise

---

📈 Climb & Descent Dynamics

Each aircraft vector displays directional status:

• Climb Indicator: A prominent green upward arrow (▲) is displayed next to the altitude tag when vertical speed exceeds +300 ft/min.
• Descent Indicator: A red downward arrow (▼) is displayed when vertical speed drops below -300 ft/min.
• Level Flight: A horizontal bar or level indicator is shown during steady cruise.

---

🛩️ Aircraft Type & Airline Route Database

To display rich contextual flight information without requiring heavy external lookups:

• ICAO Type Decoder: An embedded lookup table converts codes like A321, B789, AT76, or C172 into clear descriptions (e.g., Airbus A321-271NX, Boeing 787-9 Dreamliner, ATR 72-600, Cessna 172 Skyhawk).
• Airport & Route Matching: Embedded IATA/ICAO airport database resolves origin and destination airports for popular European flights based on callsign prefixes.

---

🚨 Emergency Squawk Detection & Tactical Auto-Switch

The aircraft tracking engine actively monitors secondary surveillance radar transponder squawk codes:

• Monitored Emergency Codes:

  • 7700: General Emergency (Mayday / in-flight technical distress)
  • 7600: Radio Communication Failure (NORDO)
  • 7500: Unlawful Interference (Hijacking)

• Automatic Action:

  • Screen Auto-Switch: If an emergency flight is detected while viewing other screens (Clock, Forecast, or Weather), the device immediately auto-switches to the Tactical Airspace Map.
  • Auto-Centering & Warning Halos: The tactical map centers directly on the coordinates of the emergency flight and draws high-contrast concentric red and white warning halos around the aircraft marker.
  • Rotation Pause: Auto-cycling between screens is paused for 60 seconds to allow the user to track the aircraft without interruption.
  • Background Scanning: A dedicated background polling routine scans for emergency squawks across a 250 km radius every 25 seconds even when the device is displaying the Clock or Forecast.

---

📊 Daily Flight Traffic Statistics (FlightStats)

Firmware v1.6.0 introduces a high-performance statistics recorder stored in 8 MB Octal PSRAM:

• Unique Aircraft Counter: Utilizes an in-memory hash set of ICAO 24-bit transponder addresses to track the exact count of unique airframes detected each day.
• Speed Record: Logs the highest ground speed recorded throughout the day alongside the callsign of the aircraft (e.g. 1042 km/h · DLH458).
• Distance Record: Logs the maximum detection distance achieved from your station and the associated callsign (e.g. 248 km · UAE152).
• Flight Level Span: Tracks the minimum and maximum cruising altitudes (e.g. FL025 - FL410).
• Total ADS-B Packets: Accumulates the raw message count received from the data feed.
• Lifecycle: All statistics automatically zero out at 00:00 midnight local time or can be reset on demand via the Web Dashboard.

---

✈️ Overhead Aircraft Tracking (Overhead Widget & Chime)

• Cylindrical Detection Zone: Monitors an airspace cylinder directly above your coordinates with a customizable radius (1 to 50 km, default 10 km).
• Clock Widget: When an aircraft enters the overhead zone, a flight badge appears on the Clock face displaying callsign, current altitude, and distance.
• Acoustic Chime: Optionally rings an alert tone on the active buzzer when a new aircraft enters overhead airspace.