convez.ai
PluginAutomaçãoAvançado
JerrettDavis

EspScreen — Firmware de Display Inteligente com Claude

JerrettDavis/EspScreen

Firmware ESP32 com LVGL, WiFi em tela e Claude integrado

Ver no GitHub
BomPluginScore · de 0 a 100

Firmware plugável para display ESP32 3.5" com interface gráfica LVGL, setup WiFi em tela, integração OAuth com Anthropic Claude e espelhamento web ao vivo. Funciona de forma autônoma sem necessidade de PC após o flash inicial, com portal cativo e armazenamento em cartão SD.

Instalação

$npx convez-ai JerrettDavis/EspScreen

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 3 semanas
Versão
v0.1.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Criar displays inteligentes com acesso a Claude via interface gráfica
  • Dispositivos IoT de borda com UI rica sem dependência de servidor
  • Prototipagem de painéis de controle com integração de IA

Veredito

Projeto robusto e bem documentado para quem quer construir displays inteligentes ESP32 com UI sofisticada e integração nativa com Claude. Requer conhecimento sólido de C++, eletrônica embarcada e PlatformIO; compensador para aplicações autônomas em edge computing.

README

A tradução para o português deste README ainda está na fila.

EspScreen

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.

CI


Table of Contents

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

Features

  • 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

Hardware

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

Pinout

Display + Touch — HSPI bus

SignalGPIONotes
TFT MOSI13
TFT MISO12Shared with T_MISO
TFT SCK14Shared with T_CLK
TFT CS15
TFT DC2
TFT RST–1Tied to EN (board hardware reset)
TFT BL27PWM backlight, HIGH = on
Touch CS33XPT2046 chip-select
Touch IRQ36Input-only GPIO; board pull-up fitted

microSD — VSPI bus (separate from display)

SignalGPIO
SD SCK18
SD MISO19
SD MOSI23
SD CS5

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.


Quick Start

Prerequisites

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

1. Clone

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

2. Flash firmware

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.

3. First boot — captive portal setup

  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.

4. Serial monitor

pio device monitor

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


Web Portal & Mirror

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: ...).

TabDescription
WiFiScan and connect to networks
AnthropicAdd / switch Claude OAuth profiles
MirrorLive downscaled display preview; click to send touch events
SettingsRename device, set passcode, reboot

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

Passcode

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>.

Mirror commands

Toggle the live mirror from the serial console:

mirror on
mirror off

Tools

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

ToolPurposeREADME
tools/provisionPush Claude OAuth tokens + WiFi to the board over USB serialprovision/README.md
tools/creds-watcherWatch ~/.claude/.credentials.json and auto-push refreshed tokenscreds-watcher/README.md
tools/creds-watcher/refresh.jsProactively renew the host OAuth access token and push to the device; designed for Task Scheduler / headless usecreds-watcher/README.md — Token Refresh
tools/claude-endpointLocal HTTP server exposing Claude usage JSON for the on-board widgetclaude-endpoint/README.md
cd tools/provision && npm install
node provision.js          # auto-detect port, push tokens
node provision.js --help   # all options

Project Status / Roadmap

Current release: v0.1.0 — Phase 1 complete.

PhaseGoalStatus
0 — Bring-upTFT_eSPI hello-world, touch sanityDone
1 — UI baseLVGL launcher, WiFi UI + portal, Claude OAuth, SD, web mirrorDone — v0.1.0
2 — MicroPython portlv_micropython build, LittleFS app loaderPlanned
3 — Real appsClaude widget polish, calculatorPlanned
4 — Slave-SPI modeESP-IDF spi_slave + DMA pipeline, host streamingPlanned
5 — Updates & trustOTA, ed25519-signed app manifestsPlanned

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


License

MIT — Copyright 2026 Jerrett Davis

Ver o original no GitHub

Bom para

Relacionados