# Overland Controller Handoff

## Current Version

Firmware: 0.4.0

## Current State

The ESP32 backend is now the source of truth and is mostly Phase 1 complete.

Working:

- ESP32 WebUI
- AP + STA WiFi
- Multiple saved WiFi networks with priority
- Relay control through built-in relay board
- JBD/Xiaoxiang BLE BMS telemetry
- DS18B20 temperature support
- Temperature scan/assign/config workflow
- HTTP API
- UART JSON protocol
- USB serial maintenance commands
- Config-driven relay/temp/BMS/device naming
- WebUI Config tab for initial setup

## Important Recent Fix

Do not use `client->setConnectTimeout()` for the JBD/Xiaoxiang BMS.

It caused Greta/BMS BLE connection failures.

Known-good BMS behavior uses the default NimBLE connection timeout.

## Current Hardware Direction

Rear enclosure:

- ESP32 2-relay board
- Mini fuse block
- Ground bus
- DS18B20 distribution board
- CAT6 keystone
- Built-in relays used for Starlink Mini and fridge
- Positive-side relay switching

Dashboard enclosure:

- Raspberry Pi Pico 2 W / RP2350
- 3.5" 320x480 ST7796S display
- FT6336U capacitive touch, wired but not required for MVP
- 12V over CAT5e from rear enclosure
- Local 12V-to-5V buck converter in dash enclosure
- Pico and display powered from dash buck converter

## CAT5e Plan

Rear to dash:

- Two conductors for fused +12V
- Two conductors for ground
- One conductor for ESP32 TX to Pico RX
- One conductor for ESP32 RX to Pico TX
- Spare pair reserved

All grounds are common:

- ESP32 GND
- Buck GND
- Pico GND
- Display GND
- UART GND

## Pico Display Solder Map

Display:

- VCC -> 5V buck output
- GND -> GND
- SCLK -> Pico GPIO18 / Pin 24
- MOSI -> Pico GPIO19 / Pin 25
- LCD_CS -> Pico GPIO17 / Pin 22
- LCD_DC -> Pico GPIO16 / Pin 21
- LCD_RST -> Pico GPIO20 / Pin 26
- LCD_BL -> Pico GPIO21 / Pin 27

Touch, wired for future:

- TP_SDA -> Pico GPIO26 / Pin 31
- TP_SCL -> Pico GPIO27 / Pin 32
- TP_INT -> Pico GPIO28 / Pin 34
- TP_RST -> Pico GPIO15 / Pin 20

UART to ESP32 dashboard UART:

- Pico GPIO0 / Pin 1 RX <- ESP32 GPIO21 TX
- Pico GPIO1 / Pin 2 TX -> ESP32 GPIO22 RX
- Pico GND -> ESP32 GND

Do not use the ESP32 6-pin UART header for dashboard UART. It has continuity to RXD and is likely UART0/programming/debug.

## Pico MVP Goal

MVP means Minimum Viable Product.

Pico MVP should be read-only first:

- Request status from ESP32 over UART
- Parse JSON status response
- Display battery SOC, voltage, current, runtime/time-to-full
- Display temps
- Display relay states
- Display ESP32 connection status

No touch controls for MVP.

## Runtime / Time-To-Full Logic

If BMS current is negative/discharging:

    runtime_hours = remaining_ah / abs(current)

If BMS current is positive/charging:

    time_to_full_hours = (capacity_ah - remaining_ah) / current

If current is near zero:

    show Idle

## Next Work

1. Build Pico MVP.
2. First prove UART status over USB serial.
3. Then prove display Hello World.
4. Then draw read-only dashboard.
5. Later add touch navigation and relay controls.
6. Later add config backup/restore.
7. Later improve BMS out-of-range behavior without changing NimBLE connect timeout.



## Dashboard Direction

Current dashboard target:

- Waveshare 5" ESP32-S3 Display
- WiFi client
- Connects to cargo ESP32 AP
- Uses existing HTTP API
- Planned LVGL implementation

Important:

- ESP32 cargo controller remains source of truth.
- Dashboard is a client only.
- Existing UART protocol remains supported but is no longer the primary dashboard transport.