zclaw

Il più piccolo assistente personale AI possibile per ESP32.

zclaw è scritto in C e funziona su schede ESP32 con un rigoroso budget totale di firmware di <= 888 KiB nella build predefinita. Supporta attività programmate, controllo GPIO, memoria persistente e composizione di strumenti personalizzati tramite linguaggio naturale.

Il limite di 888 KiB è la dimensione totale del firmware, non solo il codice dell'app. Include la logica zclaw più il runtime ESP-IDF/FreeRTOS, Wi-Fi/rete, TLS/crypto e overhead del bundle di certificati.

Divertente da usare, divertente da smanettare.

Documentazione Completa

Usa il sito di documentazione per guide complete e riferimenti.

• Documentazione completa
• Console di amministrazione locale
• Casi d'uso: utili + divertenti
• Changelog (web)
• README completo (verbatim)

Avvio Rapido

Bootstrap con una riga di comando (macOS/Linux):

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

Già clonato?

./install.sh

Installazione non interattiva:

./install.sh -y

Punti Salienti

• Chat tramite Telegram o relay web ospitato
• Programmazioni sensibili al fuso orario (daily, periodic e one-shot once)
• Strumenti integrati + definiti dall'utente
• Per nuove capacità integrate, aggiungi uno strumento firmware (gestore C + voce di registro) tramite la documentazione Build Your Own Tool.
• Diagnostica runtime tramite get_diagnostics (ambiti quick/runtime/memory/rates/time/all)
• Controllo GPIO, DHT e I2C con protezioni (incluse gpio_read_all, i2c_scan, i2c_read/i2c_write e dht_read)
• Console di amministrazione locale USB per ripristino, modalità sicura e avvio pre-rete
• Memoria persistente tra i riavvii
• Opzioni persona: neutral, friendly, technical,

Hardware

Target testati: ESP32, ESP32-C3, ESP32-S3 e ESP32-C6. Le schede classiche ESP32-WROOM/ESP32 DevKit sono supportate. Rapporti di test per altre varianti ESP32 sono molto graditi!

Scheda iniziale consigliata: Seeed XIAO ESP32-C3

Sviluppo Locale e Hacking

Loop veloce tipico:

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

Imposta il profilo una volta, poi riutilizzalo:

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

# if Telegram keeps replaying stale updates:
./scripts/telegram-clear-backlog.sh --show-config

Maggiori dettagli nella guida allo sviluppo locale e hacking.

Altri Script Utili

Console di Amministrazione Locale

Quando la scheda è in modalità sicura, non fornita, o il percorso LLM non è disponibile, puoi comunque operarla tramite USB seriale senza Wi-Fi o round trip LLM.

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

Comandi disponibili solo localmente:

• /gpio [all|pin|pin high|pin low]
• /diag [scope] [verbose]
• /reboot
• /wifi [status|scan]
• /bootcount
• /factory-reset confirm (distruttivo; cancella NVS e riavvia)

Riferimento completo: Console di amministrazione locale

Ripartizione delle Dimensioni

Ripartizione predefinita corrente per esp32 (byte dell'immagine raggruppati da idf.py -B build size-components):

La dimensione totale dell'immagine da questa build è 853034 byte; zclaw.bin con padding è 853184 byte (~833.2 KiB), lasciando 56128 byte (~54.8 KiB) sotto il limite di 888 KiB.

Benchmark di Latenza

Benchmark del percorso relay (include elaborazione relay web + round trip del dispositivo):

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

Benchmark seriale diretto (round trip host + tempo di prima risposta). Se il firmware registra righe METRIC request ..., il rapporto include anche il timing lato dispositivo:

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

Licenza

MIT