zclaw

O menor assistente pessoal de IA possível para ESP32.

zclaw é escrito em C e roda em placas ESP32 com um orçamento estrito de firmware all-in de <= 888 KiB na build padrão. Suporta tarefas agendadas, controle GPIO, memória persistente e composição personalizada de ferramentas através de linguagem natural.

O limite de 888 KiB é o tamanho total do firmware all-in, não apenas o código do aplicativo. Inclui a lógica do zclaw mais o runtime ESP-IDF/FreeRTOS, Wi-Fi/rede, TLS/criptografia e overhead do pacote de certificados.

Divertido de usar, divertido de hackear.

Documentação Completa

Use o site de documentação para guias completos e referência.

• Documentação completa
• Console de Administração Local
• Casos de uso: úteis + divertidos
• Registro de alterações (web)
• README completo (verbatim)

Início Rápido

Linha única de inicialização (macOS/Linux):

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

Já clonou?

./install.sh

Instalação não interativa:

./install.sh -y

Destaques

• Chat via Telegram ou relay web hospedado
• Agendamentos com fuso horário (diário, periódico e único uma vez)
• Ferramentas integradas + definidas pelo usuário
• Para capacidades integradas completamente novas, adicione uma ferramenta de firmware (handler C + entrada de registro) através da documentação Build Your Own Tool.
• Diagnóstico de runtime via get_diagnostics (escopos: quick/runtime/memory/rates/time/all)
• Controle GPIO, DHT e I2C com proteções (incluindo gpio_read_all, i2c_scan, i2c_read/i2c_write e dht_read)
• Console de administração local USB para recuperação, modo seguro e inicialização pré-rede
• Memória persistente entre reinicializações
• Opções de persona: neutra, amigável, técnica,

Hardware

Alvos testados: ESP32, ESP32-C3, ESP32-S3 e ESP32-C6. Placas clássicas ESP32-WROOM/ESP32 DevKit são suportadas. Relatórios de teste para outras variantes ESP32 são muito bem-vindos!

Placa inicial recomendada: Seeed XIAO ESP32-C3

Desenvolvimento Local & Hackeamento

Loop 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

Configure o perfil uma vez e depois reutilize:

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

# se o Telegram continuar reproduzindo atualizações obsoletas:
./scripts/telegram-clear-backlog.sh --show-config

Mais detalhes no guia Local Dev & Hacking.

Outros Scripts Úteis

Console de Administração Local

Quando a placa está em modo seguro, não provisionada, ou o caminho LLM está indisponível, você ainda pode operá-la via USB serial sem Wi-Fi ou uma ida e volta ao LLM.

./scripts/monitor.sh /dev/cu.usbmodem1101
# então digite:
/wifi status
/wifi scan
/bootcount
/gpio all
/reboot

Comandos locais disponíveis:

• /gpio [all|pin|pin high|pin low] - Define ou lê pinos GPIO.
• /diag [scope] [verbose] - Diagnóstico com escopo e verbosidade opcionais.
• /reboot - Reinicializar.
• /wifi [status|scan] - Status ou scan do Wi-Fi.
• /bootcount - Mostrar contagem de boot.
• /factory-reset confirm - Reset de fábrica (destrutivo; apaga NVS e reinicializa).

Referência completa: Local Admin Console

Detalhamento de Tamanho

Detalhamento atual do esp32 padrão (bytes de imagem agrupados de idf.py -B build size-components):

O tamanho total da imagem desta build é 853034 bytes; o zclaw.bin preenchido tem 853184 bytes (~833.2 KiB), deixando 56128 bytes (~54.8 KiB) abaixo do limite de 888 KiB.

Benchmark de Latência

Benchmark do caminho relay (inclui processamento do relay web + ida e volta do dispositivo):

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

Benchmark serial direto (ida e volta do host + tempo da primeira resposta). Se o firmware registrar linhas METRIC request ..., o relatório também inclui o tempo do lado do dispositivo:

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

Licença

MIT