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

7.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

  • 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 ##°.

Reference in New Issue View Git Blame Copy Permalink