overland-controller/docs/project-state.md

Project State

Last updated: 2026-06-04

Version

Current firmware version:

0.4.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:

Raspberry Pi Pico 2 W physical dashboard over UART

Optional future expansion:

Pi Zero 2 W for advanced logging, charts, and 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
• UART protocol for future Pico dashboard

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:

Battery positive -> fuse -> relay COM -> relay NO -> load positive
Load negative -> ground bus

The built-in relays are currently planned for:

• Starlink Mini
• 12V fridge

External automotive relays remain a future option for higher-current loads.

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 Pico dashboard MVP over UART.
5. Add config backup/restore.
6. Improve BMS out-of-range behavior without changing NimBLE connect timeout.

• Fixed WebUI temperature probe scan by registering /temps/scan, /temps/assign, and /temps/clear firmware routes.\n\n- Added per-temperature-sensor weather flag and WebUI outside temperature badge with emoji thresholds: below 50°F ice, 50-74°F happy, 75-84°F sun, and 85°F+ fire.\n\n- Improved WebUI temperature sensor config checkbox layout with compact On/Weather controls.\n\n- Temperature probe assignment now enforces one logical slot per physical DS18B20 address; assigning a probe to a new slot clears the old slot mapping.\n\n- Added per-slot WebUI Clear buttons for temperature probe assignments using the existing /temps/clear API.\n\n- Fixed weather temp checkbox persistence by saving the weather flag from WebUI temp config and auto-saving checkbox changes.\n\n- Fixed temperature assignment clearing so Clear removes the stored DS18B20 address, disables the slot, clears weather flag, and resets cached temp state.\n\n- Hardened /temps/clear so clearing a temp slot removes the persisted DS18B20 address, disables the slot, clears weather flag, resets cached temp state, and supports clearing all slots with an empty POST body.\n\n- Removed legacy physical-scan-order fallback for unassigned DS18B20 slots; enabled slots now require an explicit assigned address before reporting a value.\n\n- Filtered DS18B20 scan results so already-assigned probe addresses are hidden until cleared from their configured temp slot.\n\n- Moved WebUI Temperature Assignment card directly above Temperature Sensor Config for better setup flow.\n\n- Added read-only assigned DS18B20 address display under each WebUI temperature config slot.\n\n- Fixed DS18B20 scan filtering so assigned probes are hidden from assignment results without removing them from runtime polling.\n\n- Dashboard temperature list now hides disabled, unassigned, offline, or invalid temp slots while keeping all slots visible in Config.\n\n- Fixed dashboard temp filtering to avoid requiring address in runtime temp payload.\n\n- Fixed WebUI temp config so the On checkbox fully controls whether each temp slot is enabled.\n\n- Restored Overview relay control rendering after dashboard temp layout changes.\n\n- Fixed Overview relay buttons to call the existing relay() WebUI handler instead of missing setRelay().\n\n- Restored Overview relay controls to separate ON and OFF buttons per relay.\n

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

The Raspberry Pi Pico 2 W dashboard path is no longer the primary implementation target. UART JSON remains supported as an optional interface for future expansion, debugging, or alternate dashboard hardware.