361 lines
10 KiB
Markdown
361 lines
10 KiB
Markdown
# Project State
|
|
|
|
Last updated: 2026-06-07
|
|
|
|
## Version
|
|
|
|
Current firmware version:
|
|
|
|
0.5.0
|
|
|
|
## Current Architecture
|
|
|
|
The project is now an ESP32-based overland controller with a lightweight embedded WebUI.
|
|
|
|
Core controller:
|
|
|
|
ESP32 relay board
|
|
|
|
Current dashboard plan:
|
|
|
|
Waveshare ESP32-S3-Touch-LCD-5 over WiFi/HTTP
|
|
|
|
Optional future expansion:
|
|
|
|
Pi Zero for long-term logging, charts, and local integrations
|
|
|
|
## ESP32 Responsibilities
|
|
|
|
The ESP32 is the source of truth for:
|
|
|
|
- Relay control
|
|
- JBD/Xiaoxiang BLE BMS telemetry
|
|
- DS18B20 temperature sensors
|
|
- Persistent configuration
|
|
- HTTP API
|
|
- Embedded WebUI
|
|
- WiFi AP recovery network
|
|
- WiFi STA client mode
|
|
- Optional UART JSON protocol for diagnostics or alternate clients
|
|
|
|
## Current Working Features
|
|
|
|
- BMS live data from Greta/JBD BMS
|
|
- Relay control
|
|
- Embedded phone-friendly WebUI
|
|
- AP mode at `192.168.4.1`
|
|
- STA mode on saved WiFi networks
|
|
- Multiple saved WiFi networks with priority
|
|
- WiFi reconnect/failover behavior
|
|
- DS18B20 scan/assign/config workflow
|
|
- One DS18B20 probe verified working
|
|
- Generic relay IDs
|
|
- Generic temperature IDs
|
|
- Config-driven relay names
|
|
- Config-driven temperature names
|
|
- WebUI setup workflow
|
|
- HTTP API
|
|
- UART JSON protocol
|
|
- USB serial maintenance commands
|
|
|
|
## WebUI Tabs
|
|
|
|
### Overview
|
|
|
|
Shows:
|
|
|
|
- Battery SOC
|
|
- Voltage
|
|
- Current
|
|
- Estimated runtime / charging time-to-full
|
|
- Temperature sensors
|
|
- Relay controls
|
|
- Network status
|
|
- Alarm summary
|
|
|
|
### Battery
|
|
|
|
Shows:
|
|
|
|
- BMS online/offline
|
|
- Source
|
|
- Remaining Ah
|
|
- Capacity Ah
|
|
- Battery temperature
|
|
- Cycle count
|
|
- Cell count
|
|
- Cell delta
|
|
- Individual cell voltages
|
|
- BMS enable/disable controls
|
|
|
|
### Config
|
|
|
|
Supports:
|
|
|
|
- Device name editing
|
|
- BMS name/address/address type editing
|
|
- BMS reconnect
|
|
- Temperature probe scan
|
|
- Temperature probe assignment
|
|
- Relay renaming
|
|
- Temperature sensor enabled count
|
|
- Temperature sensor renaming
|
|
- WiFi network configuration
|
|
- Restart
|
|
- Factory reset
|
|
|
|
## Hardware Direction
|
|
|
|
Current rear enclosure target:
|
|
|
|
- ESP32 relay board
|
|
- Compact fuse block
|
|
- Ground bus
|
|
- CAT6 keystone
|
|
- DS18B20 terminal/distribution board
|
|
- Built-in relay outputs for Starlink Mini and fridge
|
|
|
|
Relay strategy:
|
|
|
|
ESP32 relay board output
|
|
-> external fused automotive relay or contactor trigger
|
|
-> fused load circuit
|
|
|
|
The ESP32 relay board outputs are control/trigger outputs only. Fridge, Starlink, inverter, and other major loads must use properly fused automotive relay or contactor circuits.
|
|
|
|
## Temperature Sensor Direction
|
|
|
|
DS18B20 bus:
|
|
|
|
ESP32 GPIO4 = data
|
|
ESP32 3.3V = VCC
|
|
ESP32 GND = ground
|
|
|
|
Required:
|
|
|
|
One 4.7k pull-up resistor between data and 3.3V
|
|
|
|
Final install should use a terminal/distribution board.
|
|
|
|
## Network Direction
|
|
|
|
Current:
|
|
|
|
- AP always available
|
|
- STA attempts saved networks by priority
|
|
- AP remains available even when STA is connected
|
|
|
|
Examples:
|
|
|
|
Priority 1: Starlink
|
|
Priority 2: Home WiFi
|
|
|
|
## Next Recommended Work
|
|
|
|
1. Verify WebUI setup workflow after fresh flash.
|
|
2. Clean up DS18B20 physical distribution hardware.
|
|
3. Test 2-4 temperature probes after distribution board is installed.
|
|
4. Start Waveshare ESP32-S3 dashboard MVP over WiFi/HTTP.
|
|
5. Add config backup/restore.
|
|
6. Improve BMS out-of-range behavior without changing NimBLE connect timeout.
|
|
7. Define future Pi Zero logging/integration role without moving control authority off the Cargo ESP32.
|
|
|
|
Recent notes:
|
|
|
|
- WebUI temperature scan, assign, clear, and weather/outside-air selection are implemented.
|
|
- DS18B20 slots now require explicit assigned addresses before reporting values.
|
|
- Relay controls and temperature configuration remain driven by generic IDs plus saved configuration names.
|
|
|
|
|
|
## Dashboard Architecture Update
|
|
|
|
Primary dashboard architecture is now:
|
|
|
|
Cargo ESP32 Controller
|
|
→ WiFi AP/STA
|
|
→ HTTP API
|
|
→ WebUI
|
|
|
|
Dashboard Client:
|
|
→ Waveshare 5" ESP32-S3 Display
|
|
→ Connects to cargo ESP32 over WiFi
|
|
→ Consumes existing HTTP API
|
|
→ Planned LVGL-based dashboard UI
|
|
|
|
There is no planned Pico dashboard path. Existing Pico/UART files are legacy artifacts unless explicitly revived later.
|
|
|
|
UART JSON remains optional for diagnostics or alternate clients. New dashboard work should target the Waveshare ESP32-S3 display and the HTTP API.
|
|
|
|
|
|
## 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
|
|
|
|
## Current Role Boundary
|
|
|
|
The authoritative role split is documented in `docs/controller-roles.md`.
|
|
|
|
Summary:
|
|
|
|
- Cargo ESP32: power-system controller, WebUI, REST API, output control, BMS, DS18B20, local config, optional OLED.
|
|
- Dashboard ESP32-S3: touchscreen UI, gauges, future CAN/OBD-II, future tilt/roll/off-road visualization.
|
|
- v1 communications: Dashboard connects to Cargo ESP AP over WiFi/HTTP REST.
|
|
- Not v1 communications: ESP-NOW, MQTT, UART dashboard link, or CAN between controllers.
|
|
- Load-switching hardware is still an implementation choice, not frozen architecture.
|
|
|
|
## Pico Dashboard Archive Cleanup
|
|
|
|
The old `pico-dashboard/` implementation has been moved to `archive/legacy-pico-dashboard/`.
|
|
|
|
It is retained as reference material only. It is not active firmware and is no longer part of the default validation path.
|
|
|
|
Current dashboard work should target the ESP32-S3 dashboard direction documented in `docs/dashboard-esp32s3.md` and the placeholder at `firmware/esp32-s3-dashboard/`.
|
|
|
|
## Selected Dashboard Hardware
|
|
|
|
The current dashboard target is the Waveshare ESP32-S3 Touch LCD 5B with a 5-inch 1024x600 touchscreen.
|
|
|
|
This replaces the earlier Pico dashboard concept. The Pico dashboard has been archived as reference-only material.
|
|
|
|
## Implemented DS18B20/WebUI Support
|
|
|
|
DS18B20 support is already implemented in the Cargo ESP/WebUI/API path.
|
|
|
|
This is not a future feature to add from scratch.
|
|
|
|
Future work should focus on:
|
|
|
|
- Keeping the API contract accurate
|
|
- Displaying existing temperature telemetry on the ESP32-S3 dashboard
|
|
- Preserving Cargo ESP ownership of cargo/fridge temperature sensors
|
|
|
|
## Cargo API Contract
|
|
|
|
The current Cargo ESP API ownership and expected endpoint areas are documented in `docs/cargo-api-contract.md`.
|
|
|
|
This contract should guide future ESP32-S3 dashboard work so dashboard firmware targets stable Cargo ESP data instead of duplicating sensor or relay ownership.
|
|
|
|
## Pre-LilyGO Baseline
|
|
|
|
Before migrating Cargo ESP hardware to a LilyGO T-Relay-S3 or other expanded-output controller, use `docs/pre-lilygo-baseline-checklist.md` to confirm the current 2-channel Cargo ESP baseline is stable enough to tag.
|
|
|
|
## LilyGO Ordered / Transition Plan
|
|
|
|
The LILYGO T-Relay-S3 6-way board has been ordered but is not yet the active hardware target.
|
|
|
|
Current testing continues on the original 2-channel relay board.
|
|
|
|
Near-term work should prepare the Cargo ESP API and configuration model so the future LilyGO migration is a hardware-profile change instead of an API redesign.
|
|
|
|
Primary goal:
|
|
|
|
- Keep 2-channel testing functional now.
|
|
- Support future 6-output rendering/control cleanly through the same API shape.
|
|
|
|
## Output-Count-Agnostic Relay API
|
|
|
|
The Cargo ESP API now represents relays/outputs as a hardware-profile-aware list instead of hardcoding client assumptions around exactly two relays.
|
|
|
|
Current active hardware profile:
|
|
|
|
generic_esp32_2ch_relay
|
|
|
|
Future planned profile:
|
|
|
|
lilygo_t_relay_s3_6ch_wupp
|
|
|
|
Current 2-channel testing should continue until the LilyGO board arrives and is bench tested.
|
|
|
|
## Waveshare 5B Bring-Up Pending
|
|
|
|
The Waveshare ESP32-S3 Touch LCD 5B is expected next.
|
|
|
|
Next dashboard work should follow `docs/waveshare-5b-bringup-checklist.md` and start with standalone display/touch validation before any Cargo ESP or vehicle integration.
|
|
|
|
## Dashboard MVP Status
|
|
|
|
Current dashboard hardware:
|
|
|
|
- Waveshare ESP32-S3 Touch LCD 5B
|
|
- WiFi client to Cargo ESP32 AP
|
|
- HTTP API consumer
|
|
|
|
Current dashboard communication path:
|
|
|
|
Dashboard ESP32-S3
|
|
-> WiFi
|
|
-> HTTP
|
|
-> Cargo ESP32
|
|
-> /api/v1
|
|
|
|
Current dashboard features:
|
|
|
|
- Boot screen
|
|
- Dashboard version display
|
|
- Battery SOC gauge
|
|
- Charge/discharge current display
|
|
- Runtime estimation
|
|
- Time-to-full estimation
|
|
- Idle battery state
|
|
- Relay controls
|
|
- Dynamic relay button sizing
|
|
- State-colored relay buttons
|
|
- WiFi signal indicator
|
|
- Cargo ESP connectivity indicator
|
|
- Fast status polling using field-filtered API requests
|
|
|
|
### 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.
|