Pana

La cara y la voz de tu agente de IA, en una pantalla redonda de Waveshare.

Mantén pulsado el personaje, habla, y tu agente (Hermes Agent o cualquier LLM compatible con OpenAI) te contesta en voz alta mientras ves en la pantalla lo que está haciendo: qué herramienta usa, cuánto tarda y qué te pide confirmar.

Qué es

Pana tiene dos partes:

• El cuerpo (firmware/): una placa ESP32 con pantalla táctil, micrófono y altavoz. Es «tonta» a propósito: pinta, anima, escucha y reproduce. Nada de lógica de negocio.
• El cerebro (server/): un servidor en Python que corre en tu ordenador o en tu homelab. Recibe tu voz, la transcribe con Whisper, se la pasa a tu agente, convierte la respuesta en voz con Piper y le dice a la placa qué mostrar.

Entre los dos hablan un protocolo sencillo por WebSocket (protocol/PROTOCOL.md). Varias placas pueden estar conectadas a la vez al mismo cerebro.

Lo que ves en la pantalla

• 🗣️ Push-to-talk: mantén pulsado el personaje (o el botón BOOT), habla y suelta. Suena un chirrido al empezar y otro al terminar.
• 🛠️ El agente trabajando, en vivo: cada herramienta que usa Hermes, con su detalle (df -h, la búsqueda, la ruta…), su estado y su tiempo.
• ✋ Confirmaciones: nada externo se ejecuta sin que toques Permitir. Si caduca, se cancela.
• 📊 Tu homelab: CPU, GPU, RAM y temperatura en los arcos del borde, y el estado de tus servicios.
• 📅 Tu día: la agenda (cualquier calendario con dirección iCal), y tus cifras de YouTube e Instagram.
• 🧠 Tu grafo de Obsidian, para tocar notas y ver sus conexiones.
• 🌙 Duerme solo: baja el brillo a los 45 s y se apaga a los 2 min; vuelve al tocarla.

Placas compatibles

Todas son de Waveshare. El proyecto nació con su apoyo y la idea es cubrir cada vez más modelos.

_{Los enlaces de Amazon son de afiliado: si compras por ellos, el proyecto recibe una pequeña comisión sin que te cueste más.}

¿Tienes otra placa de Waveshare? Lee cómo añadir una placa o pídeselo a Claude con la skill incluida.

Así se ve

En reposo Hora, homelab en los arcos y la agenda debajo	Habla El texto se escribe mientras suena la voz	Trabaja Las herramientas del agente, con su progreso
Consola Toca el panel para verlo todo	Pide permiso Con la cuenta atrás en el anillo	Homelab CPU, GPU, RAM, temperatura y servicios
Hoy Agenda, YouTube e Instagram	Capturas reales de la ESP32-P4 4C (720×720), sacadas de la propia placa con tools/shot.py. En la AMOLED 1.75 la interfaz es la misma idea en 466×466, con páginas: personaje, consola y grafo.

El personaje

Viene con Pana, un robot en pixel art con 16 estados que el servidor elige según lo que pasa: escucha, piensa, habla, busca, lee, ejecuta, pide permiso, se alegra, duerme…

Es solo un ejemplo: ponle tu propia cara. Dibuja (o genera) tus cuadros de 120×160 con transparencia, nómbralos <estado>-000.png, <estado>-001.png… y conviértelos:

python tools/make_avatar.py mi-avatar/      # escribe firmware/src/character/sprites43.h y sprites_data43.cpp

El robot de ejemplo se dibuja por código en tools/demo_avatar.py: cámbiale los colores en dos líneas, o úsalo de plantilla.

Cómo funciona

flowchart LR
    subgraph placa["Placa Waveshare (firmware/)"]
        UI["Pantalla redonda<br/>LovyanGFX"]
        MIC["Micrófono ES7210"]
        SPK["Altavoz ES8311"]
        TOUCH["Táctil"]
    end
    subgraph servidor["Tu máquina (server/)"]
        HUB["Hub WebSocket<br/>FastAPI :8770"]
        STT["Whisper<br/>(whisper.cpp)"]
        TTS["Piper"]
        DASH["Tablero<br/>homelab · agenda · redes"]
    end
    AGENT["Hermes Agent<br/>(o un LLM local)"]
    PLUGIN["Plugin companion<br/>de Hermes"]

    MIC -- "audio 16 kHz" --> HUB
    TOUCH -- "toques" --> HUB
    HUB --> STT --> AGENT
    AGENT -- "texto, herramientas,<br/>permisos (SSE)" --> HUB
    HUB --> TTS -- "voz" --> SPK
    HUB -- "estado, tarjetas, tablero" --> UI
    DASH --> HUB
    PLUGIN -- "lo que Hermes hace<br/>por Telegram, terminal…" --> HUB

Empezar

Necesitas: una placa compatible, un cable USB-C de datos, PlatformIO, Python 3.11+ y una máquina en tu red que haga de cerebro (Linux o macOS).

1 · El cerebro

git clone https://github.com/eriktaveras/pana-companion && cd pana-companion
python3 -m venv .venv && source .venv/bin/activate
pip install -r server/requirements.txt
cp .env.example .env          # y ajústalo (tu zona horaria, tu nombre, dónde está tu agente…)

• Voz a texto: levanta un whisper.cpp server en :8771 (STT_URL).
• Texto a voz: descarga una voz de Piper en server/voices/ (por ejemplo es_MX-claude-high.onnx y su .json) y ponla en PIPER_MODEL.
• El agente: con Hermes Agent, activa su API server (compatible con OpenAI, :8642) y guarda su clave en el archivo de HERMES_API_KEY_FILE. Sin Hermes, pon COMPANION_BRAIN=local y apunta LLM_CHAT_URL a tu llama.cpp, Ollama o LM Studio.

cd server && python main.py           # http://localhost:8770 abre un simulador web de la placa

Para dejarlo como servicio hay un ejemplo de systemd en deploy/pana.service.

2 · El cuerpo

cd firmware
pio run -e amoled175 -t upload        # ESP32-S3-Touch-AMOLED-1.75 / 1.75C
pio run -e p4-4c && ../tools/flash_p4.sh   # ESP32-P4-WIFI6-Touch-LCD-4C (ver nota)

ESP32-P4: el esptool de PlatformIO se cuelga con el P4 revisión 3. tools/flash_p4.sh graba con el de ESP-IDF (5.5 o superior).

3 · Primer arranque

La placa abre una red Wi-Fi llamada Pana-Setup. Conéctate desde el móvil, elige tu Wi-Fi y escribe la IP de la máquina del cerebro. Listo: el personaje te saluda.

(Si prefieres no usar el portal, copia firmware/include/secrets.example.h a secrets.h con tus datos antes de compilar. Está en .gitignore.)

4 · Ver lo que Hermes hace en otros canales (opcional)

Copia hermes-plugin/companion a ~/.hermes/plugins/ y reinicia Hermes. Lo que le pidas por Telegram, la terminal o el dashboard también aparecerá en la pantalla.

Personalízalo con Claude Code

El repositorio trae una skill, personalizar-pana, que le explica a Claude cómo está hecho el proyecto y dónde tocar cada cosa. Abre Claude Code en la carpeta del repo y pide lo que quieras:

«Cambia el personaje por un gato naranja»
«Pon la interfaz en tonos morados y la hora más grande»
«Añade un widget con el precio del bitcoin en la página de hoy»
«Haz que hable con acento argentino y se llame Che»
«Adapta Pana a mi Waveshare ESP32-S3-Touch-LCD-1.85C»

La skill cubre el avatar, colores y diseño de cada pantalla, la persona y la voz, nuevos datos en el tablero, nuevas placas y cómo compilar, grabar y comprobar con capturas de la propia placa.

Estructura

firmware/            el cuerpo (PlatformIO, Arduino-ESP32 3.x + LovyanGFX)
  include/board.h      pines y pantalla de cada placa
  src/ui/ui720.cpp     interfaz de la P4 4C (720×720)
  src/ui/ui175.cpp     interfaz de la AMOLED 1.75 (466×466)
  src/character/       el avatar (generado por tools/make_avatar.py)
server/              el cerebro (FastAPI)
  brain/               conversación, Hermes, persona, ánimo, memoria, tablero
  voice/               Whisper y Piper
  sim/                 simulador web de la placa
protocol/PROTOCOL.md el contrato entre cuerpo y cerebro
hermes-plugin/       plugin para que Hermes avise a la placa desde cualquier canal
tools/               avatar, fuentes, capturas de pantalla, grabado de la P4
.claude/skills/      la skill para personalizarlo con Claude

Comandos por el puerto serie

Abre el monitor a 115200 (pio device monitor) y escribe:

Problemas conocidos

• AMOLED 1.75, el táctil no responde: el CST9217 a veces se queda colgado y solo vuelve quitándole la corriente del todo (USB fuera y botón PWR unos segundos).
• AMOLED 1.75, el micrófono da silencio: el ES7210 necesita el MCLK también por GPIO16; el firmware ya lo hace.
• P4 4C, el fondo «palpita»: el CABC del panel (brillo adaptativo) estaba activo; el firmware lo apaga al arrancar. Si lo ves, prueba otra alimentación USB.
• P4 4C, rayas o parpadeo al animar: la pantalla lee de la misma PSRAM en la que se pinta; por eso solo se copia lo que cambia. Si añades animaciones grandes, mira docs/hardware.md.

Créditos

• Placas y apoyo: Waveshare.
• Gráficos: LovyanGFX (FreeBSD). Configuración de pantallas a partir de los BSP oficiales de Waveshare.
• Fuentes: Hanken Grotesk y JetBrains Mono (SIL OFL 1.1).
• Voz: whisper.cpp y Piper. Agente: Hermes Agent.

Detalle de licencias de terceros en THIRD_PARTY.md. El código de este repositorio es MIT.

Pana gives your AI agent a face and a voice on a round Waveshare touchscreen. Hold the character, talk, and your agent (Hermes Agent or any OpenAI-compatible LLM) answers out loud while the screen shows what it is doing: which tool it runs, how long it takes, and what it needs you to approve.

• Body (firmware/): an ESP32-S3 or ESP32-P4 board with display, mic and speaker. Draws, animates, listens and plays audio.
• Brain (server/): a Python/FastAPI server on your machine. Whisper for speech-to-text, Piper for text-to-speech, your agent in the middle, a WebSocket protocol to the boards.
• Supported boards: Waveshare ESP32-S3-Touch-AMOLED-1.75/1.75C and ESP32-P4-WIFI6-Touch-LCD-4C. More Waveshare boards are on the way.
• Customize it with Claude Code: the repo ships a skill (.claude/skills/personalizar-pana) so you can ask Claude to change the character, the colors, the persona, add dashboard widgets or port it to a new board.

The UI and docs are in Spanish; the code is commented in Spanish too. Quick start: cp .env.example .env, pip install -r server/requirements.txt, python server/main.py, then pio run -e amoled175 -t upload (or p4-4c + tools/flash_p4.sh), and join the Pana-Setup Wi-Fi from your phone. MIT licensed.