zclaw

El asistente personal de IA más pequeño posible para ESP32.

zclaw está escrito en C y se ejecuta en placas ESP32 con un presupuesto estricto de firmware todo incluido de <= 888 KiB en la compilación predeterminada. Admite tareas programadas, control GPIO, memoria persistente y composición de herramientas personalizadas mediante lenguaje natural.

El límite de 888 KiB es el tamaño total del firmware, no solo el código de la aplicación. Incluye la lógica de zclaw más el tiempo de ejecución de ESP-IDF/FreeRTOS, Wi-Fi/redes, TLS/criptografía y la sobrecarga del paquete de certificados.

Divertido de usar, divertido de hackear.

Documentación Completa

Utiliza el sitio de documentación para guías completas y referencia.

• Documentación completa
• Consola de administración local
• Casos de uso: útil + divertido
• Registro de cambios (web)
• README completo (textual)

Inicio Rápido

Arranque de una línea (macOS/Linux):

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

¿Ya clonado?

./install.sh

Instalación no interactiva:

./install.sh -y

Destacados

• Chatea a través de Telegram o de un relé web alojado
• Programaciones con conocimiento de zona horaria (daily, periodic y de una sola vez once)
• Herramientas integradas + definidas por el usuario
• Para capacidades integradas completamente nuevas, agrega una herramienta de firmware (controlador C + entrada de registro) a través de la documentación Construye tu propia herramienta.
• Diagnósticos en tiempo de ejecución mediante get_diagnostics (alcances: quick/runtime/memory/rates/time/all)
• Control GPIO, DHT e I2C con protecciones (incluyendo gpio_read_all, i2c_scan, i2c_read/i2c_write y dht_read)
• Consola de administración local por USB para recuperación, modo seguro y puesta en marcha previa a la red
• Memoria persistente entre reinicios
• Opciones de personalidad: neutral, friendly, technical,

Hardware

Objetivos probados: ESP32, ESP32-C3, ESP32-S3 y ESP32-C6. Las placas clásicas ESP32-WROOM/ESP32 DevKit son compatibles. ¡Los informes de prueba para otras variantes de ESP32 son muy bienvenidos!

Placa de inicio recomendada: Seeed XIAO ESP32-C3

Desarrollo Local y Hacking

Bucle rápido típico:

./scripts/test.sh host
./scripts/build.sh
./scripts/flash.sh --kill-monitor /dev/cu.usbmodem1101
./scripts/provision-dev.sh --port /dev/cu.usbmodem1101
./scripts/monitor.sh /dev/cu.usbmodem1101

Configuración de perfil una vez, luego reutiliza:

./scripts/provision-dev.sh --write-template
# editar ~/.config/zclaw/dev.env
./scripts/provision-dev.sh --show-config
./scripts/provision-dev.sh

# si Telegram sigue reproduciendo actualizaciones obsoletas:
./scripts/telegram-clear-backlog.sh --show-config

Más detalles en la Guía de desarrollo local y hacking.

Otros Scripts Útiles

Consola de Administración Local

Cuando la placa esté en modo seguro, sin aprovisionar, o la ruta del LLM no esté disponible, aún puedes operarla a través del USB serie sin Wi-Fi ni un viaje de ida y vuelta al LLM.

./scripts/monitor.sh /dev/cu.usbmodem1101
# luego escribe:
/wifi status
/wifi scan
/bootcount
/gpio all
/reboot

Comandos disponibles solo localmente:

• /gpio [all|pin|pin high|pin low]
• /diag [alcance] [verbose]
• /reboot
• /wifi [status|scan]
• /bootcount
• /factory-reset confirm (destructivo; borra NVS y reinicia)

Referencia completa: Consola de administración local

Desglose de Tamaño

Desglose predeterminado actual de esp32 (bytes de imagen agrupados desde idf.py -B build size-components):

El tamaño total de la imagen de esta compilación es 853034 bytes; el zclaw.bin rellenado es 853184 bytes (~833.2 KiB), dejando 56128 bytes (~54.8 KiB) por debajo del límite de 888 KiB.

Evaluación Comparativa de Latencia

Evaluación comparativa de la ruta del relé (incluye procesamiento del relé web + viaje de ida y vuelta del dispositivo):

./scripts/benchmark.sh --mode relay --count 20 --message "ping"

Evaluación comparativa directa por serie (viaje de ida y vuelta del host + tiempo de primera respuesta). Si el firmware registra líneas METRIC request ..., el informe también incluye tiempos del lado del dispositivo:

./scripts/benchmark.sh --mode serial --serial-port /dev/cu.usbmodem1101 --count 20 --message "ping"

Licencia

MIT