overland-controller/docs/archive/legacy-current-cleanup/handoff.md

Overland Controller Handoff

This handoff is stale and may include legacy Pico/UART dashboard assumptions.

Current source of truth:

• docs/ARCHITECTURE.md
• docs/HARDWARE.md
• docs/ROADMAP.md
• docs/API.md
• docs/dashboard-esp32s3.md

The current dashboard target is the Waveshare ESP32-S3-Touch-LCD-5 over WiFi/HTTP. No Pico dashboard is planned.

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.

See docs/dashboard-esp32s3.md for the current Waveshare ESP32-S3 dashboard plan.