From ded6e3d3605395206bbfe891eee25d7cd25c2871 Mon Sep 17 00:00:00 2001
From: pi <pi@led-controller.local>
Date: Sun, 12 Apr 2026 00:13:49 +1200
Subject: [PATCH] docs: align readme and driver api with tcp/wifi

Made-with: Cursor
---
 README.md   | 44 ++++++++++++++++++++++++++++++--------------
 docs/API.md |  6 +++---
 2 files changed, 33 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 77ff7a4..14564a4 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,52 @@
-# LED Driver - MicroPython
+# LED Driver — MicroPython
 
-MicroPython-based LED driver application for ESP32 microcontrollers.
+MicroPython LED driver for ESP32: presets, patterns, **Wi-Fi** (TCP + UDP discovery) or **ESP-NOW** transport, optional HTTP polling, and dynamic pattern modules under `src/patterns/`.
 
 ## Prerequisites
 
-- MicroPython firmware installed on ESP32
+- MicroPython firmware on the ESP32
 - USB cable for programming
-- Python 3 with pipenv
+- Python 3 with pipenv (on the host, for `dev.py` / tests)
 
 ## Setup
 
 1. Install dependencies:
+
    ```bash
    pipenv install
    ```
 
-2. Deploy to device:
+2. Deploy to the device:
+
    ```bash
    pipenv run dev
    ```
 
-## Project Structure
+## Project layout
 
 ```
 led-driver/
 ├── src/
-│   ├── main.py           # Main application code
-│   ├── presets.py        # LED pattern implementations (includes Preset and Presets classes)
-│   ├── settings.py       # Settings management
-│   └── p2p.py            # Peer-to-peer communication
-├── test/                 # Pattern tests
-├── web_app.py           # Web interface
-├── dev.py               # Development tools
-└── Pipfile              # Python dependencies
+│   ├── main.py          # Entry: Wi-Fi/TCP or ESP-NOW path, process_data(), manifest OTA
+│   ├── presets.py       # Preset runtime + Presets class
+│   ├── preset.py        # Single preset helpers
+│   ├── settings.py      # settings.json
+│   ├── hello.py         # UDP discovery (port 8766) / hello payloads
+│   ├── http_poll.py     # Optional HTTP polling helper
+│   ├── utils.py         # Colour conversion / ordering
+│   ├── presets.json     # Default preset file (on device)
+│   └── patterns/        # Pattern modules (.py), loaded dynamically
+├── tests/               # Host-side helpers (e.g. udp_client.py, test_mdns.py)
+├── test/                # On-device style pattern tests (all.py, patterns/)
+├── dev.py               # Deploy / sync to serial device
+├── docs/API.md          # Wire format (long keys); Pi app docs short keys
+├── msg.json             # Sample message
+├── Pipfile
+└── LICENSE
 ```
+
+**Transport:** `settings.json` **`transport_type`** is typically **`wifi`** (TCP to the Pi on port **8765**, discovery on **8766**) or **`espnow`**. ESP-NOW code paths are loaded only when needed so a Wi-Fi-only image stays smaller.
+
+## Further reading
+
+- **`docs/API.md`** — JSON message fields as used in examples (`pattern`, `colors`, …). The Pi app may send **short keys** (`p`, `c`, …); behaviour matches once normalised on device.
diff --git a/docs/API.md b/docs/API.md
index bfdb0f1..92f3eb5 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1,10 +1,10 @@
-# LED Driver ESPNow API Documentation
+# LED Driver API (message format)
 
-This document describes the ESPNow message format for controlling LED driver devices.
+This document describes the **JSON message format** for controlling LED driver devices. The same object is accepted from **ESP-NOW** (when that transport is enabled) and as **one JSON value per line** over **TCP** in **Wi-Fi** mode (see `src/main.py` on the device).
 
 ## Message Format
 
-All messages are JSON objects sent via ESPNow with the following structure:
+All messages are JSON objects with the following structure:
 
 ```json
 {