# 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.