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

## OBD-II / CAN Diagnostics

The hidden diagnostics overlay distinguishes raw CAN traffic from parsed
OBD-II coolant responses. It reports request successes and failures, total
raw frames received, the last frame identifier and DLC, TWAI queue depth,
controller error counters, missed or overrun frames, arbitration losses,
and bus errors.

Raw RX activity confirms that the display is receiving CAN frames even when
the vehicle does not return a matching Mode 01 PID 05 coolant response.