171 lines
3.8 KiB
Markdown
171 lines
3.8 KiB
Markdown
# 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.
|