nick/overland-controller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fea549d1e22149af0dc89ecb74603ffa805ff87f
overland-controller/docs/project-state.md
T

11 KiB
Raw Blame History

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.

Reference in New Issue View Git Blame Copy Permalink