# 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.