Pluggable smart-display firmware for the LCDWiki 3.5" ESP32-32E — standalone LVGL launcher, on-screen WiFi setup, Anthropic Claude OAuth, live web mirror, and a captive-portal first-boot flow. No PC required after first flash.

1. Features
2. Hardware
3. Quick Start
4. Web Portal & Mirror
5. Tools
6. Project Status / Roadmap
7. License

• LVGL launcher — tile-based app grid rendered on a 320×480 IPS display
• WiFi setup on-screen — scan networks, enter password with the on-screen keyboard, no serial required
• First-boot SoftAP + captive portal — boots as EspScreen-Setup AP on first run; browse to http://192.168.4.1/ to configure WiFi and Anthropic credentials with nothing but a phone
• Web portal (port 80) — browser UI for WiFi config, Anthropic OAuth setup, passcode, and device settings
• Anthropic Claude OAuth — multi-profile credential storage with automatic token refresh; set via portal or provisioning tools
• Claude usage widget — 5-hour and 7-day utilization gauges on the launcher
• Live web mirror — downscaled live screenshot at /api/screen; click-to-touch via /api/touch
• Device passcode — X-EspScreen-Secret header; set from the portal or serial api set-secret
• SD card storage — config import from microSD (VSPI bus); NVS + LittleFS fallback
• Standalone operation — runs fully without a paired PC or serial connection

Board: LCDWiki 3.5" ESP32-32E Display (official product page)

• MCU: ESP32-WROOM-32E
• Display: ST7796 320×480 IPS, color order BGR
• Touch: XPT2046 resistive (shared HSPI bus with display)
• Storage: microSD on dedicated VSPI bus

Display + Touch — HSPI bus

microSD — VSPI bus (separate from display)

Critical build flag: -D USE_HSPI_PORT

This flag is mandatory. Without it, the SD card's VSPI initialisation (SPIClass(VSPI).begin(18, 19, 23, 5)) remaps the VSPI MISO from GPIO 12 to GPIO 19, stealing the XPT2046's data line. The result is every touch read returning 0x1FFF (8191) — completely dead touch. See HARDWARE.md for the full root-cause explanation.

See HARDWARE.md for full board details, known gotchas, and additional wiring notes.

• PlatformIO Core installed and pio on your PATH
• USB cable (data, not charge-only)
• Git

git clone https://github.com/JerrettDavis/EspScreen.git
cd EspScreen

cd firmware/10-launcher

# Compile and flash the firmware
pio run -e esp32dev -t upload

# Upload the filesystem image (config, web assets)
pio run -t uploadfs

PlatformIO auto-detects the COM port. To specify it manually, pass --upload-port COM3 (Windows) or --upload-port /dev/ttyUSB0 (Linux/Mac).

Note: Do NOT run a full flash erase (esptool --chip esp32 erase_flash) before uploading unless you intend to wipe stored WiFi and OAuth credentials in NVS. A plain pio run -t upload preserves NVS.

1. Power on the board. If no WiFi credentials are stored, the device boots as a SoftAP named EspScreen-Setup.
2. Connect your phone or laptop to that network (no password).
3. A captive portal should open automatically. If not, browse to http://192.168.4.1/.
4. Enter your WiFi SSID and password, then tap Save & Connect.
5. On the next screen, enter your Anthropic OAuth credentials (or skip and provision later via the tools).

The device reboots, joins your network, and the launcher appears.

pio device monitor

Baud rate is 115200. Press Ctrl+C to exit.

Once the device is on your network, open http://<device-ip>/ in a browser (the IP is printed to serial at boot as [net] IP: ...).

The Machine API runs on port 8080 (/api/*). The web portal runs on port 80.

Set a passcode from the Settings tab or via serial:

api set-secret <your-secret>

Once set, all API requests must include the header X-EspScreen-Secret: <your-secret>.

Toggle the live mirror from the serial console:

mirror on
mirror off

Host-side Node.js utilities (Node ≥ 18, no global installs required):

cd tools/provision && npm install
node provision.js          # auto-detect port, push tokens
node provision.js --help   # all options

Current release: v0.1.0 — Phase 1 complete.

See PLAN.md for architecture, ADRs, and detailed milestone specs.

MIT — Copyright 2026 Jerrett Davis