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

7.3 KiB
Raw Permalink 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.
Reference in New Issue View Git Blame Copy Permalink