overland-controller/docs/dashboard-esp32s3.md

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.

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.