zclaw – 888 KiB AI Personal Assistant for ESP32 (C/C++)

Introducción

zclaw es un asistente personal de IA minimalista, todo en el firmware, que funciona en microcontroladores basados en ESP32 con un estricto límite de tamaño de 888 KiB. El proyecto está escrito en C puro y aprovecha ESP‑IDF y FreeRTOS, por lo que puede volcarse en cualquier placa ESP32‑C3, ESP32‑S3 o ESP32‑C6 con poco esfuerzo.

¿Por qué zclaw?

Las soluciones típicas de LLM en el dispositivo requieren gigabytes de RAM o una GPU externa. zclaw evita esas limitaciones al * entregar un backend de LLM de propósito único y compacto (Ollama, OpenAI, Anthropic, etc.) * usar APIs de programación compactas y GPIO para tareas simples tipo "cron" * almacenar todas las credenciales y configuraciones en ESP‑NVS con cifrado AES opcional * proporcionar una interfaz de chat en Telegram y un relay web ligero para navegadores.

El resultado es un AI edge que corre offline en 850 KiB de flash y puede responder preguntas en lenguaje natural en tiempo real.

Características Clave

Requisitos Previos

1. ESP‑IDF – Instala la última SDK siguiendo la guía oficial.
2. Git – Clona el repositorio.
3. Python 3.8+ – Para los scripts de aprovisionamiento y pruebas.
4. Token del Bot de Telegram – (opcional, para chat) o un endpoint HTTP LLM.
5. Credenciales Wi‑Fi – Detalles de red para arrancar el dispositivo.

Empezar en Una Línea

bash <(curl -fsSL https://raw.githubusercontent.com/tnm/zclaw/main/scripts/bootstrap.sh)

El script bootstrap hará lo siguiente: * Clonar o actualizar la fuente más reciente de zclaw. * Ejecutar el install.sh no interactivo que compila el firmware. * Grabar la compilación a la placa elegida. * Aprovisionar Wi‑Fi y credenciales LLM.

Si ya dispones de un clon local, simplemente usa ./install.sh o ./install.sh -y para una prueba sin efectos.

Voltear y Aprovisionar Seguro

El modo seguro protege tus claves API y contraseñas Wi‑Fi mediante cifrado de ESP‑NVS.

# Voltear con cifrado y establecer una frase de contraseña simple
./scripts/flash-secure.sh

Tras el volteo, ejecuta ./scripts/provision.sh. El script solicitará: * SSID / contraseña Wi‑Fi * Nombre del proveedor LLM (p. ej., ollama, openai) * Endpoint y clave API del proveedor * Token de bot Telegram y chat ID opcionales

Todos los valores se almacenan hasheados en flash. El flag --flash-mode secure garantiza que cualquier actualización posterior también preserve la cifrado.

Ejecutar el Servicio de Chat

Una vez aprovisionado, el dispositivo arranca en Wi‑Fi y espera una conexión de chat.

• Telegram – El bot reenviará automáticamente los mensajes recibidos y devolverá respuestas.
• Relay Web – Ejecuta ./scripts/web-relay.sh desde una máquina host. Se abre un endpoint HTTPS de corta duración al que se conecta el ESP32. Abre la URL proporcionada en un navegador y chatea en tiempo real.

Ambas interfaces transmiten la salida del LLM en vivo, por lo que la experiencia se siente casi nativa.

Programar Tareas

El programador de zclaw parece un cron ligero.

int main() {
    scheduler_register("");
    // Programa un ping diario a las 3 AM
    scheduler_schedule("3 * * * *", "ping_device");
}

La sintaxis cron en formato JSON es consciente de zona horaria y puede disparar cualquier herramienta zclaw registrada o función C personalizada.

GPIO y Persistencia

El API GPIO está protegido: cada escritura puede limitarse a un rango de pines, y la llamada gpio_read_all() devuelve un mapa de bits contiguo de los estados de los pines.

La memoria persistente se expone mediante un sencillo API clave‑valor en NVS:

nvs_set("user_pref", 42);
int val = nvs_get("user_pref");

Úsala para almacenar perfiles de usuario, tiempos de último prompt o tu propio estado de aplicación.

Extender zclaw con Herramientas Personalizadas

zclaw trae un pequeño sistema de plugins. Para agregar una herramienta nueva: 1. Crea una función C que cumpla con la firma zclaw_tool_t. 2. Edita main/config.h para registrar la herramienta. 3. Vuelve a compilar con ./scripts/build.sh.

La herramienta nueva puede invocarse desde la interfaz de chat anteponiendo al prompt tool: TuNombreDeHerramienta.

Flujo de Trabajo de Desarrollo

Bucle típico de desarrollo:

./scripts/test.sh host          # Validar las pruebas host
./scripts/build.sh              # Compilar el firmware
./scripts/flash.sh --kill-monitor /dev/cu.usbmodem1101
./scripts/provision-dev.sh --write-template  # Configurar un perfil dev local
./scripts/monitor.sh /dev/cu.usbmodem1101

El repositorio incluye un pipeline CI completo en .github/workflows/ que construye, prueba y verifica cada commit automáticamente.

Contribuir

¡Todas las contribuciones son bienvenidas! * Fork, crea una rama de función o corrección. * Asegúrate de que las pruebas pasen localmente. * Abre un PR y referencia el issue relevante. * La licencia es MIT – un vistazo rápido a LICENSE lo confirmará.

Si encuentras una falla de seguridad, envía un mensaje directo al mantenedor o usa la función de reporte de seguridad de GitHub.

Licencia y Créditos

zclaw se publica bajo la licencia MIT. El código es un esfuerzo colaborativo de la comunidad de código abierto. Muchas gracias al equipo ESP‑IDF, a los colaboradores de FreeRTOS y a todos los usuarios que probaron en hardware real.

Para más información visita la documentación oficial en https://zclaw.dev o el repositorio GitHub.