Agregar Placas y Herramientas: Guía de Hardware de ZeroClaw

Esta guía explica cómo agregar nuevas placas de hardware y herramientas personalizadas a ZeroClaw.

Inicio rápido: Agregar un tablero mediante CLI

# Agregar un tablero
zeroclaw peripheral add nucleo-f401re /dev/ttyACM0
zeroclaw peripheral add arduino-uno /dev/cu.usbmodem12345
zeroclaw peripheral add rpi-gpio native   # para GPIO de Raspberry Pi (Linux)

# Reiniciar el daemon para aplicar
zeroclaw daemon --host 127.0.0.1 --port 42617

Placas compatibles

Las placas se identifican mediante el VID/PID USB. El registro canónico:

El valor board en [[peripherals.boards]] se compara con estos nombres del registro (y algunos alias específicos del transporte como arduino-uno-q / rpi-gpio gestionados en peripherals/mod.rs).

Configuración manual

Las placas se configuran en peripherals y peripherals.boards. Consulte la referencia de configuración para el índice completo de campos, incluido datasheet_dir (fuente RAG).

Agregando una Hoja de Datos (RAG)

Coloca archivos .md o .txt en docs/datasheets/ (o en tu datasheet_dir). Nombra los archivos por placa: nucleo-f401re.md, arduino-uno.md. Los archivos se extraen, se dividen en fragmentos y se recuperan en el contexto del agente para preguntas específicas de la placa. El análisis de datasheets en PDF ya no es compatible desde #8519; convierte los PDFs a .md o .txt antes de indexarlos.

Alias de pines (Recomendado)

Añade una sección ## Pin Aliases para que el agente pueda mapear “red led” → pin 13:

# My Board

## Pin Aliases

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

O usa el formato de clave-valor:

## Pin Aliases
red_led: 13
builtin_led: 13

Agregar un nuevo tipo de placa

1. Crea una hoja de datos: docs/datasheets/my-board.md con alias de pines e información de GPIO.
2. Agregar a la configuración: zeroclaw peripheral add my-board /dev/ttyUSB0
3. Implementar un periférico (opcional): Para protocolos personalizados, implemente el trait Peripheral en crates/zeroclaw-hardware/src/peripherals/ y regístrelo en create_peripheral_tools.

Consulta docs/hardware/hardware-peripherals-design.md para ver el diseño completo.

Agregar una herramienta personalizada

1. Implementa el rasgo Tool en crates/zeroclaw-tools/src/.
2. Regístrate en create_peripheral_tools (para herramientas de hardware) o en el registro de herramientas del agente.
3. Agregue una descripción de la herramienta a tool_descs del agente en crates/zeroclaw-runtime/src/agent/loop_.rs.

Referencia de la CLI

Consulta la referencia de CLI generada para los subcomandos zeroclaw peripheral y zeroclaw hardware.

Solución de problemas

• Puerto serie no encontrado: En macOS use /dev/cu.usbmodem*; en Linux use /dev/ttyACM0 o /dev/ttyUSB0.
• Compilar con hardware: cargo build --features hardware
• Probe-rs para Nucleo: cargo build --features hardware,probe