dreamstack/devices/waveshare-p4-panel/README.md

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)
• VSCode + ESP-IDF extension (recommended)

Build & Flash

# 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