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 more than 4 services are present. 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.