pi-dashboard/PLAN.md

# Pi Dashboard — ESP32-S3 RLCD 4.2" Project Plan

## Goal

WebSocket client on the ESP32-S3 RLCD board that receives system status from a
Raspberry Pi home server over LAN and renders a monitoring dashboard via LVGL.

---

## New project location

Create a new ESP-IDF project directory **outside** the Examples folder, e.g.:

```
J:\dev\arduino\ESP32-S3-RLCD-4.2-main\Projects\pi_dashboard\
```

---

## Files to copy from the factory example

Source root: `Example\ESP-IDF\10_FactoryProgram\`

### Must copy (build skeleton)

| File / Dir | Why |
|---|---|
| `CMakeLists.txt` | Project root cmake — edit project name, strip `EXTRA_COMPONENT_DIRS` if not using ExternLib |
| `partitions.csv` | Partition table (8MB app partition, NVS, PHY) |
| `sdkconfig.defaults` | Base config — **strip BT lines**, keep SPIRAM/flash/LVGL settings |
| `main/CMakeLists.txt` | Main component registration |
| `main/idf_component.yml` | Managed component deps — keep `lvgl/lvgl: ^8.4.0`, drop `avi_player` and `esp_new_jpeg`, **add `espressif/esp_websocket_client`** |

### Must copy (display driver)

| File | From | Why |
|---|---|---|
| `display_bsp.h` | `components/port_bsp/` | DisplayPort class — RLCD SPI driver with LUT pixel mapping |
| `display_bsp.cpp` | `components/port_bsp/` | Full implementation: SPI init, reset, command sequences, SetPixel, Display |

These two files are the entire RLCD hardware abstraction. No other display code
exists. Copy them into a `components/display_bsp/` component in the new project.

### Must copy (LVGL port)

| File | From | Why |
|---|---|---|
| `lvgl_bsp.h` | `components/app_bsp/` | Lvgl_PortInit, Lvgl_lock/unlock declarations |
| `lvgl_bsp.cpp` | `components/app_bsp/` | LVGL display driver registration, double-buffered PSRAM, tick timer, port task on Core 0 |

Copy into a `components/lvgl_port/` component. This file is self-contained — its
only dependency is `lvgl.h` and FreeRTOS.

### Copy as reference (WiFi STA)

| File | From | Why |
|---|---|---|
| `esp_wifi_bsp.h` | `Example/ESP-IDF/02_WIFI_STA/components/esp_wifi_bsp/` | Cleaner than the factory version — no scan-and-destroy, no BLE entanglement |
| `esp_wifi_bsp.c` | same | Simple STA init + connect + reconnect skeleton |

The `02_WIFI_STA` example is a better starting point than the factory program's
wifi code. The factory version tears down WiFi for BLE scanning — useless for a
persistent connection. You will need to modify the STA code to:
- Make SSID/password configurable (NVS or Kconfig)
- Add auto-reconnect on disconnect
- Signal connection readiness via event group so the WebSocket task knows when to start

### Do NOT copy

| Component | Why not |
|---|---|
| `components/port_bsp/` (everything except display_bsp) | I2C bus, buttons, SD card, ADC, codec — none needed for a dashboard |
| `components/ExternLib/` (SensorLib, codec_board) | Sensor drivers and audio codec — irrelevant |
| `components/app_bsp/ble_scan_bsp.c` | BLE scanning — not needed, and conflicts with persistent WiFi |
| `components/app_bsp/esp_wifi_bsp.c` | Factory version destroys WiFi for BLE — use 02_WIFI_STA instead |
| `components/ui_bsp/` | NXP GUI Guider generated UI — you will design your own dashboard layout |
| `components/user_app/` | Factory test logic — all replaced by your WebSocket + dashboard code |
| `managed_components/` | Auto-downloaded by ESP-IDF component manager from `idf_component.yml` — never copy these |
| `build/` | Build artifacts — never copy |

---

## New project structure

```
pi_dashboard/
  CMakeLists.txt                  # from factory, edited
  partitions.csv                  # from factory, as-is
  sdkconfig.defaults              # from factory, stripped (no BT)
  main/
    CMakeLists.txt                # register main.cpp
    idf_component.yml             # lvgl ^8.4.0, esp_websocket_client
    main.cpp                      # app_main: wifi init, display init, lvgl init, ws connect, task spawn
  components/
    display_bsp/
      CMakeLists.txt              # new: register display_bsp.cpp, REQUIRES driver esp_lcd
      display_bsp.h               # from port_bsp, as-is
      display_bsp.cpp             # from port_bsp, as-is
    lvgl_port/
      CMakeLists.txt              # new: register lvgl_bsp.cpp, REQUIRES lvgl__lvgl esp_timer
      lvgl_bsp.h                  # from app_bsp, as-is
      lvgl_bsp.cpp                # from app_bsp, as-is
    wifi_sta/
      CMakeLists.txt              # new: register wifi_sta.c, REQUIRES esp_wifi esp_event nvs_flash
      wifi_sta.h                  # based on 02_WIFI_STA, extended with reconnect + event group
      wifi_sta.c                  # based on 02_WIFI_STA, extended
    ws_client/
      CMakeLists.txt              # new: register ws_client.cpp, REQUIRES esp_websocket_client
      ws_client.h                 # WebSocket connect/disconnect, message callback registration
      ws_client.cpp               # esp_websocket_client wrapper, reconnect logic, JSON parse
    dashboard_ui/
      CMakeLists.txt              # new: register dashboard_ui.cpp, REQUIRES lvgl__lvgl
      dashboard_ui.h              # UI layout: create/update functions for dashboard widgets
      dashboard_ui.cpp            # LVGL widget creation, label/bar/table updates from parsed data
```

---

## sdkconfig.defaults (modified for this project)

Strip from the factory version:
- `CONFIG_BT_ENABLED=y` and all BT lines (saves ~300KB flash + significant RAM)
- `CONFIG_BT_BLE_*` lines

Keep:
- `CONFIG_IDF_TARGET="esp32s3"`
- `CONFIG_ESPTOOLPY_FLASHMODE_QIO=y`
- `CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y`
- `CONFIG_PARTITION_TABLE_CUSTOM=y`
- `CONFIG_SPIRAM=y` / `CONFIG_SPIRAM_MODE_OCT=y` / `CONFIG_SPIRAM_SPEED_80M=y`
- `CONFIG_FREERTOS_HZ=1000`
- `CONFIG_LV_MEM_SIZE_KILOBYTES=64`
- `CONFIG_LV_DISP_DEF_REFR_PERIOD=1`

Add:
- `CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240=y`

---

## Runtime architecture

```
Core 0                              Core 1
------                              ------
WiFi driver (system)                main task (app_main, exits after init)
LVGL port task (priority 5)         WebSocket event task (priority 3)
  - lv_timer_handler loop             - receives WS messages
  - holds/releases lvgl_mux           - parses JSON
                                      - acquires lvgl_mux
                                      - updates dashboard widgets
                                      - releases lvgl_mux
```

### Boot sequence (app_main)

1. `wifi_sta_init()` — start WiFi STA, wait for IP
2. `RlcdPort.RLCD_Init()` — init display over SPI
3. `Lvgl_PortInit(400, 300, flush_cb)` — init LVGL with double-buffered PSRAM
4. Create initial dashboard UI (under LVGL lock)
5. `ws_client_start("ws://<pi_ip>:<port>")` — connect WebSocket, register message handler
6. app_main returns, FreeRTOS tasks take over

### Data flow

```
Pi server --[WebSocket JSON]--> ESP32 ws_client
  --> parse message
  --> Lvgl_lock()
  --> update lv_label / lv_bar / lv_table widgets
  --> Lvgl_unlock()
  --> LVGL port task flushes on next cycle
  --> flush_cb converts 16-bit to 1-bit, pushes to RLCD
```

---

## Pi side (not part of this ESP-IDF project, but for context)

A simple Python WebSocket server that:
- Collects system stats (psutil or /proc reads)
- Serializes to JSON
- Pushes to connected clients every N seconds

Example payload:
```json
{
  "cpu_pct": 23,
  "mem_pct": 61,
  "mem_used_mb": 1952,
  "disk_pct": 44,
  "cpu_temp": 52,
  "uptime_hrs": 342,
  "services": [
    {"name": "docker", "status": "running"},
    {"name": "pihole", "status": "running"},
    {"name": "nginx", "status": "stopped"}
  ],
  "net_rx_kbps": 1240,
  "net_tx_kbps": 320
}
```

---

## Key decisions still open

1. **WiFi credentials** — hardcode for now, or Kconfig menuconfig, or NVS provisioning?
2. **Dashboard layout** — what stats matter most? Single screen or multiple pages?
3. **Update frequency** — how often should the Pi push? 2s? 5s? On-change?
4. **Pi server location** — fixed IP or mDNS discovery?
5. **Error states** — what to show when WiFi drops or Pi goes offline?