zclaw

Le plus petit assistant personnel IA possible pour ESP32.

zclaw est écrit en C et fonctionne sur les cartes ESP32 avec un objectif strict de budget firmware tout-en-un de <= 888 KiB sur la construction par défaut. Il prend en charge les tâches planifiées, le contrôle GPIO, la mémoire persistante et la composition d'outils personnalisés via le langage naturel.

La limite de 888 KiB correspond à la taille totale du firmware, pas seulement au code applicatif. Elle inclut la logique zclaw ainsi que le runtime ESP-IDF/FreeRTOS, le Wi-Fi/réseau, TLS/crypto et la surcharge du bundle de certificats.

Amusant à utiliser, amusant à bidouiller.

Documentation complète

Utilisez le site de documentation pour les guides complets et les références.

• Documentation complète
• Console d'administration locale
• Cas d'utilisation : utiles + amusants
• Historique des modifications (web)
• README complet (mot pour mot)

Démarrage rapide

Bootstrap en une ligne (macOS/Linux) :

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

Déjà cloné ?

./install.sh

Installation non interactive :

./install.sh -y

Points forts

• Chat via Telegram ou relais web hébergé
• Plannings adaptés au fuseau horaire (daily, periodic, et unique once)
• Outils intégrés + définis par l'utilisateur
• Pour des capacités intégrées toutes nouvelles, ajoutez un outil firmware (gestionnaire C + entrée de registre) via la documentation Build Your Own Tool.
• Diagnostics d'exécution via get_diagnostics (portées quick/runtime/memory/rates/time/all)
• Contrôle GPIO, DHT et I2C avec garde-fous (incluant gpio_read_all, i2c_scan, i2c_read/i2c_write, et dht_read)
• Console d'administration locale USB pour la récupération, le mode sans échec et la mise en service pré-réseau
• Mémoire persistante entre les redémarrages
• Options de persona : neutral, friendly, technical,

Matériel

Cibles testées : ESP32, ESP32-C3, ESP32-S3 et ESP32-C6. Les cartes classiques ESP32-WROOM/ESP32 DevKit sont supportées. Les rapports de test pour d'autres variantes ESP32 sont les bienvenus !

Carte de démarrage recommandée : Seeed XIAO ESP32-C3

Développement local et bidouillage

Boucle rapide typique :

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

Configuration du profil une fois, puis réutilisation :

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

Plus de détails dans le guide Développement local et bidouillage.

Autres scripts utiles

Console d'administration locale

Lorsque la carte est en mode sans échec, non provisionnée, ou que le chemin LLM est indisponible, vous pouvez toujours l'utiliser via USB série sans Wi-Fi ni aller-retour LLM.

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

Commandes locales uniquement disponibles :

• /gpio [all|pin|pin high|pin low]
• /diag [scope] [verbose]
• /reboot
• /wifi [status|scan]
• /bootcount
• /factory-reset confirm (destructif ; efface NVS et redémarre)

Référence complète : Console d'administration locale

Répartition de la taille

Répartition actuelle par défaut pour esp32 (octets d'image groupés depuis idf.py -B build size-components) :

La taille totale de l'image de cette construction est de 853034 octets ; le fichier zclaw.bin rempli est de 853184 octets (~833.2 Kio), laissant 56128 octets (~54.8 Kio) sous la limite de 888 Kio.

Benchmark de latence

Benchmark du chemin relais (inclut le traitement du relais web + aller-retour appareil) :

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

Benchmark série direct (aller-retour hôte + temps de première réponse). Si le firmware enregistre des lignes METRIC request ..., le rapport inclut également le timing côté appareil :

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

Licence

MIT