diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 4b52eb4..dfc0736 100644 --- a/docs/HANDOFF.md +++ b/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 \ No newline at end of file diff --git a/docs/dashboard-esp32s3.md b/docs/dashboard-esp32s3.md new file mode 100644 index 0000000..6caf403 --- /dev/null +++ b/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. diff --git a/docs/project-state.md b/docs/project-state.md index d098823..faa4576 100644 --- a/docs/project-state.md +++ b/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 \ No newline at end of file diff --git a/docs/roadmap.md b/docs/roadmap.md index eb2a8d8..b07158e 100644 --- a/docs/roadmap.md +++ b/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 \ No newline at end of file