Plane Radar

3D printed case (STL + assembly): MakerWorld · Firmware: Releases

Firmware for an ESP32-C3 Super Mini and a 1.28″ round GC9A01 display (240×240). Shows a circular ADS-B radar around your configured location, with WiFiManager for first-time setup.

What it does

1. Wi‑Fi setup (if needed) — captive portal on AP PlaneRadar-Setup
2. Radar — live aircraft from adsb.fi on a sonar-style grid

After Wi‑Fi is saved, the device reconnects automatically; the radar runs in the main loop with periodic ADS-B updates (~5 s).

Controls (BOOT, GPIO 9, active LOW)

During setup you can also hold BOOT at power-on to force a credential reset (same as the long press).

Wi‑Fi setup portal

First-time setup (no saved Wi‑Fi):

1. Connect to PlaneRadar-Setup
2. Open http://plane-radar.local (preferred) or http://192.168.4.1 — both are shown on the yellow setup screen; captive portal may open automatically
3. Set home Wi‑Fi, then save

Reconfigure anytime (after the device is on your network):

1. Open http://plane-radar.local or http://<device-ip> (e.g. from your router or serial log at boot)
2. Change Wi‑Fi, location, units, or runway overlay; save

The same portal runs on the setup AP and on the device’s LAN IP while connected to Wi‑Fi. mDNS hostname is plane-radar → plane-radar.local (kPortalHostname in config.h). Some clients resolve .local slowly; use the IP if needed.

Custom fields (stored in NVS):

After a reset, the device reboots and shows the setup screen immediately (no “Connecting” loop on stale credentials).

Radar display

Grid

• Dark blue background, subdued green rings and crosshairs
• White N / S / E / W at the bezel; range label on the east spoke (ring 3 = ¾ of outer radius)
• White center dot

Layout and colors: include/ui/radar_theme.h.

Range presets

Preset and miles/km choice persist across reboot (planeradar NVS namespace).

Runways

• Major airports from OurAirports (large_airport); all open runway strips in range (helipads excluded)
• Teal runway lines with one ICAO label per airport (e.g. KJFK); toggle in the Wi‑Fi setup portal
• Update the embedded list: python3 scripts/build_large_airports.py

Aircraft

• Inside the outer ring — red heading triangle, magenta speed vector (clipped at the ring), callsign / type / altitude tags
• Outside the ring (still within ADS-B fetch) — small red dot on the screen rim at the correct bearing (direction cue; not distance-accurate past the ring)
• Tags — placed toward the center: west (left) → tag on the right of the symbol; east (right) → tag on the left

As range decreases (or aircraft approach), targets move inward; beyond-ring dots become full symbols when they cross the outer ring.

ADS-B

• Source: https://opendata.adsb.fi/api/v3/
• Fetch radius: ui::radar::fetchRadiusKm() — scales with the active preset to roughly the screen edge (so rim dots have data)
• Poll interval: kAdsbFetchIntervalMs (5 s) in config.h
• Ground aircraft hidden by default (kAdsbShowGroundAircraft)

Configuration

Edit include/config.h for hardware and behavior:

Range presets: include/ui/radar_range.h (kRangePresets).

Project layout

include/
  config.h
  hardware/
    lgfx_config.hpp
    display.h
    display_font.h
  data/
    large_airports.h
  ui/
    radar_theme.h
    radar_range.h
    radar_display.h
    runway_overlay.h
    status_screens.h
  services/
    wifi_setup.h
    radar_location.h
    adsb_client.h
data/
  ui_font.vlw              — embedded smooth UI font (Noto Sans Bold)
scripts/
  build_large_airports.py
src/
  main.cpp
  data/
    large_airports_data.cpp
  hardware/
  ui/
  services/

Wiring (GC9A01 ↔ ESP32-C3 Super Mini)

Build

pio run -t upload
pio device monitor

• PlatformIO env: supermini
• Serial: 115200 baud
• USB CDC on boot enabled in platformio.ini for the Super Mini

Web-flashable release image

Single .bin for esptool-js and similar tools (ESP32-C3, 4 MB, flash at 0x0):

chmod +x scripts/merge-firmware.sh   # once
./scripts/merge-firmware.sh

Writes release/plane-radar-merged.bin. Skip rebuild if firmware is already built:

./scripts/merge-firmware.sh --no-build

Or via PlatformIO only (output: .pio/build/supermini/firmware-merged.bin):

pio run -e supermini
pio run -t merge -e supermini

Put the board in download mode (hold BOOT, tap RESET), then flash with Chrome/Edge over USB.

CI and releases (GitHub Actions)

To ship a version users can download:

git tag v1.0.0
git push origin v1.0.0

The release workflow builds firmware in CI and attaches the merged image to the release. Download from Releases on GitHub, then flash at 0x0 (ESP32-C3, 4 MB).

Dependencies

• LovyanGFX
• WiFiManager
• ArduinoJson