206 lines
4.7 KiB
Markdown
206 lines
4.7 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.
|