243 lines
6.3 KiB
Markdown
243 lines
6.3 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
|