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.

Component	Location	Purpose
Bridge app	`firmware/uno-q-bridge/`	MCU sketch + Python socket server (port 9999) for GPIO
Bridge tools	`crates/zeroclaw-hardware/src/peripherals/uno_q_bridge.rs`	`gpio_read` / `gpio_write` tools that talk to the Bridge over TCP
Setup command	`crates/zeroclaw-hardware/src/peripherals/uno_q_setup.rs`	`zeroclaw peripheral setup-uno-q` deploys the Bridge via scp + arduino-app-cli
Config schema	`board = "arduino-uno-q"`, `transport = "bridge"`	Configurable via the gateway, zerocode, or `zeroclaw config set`

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

Prerequisites

Arduino Uno Q with WiFi configured
Arduino App Lab installed on your computer (for initial board setup)
arduino-app-cli available on the Uno Q (pre-installed with the board’s Debian image, used for Bridge deployment)
API key for LLM (OpenRouter, etc.)

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

1.1 Configure Uno Q via App Lab

Download Arduino App Lab (tar.gz on Linux).
Connect Uno Q via USB, power it on.
Open App Lab, connect to the board.
Follow the setup wizard:
- Set username and password (for SSH)
- Configure WiFi (SSID, password)
- Apply any firmware updates
Note the IP address shown (e.g. arduino@192.168.1.42) or find it later via ip addr show in App Lab’s terminal.

1.2 Verify SSH Access

sh

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

Phase 2: Install ZeroClaw on Uno Q

Option A: Build on the Device (Simpler)

sh

# 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 (on-device build is slow; cross-compile from a larger machine if build time matters)
export CARGO_BUILD_JOBS=1 # build will be OOM-killed mid-link without this
cargo build --release --features hardware

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

Option B: Cross-Compile on Mac (Faster)

sh

# 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 Quickstart (or Create Config Manually)

sh

ssh arduino@<UNO_Q_IP>

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

At minimum, configure one [providers.models.<type>.<alias>] entry with api_key / model, one [agents.<alias>] that references it via model_provider = "<type>.<alias>", and one [channels.telegram.<alias>] with your bot_token. Bind the channel to the agent via channels = ["telegram.<alias>"] on the agent. Leave [peripherals] disabled until Phase 4 below. See the Config reference for all fields.

Phase 4: Run ZeroClaw Daemon

sh

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 computer (with zeroclaw repo):

sh

zeroclaw peripheral setup-uno-q --host 192.168.0.48

From the Uno Q (SSH’d in):

sh

zeroclaw peripheral setup-uno-q

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

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

Step	Command
1	Configure Uno Q in App Lab (WiFi, SSH)
2	`ssh arduino@<IP>`
3	`curl -sSf https://sh.rustup.rs \| sh -s -- -y && source ~/.cargo/env`
4	`sudo apt-get install -y pkg-config libssl-dev`
5	`git clone https://github.com/zeroclaw-labs/zeroclaw.git && cd zeroclaw`
6	`export CARGO_BUILD_JOBS=1 && cargo build --release --features hardware`
7	`zeroclaw quickstart --api-key KEY --model-provider openrouter`
8	`zeroclaw config set channels.telegram.default.bot-token <token>`
9	`zeroclaw daemon --host 127.0.0.1 --port 42617`
10	Message your Telegram bot: it responds
11	`zeroclaw peripheral setup-uno-q` (deploys Bridge)
12	Add a `peripherals` board with `board = "arduino-uno-q"` via the gateway, zerocode, or `zeroclaw config set`
13	Restart daemon (`zeroclaw daemon …`), GPIO commands now work

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): Configure [providers.models.glm.<alias>] with GLM_API_KEY in env or config (the legacy zhipu synonym is collapsed onto glm). ZeroClaw uses the correct v4 endpoint.

ZeroClaw Docs