335 lines
10 KiB
Markdown
335 lines
10 KiB
Markdown
# 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 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.
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
## 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.
|