# planeMapper

A local ADS-B radar display on a 6-colour e-ink screen. Receives live aircraft positions via RTL-SDR, renders them on a map centred on a ~100nm radius, and refreshes the e-ink display every 60 seconds.

## Concept

- Pi 5 decodes ADS-B signals from a USB RTL-SDR dongle
- dump1090 exposes a live JSON feed of aircraft positions
- A Python script pulls the feed, renders a map image with aircraft overlaid
- Image is pushed to a Waveshare 7.3" 6-colour e-ink HAT via SPI
- Wall-mounted, always-on, low power

## Hardware

| Item | Link | Notes |
|------|------|-------|
| Raspberry Pi 5 | — | Already owned |
| Nooelec NESDR Smart v5 RTL-SDR dongle | [Amazon](https://www.amazon.com/Nooelec-RTL-SDR-SDR-100kHz-1-75GHz-Enclosure/dp/B01HA642SW) | 0.5PPM TCXO, SMA input. Alternative: RTL-SDR Blog V3 |
| FlightAware 1090MHz ADS-B antenna | [Amazon](https://www.amazon.com/Flightaware-1090MHz-Aviation-Receiver-Software/dp/B09P19H1Q8) | Purpose-built for 1090MHz, 5.5dBi |
| Waveshare 7.3" 6-colour e-ink HAT | [Amazon](https://www.amazon.com/gp/product/B0D9K193FY) | E-Ink Spectra 6 (E6), 40-pin GPIO, SPI, driver board included |

**Estimated cost:** ~$200 USD

## Software Stack

1. **dump1090** — decodes ADS-B from RTL-SDR, serves JSON at `http://localhost:8080/data/aircraft.json`
2. **Python script** — fetches JSON, renders map image using Pillow, pushes to display via Waveshare driver
3. **Waveshare Python library** — handles SPI communication with the e-ink HAT
4. **OpenStreetMap tiles** — base map, pre-cached for the local area

## Pipeline

```
RTL-SDR dongle
    → dump1090 (ADS-B decoder)
        → JSON feed (aircraft positions, headings, altitudes, callsigns)
            → Python renderer (Pillow)
                → map image with aircraft overlaid
                    → Waveshare SPI driver
                        → e-ink display
```

Refresh loop runs every 60 seconds.

## Map Design

- Centred on home airfield
- ~100nm radius coverage
- Base map from OpenStreetMap
- Aircraft plotted as rotated arrows (heading-aligned)
- Callsign and altitude label per aircraft
- Colour-coded by altitude band (6 colours available)
- Home airfield marked

## Aircraft Icons

- Rotated triangle/arrow pointing in direction of travel
- Short track line behind showing recent path
- Colour coded by altitude band or aircraft type
- Size optionally coded by aircraft category (heavy/medium/light)
- Differentiation options: commercial vs GA, helicopters, military
- Could highlight a known squawk code (owner's own aircraft)

## Build Order

1. Get ADS-B receiving working — RTL-SDR dongle + dump1090, confirm aircraft visible
2. Get base map rendering — OpenStreetMap tiles, 100nm radius circle centred on airfield
3. Plot aircraft on map — pull live positions from dump1090 JSON, draw heading arrows
4. Push to e-ink — convert image, send via Waveshare library, set refresh loop
5. Polish — airspace boundaries, callsign labels, altitude colour coding, frame/mount

## Notes

- E-ink only consumes power on refresh — extremely low idle draw
- Display powered directly from Pi GPIO, no separate PSU needed
- Pi Zero 2W could work as a low-power dedicated host once software is built and optimised on Pi 5
- ESP32/Pi Pico not suitable — no USB host for RTL-SDR dongle
- Script estimated ~100-150 lines of Python
- Hardest part: converting lat/lon to pixel coordinates within the display dimensions