# DreamStack Thin Client — Waveshare ESP32-P4 10.1" Panel

A 10.1" touchscreen that acts as a **dumb pixel display with touch input**. All rendering happens on the source device (laptop, Pi, server). The panel just shows pixels and reports touches.

## Architecture

```
SOURCE (laptop/Pi)              RELAY (:9100)              THIS DEVICE
───────────────                 ─────────────              ───────────

DreamStack app renders          WebSocket hub              Waveshare ESP32-P4
  800×1280 canvas                                          10.1" IPS + touch
                                
pixels ──→ XOR delta ──→ RLE ──→ relay ────────────────→   RLE decode
                                                           XOR apply
                                                           blit to screen
                                
                                ←── touch {id,x,y,phase} ← GT9271 touch
```

## Hardware

| Component | Spec |
|---|---|
| Board | Waveshare ESP32-P4-WIFI6 |
| Display | 10.1" IPS, 800×1280, MIPI DSI |
| Touch | GT9271, 10-point capacitive, toughened glass |
| CPU | ESP32-P4 RISC-V 400MHz |
| RAM | 32MB PSRAM (framebuffer lives here) |
| WiFi | WiFi 6 (ESP32-C6) |
| Display driver | `waveshare/esp_lcd_jd9365_10_1` (JD9365) |

## Project Structure

```
devices/waveshare-p4-panel/
├── CMakeLists.txt              # ESP-IDF project
├── README.md                   # This file
└── main/
    ├── CMakeLists.txt          # Component registration
    ├── idf_component.yml       # Dependencies (display driver, WebSocket)
    ├── Kconfig.projbuild       # WiFi SSID/password, relay URL
    ├── main.c                  # Entry point: WiFi → WS → receive/blit/touch
    ├── ds_codec.h              # RLE decode + XOR apply (header)
    ├── ds_codec.c              # RLE decode + XOR apply (implementation)
    └── ds_protocol.h           # Bitstream header parsing + touch encoding
```

## Building

### Prerequisites
- ESP-IDF v5.3+ ([install guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32p4/get-started/))
- VSCode + ESP-IDF extension (recommended)

### Build & Flash
```bash
# Set target to ESP32-P4
idf.py set-target esp32p4

# Configure WiFi and relay URL
idf.py menuconfig
# → DreamStack Thin Client → WiFi SSID, Password, Relay URL

# Build
idf.py build

# Flash (connect via USB-C)
idf.py -p /dev/ttyUSB0 flash monitor
```

## TODO (pending hardware arrival)
- [ ] Wire up `display_init()` with actual MIPI DSI + JD9365 driver
- [ ] Wire up `touch_task()` with GT9271 I2C touch driver
- [ ] Test framebuffer allocation in PSRAM (800×1280×2 = 2MB)
- [ ] Measure end-to-end latency (target: <50ms)
- [ ] Add reconnection logic for WiFi + WebSocket drops