nff 0.1.0__tar.gz

nff-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GauthierLechevalier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nff-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: nff
+Version: 0.1.0
+Summary: Claude Code IoT Bridge — connect Claude to hardware via USB
+Author-email: Gauthier Lechevalier <gauthier.lechevalier26@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GLechevalier/nff
+Project-URL: Repository, https://github.com/GLechevalier/nff
+Project-URL: Bug Tracker, https://github.com/GLechevalier/nff/issues
+Keywords: arduino,esp32,mcp,claude,iot,serial,embedded
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# nff — Claude Code IoT Bridge
+
+**nff** connects [Claude Code](https://claude.ai/code) to physical hardware over USB. It exposes your board as a set of MCP tools so Claude can autonomously write firmware, compile it, upload it, read serial output, and debug — all from a single conversation.
+
+```
+you: "Make the LED blink every 200 ms and print the state to serial"
+Claude: [writes sketch] → [compiles] → [uploads to ESP32] → [reads serial] → done
+```
+
+**Supported boards (v1):** Arduino Uno · Mega · Nano · Leonardo · ESP32 (CP210x / CH340) · ESP8266 (FTDI)
+
+---
+
+## Quickstart
+
+### 1. Install
+
+```bash
+pip install nff
+```
+
+### 2. Plug in your board, then run init
+
+```bash
+nff init
+```
+
+`nff init` does three things automatically:
+- Detects your board by USB vendor/product ID
+- Installs `arduino-cli` if it isn't on your system yet
+- Registers the nff MCP server in `~/.claude/claude_desktop_config.json`
+
+Expected output:
+
+```
+  ✓ Found: ESP32 (CP210x) on COM10 (vendor: 10c4, product: ea60)
+  ✓ arduino-cli installed.
+  ✓ Config written to C:\Users\you\.nff\config.json
+  ✓ MCP config written to C:\Users\you\.claude\claude_desktop_config.json
+```
+
+### 3. Verify everything works
+
+```bash
+nff doctor
+```
+
+All checks should be green. If `arduino-cli` boards/cores are missing, install them:
+
+```bash
+arduino-cli core install arduino:avr      # Arduino boards
+arduino-cli core install esp32:esp32      # ESP32
+arduino-cli core install esp8266:esp8266  # ESP8266
+```
+
+### 4. Open Claude Code and start talking to your hardware
+
+Restart Claude Code (or Claude Desktop) so it picks up the new MCP server. You're ready.
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `nff init` | Detect board, install arduino-cli, write config, register MCP server |
+| `nff flash <file>` | Compile and upload a `.ino` sketch or sketch directory |
+| `nff monitor` | Interactive serial monitor (Ctrl+C to exit) |
+| `nff doctor` | Check all dependencies and configuration |
+| `nff install-deps` | Re-download and install arduino-cli |
+| `nff mcp` | Start the MCP server (called automatically by Claude Code) |
+
+### `nff flash`
+
+```bash
+nff flash ./blink.ino
+nff flash ./my_sketch/                       # sketch directory
+nff flash ./blink.ino --board arduino:avr:uno --port COM3
+nff flash ./blink.ino --manual-reset         # for boards with broken auto-reset
+```
+
+### `nff monitor`
+
+```bash
+nff monitor
+nff monitor --port COM10 --baud 115200
+nff monitor --timeout 10                     # stop after 10 seconds
+```
+
+---
+
+## 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.
+
+---
+
+## Config file
+
+Stored at `~/.nff/config.json`, written by `nff init`, editable by hand:
+
+```json
+{
+  "version": "1",
+  "default_device": {
+    "port": "COM10",
+    "board": "ESP32 (CP210x)",
+    "fqbn": "esp32:esp32:esp32",
+    "baud": 115200
+  }
+}
+```
+
+---
+
+## Supported Boards
+
+| Board | Vendor ID | Product ID | FQBN |
+|---|---|---|---|
+| 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` |
+| ESP32 (CP210x) | 10c4 | ea60 | `esp32:esp32:esp32` |
+| ESP32 (CH340) | 1a86 | 7523 | `esp32:esp32:esp32` |
+| ESP8266 (FTDI) | 0403 | 6001 | `esp8266:esp8266:generic` |
+
+Board not listed? Open a PR — adding one is [two lines of code](CONTRIBUTING.md#adding-a-new-board).
+
+---
+
+## Linux: serial port permissions
+
+On Linux, serial ports require the `dialout` group:
+
+```bash
+sudo usermod -aG dialout $USER
+# then log out and back in
+```
+
+`nff doctor` will detect this and print the fix if your port is inaccessible.
+
+---
+
+## 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
+│   │   ├── monitor.py      # nff monitor
+│   │   └── doctor.py       # nff doctor
+│   └── tools/
+│       ├── boards.py       # USB vendor ID detection
+│       ├── serial.py       # pyserial read/write/stream
+│       ├── toolchain.py    # arduino-cli subprocess wrappers
+│       └── installer.py    # arduino-cli auto-installer
+├── scripts/
+│   └── install_arduino_cli.py   # Standalone installer (thin wrapper)
+├── sketches/
+│   └── blink_esp32/        # Example sketch
+├── tests/
+├── pyproject.toml
+└── CONTRIBUTING.md
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).  
+Copyright (c) 2026 Gauthier Lechevalier

nff-0.1.0/README.md

@@ -0,0 +1,188 @@
+# nff — Claude Code IoT Bridge
+
+**nff** connects [Claude Code](https://claude.ai/code) to physical hardware over USB. It exposes your board as a set of MCP tools so Claude can autonomously write firmware, compile it, upload it, read serial output, and debug — all from a single conversation.
+
+```
+you: "Make the LED blink every 200 ms and print the state to serial"
+Claude: [writes sketch] → [compiles] → [uploads to ESP32] → [reads serial] → done
+```
+
+**Supported boards (v1):** Arduino Uno · Mega · Nano · Leonardo · ESP32 (CP210x / CH340) · ESP8266 (FTDI)
+
+---
+
+## Quickstart
+
+### 1. Install
+
+```bash
+pip install nff
+```
+
+### 2. Plug in your board, then run init
+
+```bash
+nff init
+```
+
+`nff init` does three things automatically:
+- Detects your board by USB vendor/product ID
+- Installs `arduino-cli` if it isn't on your system yet
+- Registers the nff MCP server in `~/.claude/claude_desktop_config.json`
+
+Expected output:
+
+```
+  ✓ Found: ESP32 (CP210x) on COM10 (vendor: 10c4, product: ea60)
+  ✓ arduino-cli installed.
+  ✓ Config written to C:\Users\you\.nff\config.json
+  ✓ MCP config written to C:\Users\you\.claude\claude_desktop_config.json
+```
+
+### 3. Verify everything works
+
+```bash
+nff doctor
+```
+
+All checks should be green. If `arduino-cli` boards/cores are missing, install them:
+
+```bash
+arduino-cli core install arduino:avr      # Arduino boards
+arduino-cli core install esp32:esp32      # ESP32
+arduino-cli core install esp8266:esp8266  # ESP8266
+```
+
+### 4. Open Claude Code and start talking to your hardware
+
+Restart Claude Code (or Claude Desktop) so it picks up the new MCP server. You're ready.
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `nff init` | Detect board, install arduino-cli, write config, register MCP server |
+| `nff flash <file>` | Compile and upload a `.ino` sketch or sketch directory |
+| `nff monitor` | Interactive serial monitor (Ctrl+C to exit) |
+| `nff doctor` | Check all dependencies and configuration |
+| `nff install-deps` | Re-download and install arduino-cli |
+| `nff mcp` | Start the MCP server (called automatically by Claude Code) |
+
+### `nff flash`
+
+```bash
+nff flash ./blink.ino
+nff flash ./my_sketch/                       # sketch directory
+nff flash ./blink.ino --board arduino:avr:uno --port COM3
+nff flash ./blink.ino --manual-reset         # for boards with broken auto-reset
+```
+
+### `nff monitor`
+
+```bash
+nff monitor
+nff monitor --port COM10 --baud 115200
+nff monitor --timeout 10                     # stop after 10 seconds
+```
+
+---
+
+## 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.
+
+---
+
+## Config file
+
+Stored at `~/.nff/config.json`, written by `nff init`, editable by hand:
+
+```json
+{
+  "version": "1",
+  "default_device": {
+    "port": "COM10",
+    "board": "ESP32 (CP210x)",
+    "fqbn": "esp32:esp32:esp32",
+    "baud": 115200
+  }
+}
+```
+
+---
+
+## Supported Boards
+
+| Board | Vendor ID | Product ID | FQBN |
+|---|---|---|---|
+| 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` |
+| ESP32 (CP210x) | 10c4 | ea60 | `esp32:esp32:esp32` |
+| ESP32 (CH340) | 1a86 | 7523 | `esp32:esp32:esp32` |
+| ESP8266 (FTDI) | 0403 | 6001 | `esp8266:esp8266:generic` |
+
+Board not listed? Open a PR — adding one is [two lines of code](CONTRIBUTING.md#adding-a-new-board).
+
+---
+
+## Linux: serial port permissions
+
+On Linux, serial ports require the `dialout` group:
+
+```bash
+sudo usermod -aG dialout $USER
+# then log out and back in
+```
+
+`nff doctor` will detect this and print the fix if your port is inaccessible.
+
+---
+
+## 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
+│   │   ├── monitor.py      # nff monitor
+│   │   └── doctor.py       # nff doctor
+│   └── tools/
+│       ├── boards.py       # USB vendor ID detection
+│       ├── serial.py       # pyserial read/write/stream
+│       ├── toolchain.py    # arduino-cli subprocess wrappers
+│       └── installer.py    # arduino-cli auto-installer
+├── scripts/
+│   └── install_arduino_cli.py   # Standalone installer (thin wrapper)
+├── sketches/
+│   └── blink_esp32/        # Example sketch
+├── tests/
+├── pyproject.toml
+└── CONTRIBUTING.md
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).  
+Copyright (c) 2026 Gauthier Lechevalier

nff-0.1.0/nff/__init__.py

@@ -0,0 +1,3 @@
+"""nff — Claude Code IoT Bridge."""
+
+__version__ = "0.1.0"

nff-0.1.0/nff/cli.py

@@ -0,0 +1,79 @@
+"""nff — entry point that wires all subcommands into one CLI."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+from rich.console import Console
+
+from nff import __version__
+
+if sys.platform == "win32" and hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+
+console = Console(legacy_windows=False)
+
+
+# ---------------------------------------------------------------------------
+# Root group
+# ---------------------------------------------------------------------------
+
+@click.group()
+@click.version_option(__version__, "-V", "--version", prog_name="nff")
+def cli() -> None:
+    """nff — Claude Code IoT Bridge.
+
+    Connects Claude Code to physical hardware devices via USB.
+    Run `nff init` to get started.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Subcommands
+# ---------------------------------------------------------------------------
+
+from nff.commands.init import init          # noqa: E402
+from nff.commands.flash import flash        # noqa: E402
+from nff.commands.monitor import monitor    # noqa: E402
+from nff.commands.doctor import doctor      # noqa: E402
+
+cli.add_command(init)
+cli.add_command(flash)
+cli.add_command(monitor)
+cli.add_command(doctor)
+
+
+@cli.command("install-deps")
+@click.option("--force", is_flag=True, help="Reinstall even if already present.")
+def install_deps(force: bool) -> None:
+    """Download and install arduino-cli (runs automatically during `nff init`)."""
+    from nff.tools import installer
+    console.print("[bold cyan]arduino-cli installer[/bold cyan]")
+    try:
+        exe = installer.install(force=force)
+        if not installer.verify(exe):
+            raise SystemExit(1)
+    except Exception as exc:
+        console.print(f"  [bold red]✗[/bold red] {exc}")
+        raise SystemExit(1)
+
+
+@cli.command()
+def mcp() -> None:
+    """Start the MCP server (stdio). Called automatically by Claude Code."""
+    from nff.mcp_server import main as _mcp_main
+    _mcp_main()
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    """Setuptools / pipx entry point: ``nff = "nff.cli:main"``."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

nff-0.1.0/nff/commands/doctor.py

@@ -0,0 +1,176 @@
+"""nff doctor — dependency and configuration health check."""
+
+from __future__ import annotations
+
+import pathlib
+import sys
+
+# Fix sys.path when this file is run directly (`python doctor.py`).
+# Python adds commands/ to sys.path, making `nff` unresolvable.
+if __name__ == "__main__":
+    _pkg_parent = str(pathlib.Path(__file__).resolve().parents[2])
+    if _pkg_parent not in sys.path:
+        sys.path.insert(0, _pkg_parent)
+
+import importlib.metadata
+import json
+import platform
+import sys
+from pathlib import Path
+from typing import NamedTuple
+
+import click
+from rich.console import Console
+
+# Windows PowerShell defaults to cp1252 which can't encode ✓/✗.
+# Reconfigure stdout to UTF-8 before Rich initialises its stream.
+if sys.platform == "win32" and hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+
+from nff import config as cfg_module
+from nff.tools import boards as boards_module
+from nff.tools import toolchain
+
+console = Console(legacy_windows=False)
+
+_CLAUDE_DESKTOP_CONFIG = Path.home() / ".claude" / "claude_desktop_config.json"
+
+
+class Check(NamedTuple):
+    passed: bool
+    detail: str          # printed next to ✓ / ✗
+    fix: str | None = None   # hint shown when failed
+
+
+# ---------------------------------------------------------------------------
+# Individual checks
+# ---------------------------------------------------------------------------
+
+def check_python() -> Check:
+    v = sys.version_info
+    label = f"Python {v.major}.{v.minor}.{v.micro}"
+    if (v.major, v.minor) >= (3, 10):
+        return Check(True, label)
+    return Check(False, f"{label} — nff requires Python 3.10+", "Upgrade Python")
+
+
+def check_arduino_cli() -> Check:
+    version = toolchain.arduino_cli_version()
+    if version:
+        return Check(True, f"{version}  ({toolchain.find_arduino_cli()})")
+    return Check(
+        False,
+        "arduino-cli not found",
+        "Install from https://arduino.github.io/arduino-cli",
+    )
+
+
+def check_esptool() -> Check:
+    version = toolchain.esptool_version()
+    if version:
+        loc = toolchain.find_esptool() or "python -m esptool"
+        return Check(True, f"{version}  ({loc})")
+    return Check(False, "esptool not found", "Run: pip install esptool")
+
+
+def check_pyserial() -> Check:
+    try:
+        version = importlib.metadata.version("pyserial")
+        return Check(True, f"pyserial {version}")
+    except importlib.metadata.PackageNotFoundError:
+        return Check(False, "pyserial not installed", "Run: pip install pyserial")
+
+
+def check_config() -> Check:
+    if not cfg_module.exists():
+        return Check(False, "Config not found", "Run: nff init")
+    try:
+        cfg_module.load()
+        return Check(True, f"Config found at {cfg_module.CONFIG_PATH}")
+    except cfg_module.ConfigError as exc:
+        return Check(
+            False,
+            f"Config unreadable: {exc}",
+            f"Fix or delete {cfg_module.CONFIG_PATH}",
+        )
+
+
+def check_device() -> Check:
+    """Check that a recognised board is detected and its port is openable."""
+    # Lazy import — pyserial may not be installed; check_pyserial will flag it.
+    try:
+        import serial as _serial
+    except ImportError:
+        return Check(False, "Cannot check device — pyserial missing", "Run: pip install pyserial")
+
+    devices = boards_module.list_devices()
+    if not devices:
+        return Check(False, "No recognised board detected", "Plug in a board and run nff init")
+
+    device = devices[0]
+    label = f"Device detected: {device.board} on {device.port}"
+
+    try:
+        conn = _serial.Serial(device.port, timeout=0.5)
+        conn.close()
+    except _serial.SerialException as exc:
+        fix = f"Port {device.port} is inaccessible: {exc}"
+        if platform.system() == "Linux":
+            fix += "\n    → Add yourself to the dialout group: sudo usermod -aG dialout $USER"
+        return Check(False, f"{label} — port inaccessible", fix)
+
+    return Check(True, label)
+
+
+def check_claude_desktop() -> Check:
+    if not _CLAUDE_DESKTOP_CONFIG.exists():
+        return Check(False, "Claude Desktop config not found", "Run: nff init")
+    try:
+        data = json.loads(_CLAUDE_DESKTOP_CONFIG.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        return Check(False, f"Claude Desktop config unreadable: {exc}")
+    if "nff" not in data.get("mcpServers", {}):
+        return Check(
+            False,
+            "nff not registered in Claude Desktop config",
+            "Run: nff init",
+        )
+    return Check(True, f"Claude Desktop config OK  ({_CLAUDE_DESKTOP_CONFIG})")
+
+
+# ---------------------------------------------------------------------------
+# Click command
+# ---------------------------------------------------------------------------
+
+_CHECKS = [
+    check_python,
+    check_arduino_cli,
+    check_esptool,
+    check_pyserial,
+    check_config,
+    check_device,
+    check_claude_desktop,
+]
+
+
+@click.command()
+def doctor() -> None:
+    """Check dependencies, config, and device connectivity."""
+    any_failed = False
+
+    for fn in _CHECKS:
+        result = fn()
+        if result.passed:
+            console.print(f"  [bold green]✓[/bold green] {result.detail}")
+        else:
+            console.print(f"  [bold red]✗[/bold red] {result.detail}")
+            if result.fix:
+                console.print(f"    [yellow]→[/yellow] {result.fix}")
+            any_failed = True
+
+    if any_failed:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    doctor()