# 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
- Implemented as a left-side page from the main dashboard.
- Swipe right from the main dashboard to open it.
- Swipe left from Battery Detail to return to the main dashboard.
- 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.


## Current communications and GPIO decision

Active dashboard communication is WiFi/HTTP using `/api/v1`.

The old Pico/dashboard UART path is retired from active hardware use. USB Serial remains available for development, debug, and manual configuration from a computer.

Current Cargo ESP32 GPIO plan:

- GPIO 16: Relay 1 trigger output
- GPIO 17: Relay 2 trigger output
- GPIO 4: DS18B20 OneWire temperature bus
- GPIO 34: Ignition sense input
- GPIO 21: SSD1306 OLED I2C SDA
- GPIO 22: SSD1306 OLED I2C SCL
- GPIO 25: OLED setup/status button

## Not Dashboard Responsibilities

The Dashboard ESP32-S3 does not own:

- Relay state authority
- BMS connection/configuration
- Cargo ESP configuration
- Alarm authority
- Load-switching output ownership

It may display state and request changes through the Cargo ESP HTTP API, but the Cargo ESP remains the source of truth.

## Temperature Data Source

The ESP32-S3 dashboard should display temperature data from the Cargo ESP API.

DS18B20 sensors are already implemented on the Cargo ESP/WebUI/API side. For v1, the dashboard should not directly own cargo/fridge DS18B20 wiring or sensor reads.

## API Dependency

The ESP32-S3 dashboard depends on the Cargo ESP API contract documented in `docs/cargo-api-contract.md`.

For v1, the dashboard should consume:

- System status
- Battery/BMS telemetry
- DS18B20 temperature telemetry
- Relay/output state
- Alarm/fault state

The dashboard may request output changes through the Cargo ESP API, but the Cargo ESP remains the source of truth.

## Waveshare 5B Bring-Up

Use `docs/waveshare-5b-bringup-checklist.md` when the Waveshare ESP32-S3 Touch LCD 5B arrives.

First priority is standalone validation:

- USB/serial detection
- Display output
- Touch input
- Correct 1024x600 target
- Basic LVGL/demo functionality

Second priority is Cargo ESP API integration over WiFi using `/api/v1`.

## Current Dashboard Status

Status: Functional MVP

Implemented:

- Boot screen while connecting to Cargo ESP AP
- Dashboard version display on boot screen
- WiFi client connection to Cargo ESP
- HTTP API polling via `/api/v1`
- Field-filtered status polling with `/api/v1/status?fields=battery,temps,relays`
- Relay control via HTTP POST
- Dynamic relay button layout designed to scale up to 6 outputs
- State-colored relay buttons with dimensional styling
- Battery SOC gauge
- Charge/discharge current display
- Runtime estimate while discharging
- Time-to-full estimate while charging
- Idle state when current is near zero
- WiFi signal strength display
- Cargo ESP connectivity indicator

Planned next work:

- Temperature card redesign
- Swipe/page navigation
- Battery detail page
- Vehicle data page
- CAN/OBD-II integration
- BNO085/BNO086 tilt visualization

### Temperature Sensor Grouping

Temperature sensors now support a `group` field in addition to the existing `weather` flag.

Supported group values:

- `cabin`
- `fridge`
- `outside`
- `battery`
- `other`

The dashboard overview combines multiple online sensors in the same group into one tile. For example, two fridge sensors may display as `34°/45°` under a single `Fridge` tile. Sensors marked `weather: true` continue to be treated as the outside/weather sensor for dashboard display.

### Temperature Sensor Priority

Temperature sensors support a numeric `priority` field. Lower numbers are displayed first within a grouped dashboard tile.

Example:

- Fridge Zone 1: `group=fridge`, `priority=1`
- Fridge Zone 2: `group=fridge`, `priority=2`

The dashboard displays the grouped fridge tile in priority order, for example `34°/45°`.

### Temperature Slot and Group Display

The Cargo ESP currently supports 4 temperature sensor slots.

Temperature sensor `group` values are free-form text in the WebUI. Entering a new group name effectively creates that group. The dashboard overview shows the first two available non-weather groups by priority. Multiple sensors in the same group are combined into one tile, such as `34°/45°`.

Sensors marked `weather: true` are excluded from the temperature card and shown in the top status strip as `OUT ##°`.

### Temperature High Alerts

Each temperature sensor supports optional high-temperature alerting:

- `high_alert_enabled`
- `high_alert_f`
- `high_alert`

When enabled and the live sensor temperature exceeds the configured threshold, the Cargo ESP includes `high_alert: true` for that sensor in `/api/v1/status`. The ESP32-S3 dashboard colors the affected grouped temperature tile red if any sensor in that displayed group is in alert.

## M9N GPS Module

The dashboard enclosure will include an M9N GPS module connected to the ESP32-S3 dashboard over UART. It will provide GPS fix status, satellite count, position, speed, and UTC time. Future work will use GPS time/location for automatic timezone and DST handling.

### Hidden Dashboard Diagnostics

The dashboard has a hidden diagnostics overlay. Tap the top status card five times within roughly three seconds to open it. Double-tap the diagnostics overlay to return to the main dashboard.

The diagnostics overlay shows dashboard version, uptime, heap, WiFi RSSI/IP, Cargo API status, Cargo firmware version, Cargo uptime, Cargo heap, Cargo AP client count, BMS status, relay count, and basic control-loop state.


## Dashboard Page Navigation
- Main Dashboard remains the default startup page.
- Swipe right from the main dashboard to open Battery Detail.
- Swipe left from Battery Detail to return to the main dashboard.
- Diagnostics remains hidden behind the multi-tap system-card gesture.


## OBD-II Coolant Polling
- Dashboard ESP32-S3 Touch LCD 5B uses onboard CAN/TWAI via GPIO15 CANTX and GPIO16 CANRX.
- First implemented PID is Mode 01 PID 05 coolant temperature.
- Sends standard 11-bit functional request ID `0x7DF` and accepts ECU responses from `0x7E8` through `0x7EF`.
- Diagnostics page shows TWAI state, coolant value, TX/RX counts, and last OBD status.
- Overview coolant gauge shows `--°` until a valid OBD response is received.