overland-controller/docs/project-state.md

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

    lilygo_t_relay_s3_6ch

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.

## M9N GPS Module

The dashboard enclosure will include an M9N GPS module connected to the ESP32-S3 dashboard over UART. It will provide GPS fix status, satellite count, position, speed, and UTC time. Future work will use GPS time/location for automatic timezone and DST handling.

### Hidden Dashboard Diagnostics

The dashboard has a hidden diagnostics overlay. Tap the top status card five times within roughly three seconds to open it. Double-tap the diagnostics overlay to return to the main dashboard.

The diagnostics overlay shows dashboard version, uptime, heap, WiFi RSSI/IP, Cargo API status, Cargo firmware version, Cargo uptime, Cargo heap, Cargo AP client count, BMS status, relay count, and basic control-loop state.