# ESP32-S3 Dashboard Firmware

Target Hardware:

- Waveshare ESP32-S3 Touch LCD 5B
- 1024x600 display
- Capacitive touch
- ESP32-S3
- 16MB Flash
- 8MB PSRAM

Current Status:

- Basic dashboard bring-up sketch created

Upcoming milestones:

1. Serial bring-up
2. Display bring-up
3. Touch validation
4. WiFi connection
5. Cargo ESP API integration
6. LVGL dashboard
7. CAN integration
8. Vehicle telemetry

Cargo ESP API Base:

    /api/v1


## Arduino IDE Note

Arduino IDE expects the primary `.ino` filename to match the folder name.

Current sketch path:

    firmware/esp32-s3-dashboard/esp32-s3-dashboard.ino


## Current Bring-Up Screen

The dashboard sketch now replaces the stock Waveshare LVGL demo with a simple Overland Controller boot/status screen.

Current screen shows:

- Overland Controller title
- Waveshare ESP32-S3 Touch LCD 5B hardware target
- 1024x600 display note
- `/api/v1` Cargo API base
- WiFi placeholder
- Touch test button

This is intentionally not connected to WiFi or the Cargo ESP yet.


## Firmware Structure

Current dashboard firmware files:

- `esp32-s3-dashboard.ino` - Main Arduino entry point, LVGL screen, WiFi/API loop
- `dashboard_config.h` - Dashboard version, Cargo ESP WiFi credentials, `/api/v1` endpoint URLs
- `dashboard_status_model.h` - Parsed Cargo ESP status data model
- `lvgl_v8_port.cpp/.h` - Waveshare LVGL port support
- `esp_panel_board_custom_conf.h` - Waveshare board/display configuration

This refactor keeps behavior unchanged while preparing for later `api` and `ui` file splits.


## Status Field Filtering

The dashboard uses field-filtered `/api/v1/status` calls:

- Fast poll: `/api/v1/status?fields=battery,temps,relays`
- Slow poll: `/api/v1/status?fields=network,system,config`

This keeps the endpoint model simple while reducing payload size, JSON parsing, and UI churn.

## XIAO sensor-node RS485 diagnostics

The dashboard listens to the onboard RS485 receiver at 115200 baud using GPIO43 RX and GPIO44 TX. The Waveshare transceiver switches direction automatically, so no DE GPIO is required. The receiver accepts newline-delimited schema-v1 `sensor_status` JSON from the XIAO node and does not change Cargo HTTP/control behavior.

Open the hidden diagnostics overlay to view link state, frame sequence/gaps/errors, IMU accuracy/stability/pitch/roll/yaw, and GPS fix/satellites/HDOP/location/altitude/speed/UTC. This is a temporary bring-up view ahead of a dedicated off-road page.

Arduino **USB CDC On Boot** must remain enabled so dashboard debug `Serial` output uses native USB rather than competing with the GPIO43/GPIO44 RS485 UART.

## Passive CAN Logger

The dashboard runs its 500 kbps TWAI controller in listen-only mode and never
transmits onto the vehicle bus. At 115200 baud it prints changed frames as:

    CAN,ms,id,format,dlc,b0,b1,b2,b3,b4,b5,b6,b7

During a cold-start warm-up, enter the scan-tool coolant reading periodically:

    TEMP,68
    TEMP,95
    TEMP,140

Generic timestamped markers can be added with `MARK,<label>`. For a stationary
4WD capture, start in 2H and enter each marker only after the corresponding
dashboard indicator has settled:

    MARK,2H
    MARK,4H
    MARK,4LO
    MARK,4H
    MARK,2H

Wait 10-15 seconds between mode changes. Follow the vehicle owner's manual for
the conditions required to select 4LO, keep the vehicle stationary where
required, and save the complete serial output. The repeated return transitions
help distinguish an actual mode signal from unrelated counters and timers.

Save the serial output, then rank CAN ID/byte candidates with:

    python tools/analyze_can_coolant.py can-warmup.log

Verify strong candidates over multiple warm-up captures before using one for
the dashboard gauge.