Add ESP32-S3 dashboard planning doc

docs/HANDOFF.md

@@ -153,4 +153,4 @@ Important:
 
 - ESP32 cargo controller remains source of truth.
 - Dashboard is a client only.
-- Existing UART protocol remains supported but is no longer the primary dashboard transport.
+- Existing UART protocol remains supported but is no longer the primary dashboard transport.\n\nSee docs/dashboard-esp32s3.md for the current Waveshare ESP32-S3 dashboard plan.\n

docs/dashboard-esp32s3.md

@@ -0,0 +1,156 @@
+# ESP32-S3 Dashboard Plan
+
+## Direction
+
+The primary dashboard target is now a Waveshare 5 inch ESP32-S3 display.
+
+The cargo ESP32 remains the source of truth. The dashboard is a WiFi client that connects to the cargo ESP32 AP and consumes the existing HTTP API.
+
+## Architecture
+
+Cargo ESP32 Controller
+- AP / STA WiFi
+- HTTP API
+- WebUI
+- Relays
+- JBD/Xiaoxiang BMS
+- DS18B20 sensors
+
+Waveshare ESP32-S3 Dashboard
+- Connects to cargo ESP32 AP
+- Polls /status
+- Renders LVGL dashboard
+- Sends relay commands over HTTP
+
+## Transport
+
+Primary transport:
+- WiFi
+- HTTP JSON API
+
+Not required for normal dashboard operation:
+- Pico UART
+- MicroPython display drivers
+- CAT5e UART data pair
+
+UART JSON remains useful for future diagnostics, alternate displays, or debug clients.
+
+## Power
+
+Dashboard power path:
+
+Cargo area 12V
+→ CAT5e power pair(s)
+→ Dash enclosure
+→ Buck converter
+→ 5V dashboard input
+
+All grounds remain common.
+
+## API endpoints consumed
+
+Minimum dashboard MVP:
+- GET /status
+- POST /relay/set
+
+Potential later use:
+- GET /config
+- POST /config/save
+- POST /temps/scan
+- POST /temps/assign
+- POST /temps/clear
+
+## MVP Display Goals
+
+Read-only first:
+- ESP32 connection status
+- Battery SOC
+- Voltage
+- Current
+- Runtime / time-to-full
+- BMS state
+- Temperature sensors
+- Weather/outside temp badge
+- Relay states
+
+Then interactive:
+- Relay ON/OFF buttons
+- Alarm/details pages
+- Settings/status pages
+
+## Suggested LVGL screens
+
+### Main Dashboard
+- SOC gauge
+- Voltage/current
+- Runtime or time-to-full
+- Outside temp/weather badge
+- Fridge/freezer temps
+- Relay state summary
+
+### Battery Detail
+- SOC
+- Voltage
+- Current
+- Remaining Ah
+- Capacity Ah
+- Cell voltages
+- Cell delta
+- BMS temp
+- Cycle count
+
+### Relay Control
+- Starlink relay
+- Fridge relay
+- Future accessory relays
+- Clear ON/OFF touch targets
+
+### Temperature Detail
+- Freezer
+- Fridge
+- Outside/weather
+- Cargo/ambient
+- Online/offline status
+
+### System Status
+- Cargo ESP firmware version
+- WiFi state
+- API connectivity
+- Uptime
+- Alarm status
+
+## Connection Flow
+
+1. Dashboard boots.
+2. Connects to cargo ESP32 AP.
+3. Polls GET /status.
+4. Shows disconnected state until valid JSON is received.
+5. Updates dashboard on a fixed interval.
+6. Relay buttons call POST /relay/set.
+
+## Polling Guidance
+
+Initial MVP:
+- Poll /status every 1-2 seconds.
+- Treat failed requests as dashboard disconnected.
+- Avoid blocking UI rendering while waiting for HTTP.
+
+Later:
+- Add retry/backoff.
+- Add cached last-known values.
+- Add visual stale-data indicator.
+
+## Important Constraints
+
+- Do not move source-of-truth logic to the dashboard.
+- Do not duplicate BMS parsing on the dashboard.
+- Do not require internet access.
+- Do not make dashboard config the primary setup workflow.
+- WebUI Config tab remains the preferred setup workflow.
+- Cargo ESP32 should continue to work without the dashboard powered on.
+
+## Deferred Pico Path
+
+The Pico 2 W dashboard plan is deferred.
+
+Keep existing UART protocol docs because UART remains useful, but new dashboard work should target the ESP32-S3 display first.

docs/project-state.md

@@ -181,4 +181,4 @@ Dashboard Client:
 → Consumes existing HTTP API
 → Planned LVGL-based dashboard UI
 
-The Raspberry Pi Pico 2 W dashboard path is no longer the primary implementation target. UART JSON remains supported as an optional interface for future expansion, debugging, or alternate dashboard hardware.
+The Raspberry Pi Pico 2 W dashboard path is no longer the primary implementation target. UART JSON remains supported as an optional interface for future expansion, debugging, or alternate dashboard hardware.\n\n- Added dedicated ESP32-S3 dashboard planning document covering architecture, API use, LVGL screens, connection flow, and deferred Pico path.\n

docs/roadmap.md

@@ -523,4 +523,4 @@ Advanced Integrations
 - Home Assistant
 - MQTT
 - Grafana
-- InfluxDB
+- InfluxDB\n\n- Added docs/dashboard-esp32s3.md as the primary dashboard implementation plan for the Waveshare 5 inch ESP32-S3 display.\n