# 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