# planeMapper

A wall-mounted ADS-B radar display in a picture-frame form factor. Receives live aircraft positions via RTL-SDR, renders them on an OpenStreetMap base map centred on a home airfield (~100nm radius), and refreshes a 6-colour e-ink display every 60 seconds.

Designed to sit on a desk or hang on a wall — always on, no interaction required, no glare.

## Hardware

| Item | Notes |
|------|-------|
| Raspberry Pi Zero 2W | Deployment target. Build and test on Pi 5 first. |
| Nooelec NESDR Smart v5 RTL-SDR dongle | 0.5PPM TCXO, SMA input. Needs micro-USB OTG adapter on Zero 2W. |
| FlightAware 1090MHz ADS-B antenna | Purpose-built for 1090MHz, 5.5dBi |
| Waveshare 7.3" 6-colour e-ink HAT | E-Ink Spectra 6, 800×480, 40-pin GPIO, SPI |

## Software Stack

- **dump1090** — decodes ADS-B from RTL-SDR, serves JSON at `http://localhost:8080/data/aircraft.json`
- **Python + Pillow** — fetches JSON, renders map image
- **Waveshare Python library** — SPI driver for the e-ink HAT
- **OpenStreetMap tiles** — base map, pre-cached for the local area

## Pipeline

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

Refresh loop runs every 60 seconds.

## Map Design

- Centred on home airfield, ~100nm radius
- OpenStreetMap base tiles (pre-cached)
- Aircraft plotted as rotated arrows aligned to heading
- Short track line behind each aircraft
- Callsign and altitude label per aircraft
- Colour-coded by altitude band (6 colours match display palette)
- Home airfield marked

## Colour Bands (altitude)

The Waveshare E-Ink Spectra 6 supports black, white, red, yellow, blue, and green — mapped to altitude bands TBD during development.

## Build Order

1. RTL-SDR + dump1090 — confirm aircraft visible in JSON feed
2. Base map — render OSM tiles at correct scale, 100nm radius
3. Aircraft overlay — pull live positions, draw heading arrows and labels
4. E-ink output — push image via Waveshare library, set 60s refresh loop
5. Polish — airspace overlays, altitude colour coding, frame and mount

## Notes

- E-ink only draws power on refresh — very low idle draw, suits always-on use
- Pi Zero 2W runs the full stack comfortably given the relaxed 60s refresh cycle
- OTG adapter required to connect RTL-SDR dongle to the Zero 2W's single micro-USB port
- Lat/lon to pixel coordinate conversion is the trickiest part of the renderer