Arduino Setup

Flash and configure Arduino boards with ZeroClaw

Arduino Setup

Arduino boards are widely used microcontrollers perfect for education and hobby projects. ZeroClaw supports Arduino via USB serial with JSON protocol communication.

Supported Boards

Board	MCU	Flash	RAM	WiFi	Status
Arduino Uno	ATmega328P	32KB	2KB	No	✅ Stable
Arduino Uno R4 WiFi	RA4M1 + ESP32-S3	256KB	32KB	Yes	✅ Stable (Bridge)

Arduino Uno (Classic)

Hardware Features

• MCU: AVR ATmega328P, 16 MHz
• GPIO: 14 digital pins (6 PWM), 6 analog inputs
• Serial: USB (CH340 or ATmega16U2 USB-to-serial)
• LED: Pin 13 (built-in LED)
• Firmware: firmware/zeroclaw-arduino/zeroclaw-arduino.ino

Quick Start

1. Flash Firmware

Via ZeroClaw (Recommended)

# Auto-flash via avrdude
zeroclaw peripheral flash --port /dev/ttyUSB0

# macOS
zeroclaw peripheral flash --port /dev/cu.usbserial-14320

# Windows
zeroclaw peripheral flash --port COM3

This command:

1. Compiles the Arduino sketch
2. Uploads via avrdude
3. Verifies the upload

Via Arduino IDE

1. Open Arduino IDE
2. File → Open → firmware/zeroclaw-arduino/zeroclaw-arduino.ino
3. Tools → Board → Arduino Uno
4. Tools → Port → /dev/ttyUSB0 (or your port)
5. Click Upload button

2. Find Serial Port

# Linux
ls /dev/ttyUSB*
# Should show: /dev/ttyUSB0

# macOS
ls /dev/cu.usbserial* /dev/cu.usbmodem*
# CH340: /dev/cu.usbserial-14320
# Native: /dev/cu.usbmodem14201

# Windows
mode
# Should show: COM3, COM4, etc.

3. Add to Configuration

# Auto-configure
zeroclaw peripheral add arduino-uno /dev/ttyUSB0

# Or manually edit ~/.zeroclaw/config.toml

[peripherals]
enabled = true

[[peripherals.boards]]
board = "arduino-uno"
transport = "serial"
path = "/dev/ttyUSB0"  # Adjust for your system
baud = 115200

4. Test Connection

# Test built-in LED (pin 13)
zeroclaw agent -m "Turn on the LED on Arduino"

# Should light up the built-in LED (orange LED labeled 'L')

Pin Mapping

Digital Pins:
0  = RX (Serial, avoid using)
1  = TX (Serial, avoid using)
2-12 = General GPIO
13 = Built-in LED + GPIO

PWM Pins (~ marked on board):
3, 5, 6, 9, 10, 11

Analog Pins:
A0-A5 (can also be used as digital GPIO)

Wiring Examples

External LED

Arduino         LED
───────         ───
Pin 9 ────────┬──▶│
                │    └─── GND
                └─── 220Ω

zeroclaw agent -m "Set pin 9 high on Arduino"

Button Input

Arduino         Button
───────         ──────
Pin 7 ─────────┤  ├──── 5V
GND ───────────┤  ├
                └──┘

zeroclaw agent -m "Read pin 7 on Arduino"

Arduino Uno R4 WiFi (Uno Q)

The Uno R4 WiFi has a unique architecture:

• Main MCU: Renesas RA4M1 (ARM Cortex-M4, 48 MHz)
• WiFi: ESP32-S3 co-processor
• Transport: Bridge mode (WebSocket to Arduino Cloud)

Setup

# Configure Uno Q bridge
zeroclaw peripheral setup-uno-q --host robot.local

# Add to config
zeroclaw peripheral add arduino-uno-q bridge

Uno R4 WiFi uses a bridge transport that connects to the Arduino Cloud IoT platform. This is different from direct serial communication.

Serial Protocol

The firmware implements a JSON-over-UART protocol:

Request Format

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

Response Format

{"id":"1","ok":true,"result":"done"}

Supported Commands

Command	Args	Description
ping	None	Health check, returns “pong”
gpio_read	{"pin": N}	Read digital pin (0 or 1)
gpio_write	{"pin": N, "value": V}	Write digital pin (0=LOW, 1=HIGH)
capabilities	None	Get available GPIO pins and LED pin

Testing Manually

# Open serial monitor
screen /dev/ttyUSB0 115200

# Type commands and press Enter:
{"id":"1","cmd":"ping","args":{}}
{"id":"2","cmd":"gpio_write","args":{"pin":13,"value":1}}
{"id":"3","cmd":"gpio_read","args":{"pin":13}}
{"id":"4","cmd":"capabilities","args":{}}

# Exit: Ctrl+A, then K, then Y

Firmware Source

The Arduino firmware is written in C++ (Arduino sketch format):

Location: firmware/zeroclaw-arduino/zeroclaw-arduino.ino

Key features:

• Newline-delimited JSON parsing (no libraries)
• Pin 0-13 support (digital I/O)
• Built-in LED (pin 13) support
• Dynamic capabilities discovery
• ~2KB compiled size

Tools Provided

When an Arduino is connected, ZeroClaw exposes:

Tool	Description
gpio_read	Read digital pin value
gpio_write	Set digital pin high or low
hardware_capabilities	Query available GPIO pins
arduino_upload	Upload new sketches to Arduino

Advanced: Custom Firmware

To add custom features:

1. Edit firmware/zeroclaw-arduino/zeroclaw-arduino.ino
2. Add new command handlers in handleLine()
3. Upload via Arduino IDE or ZeroClaw

Example: Add analog read

if (hasCmd(line, "analog_read")) {
  int pin = parseArg("pin", line);
  if (pin < 0 || pin > 5) {
    Serial.println("{\"id\":\"1\",\"ok\":false,\"error\":\"Invalid analog pin\"}");
    return;
  }
  int value = analogRead(A0 + pin);
  Serial.print("{\"id\":\"");
  Serial.print(idBuf);
  Serial.print("\",\"ok\":true,\"result\":\"");
  Serial.print(value);
  Serial.println("\"}");
  return;
}

Troubleshooting

Serial port not found

# Check USB connection
# Linux
lsusb | grep -i "CH340\|arduino"

# macOS
system_profiler SPUSBDataType | grep -i "arduino\|ch340"

# Windows
# Device Manager > Ports (COM & LPT)

Permission denied (Linux)

# Add user to dialout group
sudo usermod -aG dialout $USER

# Logout and login, or:
newgrp dialout

Upload fails

# Check port is correct
ls /dev/ttyUSB*

# Try manual reset
# Press reset button on Arduino, then immediately:
zeroclaw peripheral flash --port /dev/ttyUSB0

# Check avrdude is installed
avrdude -v

# Ubuntu/Debian
sudo apt install avrdude

# macOS
brew install avrdude

No response from firmware

# Reset Arduino
# Press reset button (small button near USB port)

# Check baud rate
# Must be 115200 (set in firmware setup())

# Test with Arduino IDE Serial Monitor
# Tools > Serial Monitor
# Set to 115200 baud
# Type: {"id":"1","cmd":"ping","args":{}}

CH340 driver issues (macOS)

# Download CH340 driver
# https://github.com/adrianmihalko/ch340g-ch34g-ch34x-mac-os-x-driver

# Or use Homebrew
brew tap mengbo/ch340g-ch34g-ch34x-mac-os-x-driver
brew install ch340g-ch34g-ch34x-mac-os-x-driver

# Reboot after installation

Wrong board type

# If using Arduino Nano, Mega, etc.
# Edit firmware/zeroclaw-arduino/zeroclaw-arduino.ino
# Adjust pin definitions for your board

# Or flash appropriate firmware for your board

Arduino Shields & Add-ons

Popular shields that work with ZeroClaw:

Shield	Use Case	Notes
Motor Shield (L293D)	Robot drive	Use PWM pins 9, 10, 11
Ethernet Shield	Network control	Alternative to WiFi
LCD Shield	Display output	I2C or parallel
Sensor Shield	Easy wiring	No soldering needed

Performance Notes

• GPIO speed: ~100 kHz toggle rate
• Serial latency: ~20ms round-trip
• Flash size: 32KB (firmware uses ~2KB)
• RAM: 2KB (firmware uses ~500 bytes)
• Boot time: ~2 seconds after reset

Next Steps

Supported Boards

Compare all hardware platforms

STM32 Nucleo

More powerful ARM-based alternative

ESP32 Setup

Arduino-like board with WiFi

Hardware Architecture

Understand the peripheral system

Reference

• Arduino Uno Product Page
• Arduino Language Reference
• ATmega328P Datasheet
• Arduino Uno R4 WiFi