Conception des périphériques matériels : ZeroClaw

ZeroClaw permet aux microcontrôleurs (MCU) et aux ordinateurs monocartes (SBC) d’interpréter dynamiquement des commandes en langage naturel, de générer du code spécifique au matériel et d’exécuter des interactions périphériques en temps réel.

1. Vision

Objectif : ZeroClaw agit comme un agent IA conscient du matériel qui :

• Reçoit des déclencheurs en langage naturel (par ex. “Déplacer le bras X”, “Allumer la LED”) via des canaux (WhatsApp, Telegram)
• Récupère la documentation matérielle précise (datasheets, cartes des registres)
• Génère du code/logique Rust en utilisant un LLM (Gemini, modèles open source locaux)
• Exécute la logique pour manipuler les périphériques (GPIO, I2C, SPI)
• Conserve le code optimisé pour une future réutilisation

Modèle mental : ZeroClaw = cerveau qui comprend le matériel. Périphériques = bras et jambes qu’il contrôle.

2. Deux modes de fonctionnement

Mode 1 : Edge-Native (Autonome)

Cible : Cartes avec Wi-Fi (ESP32, Raspberry Pi).

ZeroClaw s’exécute directement sur l’appareil. La carte met en place un serveur gRPC/nanoRPC et communique avec les périphériques localement.

ZeroClaw on ESP32 / Raspberry Pi (Edge-Native)

  Channels (WhatsApp, Telegram)
        │
        ▼
  Agent Loop (LLM calls) ──► RAG: datasheets, register maps ──► LLM context
        │
        ▼
  Code synthesis ──► Wasm / dynamic exec ──► GPIO / I2C / SPI ──► persist
        │
        ▼
  gRPC/nanoRPC server ◄──► Peripherals (GPIO, I2C, SPI, sensors, actuators)

Flux de travail :

1. L’utilisateur envoie WhatsApp : “Allumer la LED sur la broche 13”
2. ZeroClaw récupère les documents spécifiques à la carte (par exemple, la correspondance des broches GPIO de l’ESP32)
3. Le LLM synthétise du code Rust
4. Le code s’exécute dans un bac à sable (Wasm ou liaison dynamique)
5. La GPIO est basculée ; le résultat est renvoyé à l’utilisateur
6. Le code optimisé est conservé pour les futures demandes “Activer la LED”

Tout se fait sur l’appareil. Aucun hôte requis.

Mode 2 : Hôte-médié (Développement / Débogage)

Cible : matériel connecté via USB / J-Link à un hôte (macOS, Linux).

ZeroClaw s’exécute sur l’hôte et maintient un lien adapté au matériel avec la cible. Utilisé pour le développement, l’inspection et le flashage.

  ZeroClaw on Mac (host)              STM32 Nucleo-F401RE (or other MCU)
  ─────────────────────              ──────────────────────────────────
  - Channels                         - Memory map
  - LLM                              - Peripherals (GPIO, ADC, I2C)
  - Hardware probe        ◄────────► - Flash / RAM
  - Flash / debug
                       USB / J-Link
                       VID/PID discovery

Flux de travail :

1. L’utilisateur envoie un message Telegram : “Quelles sont les adresses mémoire lisibles sur cet appareil USB ?”
2. ZeroClaw identifie le matériel connecté (VID/PID, architecture)
3. Effectue le mappage mémoire; suggère les espaces d’adresse disponibles
4. Renvoie le résultat à l’utilisateur

Ou :

1. User: “Flash firmware sur la Nucleo”
2. ZeroClaw écrit/firmware via OpenOCD ou probe-rs
3. Confirme la réussite

Ou :

1. ZeroClaw découvre automatiquement : “STM32 Nucleo sur /dev/ttyACM0, ARM Cortex-M4”**
2. Suggestions : « Je peux lire/écrire GPIO, ADC, flash. Que souhaitez-vous faire ? »

Comparaison des modes

3. Modes hérités / plus simples (avant LLM-on-Edge)

Pour les cartes sans WiFi ou avant que la version Edge-Native complète soit prête :

Mode A : Hôte + Périphérique distant (STM32 via série)

L’hôte exécute ZeroClaw ; les périphériques exécutent un firmware minimal. JSON simple via le port série.

Mode B : RPi comme hôte (GPIO natif)

ZeroClaw sur Pi ; GPIO via rppal ou sysfs. Aucun firmware séparé.

4. Exigences techniques

Pipeline RAG (Récupération de Datasheet)

• Index: Fiches techniques, manuels de référence, cartes des registres (pré-convertis en .md / .txt → chunks, embeddings).
• Récupérer : Lors d’une requête utilisateur (« allumer la LED »), récupérer les extraits pertinents (par exemple, la section GPIO pour la carte cible).
• Injecter : Ajouter au prompt système ou au contexte du LLM.
• Résultat : Le LLM génère du code précis, spécifique au tableau.

Options d’exécution dynamique

Recommandation : Commencez par des modèles précompilés avec paramétrisation ; évoluez vers Wasm pour la logique définie par l’utilisateur une fois que cela sera stable.

5. CLI et configuration

Consultez la référence CLI pour les sous-commandes zeroclaw hardware / zeroclaw peripheral et la référence de configuration pour les champs [peripherals] et [[peripherals.boards]].

6. Architecture : Périphérique comme point d’extension

Nouveau trait : Peripheral

#![allow(unused)]
fn main() {
/// Une périphérique matériel qui expose des capacités en tant qu'outils.
#[async_trait]
pub trait Peripheral: Send + Sync {
    fn name(&self) -> &str;
    fn board_type(&self) -> &str;  // par ex. "nucleo-f401re", "rpi-gpio"
    async fn connect(&mut self) -> anyhow::Result<()>;
    async fn disconnect(&mut self) -> anyhow::Result<()>;
    async fn health_check(&self) -> bool;
    /// Outils fournis par cette périphérie (gpio_read, gpio_write, sensor_read, etc.)
    fn tools(&self) -> Vec<Box<dyn Tool>>;
}
}

Flux

1. Démarrage : ZeroClaw charge la configuration et détecte peripherals.boards.
2. Connecter : Pour chaque carte, créez une implémentation de Peripheral et appelez connect().
3. Outils : Collecter les outils de tous les périphériques connectés ; les fusionner avec les outils par défaut.
4. Boucle d’agent : L’agent peut appeler gpio_write, sensor_read, etc., ceux-ci délèguent au périphérique.
5. Arrêt : Appelez disconnect() sur chaque périphérique.

Prise en charge de la carte

Les cartes sont identifiées par leur VID/PID USB dans le registre canonique :

Chaque carte connectée est pilotée via l’un des transports du sous-système :

Les outils de base exposés par chaque carte sont répertoriés dans Sous-système matériel → Outils d’exécution.

7. Protocoles de communication

gRPC / nanoRPC (Edge-Native, Host-Mediated)

Pour une RPC typée à faible latence entre ZeroClaw et les périphériques :

• nanoRPC ou tonic (gRPC) : Services définis par Protobuf.
• Méthodes : GpioWrite, GpioRead, I2cTransfer, SpiTransfer, MemoryRead, FlashWrite, etc.
• Active les appels bidirectionnels en streaming et la génération de code à partir des fichiers .proto.

Transport série (médiation par l’hôte, hérité)

JSON simple sur série pour les cartes sans prise en charge de gRPC :

Requête (hôte → périphérique) :

{"id":"1","cmd":`gpio_write`,"args":{"épingler":13,"valeur":1}}

Réponse (périphérique → hôte) :

{"id":"1","ok":true,"résultat":"terminé"}

8. Microprogramme (dépôt ou crate séparé)

• zeroclaw-firmware ou zeroclaw-peripheral : un crate/workspace distinct.
• Cibles : thumbv7em-none-eabihf (STM32), armv7-unknown-linux-gnueabihf (RPi), etc.
• Utilise embassy ou Zephyr pour STM32.
• Implémente le protocole ci-dessus.
• L’utilisateur flashe cette configuration sur la carte ; ZeroClaw se connecte et découvre les capacités.

9. Couches de capacités

Le sous-système est construit en couches ; chacune est utilisable indépendamment. Plutôt que de suivre ici l’état d’avancement des phases (qui dérive au fur et à mesure que le travail est intégré), les couches sont :

• Squelette. Le trait Peripheral, le schéma de configuration et la CLI zeroclaw peripheral. Le drapeau --peripheral connecte une carte à l’agent.

• Découverte assistée par l’hôte. zeroclaw hardware discover énumère les périphériques USB par VID/PID ; le registre des cartes les associe à une architecture et un nom ; zeroclaw hardware introspect <path> rapporte la cartographie mémoire et la liste des périphériques.

• Transport série / sonde. SerialPeripheral transporte le protocole JSON via USB CDC ; la fonctionnalité probe ajoute le SWD de probe-rs pour le flash, la carte mémoire et la lecture mémoire (voir les outils hardware_*).

• Pipeline RAG. Les fiches techniques sont indexées et injectées dans le contexte du LLM lors des requêtes matérielles.

  Utilisation : zeroclaw config set peripherals.datasheet-dir docs/datasheets. Placez des fichiers .md ou .txt nommés par carte (par exemple nucleo-f401re.md, rpi-gpio.md). Les fichiers dans _generic/ ou nommés generic.md s’appliquent à toutes les cartes. Les extraits sont récupérés par correspondance de mot-clé et injectés dans le contexte du message utilisateur.

• Natif en périphérie (Raspberry Pi). ZeroClaw s’exécute sur le Pi avec un accès GPIO natif via rppal (la fonctionnalité peripheral-rpi).

• ESP32. Médié par l’hôte via le transport série, même protocole JSON que STM32. Les cartes de développement ESP32 figurent dans le registre via leur VID/PID USB CH340.

  Utilisation : Flashez firmware/esp32 sur l’ESP32, ajoutez board = "esp32", transport = "serial", path = "/dev/ttyUSB0" à la configuration.

• Exécution dynamique. La logique générée par LLM s’exécute via des modèles paramétrés, avec un environnement d’exécution Wasm en sandbox comme orientation à plus long terme pour la logique définie par l’utilisateur.

10. Considérations de sécurité

• Chemin série : Valider que le path figure dans la liste autorisée (par exemple /dev/ttyACM*, /dev/ttyUSB*) ; jamais des chemins arbitraires.
• GPIO : Restreindre les broches exposées ; éviter les broches d’alimentation et de réinitialisation.
• Aucun secret sur le périphérique : Le firmware ne doit pas stocker de clés API ; l’hôte gère l’authentification.

11. Objectifs exclus (pour l’instant)

• Exécution complète de ZeroClaw sur un STM32 nu (sans WiFi, RAM limitée), utilisez Host-Mediated à la place
• Garanties temps réel : les périphériques fonctionnent en mode best-effort
• Exécution de code natif arbitraire depuis un LLM : préférez Wasm ou les templates

12. Documents connexes

• adding-boards-and-tools.md : Comment ajouter des cartes et des fiches techniques
• network-deployment.md : RPi et déploiement réseau

13. Références

• Prise en charge de Rust dans Zephyr RTOS
• Embassy : framework embarqué asynchrone
• rppal : GPIO du Raspberry Pi en Rust
• STM32 Nucleo-F401RE
• tonic : gRPC pour Rust
• probe-rs : sonde de débogage ARM, flash, accès mémoire
• nusb : énumération des périphériques USB (VID/PID)

14. Résumé du prompt brut

_« Les cartes comme ESP, Raspberry Pi, ou les cartes avec WiFi peuvent se connecter à un LLM (Gemini ou open-source). ZeroClaw s’exécute sur l’appareil, crée son propre gRPC, le démarre et communique avec les périphériques. L’utilisateur demande via WhatsApp : ‘bouge le bras X’ ou ‘allume la LED’. ZeroClaw obtient une documentation précise, écrit le code, l’exécute, le stocke de manière optimale, le lance et allume la LED, le tout sur la carte de développement.

For STM Nucleo connecté via USB/J-Link à mon Mac : ZeroClaw depuis mon Mac accède au matériel, installe ou écrit ce qu’il veut sur l’appareil, puis renvoie le résultat. Exemple : ‘Hé ZeroClaw, quelles sont les adresses disponibles/lisibles sur cet appareil USB ?’ Il peut déterminer ce qui est connecté et où, puis faire des suggestions.