# 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:
- MicroPython display drivers
- CAT5e UART data pair

UART JSON remains useful for diagnostics, alternate displays, or debug clients, but it is not part of the planned dashboard path.

## Power

Dashboard power path:

ACC switched 12V
-> fuse
-> Waveshare VIN

All grounds remain common.

## API endpoints consumed

Minimum dashboard MVP:
- GET /api/v1/health
- GET /api/v1/status
- POST /api/v1/relay/set

Potential later use:
- GET /api/v1/capabilities
- GET /api/v1/config
- GET /api/v1/config/export
- POST /api/v1/config/import
- POST /api/v1/config/save
- POST /api/v1/temps/scan
- POST /api/v1/temps/assign
- POST /api/v1/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. Checks GET /api/v1/health.
4. Polls GET /api/v1/status.
5. Shows disconnected state until valid JSON is received.
6. Updates dashboard on a fixed interval.
7. Relay buttons call POST /api/v1/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.

## Out of Scope

No Pico dashboard is planned. Existing Pico/UART material is legacy unless explicitly revived for diagnostics or alternate hardware.