Diseño de periféricos de hardware: ZeroClaw

ZeroClaw permite que los microcontroladores (MCUs) y las computadoras de placa única (SBC) interpreten dinámicamente comandos en lenguaje natural, generen código específico del hardware y ejecuten interacciones con periféricos en tiempo real.

1. Visión

Objetivo: ZeroClaw actúa como un agente de IA consciente del hardware que:

• Recibe activadores en lenguaje natural (por ejemplo, “Mover el brazo X”, “Encender el LED”) a través de canales (WhatsApp, Telegram).
• Obtiene documentación precisa del hardware (datasheets, mapas de registros)
• Sintetiza código/lógica en Rust utilizando un modelo de lenguaje grande (LLM) (Gemini, modelos de código abierto locales)
• Ejecuta la lógica para manipular periféricos (GPIO, I2C, SPI)
• Persiste el código optimizado para su reutilización futura

Modelo mental: ZeroClaw = cerebro que comprende el hardware. Los periféricos = brazos y piernas que controla.

2. Dos modos de operación

Modo 1: Edge-Native (Autónomo)

Objetivo: Placas con Wi-Fi (ESP32, Raspberry Pi).

ZeroClaw se ejecuta directamente en el dispositivo. La placa inicia un servidor gRPC/nanoRPC y se comunica con los periféricos de forma local.

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)

Flujo de trabajo:

1. El usuario envía por WhatsApp: “Enciende el LED en el pin 13”
2. ZeroClaw obtiene documentación específica de la placa (por ejemplo, el mapeo de GPIO de ESP32).
3. LLM sintetiza código en Rust
4. El código se ejecuta en un entorno aislado (Wasm o enlace dinámico)
5. El GPIO se alterna; el resultado se devuelve al usuario
6. El código optimizado se guarda para futuras solicitudes de “Encender LED”.

Todo ocurre en el dispositivo. No se requiere un host.

Modo 2: Mediado por el host (Desarrollo / Depuración)

Destino: Hardware conectado mediante USB / J-Link a un host (macOS, Linux).

ZeroClaw se ejecuta en el host y mantiene un enlace consciente del hardware con el objetivo. Se utiliza para desarrollo, introspección y flasheo.

  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

Flujo de trabajo:

1. El usuario envía por Telegram: “¿Cuáles son las direcciones de memoria legibles en este dispositivo USB?”
2. ZeroClaw identifica el hardware conectado (VID/PID, arquitectura)
3. Realiza el mapeo de memoria; sugiere los espacios de direcciones disponibles
4. Devuelve el resultado al usuario

O:

1. Flash this firmware to the Nucleo
2. ZeroClaw escribe/flasha mediante OpenOCD o probe-rs
3. Confirma el éxito

O:

1. ZeroClaw descubre automáticamente: “STM32 Nucleo en /dev/ttyACM0, ARM Cortex-M4”
2. Sugerencias: “Puedo leer/escribir GPIO, ADC, flash. ¿Qué te gustaría hacer?”

Comparación de modos

3. Modos heredados / más simples (antes de LLM en el borde)

Para placas sin WiFi o antes de que Edge-Native esté completamente listo:

Modo A: Host + Periférico Remoto (STM32 a través de serie)

El host ejecuta ZeroClaw; el periférico ejecuta un firmware mínimo. JSON simple a través de serial.

Modo B: RPi como host (GPIO nativo)

ZeroClaw en Pi; GPIO mediante rppal o sysfs. Sin firmware separado.

4. Requisitos técnicos

Pipeline de RAG (Recuperación de Datasheets)

• Índice: Hojas de datos, manuales de referencia, mapas de registros ( .md / .txt preconvertidos → fragmentos, embeddings).
• Recuperar: En la consulta del usuario (“activar LED”), obtener fragmentos relevantes (por ejemplo, la sección de GPIO para la placa objetivo).
• Inyectar: Agregar al prompt o contexto del sistema de LLM.
• Resultado: El LLM genera código preciso y específico para la placa.

Opciones de ejecución dinámica

Recomendación: Comienza con plantillas precompiladas y parametrización; evoluciona a Wasm para la lógica definida por el usuario una vez que sea estable.

5. CLI y Configuración

Consulta la referencia de CLI para los subcomandos zeroclaw hardware / zeroclaw peripheral y la referencia de configuración para los campos [peripherals] y [[peripherals.boards]].

6. Arquitectura: Periférico como punto de extensión

Nuevo rasgo: Peripheral

#![allow(unused)]
fn main() {
/// Un periférico de hardware que expone capacidades como herramientas.
#[async_trait]
pub trait Peripheral: Send + Sync {
    fn name(&self) -> &str;
    fn board_type(&self) -> &str;  // por ejemplo, "nucleo-f401re", "rpi-gpio"
    async fn connect(&mut self) -> anyhow::Result<()>;
    async fn disconnect(&mut self) -> anyhow::Result<()>;
    async fn health_check(&self) -> bool;
    /// Herramientas que proporciona este periférico (gpio_read, gpio_write, sensor_read, etc.)
    fn tools(&self) -> Vec<Box<dyn Tool>>;
}
}

Flujo

1. Inicio: ZeroClaw carga la configuración y detecta peripherals.boards.
2. Conectar: Para cada placa, crea una implementación de Peripheral y llama a connect().
3. Herramientas: Recopilar herramientas de todos los periféricos conectados; fusionar con las herramientas predeterminadas.
4. Bucle del agente: El agente puede llamar a gpio_write, sensor_read, etc., que delegan en el periférico.
5. Apagado: Llama a disconnect() en cada periférico.

Soporte de placa

Las placas se identifican mediante el VID/PID de USB en el registro canónico:

Cada placa conectada se controla a través de uno de los transportes del subsistema:

Las herramientas básicas que expone cada placa se enumeran en Subsistema de hardware → Herramientas de tiempo de ejecución.

7. Protocolos de comunicación

gRPC / nanoRPC (Nativo para el borde, Mediado por el host)

Para RPC tipado y de baja latencia entre ZeroClaw y periféricos:

• nanoRPC o tonic (gRPC): Servicios definidos mediante Protobuf.
• Métodos: GpioWrite, GpioRead, I2cTransfer, SpiTransfer, MemoryRead, FlashWrite, etc.
• Habilita las llamadas bidireccionales en streaming y la generación de código a partir de archivos .proto.

Transporte Serial (Mediado por Host, heredado)

JSON simple sobre serie para placas sin soporte de gRPC:

Solicitud (host → periférico):

{"id":"1","cmd":`gpio_write`,"args":{"pin":13,"valor":1}}

Respuesta (periférico → host):

{"id":"1","ok":true,"resultado":"hecho"}

8. Firmware (Repositorio o Crate separado)

• zeroclaw-firmware o zeroclaw-peripheral: un crate/workspace separado.
• Objetivos: thumbv7em-none-eabihf (STM32), armv7-unknown-linux-gnueabihf (RPi), etc.
• Utiliza embassy o Zephyr para STM32.
• Implementa el protocolo anterior.
• El usuario flashea esto en la placa; ZeroClaw se conecta y descubre las capacidades.

9. Capas de capacidades

El subsistema está construido en capas; cada una es utilizable de forma independiente. En lugar de hacer seguimiento del estado de las fases aquí (que se desactualiza a medida que se integra el trabajo), las capas son:

• Esqueleto. El trait Peripheral, el esquema de configuración y la CLI zeroclaw peripheral. El flag --peripheral conecta una placa al agente.

• Descubrimiento mediado por el host. zeroclaw hardware discover enumera los dispositivos USB por VID/PID; el registro de placas los asigna a la arquitectura y el nombre; zeroclaw hardware introspect <path> informa el mapa de memoria y la lista de periféricos.

• Transporte serial / de sonda. SerialPeripheral transporta el protocolo JSON sobre USB CDC; la característica probe añade SWD de probe-rs para flash, mapa de memoria y lectura de memoria (consulte las herramientas hardware_*).

• Pipeline de RAG. Las hojas de datos se indexan y se inyectan en el contexto del LLM en las consultas de hardware.

  Uso: zeroclaw config set peripherals.datasheet-dir docs/datasheets. Coloca archivos .md o .txt nombrados según la placa (por ejemplo, nucleo-f401re.md, rpi-gpio.md). Los archivos en _generic/ o nombrados generic.md se aplican a todas las placas. Los fragmentos se recuperan mediante coincidencia de palabras clave y se inyectan en el contexto del mensaje del usuario.

• Nativo en el edge (Raspberry Pi). ZeroClaw se ejecuta en la Pi con GPIO nativo mediante rppal (la característica peripheral-rpi).

• ESP32. Mediado por el host a través del transporte serie, mismo protocolo JSON que STM32. Las placas de desarrollo ESP32 están en el registro por su VID/PID USB del CH340.

  Uso: Flashee firmware/esp32 en el ESP32, agregue board = "esp32", transport = "serial", path = "/dev/ttyUSB0" a la configuración.

• Ejecución dinámica. La lógica generada por LLM se ejecuta a través de plantillas parametrizadas, con un entorno de ejecución Wasm en sandbox como la dirección a largo plazo para la lógica definida por el usuario.

10. Consideraciones de seguridad

• Ruta serial: Valida que path esté en la lista permitida (por ejemplo, /dev/ttyACM*, /dev/ttyUSB*); nunca rutas arbitrarias.
• GPIO: Restringir los pines que se exponen; evitar los pines de alimentación y de reinicio.
• Sin secretos en el periférico: El firmware no debe almacenar claves API; el host gestiona la autenticación.

11. Objetivos no contemplados (por ahora)

• Ejecutando ZeroClaw completo en STM32 bare-metal (sin WiFi, RAM limitada), usa Host-Mediated en su lugar
• Garantías de tiempo real: los periféricos son de mejor esfuerzo (best-effort)
• Ejecución arbitraria de código nativo desde el LLM: prefiera Wasm o plantillas

12. Documentos relacionados

• adding-boards-and-tools.md: Cómo añadir placas y hojas de datos
• network-deployment.md: Implementación de RPi y de red

13. Referencias

• Soporte de Rust para Zephyr RTOS
• Embassy: framework embebido asíncrono
• rppal: GPIO de Raspberry Pi en Rust
• STM32 Nucleo-F401RE
• tonic: gRPC para Rust
• probe-rs: sonda de depuración ARM, flash, acceso a memoria
• nusb: enumeración de dispositivos USB (VID/PID)

14. Resumen del Prompt en crudo

“Placas como ESP, Raspberry Pi o placas con WiFi pueden conectarse a un LLM (Gemini o de código abierto). ZeroClaw se ejecuta en el dispositivo, crea su propio gRPC, lo pone en marcha y se comunica con los periféricos. El usuario solicita por WhatsApp: ‘mueve el brazo X’ o ‘enciende el LED’. ZeroClaw obtiene documentación precisa, escribe código, lo ejecuta, lo almacena de forma óptima, lo ejecuta y enciende el LED, todo en la placa de desarrollo.

Para STM Nucleo conectado mediante USB/J-Link a mi Mac: ZeroClaw desde mi Mac accede al hardware, instala o escribe lo que quiera en el dispositivo y devuelve el resultado. Ejemplo: ‘Oye ZeroClaw, ¿cuáles son las direcciones disponibles/legibles en este dispositivo USB?’. Puede averiguar qué está conectado y dónde, y sugerir.