commit bbdb962e81b39076def2d569483e671bc3def385
Author: Matt Edholm <medholm@lokion.com>
Date:   Wed Apr 22 19:39:37 2026 -0400

    Initial commit: project spec and README

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..34d6840
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,33 @@
+# planeMapper
+
+ADS-B radar display on a Waveshare 7.3" 6-colour e-ink screen, driven by a Pi 5 + RTL-SDR dongle.
+
+## Project goal
+
+Render a live ~100nm radius radar map centred on home airfield, with aircraft positions, headings, altitudes, and callsigns. Refresh every 60 seconds.
+
+## Stack
+
+- **dump1090** — ADS-B decoder, JSON feed at `http://localhost:8080/data/aircraft.json`
+- **Python + Pillow** — fetches JSON, renders map image
+- **OpenStreetMap tiles** — base map, pre-cached locally
+- **Waveshare Python library** — SPI driver for the e-ink HAT
+
+## Hardware
+
+- Raspberry Pi 5
+- Nooelec NESDR Smart v5 RTL-SDR dongle (SMA, 0.5PPM TCXO)
+- FlightAware 1090MHz antenna (5.5dBi)
+- Waveshare 7.3" 6-colour e-ink HAT (E-Ink Spectra 6, 40-pin GPIO, SPI, driver board included)
+
+## Design decisions
+
+- Aircraft icons: rotated triangle/arrow aligned to heading, short track line behind
+- Colour-coded by altitude band (6 colours available on display)
+- Callsign + altitude label per aircraft
+- Home airfield marked on map
+- Potential: differentiate commercial/GA/helicopter, highlight own squawk code
+
+## Full spec
+
+See README.md in this directory.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1e2cf03
--- /dev/null
+++ b/README.md
@@ -0,0 +1,79 @@
+# 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