pi-dashboard/README.md

# Pi Dashboard

Raspberry Pi system monitor running on a Waveshare ESP32-S3 RLCD 4.2" board. Connects to a Pi over WebSocket, parses JSON stats, and renders a live dashboard on a 400x300 1-bit monochrome reflective LCD using LVGL.

## Hardware

- **Board:** Waveshare ESP32-S3 RLCD 4.2"
- **Display:** 400x300 reflective LCD (1-bit monochrome, no backlight needed)
- **Sensors:** SHTC3 temp/humidity (I2C 0x70), PCF85063 RTC (I2C 0x51)

## Architecture

```
Pi (server)                    ESP32-S3 (client)
stats_server.py  --WS/JSON-->  ws_client --> dashboard_ui (LVGL)
                                            + local sensors (SHTC3)
                                            + RTC clock (PCF85063)
```

The Pi runs a WebSocket server that pushes system stats (CPU, memory, disk, temperature, network, services) as JSON every 2 seconds. The ESP32 parses the JSON and updates LVGL widgets. A data staleness watchdog forces reconnection if the server goes silent.

The display uses a two-column layout: left half shows Pi stats (CPU/RAM/DISK bars, CPU temp) and a services table; right half shows a large HH:MM:SS clock (montserrat_36), date with day-of-week, and local sensor readings (room temp, humidity). The services table auto-scrolls when services exceed the visible area; row height and visible row count are measured from LVGL at runtime, so the scroll loop adapts automatically to font, padding, or border changes. The clock updates every second from the on-board RTC, which syncs from the Pi's time when drift exceeds 60 seconds.

## Configuration

Edit `components/esp_wifi_bsp/wifi_config.h`:

```c
#define WIFI_SSID       "your_ssid"
#define WIFI_PASSWORD   "your_password"
#define WS_SERVER_URI   "ws://192.168.x.x:8765"
```

## Build and Flash

Requires ESP-IDF v5.5+.

```bash
idf.py build
idf.py flash monitor
```

## Mock Server

Test without a real Pi using the mock server:

```bash
pip install -r pi/requirements.txt
python pi/mock_server.py
```

Sends randomized stats on `ws://0.0.0.0:8765` every 2 seconds.