nff 0.2.14

Claude Code IoT Bridge — connect Claude to hardware via USB

nff — Your bench hardware as a CI target

Firmware iteration is slow because the hardware loop is manual. nff connects your existing bench hardware to Claude Code — push code, it compiles, flashes, and returns serial output automatically. No new hardware. No cloud boards. Your device, automated.

you: "Run the sensor init sequence and assert the calibration values over serial"
Claude: [writes test] → [compiles] → [flashes ESP32] → [reads serial] → returns structured output

Supported boards: ESP32 (CP210x / CH340) · ESP8266 (FTDI) · Arduino AVR (Uno, Mega, Nano, Leonardo)
STM32 and RP2040 support in progress — open a PR, adding a board is two lines of code.

---

Why this exists

Every firmware iteration means manually compiling, flashing, and reading serial by hand. On a real bench. One cycle takes minutes. Multiply that by a day of debugging and you've lost hours to logistics. nff closes that loop — your board becomes a CI target.

It doesn't replace your toolchain — it automates the logistics around it. arduino-cli handles compilation, esptool handles flashing, your board stays on your bench. nff just closes the loop.

---

MCP Tools (what Claude can call)

Once registered, Claude Code has access to these tools:

Tool	What it does
list_devices()	List all connected USB boards
flash(code, board?, port?)	Write, compile, and upload a sketch
serial_read(duration_ms?, port?, baud?)	Capture serial output for N ms
serial_write(data, port?, baud?)	Send a string to the device
reset_device(port?)	Toggle DTR to hardware-reset the board
get_device_info(port?)	Return port, board name, FQBN, baud rate

All tools fall back to the default device in ~/.nff/config.json when port and board are omitted.

Simulation via Wokwi also supported — useful for CI without a bench. See Wokwi simulation below.

---

Demo

Real Hardware

Wokwi Simulation

Quickstart

If you've ever lost a morning to manual flash-debug cycles, nff is for you. It doesn't add steps to your workflow — it removes them.

1. Install

pip install nff

esptool is bundled — no separate install needed.

2. Install external tools

# Board cores (install the ones you need)
arduino-cli core install esp32:esp32
arduino-cli core install arduino:avr
arduino-cli core install esp8266:esp8266

arduino-cli is auto-installed by nff init if it is not already on your PATH. You can also install it manually from https://arduino.github.io/arduino-cli.

3. Plug in your board and run init

nff init

This single command does everything:

• Detects your board by USB vendor/product ID
• Writes ~/.nff/config.json and a CLAUDE.md in the current directory
• Registers the nff MCP server (claude mcp add nff nff mcp)
• Installs the /nff and /wokwi-diagram Claude Code skills globally

  ✓ Found: ESP32 (CP210x) on COM10
  ✓ Config written to ~/.nff/config.json
  ✓ CLAUDE.md written to ./CLAUDE.md
  ✓ Claude skills installed: /nff, /wokwi-diagram
  ✓ Registered with Claude Code CLI (claude mcp add nff nff mcp)
  ✓ Claude Desktop config updated

4. Verify everything works

nff doctor

---

CLI Reference

Real hardware

Command	Description
nff init	Detect board, write config, register MCP server
nff flash <file>	Compile and upload a sketch or sketch directory
nff monitor	Stream serial output (Ctrl+C to exit, or --timeout SECONDS)
nff doctor	Check all dependencies and configuration
nff mcp	Start the MCP server (called automatically by Claude Code)

nff flash sketches/sensor_init
nff flash sketches/sensor_init --board esp32:esp32:esp32 --port COM3
nff flash sketches/sensor_init --manual-reset    # for boards with broken auto-reset
nff monitor --port COM10 --baud 115200
nff monitor --port COM10 --baud 115200 --timeout 15   # stop after 15 seconds

Wokwi simulation (CI without a bench)

Command	Description
nff wokwi init	Scaffold wokwi.toml + diagram.json in current directory
nff flash --sim <file>	Compile sketch and run headless Wokwi simulation
nff wokwi run	Run simulation, stream serial output to terminal
nff wokwi run --gui	Open diagram.json in VS Code and auto-start visual simulation
nff wokwi run --serial-log FILE	Save serial output to file
nff wokwi run --timeout MS	Set simulation timeout (default 5000 ms)

---

Supported Boards

Board	Vendor ID	Product ID	FQBN
ESP32 (CP210x)	10c4	ea60	esp32:esp32:esp32
ESP32 (CH340)	1a86	7523	esp32:esp32:esp32
ESP8266 (FTDI)	0403	6001	esp8266:esp8266:generic
Arduino Uno	2341	0043	arduino:avr:uno
Arduino Mega 2560	2341	0010	arduino:avr:mega
Arduino Leonardo	2341	0036	arduino:avr:leonardo
Arduino Nano	2341	0058	arduino:avr:nano

Board not listed? Open a PR — adding one is two lines of code.

---

Config File

~/.nff/config.json, written by nff init and nff wokwi init, editable by hand:

{
  "version": "1",
  "default_device": {
    "port": "COM10",
    "board": "ESP32 (CP210x)",
    "fqbn": "esp32:esp32:esp32",
    "baud": 115200
  },
  "wokwi": {
    "api_token": "YOUR_TOKEN",
    "default_timeout_ms": 5000,
    "diagram_path": null
  }
}

The Wokwi token can also be set via the WOKWI_CLI_TOKEN environment variable (takes precedence over config).

---

Claude Code Skills

nff ships two Claude Code skills that are automatically installed to ~/.claude/commands/ when you run nff init, making them available globally in every Claude Code session.

Skill	When to use
/nff	Full pipeline reference — hardware and simulation workflows, sketch-first rules, servo calibration, debugging checklist
/wokwi-diagram	diagram.json authoring reference — component types, pin names, wiring patterns for LEDs, buttons, servos, sensors

Type the skill name in any Claude Code prompt to load the reference into context:

/nff
/wokwi-diagram

The skill files are also available in the repository at .claude/commands/ for project-level use, and are bundled inside the nff package at nff/skills/ so they ship with every pip install nff.

---

Repository Structure

nff/
├── nff/
│   ├── cli.py              # Click entry point — routes subcommands
│   ├── mcp_server.py       # MCP server — registers all tools for Claude
│   ├── config.py           # Read/write ~/.nff/config.json
│   ├── commands/
│   │   ├── init.py         # nff init
│   │   ├── flash.py        # nff flash [--sim]
│   │   ├── monitor.py      # nff monitor
│   │   ├── doctor.py       # nff doctor
│   │   └── wokwi.py        # nff wokwi init / run [--gui]
│   └── tools/
│       ├── boards.py       # USB vendor ID detection
│       ├── serial.py       # pyserial read/write/stream
│       ├── toolchain.py    # arduino-cli subprocess wrappers
│       └── wokwi.py        # WokwiRunner, generate_diagram, write_wokwi_toml
├── sketches/
│   ├── blink_esp32/        # LED blink example
│   └── servo_button/       # Servo + button example (LEDC, no library)
├── diagram.json            # Wokwi circuit schematic
├── wokwi.toml              # Wokwi project config (points to compiled ELF)
├── .claude/
│   └── commands/
│       └── nff.md          # /nff Claude Code skill
├── tests/
├── pyproject.toml
└── CONTRIBUTING.md

---

Linux: Serial Port Permissions

sudo usermod -aG dialout $USER
# then log out and back in

nff doctor detects this and prints the fix if your port is inaccessible.

---

Wokwi Simulation

Simulation is available for CI runs where no bench hardware is present. Get a free CI token at https://wokwi.com/dashboard/ci, then:

nff wokwi init --board esp32:esp32:esp32 --token YOUR_TOKEN
nff flash --sim sketches/my_sketch --board esp32:esp32:esp32
nff wokwi run              # headless, serial output only
nff wokwi run --gui        # visual simulation in VS Code

Install the Wokwi VS Code extension for the animated circuit view. nff wokwi run --gui opens diagram.json as a new tab and automatically triggers Wokwi: Start Simulator after 3 seconds.

Wokwi MCP Tools

Tool	What it does
wokwi_flash(code, board?, timeout_ms?)	Compile and simulate a sketch via Wokwi
wokwi_serial_read(code, board?, duration_ms?)	Compile, simulate, return serial output
wokwi_get_diagram(board)	Return a minimal diagram.json stub to extend

diagram.json — Circuit Schematic

The circuit lives in diagram.json next to wokwi.toml. nff wokwi init generates a minimal single-MCU stub; add components and wiring by hand or ask Claude.

Always include the serial monitor wires:

["esp:TX0", "$serialMonitor:RX", "", []],
["esp:RX0", "$serialMonitor:TX", "", []]

Common components:

{ "type": "wokwi-led",        "id": "led1", "attrs": { "color": "red" } }
{ "type": "wokwi-pushbutton", "id": "btn1", "attrs": { "color": "blue" } }
{ "type": "wokwi-servo",      "id": "srv1", "attrs": { "minAngle": "-90", "maxAngle": "90" } }
{ "type": "wokwi-resistor",   "id": "r1",   "attrs": { "value": "220" } }

ESP32 DevKit V1 pins: esp:D<gpio> · esp:GND.1 · esp:GND.2 · esp:3V3 · esp:VIN · esp:TX0 · esp:RX0

Pushbutton wiring: one side to GPIO (btn1:1.l), other side to GND (btn1:2.l). Use INPUT_PULLUP in the sketch.

ESP32 Servo — No Library Required

Use the built-in LEDC peripheral instead of ESP32Servo. Wokwi maps its full servo range to 500 µs – 2500 µs pulses.

With 50 Hz / 16-bit resolution (period = 20 000 µs):

Angle	Pulse	Duty
−90° (min)	500 µs	1638
0° (center)	1500 µs	4915
+90° (max)	2500 µs	8192

ledcAttach(SERVO_PIN, 50, 16);     // ESP32 Arduino core 3.x API
ledcWrite(SERVO_PIN, 4915);        // move to center

Set "minAngle": "-90", "maxAngle": "90" in diagram.json for correct visual mapping.

---

License

MIT — see LICENSE.
Copyright (c) 2026 Gauthier Lechevalier