Sky Overhead

Sky Overhead turns a Seeed reTerminal E1001 into a quiet wall display for nearby aircraft. It shows the nearest aircraft's type, callsign, registration, airline, route, altitude, trend, and speed alongside indoor temperature and humidity.

The display wakes periodically, fetches current data, redraws when useful information changes, and returns to sleep. Temporary network failures leave the last good screen in place, and optional quiet hours pause aircraft checks overnight.

Features

• Nearest-aircraft data from a public ADS-B service, with an optional local receiver fallback
• Callsign-based airline and route details
• Configurable units, search radius, refresh timing, and quiet hours
• QR link to more information about the displayed live or retained aircraft
• Indoor temperature and humidity from the device's built-in sensor
• E-paper-aware refresh behavior that limits unnecessary updates and ghosting

Requirements

• Seeed reTerminal E1001 with XIAO ESP32S3
• FAT-formatted microSD card
• Wi-Fi network with internet access
• Observer latitude, longitude, altitude, and timezone

Install

Download the merged firmware image and checksums from the latest GitHub release. Follow FLASHING.md to verify and install the image and prepare the microSD card.

Configure

Copy config.example.txt to /config.txt at the root of the microSD card and replace the placeholder values. Use one KEY=VALUE pair per line. Spaces around = are accepted, setting names and documented option values are case-insensitive, and blank lines or lines beginning with # are ignored.

Required settings:

• SSID: Wi-Fi network name
• LAT, LON: observer location in decimal degrees, within -90 to 90 and -180 to 180 respectively
• ALT: observer altitude in meters above sea level
• TZ: POSIX timezone string used for local timestamps and quiet hours

Optional settings (defaults apply when a key is omitted):

• PASS: Wi-Fi password; leave empty for an open network
• SPEED: kph (default), mph, or kts
• HEIGHT: ftfl (default) or metric
• TEMP: c (default) or f
• RADIUS: horizontal aircraft search radius in kilometers, from 1 to 463; default 30
• NIGHT_MODE: quiet-hours range in HH:MM-HH:MM; disabled by default. Omit or leave empty to disable. Daytime and overnight ranges work; equal start and end times mean quiet hours all day.
• BUSY: normal sleep interval in seconds, from 15 to 600; default 60
• MAX_REFRESH: time in seconds after which the next wake forces a display update; 0 (default) disables forced updates, while positive values range from 60 to 86400
• LOCAL_ADSB_URL: optional readsb/tar1090 base URL, such as http://192.168.1.20:8080; empty (disabled) by default. The firmware appends /data/aircraft.json.
• QR_URL: HTTP(S) aircraft-information URL template containing {reg}; default https://www.flightradar24.com/data/aircraft/{reg}. Leave empty to hide the QR code. The generated URL must fit within 53 bytes after substituting the registration.

The QR code is hidden when no usable registration is available or the generated URL is invalid or too long. Prefer a DHCP-reserved address over an .local hostname for a local ADS-B receiver.

Example timezone values:

• Central Europe: CET-1CEST,M3.5.0,M10.5.0/3
• UTC: UTC0

Display Behavior

• The left side shows the nearest current aircraft, or the last-seen aircraft when no current aircraft is found.
• The right side shows indoor temperature and humidity.
• Quiet hours show a sleep screen and pause aircraft checks until the configured end time.
• The footer shows the local refresh time and the sources used for the displayed data.
• Missing aircraft fields are omitted rather than leaving blank rows.
• A QR code links to information about the displayed live or retained aircraft when its registration is available.

Within the horizontal search radius, the nearest aircraft is selected by 3D distance, using ALT to account for the observer's elevation. Aircraft reported on the ground, without usable position or altitude, or with positions reported as older than 120 seconds are excluded.

The screen is intentionally not updated second by second. A different aircraft or other static display change causes a redraw, while telemetry and climate changes update with the next redraw. MAX_REFRESH can ensure periodic updates, but it does not shorten BUSY sleep intervals or interrupt quiet hours.

Data Sources

• adsb.lol provides public live-aircraft data.
• An optional local readsb/tar1090 receiver is used when the public aircraft request fails.
• adsb.im provides route information based on the aircraft callsign and position.

If the public source successfully reports an empty sky, the local receiver is not queried. Source labels in the display footer identify whether current or retained data is shown.

Data and Privacy

Configuration is read from the microSD card. config.txt is ignored by Git to reduce the risk of publishing it accidentally, and the firmware does not send the Wi-Fi password to a data provider.

The configured observer latitude and longitude are included in requests to adsb.lol. The optional local ADS-B receiver is queried only after a failed public aircraft request. Aircraft position and callsign are sent to adsb.im for route lookup.

HTTPS certificate verification is disabled in the current firmware to accommodate the embedded networking stack. Do not treat aircraft or route data as authenticated or safety-critical information.

Build and Contribute

Docker with Buildx is the recommended way to build and test from source, using the same pinned environment as CI. From the repository root, run:

docker buildx bake

Firmware and release packages are exported to .build/firmware/ and .build/release/. See CONTRIBUTING.md for Docker setup, flashing, debug options, and contribution guidelines. Native builds are available as an alternative.

License

Sky Overhead is available under the MIT License.