ZeroClaw on Arduino Uno Q — Step-by-Step Guide

Run ZeroClaw on the Arduino Uno Q's Linux side. Telegram works over WiFi; GPIO control uses the Bridge (requires a minimal App Lab app).

What's Included (No Code Changes Needed)

ZeroClaw includes everything needed for Arduino Uno Q. Clone the repo and follow this guide — no patches or custom code required.

Build with --features hardware to include Uno Q support.

Prerequisites

• Arduino Uno Q with WiFi configured
• Arduino App Lab installed on your Mac (for initial setup and deployment)
• API key for LLM (OpenRouter, etc.)

Phase 1: Initial Uno Q Setup (One-Time)

1.1 Configure Uno Q via App Lab

1. Download Arduino App Lab (tar.gz on Linux).
2. Connect Uno Q via USB, power it on.
3. Open App Lab, connect to the board.
4. Follow the setup wizard:
   • Set username and password (for SSH)
   • Configure WiFi (SSID, password)
   • Apply any firmware updates
5. Note the IP address shown (e.g. [email protected]) or find it later via ip addr show in App Lab's terminal.

1.2 Verify SSH Access

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

Phase 2: Install ZeroClaw on Uno Q

Option A: Build on the Device (Simpler, ~20–40 min)

# SSH into 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

# Install build deps (Debian)
sudo apt-get update
sudo apt-get install -y pkg-config libssl-dev

# Clone zeroclaw (or scp your project)
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

# Build (takes ~15–30 min on Uno Q)
cargo build --release --features hardware

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

Option B: Cross-Compile on Mac (Faster)

# On your Mac — add aarch64 target
rustup target add aarch64-unknown-linux-gnu

# Install cross-compiler (macOS; required for linking)
brew tap messense/macos-cross-toolchains
brew install aarch64-unknown-linux-gnu

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

# Copy to 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/"

If cross-compile fails, use Option A and build on the device.

Phase 3: Configure ZeroClaw

3.1 Run Onboard (or Create Config Manually)

ssh arduino@<UNO_Q_IP>

# Quick config
zeroclaw onboard --api-key YOUR_OPENROUTER_KEY --provider openrouter

# Or create config manually
mkdir -p ~/.zeroclaw/workspace
nano ~/.zeroclaw/config.toml

3.2 Minimal config

At minimum, set api_key / default_provider / default_model, plus [channels.telegram] with your bot_token. Leave [peripherals] disabled until Phase 4 below. See the Config reference for all fields.

Phase 4: Run ZeroClaw Daemon

ssh arduino@<UNO_Q_IP>

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

At this point: Telegram chat works. Send messages to your bot — ZeroClaw responds. No GPIO yet.

Phase 5: GPIO via Bridge (ZeroClaw Handles It)

ZeroClaw includes the Bridge app and setup command.

5.1 Deploy Bridge App

From your Mac (with zeroclaw repo):

zeroclaw peripheral setup-uno-q --host 192.168.0.48

From the Uno Q (SSH'd in):

zeroclaw peripheral setup-uno-q

This copies the Bridge app to ~/ArduinoApps/uno-q-bridge and starts it.

5.2 Add to config

Enable [peripherals] and add a [[peripherals.boards]] entry with board = "arduino-uno-q" and transport = "bridge".

5.3 Run ZeroClaw

zeroclaw daemon --host 127.0.0.1 --port 42617

Now when you message your Telegram bot "Turn on the LED" or "Set pin 13 high", ZeroClaw uses gpio_write via the Bridge.

Summary: Commands Start to End

Troubleshooting

• "command not found: zeroclaw" — Use full path: /usr/local/bin/zeroclaw or ensure ~/.cargo/bin is in PATH.
• Telegram not responding — Check bot_token, allowed_users, and that the Uno Q has internet (WiFi).
• Out of memory — Keep features minimal (--features hardware for Uno Q); consider compact_context = true.
• GPIO commands ignored — Ensure Bridge app is running (zeroclaw peripheral setup-uno-q deploys and starts it). Config must have board = "arduino-uno-q" and transport = "bridge".
• LLM provider (GLM/Zhipu) — Use default_provider = "glm" or "zhipu" with GLM_API_KEY in env or config. ZeroClaw uses the correct v4 endpoint.