Open-source firmware that shows live ADS-B traffic on a sweeping radar around your preset position. Built for the LilyGO T-Encoder Pro, inspired by desktop flight-tracking radar gadgets such as ESP32-Plane-Radar and deskradar.

Firmware is released under CC BY-NC-SA 4.0 (see LICENSE) instead of MIT. Permissive MIT licensing on similar projects has made it easy for vendors to ship closed derivatives without keeping firmware open to the community. This license keeps the source shareable for hobbyists and open-source builders while discouraging proprietary takeaways.

3D-printed enclosure: MakerWorld Link. Licensed separately. See Enclosure license below.

• Sweeping radar: concentric range rings, compass rose, radar sweep line, top-down aircraft pips (heading-aligned), and callsign / type / altitude tags
• Display range: 2 / 4 / 6 / 8 mi on the outermost ring. Inner rings show 1/3 and 2/3 of that scale. Knob changes preset.
• Distance units: statute miles or kilometers on ring labels and detail readouts
• Radar theme color: Red, Yellow, Orange, Green, or White for crosshairs, compass rose, scale labels, and sweep line
• Beyond-ring pips: aircraft outside the active range still appear on the rim
• Flight detail: tap a blip or short press the knob for callsign, airline, route, ICAO type, altitude, and speed. Turn the knob to cycle through visible aircraft.
• Settings: swipe left from radar for page 1 (network / location), page 2 (brightness, units, compass rose), and page 3 (radar theme color)
• Clock: swipe down from radar for large local time (NTP). Swipe left for UTC offset and 12h/24h format.
• Web settings: on your local network at http://flightscnr.local/ (or device IP) for radar center, filters, route API keys, monthly limits, and route-cache download
• Setup portal: captive portal on first boot or after knob reset. Wi‑Fi network and password only at http://4.3.2.1. Other settings use the live web portal after connecting.
• Airline & route: optional API sources to fetch flight details. Vendors are used in the order of: AirLabs > FlightAware > FR24 (same idea as plane-tracker-rgb-pi). One live lookup per callsign, then flash/RAM cache.
• Background ADS-B: non-blocking fetch on a FreeRTOS task (~2 s via adsb.fi)
• Auto reconnect: STA retries after a short grace period if network drops

Idle timeout (10 s): flight detail and all settings pages return to radar. Clock settings return to the clock (not radar). The clock face has no idle timeout.

Range, distance units, brightness, radar theme color, clock timezone/format, and route API settings persist across reboots.

Note: Do not hold the knob while powering on. It shares GPIO 0 with the ESP32-S3 and will enter USB download / bootloader mode. Use the 3 s hold while the app is already running to open the setup portal again.

1. Power on. If no saved Wi‑Fi (or after a reset), the display shows the setup AP name.
2. Join Wi‑Fi FlightScnr-AP on your phone or PC.
3. Open http://flightscnr.local (mDNS) or http://4.3.2.1.
4. In the captive portal, choose your desired Wi‑Fi SSID and enter the password
5. Save. The device connects to your network and shows the radar. Set radar center, filters, and route APIs at http://flightscnr.local/ once connected.

On the local network, open http://flightscnr.local/ or http://<device-ip>/. Edit radar center, miles/km, min altitude, range preset, and route API keys/limits, then Save & reboot.

The on-device settings page 1 shows flightscnr.local and the device IP address when Wi‑Fi is connected.

To reset Wi‑Fi and reopen the captive portal, hold the knob 3 s (clears saved Wi‑Fi only).

• Up to 64 aircraft per refresh with a non blocking radar sweep
• ADS-B poll about every 2 s

• Callsign, airline, route (ORIG > DEST), ICAO aircraft type (e.g. B738), altitude, ground speed
• Footer: aircraft index, gesture guide

• Page 1: IP, Wi‑Fi SSID, lat/lon, min altitude, web hostname
• Page 2: brightness, miles/km, compass rose on/off (knob press cycles highlighted row; turn adjusts value)
• Page 3: radar theme color — Red, Yellow, Orange, Green, or White (turn knob to cycle). Applies to range rings, crosshairs, compass rose, scale labels, and sweep line.
• Footer: gesture guide

• Shows time in 12h/24h format , date, UTC offset label.
• Footer: gesture guide

• Timezone (UTC offset, hours) and 12h/24h format. Knob press cycles focus. Turn adjusts value.
• Footer: gesture guide

Requires PlatformIO. On Windows, if pio is not on PATH:

python -m platformio run -e tencoder-pro -t upload
python -m platformio device monitor

Otherwise:

pio run -e tencoder-pro -t upload
pio device monitor

Each build downloads the latest tar1090-db aircraft database and regenerates the ICAO type lookup (e.g. E75L → Embraer ERJ-170-200). If the download fails, the last cached or committed lookup is used. Refresh manually with python tools/icao_types_to_header.py.

pio run -e tencoder-pro
pio run -t merge -e tencoder-pro

Output: .pio/build/tencoder-pro/firmware-merged.bin. For a full factory flash, write at offset 0x0 (erases saved Wi‑Fi and settings). Normal updates use the app image at 0x10000 instead (see WebFlasher below).

If upload fails, hold the board BOOT button (not the knob), tap reset, and retry.

FlightScnr WebFlasher flashes firmware over USB from Chrome or Edge — no PlatformIO required.

1. Connect the T-Encoder Pro via USB.
2. Open WebFlasher, click Connect, then Install.
3. If needed, hold BOOT while connecting.

Sign up for desired tiers with each vendor:

Enable providers and paste keys on the web settings page. You can enter multiple keys per provider, comma-separated (key1, key2, key3). When one key reaches its monthly cap, the next key is used before the API calls move on to the next provider.

Route lookups are cached in RAM and on the ~3.4 MB LittleFS partition as /route_cache.csv (saved every ~10 min). Live route APIs run at most once per callsign on first sight of an unfamiliar ICAO callsign. Cached and previously looked-up callsigns are not sent to the providers again. Download the CSV from http://flightscnr.local/ under Route cache.

Monthly API limits apply per key and are editable on the web settings page. Counters reset each calendar month when NTP time is valid. Cached callsigns do not count toward limits.

Defaults match typical free tiers (AirLabs 1,000 queries/month. AeroAPI Personal up to $5/month free. ADS-B feeders may get $10). Adjust on the settings page if your plan or pricing differs.

The flash cache holds up to 1500 callsign rows. Oldest entries are replaced when full.

Larger cache compatibility is still a work in progress.

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

• Attribution: credit the author and link to 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.

Vendored libraries (lib/Arduino_GFX, lib/SensorLib, and PlatformIO registry dependencies) remain under their own licenses (GPL, MIT, etc.). Combining them into a binary does not re-license those components. Comply with each upstream license when you distribute builds.

The optional 3D-printed enclosure is not part of this firmware repository. Its digital files and physical prints are governed by the license shown on the linked MakerWorld model page. 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.