> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nullclaw/nullclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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

<ParamField path="--file" type="string" required>
  Firmware file to flash (.hex, .elf, .bin)
</ParamField>

<ParamField path="--port" type="string">
  Serial port (default: auto-detect)
</ParamField>

<ParamField path="--baud" type="number">
  Baud rate for serial flashing (default: 115200)
</ParamField>

### Flash Process

<Steps>
  <Step title="Detect device">
    Auto-detect device by VID:PID or use `--port` to specify
  </Step>

  <Step title="Select flash tool">
    * Arduino: `avrdude`
    * STM32/Nucleo: `probe-rs`
    * ESP32: `esptool.py`
  </Step>

  <Step title="Flash firmware">
    Execute flash command with appropriate tool
  </Step>

  <Step title="Verify">
    Read back and verify flash contents
  </Step>
</Steps>

## hardware monitor

Monitor serial output from a device:

```bash theme={null}
nullclaw hardware monitor arduino-uno
```

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

### Example

```bash theme={null}
$ 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:

```zig theme={null}
// 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

```bash theme={null}
# macOS
brew install avrdude

# Linux
sudo apt install avrdude
```

### STM32/Nucleo

```bash theme={null}
# 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

```bash theme={null}
# Install esptool
pip install esptool
```

## Agent Integration

Hardware peripherals are accessible via tools:

```bash theme={null}
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](/guides/hardware) for detailed integration examples.

## Examples

### Scan for devices

```bash theme={null}
nullclaw hardware scan
```

### Flash Arduino

```bash theme={null}
# 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

```bash theme={null}
# Build firmware
zig build -Dtarget=thumbv7em-freestanding-eabihf

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

### Monitor serial output

```bash theme={null}
nullclaw hardware monitor arduino-uno
```

## Troubleshooting

### Device not detected

```
Error: No devices found
```

**Fix**:

1. Check USB connection
2. Verify device appears in system:
   ```bash theme={null}
   # macOS/Linux
   ls /dev/tty*

   # Linux: Check USB devices
   lsusb
   ```
3. Add user to dialout group (Linux):
   ```bash theme={null}
   sudo usermod -a -G dialout $USER
   ```

### Permission denied

```
Error: Permission denied: /dev/ttyACM0
```

**Fix** (Linux):

```bash theme={null}
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:

```bash theme={null}
nullclaw hardware monitor arduino-uno --baud 9600
```

## See Also

* [Hardware Guide](/guides/hardware) - Detailed integration guide
* [Peripherals Configuration](/configuration/security) - Configure hardware access
* [Tools](/tools/overview) - Hardware interaction tools