overland-controller/docs/roadmap.md

Roadmap

Phase 1: Solid Local Cargo Controller

• Reliable relay control
• Reliable DS18B20 temps
• Reliable JBD/Xiaoxiang BMS BLE
• WPA2 AP mode
• Stable WebUI
• Stable HTTP API
• Clear status/config/control model

Phase 2: Waveshare ESP32-S3 Dashboard

• LVGL project scaffold
• WiFi client to Cargo ESP32 AP
• Poll /status
• Display battery, relays, temps, and alarms
• Send relay commands
• Handle offline/stale/failed-command states

UI direction:

• Dark theme
• Large readable text
• Circular SOC gauge
• Card-based layout
• Smooth subtle animations
• No stock LVGL demo look

Phase 3: Vehicle Data

• Connect Waveshare CAN to OBD-II CAN-H/CAN-L
• Keep CAN termination disabled
• Read coolant temp via PID 0105
• Read RPM via PID 010C
• Read vehicle speed via PID 010D

Phase 4: Transmission Temperature

• Install dedicated sender
• Read through exposed ADC or ADS1115 over I2C
• Convert resistance to temp with lookup interpolation
• Add alert thresholds

Phase 5: Future Home Server

• Cargo ESP32 outbound connection
• Remote read-only dashboard first
• Optional commands later
• HTTPS reverse proxy/PWA
• Possible MQTT/WebSocket bridge
• Optional Grafana/Home Assistant/InflDB

Phase 6: Optional Enhancements

• microSD logging
• GPS
• OTA updates
• Dashboard alert sounds
• More vehicle PIDs
• Historical charts

AP Security, OLED Setup, and Dashboard Pairing

Phase 1 — Cargo AP security

• Require WPA2 on the Cargo ESP32 AP.
• Generate a unique AP password on first boot.
• Store AP SSID/password in Preferences.
• Add /api/v1/config/ap for AP configuration.
• Add AP auth/SSID metadata to status responses.
• Do not expose AP password in API responses.

Phase 2 — Cargo OLED setup display

• Add 128x64 SSD1306 OLED support on the Cargo ESP32.
• Show AP SSID/password/IP during first boot and setup mode.
• Show critical operational state during normal operation:
  • SOC
  • voltage/current
  • relay state
  • WiFi/IP
  • alarms
• Add setup/status button:
  • short press cycles pages
  • long press shows AP credentials
  • extended hold enters recovery/reset mode

Phase 3 — Dashboard credential migration

• Dashboard ESP32-S3 connects as a client to the Cargo ESP AP.
• Cargo ESP remains the network/configuration authority.
• When AP credentials are changed from the phone WebUI, Cargo stages the new credentials.
• Dashboard fetches and saves pending credentials before Cargo restarts AP.
• Cargo applies the new AP settings.
• Dashboard reconnects automatically.
• Temporary dashboard setup AP is fallback/recovery only.

Phase 4 — User-friendly setup polish

• Add QR code display for joining Cargo AP.
• Add dashboard settings UI.
• Add LVGL on-screen keyboard only after core dashboard functionality is stable.

Cargo OLED firmware foundation

Status: planned / scaffolded

Initial OLED firmware goals:

• Add optional SSD1306 128x64 support behind a compile-time flag.
• Keep OLED support disabled by default so the controller firmware builds without extra libraries.
• Display boot/setup status.
• Display AP SSID/password/IP for phone-first setup.
• Display rotating service pages:
  • battery
  • relays
  • network
  • alarms

Future OLED goals:

• Add setup/status button.
• Short press cycles pages.
• Long press shows AP credentials.
• Extended hold enters recovery/reset mode.
• Add first-boot setup screen once AP password generation is finalized.

Current communications and GPIO decision

Active dashboard communication is WiFi/HTTP using /api/v1.

The old Pico/dashboard UART path is retired from active hardware use. USB Serial remains available for development, debug, and manual configuration from a computer.

Current Cargo ESP32 GPIO plan:

• GPIO 16: Relay 1 trigger output
• GPIO 17: Relay 2 trigger output
• GPIO 4: DS18B20 OneWire temperature bus
• GPIO 34: Ignition sense input
• GPIO 21: SSD1306 OLED I2C SDA
• GPIO 22: SSD1306 OLED I2C SCL
• GPIO 25: OLED setup/status button

Future Wishlist Parking Lot

These are intentionally not committed v1 architecture until explicitly promoted:

• BNO085/BNO086 tilt sensor
• CAN sniffing beyond standard OBD-II polling
• Fault-code support
• Standalone dashboard mode
• Additional cargo outputs
• Custom PCB
• Smart high-side switching
• WUPP-style fused distribution module
• MQTT/Home Assistant/Grafana/InfluxDB integrations

Dashboard Overview MVP

Status: Complete

Completed:

• Boot screen
• Dashboard version display
• Cargo AP connectivity
• HTTP API polling
• Field-filtered /api/v1/status polling
• Battery SOC gauge
• Runtime / time-to-full calculations
• Idle battery state
• Relay controls
• Dynamic relay layout
• WiFi signal indicator
• Cargo ESP connectivity indicator

Next Dashboard Milestones:

• Temperature card redesign
• Swipe navigation
• Battery detail page
• Vehicle page
• OBD-II integration
• CAN integration
• BNO085/BNO086 off-road attitude display

M9N GPS Module

The dashboard enclosure will include an M9N GPS module connected to the ESP32-S3 dashboard over UART. It will provide GPS fix status, satellite count, position, speed, and UTC time. Future work will use GPS time/location for automatic timezone and DST handling.

Planned: WebSocket live dashboard updates

Add a WebSocket push channel alongside the existing /api/v1 REST API. The REST API remains the stable snapshot/debug/control contract, while WebSockets provide lower-latency live status updates for the dashboard.

Planned behavior:

• Cargo ESP continues to expose /api/v1/status and existing /api/v1/... endpoints.
• Cargo ESP adds a WebSocket endpoint, likely /ws.
• Dashboard ESP connects once to /ws and receives pushed status updates.
• Relay commands may continue using REST initially, with pushed status updates confirming state changes.
• Future high-rate data such as CAN/OBD, GPS, inclinometer, and temperature updates can use the WebSocket path.
• If WebSocket disconnects, dashboard should fall back to the existing REST polling behavior.

Rationale:

• Keeps the current API architecture intact and easy to debug.
• Avoids ESP-NOW channel-management complexity for now.
• Improves perceived responsiveness without a major communication rewrite.
• Supports future live gauges better than fixed-interval polling.

LilyGO T-Relay-S3 6-relay migration

• Expand cargo relay model from 2 outputs to 6 outputs.
• Replace direct GPIO relay writes with LilyGO 74HC595 shift-register writes.
• Map relay_1 through relay_6 to CH1 through CH6.
• Move DS18B20 OneWire default from GPIO4 to GPIO14 because GPIO4 is relay nOE.
• Bench test relay boot behavior with no vehicle loads connected.
• Confirm CH1-CH6 order with a meter or test lamp before wiring vehicle loads.