nick/overland-controller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
97048b8ceb43ea62bb2bb9260fd17e5a2a77f257
overland-controller/docs/dashboard-esp32s3.md
T

9.2 KiB
Raw Blame History

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.
Reference in New Issue View Git Blame Copy Permalink