From 175630cda21e214876b29cb548a2d8f89ffdd0fc Mon Sep 17 00:00:00 2001 From: nick Date: Fri, 5 Jun 2026 00:41:21 -0600 Subject: [PATCH] Add project handoff and Pico MVP documentation --- docs/HANDOFF.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/roadmap.md | 42 +++++++++++++++ docs/wiring.md | 43 +++++++++++++++ 3 files changed, 223 insertions(+) create mode 100644 docs/HANDOFF.md diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md new file mode 100644 index 0000000..c086178 --- /dev/null +++ b/docs/HANDOFF.md @@ -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. diff --git a/docs/roadmap.md b/docs/roadmap.md index 3bbb5b2..902f6d2 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -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. diff --git a/docs/wiring.md b/docs/wiring.md index d568613..3275190 100644 --- a/docs/wiring.md +++ b/docs/wiring.md @@ -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.