ZeroClaw en Arduino Uno Q: Guía paso a paso

Ejecuta ZeroClaw en la parte de Linux del Arduino Uno Q. Telegram funciona a través de WiFi; el control de GPIO utiliza el puente (requiere una aplicación mínima de App Lab).

Qué incluye (sin necesidad de cambios en el código)

ZeroClaw incluye todo lo necesario para Arduino Uno Q. Clona el repositorio y sigue esta guía, no se requieren parches ni código personalizado.

Compila con --features hardware para incluir la compatibilidad con Uno Q.

Requisitos previos

• Arduino Uno Q con WiFi configurado
• Arduino App Lab instalado en tu computadora (para la configuración inicial de la placa)
• arduino-app-cli disponible en la Uno Q (preinstalado con la imagen de Debian de la placa, usado para el despliegue de Bridge)
• Clave API para LLM (OpenRouter, etc.)

Fase 1: Configuración inicial de Uno Q (única)

1.1 Configurar Uno Q a través de App Lab

1. Descarga Arduino App Lab (tar.gz en Linux).
2. Conecta el Uno Q mediante USB y enciéndelo.
3. Abre App Lab y conéctate a la placa.
4. Sigue el asistente de configuración:
   • Establecer nombre de usuario y contraseña (para SSH)
   • Configurar WiFi (SSID, contraseña)
   • Aplicar cualquier actualización de firmware
5. Tenga en cuenta la dirección IP mostrada (por ejemplo, arduino@192.168.1.42) o búsquela más tarde mediante ip addr show en la terminal de App Lab.

1.2 Verificar el acceso SSH

ssh arduino@<UNO_Q_IP>
# Enter the password you set

Fase 2: Instalar ZeroClaw en Uno Q

Opción A: Compilar en el dispositivo (más sencillo)

# SSH en Uno Q
ssh arduino@<UNO_Q_IP>

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source ~/.cargo/env

# Instalar dependencias de compilación (Debian)
sudo apt-get update
sudo apt-get install -y pkg-config libssl-dev

# Clona zeroclaw (o copia tu proyecto con scp)
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

# Compilación (la compilación en el dispositivo es lenta; haz compilación cruzada desde una máquina más potente si el tiempo de compilación es importante)
export CARGO_BUILD_JOBS=1 # build will be OOM-killed mid-link without this
cargo build --release --features hardware

# Instalar
sudo cp target/release/zeroclaw /usr/local/bin/

Opción B: Compilación cruzada en Mac (más rápido)

# En tu Mac — agrega el objetivo aarch64
rustup target add aarch64-unknown-linux-gnu

# Instalar el compilador cruzado (macOS; necesario para el enlazado)
brew tap messense/macos-cross-toolchains
brew install aarch64-unknown-linux-gnu

# Construir
CC_aarch64_unknown_linux_gnu=aarch64-unknown-linux-gnu-gcc cargo build --release --target aarch64-unknown-linux-gnu --features hardware

# Copiar a Uno Q
scp target/aarch64-unknown-linux-gnu/release/zeroclaw arduino@<UNO_Q_IP>:~/
ssh arduino@<UNO_Q_IP> `sudo mv ~/zeroclaw /usr/local/bin/`

Si la compilación cruzada falla, utiliza la Opción A y compila en el dispositivo.

Fase 3: Configurar ZeroClaw

3.1 Ejecutar Quickstart (o crear la configuración manualmente)

ssh arduino@<UNO_Q_IP>

# Quick config
zeroclaw quickstart --api-key YOUR_OPENROUTER_KEY --model-provider openrouter

3.2 Configuración mínima

Como mínimo, configura una entrada [providers.models.<type>.<alias>] con api_key / model, una [agents.<alias>] que la referencie mediante model_provider = "<type>.<alias>", y una [channels.telegram.<alias>] con tu bot_token. Vincula el canal al agente mediante channels = ["telegram.<alias>"] en el agente. Deja [peripherals] deshabilitado hasta la Fase 4 a continuación. Consulta la referencia de configuración para ver todos los campos.

Fase 4: Ejecutar el demonio ZeroClaw

ssh arduino@<UNO_Q_IP>

# Run daemon (Telegram polling works over WiFi)
zeroclaw daemon --host 127.0.0.1 --port 42617

En este punto: El chat de Telegram funciona. Envía mensajes a tu bot, ZeroClaw responde. Aún sin GPIO.

Fase 5: GPIO a través del puente (ZeroClaw se encarga de ello)

ZeroClaw incluye la aplicación Bridge y el comando de configuración.

5.1 Desplegar la aplicación Bridge

Desde tu computadora (con el repositorio zeroclaw):

zeroclaw peripheral setup-uno-q --host 192.168.0.48

Desde Uno Q (conectado por SSH):

zeroclaw peripheral setup-uno-q

Esto copia la aplicación Bridge a ~/ArduinoApps/uno-q-bridge y la inicia.

5.2 Agregar a la configuración

Habilita [peripherals] y añade una entrada [[peripherals.boards]] con board = "arduino-uno-q" y transport = "bridge".

5.3 Ejecutar ZeroClaw

zeroclaw daemon --host 127.0.0.1 --port 42617

Ahora, cuando le envías un mensaje a tu bot de Telegram con “Encender el LED” o “Establecer el pin 13 en alto”, ZeroClaw utiliza gpio_write a través del Bridge.

Resumen: Comandos de inicio a fin

Solución de problemas

• “command not found: zeroclaw”: Use la ruta completa: /usr/local/bin/zeroclaw o asegúrese de que ~/.cargo/bin esté en PATH.
• Telegram no responde: Verifica bot_token, allowed_users y que el Uno Q tenga internet (WiFi).
• Sin memoria: Mantén las funcionalidades al mínimo (--features hardware para Uno Q); considera usar compact_context = true.
• Comandos GPIO ignorados: Asegúrese de que la aplicación Bridge esté en ejecución (zeroclaw peripheral setup-uno-q la despliega e inicia). La configuración debe tener board = "arduino-uno-q" y transport = "bridge".
• Proveedor LLM (GLM/Zhipu): Configura [providers.models.glm.<alias>] con GLM_API_KEY en el entorno o la configuración (el sinónimo heredado zhipu se consolida en glm). ZeroClaw usa el endpoint v4 correcto.