nullclaw hardware

Scan, flash, and manage hardware peripherals

The nullclaw hardware command provides utilities for discovering and managing hardware peripherals like Arduino boards, STM32/Nucleo devices, and Raspberry Pi.

Subcommands

nullclaw hardware scan              # Scan for connected devices
nullclaw hardware flash <device>    # Flash firmware to device
nullclaw hardware monitor <device>  # Monitor serial output

Supported Hardware

NullClaw supports:

Hardware	Interface	Flash Tool	Features
Arduino Uno/Mega	Serial (USB)	avrdude	GPIO, serial, I2C, SPI
STM32 Nucleo	USB (ST-Link)	probe-rs	GPIO, ADC, PWM, timers
Raspberry Pi	GPIO sysfs	-	GPIO read/write
ESP32	Serial (CH340)	esptool	WiFi, Bluetooth, GPIO

hardware scan

Scan for connected hardware devices:

nullclaw hardware scan

Example Output

Scanning for hardware devices...

✓ Arduino Uno (ATmega328P)
  VID:PID: 2341:0043
  Port: /dev/ttyACM0
  Architecture: AVR ATmega328P

✓ STM32 Nucleo F401RE
  VID:PID: 0483:374b
  Port: /dev/ttyACM1
  Architecture: ARM Cortex-M4
  Flash tool: probe-rs

✓ ESP32 DevKit
  VID:PID: 1a86:7523
  Port: /dev/ttyUSB0
  Architecture: ESP32 (CH340)

✓ Raspberry Pi GPIO
  Interface: sysfs
  Available pins: 27

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Found 4 devices

hardware flash

Flash firmware to a device:

# Flash Arduino
nullclaw hardware flash arduino-uno --file sketch.hex

# Flash STM32 with probe-rs
nullclaw hardware flash nucleo-f401re --file firmware.elf

# Flash ESP32
nullclaw hardware flash esp32 --file firmware.bin

Options

--file · string · required

Firmware file to flash (.hex, .elf, .bin)

--port · string

Serial port (default: auto-detect)

--baud · number

Baud rate for serial flashing (default: 115200)

Flash Process

1. Detect device

   Auto-detect device by VID:PID or use --port to specify

2. Select flash tool

   • Arduino: avrdude
   • STM32/Nucleo: probe-rs
   • ESP32: esptool.py
3. Flash firmware

   Execute flash command with appropriate tool

4. Verify

   Read back and verify flash contents

hardware monitor

Monitor serial output from a device:

nullclaw hardware monitor arduino-uno

This opens a serial monitor showing real-time output from the device.

Example

$ nullclaw hardware monitor arduino-uno
Connected to /dev/ttyACM0 at 115200 baud
Press Ctrl+C to exit

Arduino initialization...
Sensor reading: 23.5°C
Sensor reading: 23.7°C
Sensor reading: 23.6°C
^C
Disconnected

Known Devices Registry

NullClaw maintains a registry of known USB VID/PID mappings:

// From src/hardware.zig
const known_boards: []const BoardInfo = &.{
    .{ .vid = 0x2341, .pid = 0x0043, .name = "arduino-uno", .architecture = "AVR ATmega328P" },
    .{ .vid = 0x2341, .pid = 0x0042, .name = "arduino-mega", .architecture = "AVR ATmega2560" },
    .{ .vid = 0x0483, .pid = 0x374b, .name = "nucleo-f401re", .architecture = "ARM Cortex-M4" },
    .{ .vid = 0x0483, .pid = 0x3748, .name = "nucleo-f411re", .architecture = "ARM Cortex-M4" },
    .{ .vid = 0x1a86, .pid = 0x7523, .name = "esp32", .architecture = "ESP32 (CH340)" },
    .{ .vid = 0x10c4, .pid = 0xea60, .name = "cp2102", .architecture = "USB-UART bridge" },
};

Prerequisites

Arduino

# macOS
brew install avrdude

# Linux
sudo apt install avrdude

STM32/Nucleo

# Install probe-rs
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/probe-rs/probe-rs/releases/latest/download/probe-rs-installer.sh | sh

ESP32

# Install esptool
pip install esptool

Agent Integration

Hardware peripherals are accessible via tools:

nullclaw agent -m "Read GPIO pin 17 on Raspberry Pi"

The agent uses the hardware_info and hardware_memory tools to interact with devices.

See Hardware Guide for detailed integration examples.

Examples

Scan for devices

nullclaw hardware scan

Flash Arduino

# Compile sketch (using Arduino IDE or cli)
arduino-cli compile --fqbn arduino:avr:uno sketch/

# Flash
nullclaw hardware flash arduino-uno --file sketch/build/sketch.hex

Flash STM32

# Build firmware
zig build -Dtarget=thumbv7em-freestanding-eabihf

# Flash
nullclaw hardware flash nucleo-f401re --file zig-out/firmware.elf

Monitor serial output

nullclaw hardware monitor arduino-uno

Troubleshooting

Device not detected

Error: No devices found

Fix:

1. Check USB connection
2. Verify device appears in system:
   # macOS/Linux
   ls /dev/tty*
   
   # Linux: Check USB devices
   lsusb
   
3. Add user to dialout group (Linux):
   sudo usermod -a -G dialout $USER
   

Permission denied

Error: Permission denied: /dev/ttyACM0

Fix (Linux):

sudo chmod 666 /dev/ttyACM0
# Or add to dialout group (permanent)
sudo usermod -a -G dialout $USER

Flash tool not found

Error: probe-rs not found in PATH

Fix: Install required flash tool (see Prerequisites above)

Wrong baud rate

Error: Serial communication failed

Fix: Specify correct baud rate:

nullclaw hardware monitor arduino-uno --baud 9600

See Also

• Hardware Guide - Detailed integration guide
• Peripherals Configuration - Configure hardware access
• Tools - Hardware interaction tools