# Project State

Last Updated: June 2026

## Project Name

Overland Controller

## Current Status

Phase 1 is functional.

The ESP32 controller can:

- Host a local WiFi access point
- Serve a web interface
- Expose an HTTP API
- Read JBD/Xiaoxiang BLE BMS data
- Persist configuration
- Factory reset configuration
- Control relay outputs
- Report relay status
- Report BMS status
- Report temperature sensor status
- Communicate over UART
- Support BLE setup mode for BMS discovery

The Pico dashboard hardware has not yet been brought online.

---

## Hardware Owned

### ESP32 Controller

Owned and operational.

Current hardware:

- ESP32 relay board
- 2 relay outputs

### Dashboard

Owned but not yet integrated.

Current hardware:

- Raspberry Pi Pico 2 W

Potential display:

- 3.5" touchscreen expansion board

### Vehicle

Current target vehicle:

- Nissan Xterra

The firmware itself should remain vehicle-agnostic.

---

## BMS Status

Working.

Current battery:

- JBD / Xiaoxiang BLE BMS

Current telemetry:

- SOC
- Voltage
- Current
- Remaining Ah
- Capacity
- Temperature
- Cycle count
- Cell voltages
- Cell delta

Configuration is stored in persistent settings.

---

## Relay Status

Working.

Current relay outputs:

    relay_1
    relay_2

Current installation-specific names:

    Starlink
    Fridge

These names are configuration only.

No relay names are intended to be hardcoded.

---

## Temperature Sensor Status

Partially complete.

Framework exists.

Current status:

- Configuration exists
- Status reporting exists
- Naming exists

Not yet completed:

- Physical DS18B20 integration
- Sensor discovery workflow
- Sensor assignment workflow

Planned support:

Up to 8 DS18B20 sensors.

---

## Configuration Status

Persistent configuration works.

Stored settings include:

- Device name
- Relay names
- Relay enabled state
- Temperature sensor names
- Temperature sensor enabled state
- BMS name
- BMS address
- BMS address type

Factory reset is functional.

---

## HTTP API Status

Working.

Implemented:

- Status endpoint
- Config endpoint
- Relay control
- Configuration updates
- Save configuration
- Factory reset

Documentation:

See:

    docs/api.md

---

## UART Status

Partially complete.

Current UART capabilities:

- Status requests
- Dashboard communications
- Basic command support

Missing goal:

UART should eventually expose every operation available through HTTP and serial.

Target:

UART becomes the primary dashboard integration interface.

---

## Simulator Status

Working.

Simulator provides:

- Fake ESP32 controller
- Fake Pico dashboard
- Test data generation
- Protocol validation

Useful for development before hardware is connected.

---

## Documentation Status

Primary documents:

    README.md
    HARDWARE.md

    docs/project-state.md
    docs/architecture.md
    docs/api.md
    docs/protocol.md
    docs/roadmap.md
    docs/decisions.md
    docs/SERIAL_COMMANDS.md

Older planning/design documents may be archived later.

---

## Highest Priority Next Tasks

### Priority 1

UART parity.

Goal:

Anything possible through serial or HTTP should also be possible through UART.

Required additions:

- config_request
- config_device
- config_relay
- config_temp
- config_bms
- save_config
- factory_reset
- enter_bms_setup
- scan_ble
- select_bms
- exit_bms_setup

### Priority 2

DS18B20 support.

Needed:

- Scan sensors
- Assign sensors
- Save assignments

### Priority 3

Pico hardware bring-up.

Needed:

- UART communication
- Display status screen
- Relay control screen

---

## Long-Term Vision

A vehicle-agnostic overland monitoring and control platform.

Core principles:

- Local-first
- No cloud required
- Generic hardware model
- Generic API model
- Generic UART model
- Dashboard optional
- Vehicle independent

Target use cases:

- Overland vehicles
- Campers
- Trailers
- RV electrical systems
- Mobile command systems
- Off-grid battery monitoring

---

## Current Direction Update

The project direction is now:

ESP32:

    Controller
    Source of truth
    BMS telemetry
    Temperature sensors
    Relay control
    Configuration storage
    HTTP API
    Lightweight embedded web dashboard
    WiFi AP recovery network

Pico 2 W:

    Instant-on physical dashboard
    UART client
    Touchscreen UI
    Local control surface

Optional future Pi Zero 2 W:

    Advanced web app
    Historical logging
    Graphs
    MQTT/Home Assistant bridge
    Advanced integrations

The base system should remain ESP32 + Pico.

A Pi Zero may be added later as an optional expansion module, not a required component.

---

## Networking Direction

Current:

    ESP32 AP mode
    http://192.168.4.1

Planned:

    ESP32 AP + STA mode

Expected future behavior:

    AP always remains enabled
    ESP32 attempts to join configured WiFi networks
    Multiple saved networks are tried in priority order

Example network priority:

    1. Starlink
    2. Home WiFi
    3. Shop WiFi

This allows:

- Direct connection when camping without Starlink
- Phone access over Starlink at camp
- Phone/laptop access over home WiFi in the driveway
- Recovery access even when STA setup fails

---

## Recent Design Decisions

The onboard ESP32 relays may be acceptable for low-current loads such as:

    Starlink Mini
    12V fridge
    small accessories

Reason:

- Starlink Mini current draw is modest
- Typical 12V fridge current is modest
- Smaller enclosure is a priority

External automotive relays remain recommended for higher-current loads or future expansion.

The current enclosure concept includes:

- ESP32 relay board
- Small fuse block
- Ground bus
- CAT6 keystone
- CAT5/CAT6 run to dash
- 12V feed to dash
- Buck converter in dash enclosure

The dash power plan is:

    Rear fused 12V
      -> CAT5/CAT6 blue pair
      -> dash buck converter
      -> Pico VSYS