zclaw – Assistant personnel IA de 888 KiB pour ESP32 (C/C++)
Introduction
zclaw est un assistant personnel IA minimal, entièrement intégré dans le microprogramme, qui fonctionne sur des microcontrôleurs basés sur l'ESP32 avec une enveloppe de taille stricte de 888 KiB. Le projet est écrit en C standard et s'appuie sur ESP‑IDF et FreeRTOS, ce qui permet d'être flasheur sur n'importe quel ESP32‑C3, ESP32‑S3 ou ESP32‑C6 avec peu d'effort.
Pourquoi zclaw ?
Les solutions LLM sur‑dispositif classiques requièrent des gigaoctets de RAM ou un GPU externe. zclaw contourne ces limitations en :
- livrant un backend LLM petit et dédié (Ollama, OpenAI, Anthropic, etc.)
- utilisant une planification compacte et des API GPIO pour des tâches simples “cron‑type”
- stockant toutes les informations d'identification et la configuration dans ESP‑NVS avec option d'encryption AES
- fournissant une interface de chat Telegram et un relais web léger pour les navigateurs.
Le résultat est une IA de périphérique qui fonctionne hors‑ligne en 850 KiB de flash et peut répondre à des requêtes en langage naturel en temps réel.
Caractéristiques clés
| Fonctionnalité | Description |
|---|---|
| Empreinte Minuscule | Construction par défaut de 858 KiB, ≤ 888 KiB avec configuration sécurisée |
| Planification | Tâches quotidiennes, périodiques et ponctuelles avec prise en compte du fuseau horaire |
| Contrôle GPIO | Lecture / écriture avec garde-fous, lecture en bloc gpio_read_all() |
| État Persistant | E/S rapide vers NVS afin que les données survivent aux redémarrages |
| Outils Personnalisés | Enregistrez vos propres fonctions C comme plugins LLM |
| Mode Sécurisé | Encryption AES‑256 pour les identifiants stockés en flash |
| Canaux de Chat | Bot Telegram + interface web‑relay facultative |
| Backends LLM | Anthropic, OpenAI, OpenRouter, Ollama ou tout point de terminaison personnalisé |
| Scripts CLI | Bootstrap, installation, provision, flash, surveillance et benchmark |
Prérequis
- ESP‑IDF – Installez le dernier SDK en suivant le guide officiel.
- Git – Clonez le dépôt.
- Python 3.8+ – Pour les scripts de provisioning et de test.
- Token Bot Telegram – (facultatif, pour le chat) ou un point de terminaison LLM HTTP.
- Données Wi‑Fi – Détails réseau pour démarrer l’appareil.
Démarrage en une ligne
bash <(curl -fsSL https://raw.githubusercontent.com/tnm/zclaw/main/scripts/bootstrap.sh)
Le script bootstrap effectuera :
- Cloner ou tirer la dernière source zclaw.
- Exécuter le script install.sh non interactif qui compile le microprogramme.
- Flash la construction sur la carte choisie.
- Provisionner les identifiants Wi‑Fi et LLM.
Si vous avez déjà un clone local, utilisez simplement ./install.sh ou ./install.sh -y pour un test sans exécution.
Flash et Provisionnement Sécurisé
Le mode sécurisé protège vos clés API et mots de passe Wi‑Fi grâce au chiffrement ESP‑NVS.
# Flash avec chiffrement et définir une phrase de passe simple
./scripts/flash-secure.sh
./scripts/provision.sh. Le script vous demandera :
- SSID / mot de passe Wi‑Fi
- Nom du fournisseur LLM (ex. ollama, openai)
- Point de terminaison du fournisseur et clé API
- Token du bot Telegram et ID de chat (facultatif)
Toutes les valeurs sont stockées hachées dans le flash. Le drapeau --flash-mode secure garantit que toute mise à jour future conserve le chiffrement.
Lancement du Service de Chat
Une fois provisionné, l’appareil démarre sur le Wi‑Fi et attend une connexion de chat.
- Telegram – Le bot transfère automatiquement les messages reçus et renvoie les réponses.
- Relais Web – Lancez ./scripts/web-relay.sh depuis une machine hôte. Il ouvre un point de terminaison HTTPS temporaire que l'ESP32 se connecte. Ouvrez l’URL fournie dans un navigateur et discutez en temps réel.
Les deux interfaces diffusent le résultat du LLM en direct, pour une expérience quasi native.
Planification des Tâches
Le scheduler de zclaw ressemble à un cron léger.
int main() {
scheduler_register("");
// Programmer un ping quotidien à 3 h du matin
scheduler_schedule("3 * * * *", "ping_device");
}
GPIO et Persistance
L’API GPIO est protégée : chaque écriture peut être limitée à une plage de broches, et l’appel gpio_read_all() renvoie une carte bitmap contiguë d’états de broches.
La mémoire persistante est exposée via une API clé‑valeur simple dans NVS :
nvs_set("user_pref", 42);
int val = nvs_get("user_pref");
Extension de zclaw avec des Outils Personnalisés
zclaw est livré avec un petit système de plugins. Pour ajouter un nouvel outil :
1. Créez une fonction C conforme à la signature zclaw_tool_t.
2. Modifiez main/config.h pour enregistrer l’outil.
3. Recompilez avec ./scripts/build.sh.
Le nouvel outil peut être invoqué depuis l’interface de chat en préfixant la requête par tool: YourToolName.
Workflow de Développement
Boucle de développement typique :
./scripts/test.sh host # Valider les tests hôtes
./scripts/build.sh # Compiler le microprogramme
./scripts/flash.sh --kill-monitor /dev/cu.usbmodem1101
./scripts/provision-dev.sh --write-template # Mettre en place un profil de dev local
./scripts/monitor.sh /dev/cu.usbmodem1101
.github/workflows/ qui construit, teste et vérifie automatiquement chaque commit.
Contribuer
Toutes les contributions sont les bienvenues !
- Fork, créez une branche de fonctionnalité ou de correction.
- Assurez-vous que les tests passent localement.
- Ouvrez un PR et référencez le problème pertinent.
- La licence est MIT : un rapide examen du fichier LICENSE le confirmera.
Si vous découvrez une faille de sécurité, contactez directement le mainteneur ou utilisez la fonction de rapport de sécurité GitHub.
Licence & Crédits
zclaw est publié sous licence MIT. Le code est le fruit d’un effort collaboratif de la communauté open‑source. Un grand merci à l’équipe ESP‑IDF, aux contributeurs de FreeRTOS et à tous les utilisateurs qui ont testé sur du matériel réel.
Pour plus d’informations, consultez la documentation officielle sur https://zclaw.dev ou le dépôt GitHub.