294 lines
7.6 KiB
Markdown
294 lines
7.6 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
|
|
- 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.
|