nick/overland-controller

Fork 0

Files

T

nick fea549d1e2 dashboard: expand RS485 sensor diagnostics

2026-07-26 18:15:48 -06:00

10 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

Dashboard boots.
Connects to cargo ESP32 AP.
Checks GET /api/v1/health.
Polls GET /api/v1/status.
Shows disconnected state until valid JSON is received.
Updates dashboard on a fixed interval.
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 overlay also provides the initial XIAO sensor-node bring-up view. The dashboard receives newline-delimited JSON through its onboard automatic-direction RS485 transceiver on GPIO43 RX / GPIO44 TX at 115200 baud. It shows link age, received/dropped/error counts, IMU pitch/roll/yaw/accuracy/stability, and GPS fix/satellites/HDOP/location/altitude/speed/UTC. Cargo communication remains WiFi/HTTP through /api/v1.

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.

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.

Dashboard first-boot WiFi setup

The ESP32-S3 dashboard no longer hardcodes Cargo ESP WiFi credentials or the Cargo API base URL. On first boot, it shows a touchscreen setup page where the user enters:

Cargo ESP WiFi SSID
Cargo ESP WiFi password
Cargo API base URL, for example http://192.168.4.1

The dashboard saves these values in ESP32 Preferences/NVS and builds all /api/v1 endpoint URLs at runtime. The boot screen also provides a Setup button for changing saved settings later.

10 KiB Raw Blame History