Add ESP32-S3 dashboard planning doc

2026-06-07 09:18:37 -06:00
parent a0cad804a2
commit e1ea6a19e0
4 changed files with 159 additions and 3 deletions
@@ -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.