Ajout de cartes et d’outils : guide matériel ZeroClaw

Ce guide explique comment ajouter de nouvelles cartes matérielles et des outils personnalisés à ZeroClaw.

Démarrage rapide : Ajouter un tableau via l’interface CLI

# Ajouter un tableau
zeroclaw peripheral add nucleo-f401re /dev/ttyACM0
zeroclaw peripheral add arduino-uno /dev/cu.usbmodem12345
zeroclaw peripheral add rpi-gpio native   # pour GPIO Raspberry Pi (Linux)

# Redémarrez le daemon pour appliquer
zeroclaw daemon --host 127.0.0.1 --port 42617

Cartes prises en charge

Les cartes sont identifiées par leur VID/PID USB. Le registre canonique :

La valeur board dans [[peripherals.boards]] est comparée à ces noms du registre (ainsi qu’à quelques alias spécifiques au transport tels que arduino-uno-q / rpi-gpio, gérés dans peripherals/mod.rs).

Configuration manuelle

Les cartes sont configurées sous peripherals et peripherals.boards. Consultez la référence de configuration pour l’index complet des champs, y compris datasheet_dir (source RAG).

Ajout d’une fiche technique (RAG)

Placez les fichiers .md ou .txt dans docs/datasheets/ (ou votre datasheet_dir). Nommez les fichiers par carte : nucleo-f401re.md, arduino-uno.md. Les fichiers sont extraits, découpés en chunks et récupérés dans le contexte de l’agent pour les questions spécifiques à la carte. L’analyse des fiches techniques PDF n’est plus prise en charge à partir de #8519 ; convertissez les PDF en .md ou .txt avant l’indexation.

Alias de point de fixation (Recommandé)

Ajoutez une section ## Alias des broches afin que l’agent puisse mapper « led rouge » → broche 13 :

# My Board

## Pin Aliases

| alias       | pin |
|-------------|-----|
| red_led     | 13  |
| builtin_led | 13  |
| user_led    | 5   |

Ou utilisez le format clé-valeur :

## Pin Aliases
red_led: 13
builtin_led: 13

Ajout d’un nouveau type de carte

1. Créer une fiche technique : docs/datasheets/my-board.md avec les alias de broches et les informations GPIO.
2. Ajouter à la configuration : zeroclaw peripheral add my-board /dev/ttyUSB0
3. Implémenter un périphérique (optionnel) : pour les protocoles personnalisés, implémentez le trait Peripheral dans crates/zeroclaw-hardware/src/peripherals/ et enregistrez-le dans create_peripheral_tools.

Voir docs/hardware/hardware-peripherals-design.md pour la conception complète.

Ajout d’un outil personnalisé

1. Implémentez le trait Tool dans crates/zeroclaw-tools/src/.
2. Enregistrez dans create_peripheral_tools (pour les outils matériels) ou dans le registre des outils de l’agent.
3. Ajoutez une description de l’outil à tool_descs de l’agent dans crates/zeroclaw-runtime/src/agent/loop_.rs.

Référence CLI

Consultez la référence CLI générée pour les sous-commandes zeroclaw peripheral et zeroclaw hardware.

Dépannage

• Port série introuvable : Sur macOS, utilisez /dev/cu.usbmodem* ; sur Linux, utilisez /dev/ttyACM0 ou /dev/ttyUSB0.
• Compiler avec le matériel : cargo build --features hardware
• Probe-rs pour Nucleo : cargo build --features hardware,probe