Add project handoff and Pico MVP documentation

2026-06-05 00:41:21 -06:00
parent 0043e50533
commit 175630cda2
3 changed files with 223 additions and 0 deletions
@@ -0,0 +1,138 @@
+# 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.
@@ -437,3 +437,45 @@ This is important if the project becomes shareable or sellable.
 - MQTT/Home Assistant bridge.
 - Ignition sense.
 - House battery voltage sense.
+
+---
+
+## Pico Dashboard MVP Plan
+
+MVP means Minimum Viable Product.
+
+Goal:
+
+    Prove Pico 2 W can reliably read ESP32 status over UART and display live data.
+
+Phase 1:
+
+- MicroPython on Pico 2 W / RP2350
+- UART to ESP32 dashboard UART
+- USB debug output
+- Request status from ESP32
+- Parse status JSON
+
+Phase 2:
+
+- ST7796S display bring-up
+- Backlight control
+- Hello World screen
+- Static dashboard layout
+
+Phase 3:
+
+- Live battery card
+- Runtime / time-to-full card
+- Temperature list
+- Relay state list
+- ESP32 connection indicator
+
+Phase 4:
+
+- Touch support using FT6336U
+- Page navigation
+- Relay controls
+- Alarm details
+
+Do not start with touch or config UI on the Pico. The WebUI is the preferred configuration workflow.
@@ -592,3 +592,46 @@ Only three wires need to return to the ESP32:
    3.3V
    GPIO4
    GND
+
+---
+
+## Pico Dashboard Wiring
+
+The Pico dashboard should be powered from a local 12V-to-5V buck converter in the dash enclosure.
+
+Rear enclosure sends fused 12V over CAT5e.
+
+Dash side:
+
+    CAT5e +12V -> buck IN+
+    CAT5e GND  -> buck IN-
+
+    buck OUT+ 5V -> Pico VSYS
+    buck OUT+ 5V -> Display VCC
+
+    buck OUT- GND -> Pico GND
+    buck OUT- GND -> Display GND
+
+Display wiring:
+
+    SCLK     -> Pico GPIO18
+    MOSI     -> Pico GPIO19
+    LCD_CS   -> Pico GPIO17
+    LCD_DC   -> Pico GPIO16
+    LCD_RST  -> Pico GPIO20
+    LCD_BL   -> Pico GPIO21
+
+Touch wiring, reserved for future:
+
+    TP_SDA   -> Pico GPIO26
+    TP_SCL   -> Pico GPIO27
+    TP_INT   -> Pico GPIO28
+    TP_RST   -> Pico GPIO15
+
+UART wiring:
+
+    ESP32 GPIO21 TX -> Pico GPIO0 RX
+    ESP32 GPIO22 RX -> Pico GPIO1 TX
+    ESP32 GND       -> Pico GND
+
+Do not use the ESP32 6-pin UART header for the dashboard UART. It appears to be connected to RXD/TXD for UART0/programming/debug.