nff 0.2.3__tar.gz → 0.2.4__tar.gz

{nff-0.2.3 → nff-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nff
-Version: 0.2.3
+Version: 0.2.4
 Summary: Claude Code IoT Bridge — connect Claude to hardware via USB
 Author-email: Gauthier Lechevalier <gauthier.lechevalier26@gmail.com>
 License-Expression: MIT

{nff-0.2.3 → nff-0.2.4}/nff/commands/flash.py

@@ -238,7 +238,7 @@ def flash(
     """
     fqbn, resolved_port = _resolve_target(board, port, sim=sim)
     sketch_dir = _resolve_sketch(file)
-
+    
     if sim:
         console.print(
             f"  [bold]{sketch_dir.name}[/bold]  →  "

{nff-0.2.3 → nff-0.2.4}/nff/commands/init.py

@@ -13,6 +13,7 @@ if __name__ == "__main__":
 import json
 import shutil
 import subprocess
+from importlib import resources
 from pathlib import Path
 
 import click
@@ -107,6 +108,33 @@ def _register_mcp_claude_code() -> bool:
         return False
 
 
+def _install_claude_skills() -> None:
+    """Copy bundled skill files to ~/.claude/commands/ (user-level global skills).
+
+    Silently skips any file that cannot be written so it never aborts init.
+    """
+    dest_dir = Path.home() / ".claude" / "commands"
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    skills_pkg = resources.files("nff") / "skills"
+    installed: list[str] = []
+    for skill_file in skills_pkg.iterdir():
+        if not skill_file.name.endswith(".md"):
+            continue
+        try:
+            dest = dest_dir / skill_file.name
+            dest.write_text(skill_file.read_text(encoding="utf-8"), encoding="utf-8")
+            installed.append(skill_file.name)
+        except OSError:
+            pass
+
+    if installed:
+        names = ", ".join(f"/{p.removesuffix('.md')}" for p in installed)
+        console.print(
+            f"  [bold green]✓[/bold green] Claude skills installed: [bold]{names}[/bold]"
+        )
+
+
 def _update_claude_desktop_config() -> None:
     """Merge the nff MCP entry into ~/.claude/claude_desktop_config.json.
 
@@ -379,6 +407,12 @@ def _write_success(port: str, board: str, device: DetectedDevice | None) -> None
     except OSError as exc:
         console.print(f"  [yellow]⚠[/yellow]  Could not write CLAUDE.md: {exc}")
 
+    # Install Claude skills globally
+    try:
+        _install_claude_skills()
+    except Exception as exc:
+        console.print(f"  [yellow]⚠[/yellow]  Could not install Claude skills: {exc}")
+
     # Claude Code CLI — preferred
     if _register_mcp_claude_code():
         console.print(

nff-0.2.4/nff/skills/nff.md

@@ -0,0 +1,213 @@
+# nff — IoT CLI Bridge for Claude Code
+
+`nff` connects Claude Code to embedded hardware (Arduino, ESP32, ESP8266) via USB or Wokwi simulation.
+Use this skill whenever you need to write, compile, simulate, or flash a sketch.
+
+---
+
+## Core Rules
+
+- **Always use `nff flash` to compile/flash** — never call `arduino-cli` directly.
+- **Never install libraries with `arduino-cli lib install`** — write sketches that use built-in APIs only, or ask the user to install the library first.
+- For ESP32 servo control use `ledcAttach` / `ledcWrite` (built-in LEDC, no library needed).
+- The working directory for all `nff` commands is the project root (where `wokwi.toml` lives).
+
+---
+
+## Prerequisites Check
+
+Before any pipeline, run:
+
+```bash
+nff doctor
+```
+
+This verifies: arduino-cli, wokwi-cli, Wokwi token, connected device.
+
+---
+
+## Full Simulation Pipeline (no hardware)
+
+### Step 1 — Write the sketch
+
+Place it in `sketches/<name>/<name>.ino`. The folder name must match the `.ino` filename (arduino-cli requirement).
+
+### Step 2 — Initialize Wokwi project (first time only)
+
+```bash
+nff wokwi init --board <fqbn>
+```
+
+Creates `wokwi.toml` and a minimal `diagram.json` in the project root.
+To add components (LEDs, buttons, servos, sensors), edit `diagram.json` directly.
+
+**Common FQBNs:**
+| Board | FQBN |
+|---|---|
+| ESP32 DevKit V1 | `esp32:esp32:esp32` |
+| Arduino Uno | `arduino:avr:uno` |
+| Arduino Nano | `arduino:avr:nano` |
+| ESP8266 | `esp8266:esp8266:generic` |
+
+### Step 3 — Compile (flash to simulator)
+
+```bash
+nff flash --sim sketches/<name> --board <fqbn>
+```
+
+This compiles the sketch and writes the ELF to:
+`sketches/<name>/build/<fqbn_dotted>/<name>.elf/<name>.ino.elf`
+
+The headless simulation will time out (expected — there's no button to click). What matters is that compilation succeeds.
+
+### Step 4 — Update `wokwi.toml`
+
+Make sure `wokwi.toml` points to the compiled ELF:
+
+```toml
+[wokwi]
+version = 1
+firmware = "sketches/<name>/build/<fqbn_dotted>/<name>.elf/<name>.ino.elf"
+```
+
+Where `<fqbn_dotted>` replaces `:` with `.` (e.g. `esp32.esp32.esp32`).
+
+### Step 5 — Run visual simulation
+
+```bash
+nff wokwi run --gui
+```
+
+Opens `diagram.json` as a new tab in the existing VS Code window and auto-starts the Wokwi simulator after ~3 s.
+
+### Step 6 — Run headless simulation (serial output only)
+
+```bash
+nff wokwi run
+nff wokwi run --timeout 10000 --serial-log output.txt
+```
+
+---
+
+## diagram.json — Component Reference
+
+Always keep the serial monitor wired:
+
+```json
+["esp:TX0", "$serialMonitor:RX", "", []],
+["esp:RX0", "$serialMonitor:TX", "", []]
+```
+
+**ESP32 pin naming:** `esp:D<gpio>` (e.g. `esp:D18`), `esp:GND.1`, `esp:GND.2`, `esp:3V3`, `esp:VIN`
+
+**Common components and their pins — use `/wokwi-diagram` for the full reference:**
+
+| Type | Pins |
+|---|---|
+| `wokwi-led` | `A` (anode), `C` (cathode — **not K**) |
+| `wokwi-resistor` | `1`, `2` |
+| `wokwi-pushbutton` | `1.l`, `1.r`, `2.l`, `2.r` |
+| `wokwi-servo` | `PWM`, `V+`, `GND` |
+| `wokwi-ntc-temperature-sensor` | `VCC`, `GND`, `OUT` |
+
+```json
+{ "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" } }
+{ "type": "wokwi-ntc-temperature-sensor", "id": "tmp1", "attrs": {} }
+```
+
+---
+
+## Servo (ESP32 LEDC — no library)
+
+Wokwi servo maps its full range to **500 µs – 2500 µs** pulses.
+With 50 Hz / 16-bit LEDC resolution (period = 20 000 µs, max count = 65535):
+
+| Angle | Pulse | Duty count |
+|---|---|---|
+| min (−90°) | 500 µs | 1638 |
+| center (0°) | 1500 µs | 4915 |
+| max (+90°) | 2500 µs | 8192 |
+
+```cpp
+ledcAttach(SERVO_PIN, 50, 16);          // attach (ESP32 core 3.x API)
+ledcWrite(SERVO_PIN, 4915);             // move to center
+```
+
+Always declare `minAngle: "-90"` and `maxAngle: "90"` in `diagram.json` for correct visual mapping.
+
+---
+
+## Full Real Hardware Pipeline
+
+### Step 1 — Detect device
+
+```bash
+nff init
+```
+
+Scans USB ports, identifies the board, writes `~/.nff/config.json`.
+
+### Step 2 — Compile and flash
+
+```bash
+nff flash sketches/<name>
+```
+
+Uses board and port from config. Override with `--board <fqbn> --port <port>`.
+
+```bash
+nff flash sketches/<name> --board esp32:esp32:esp32 --port COM3
+```
+
+If upload fails with "Wrong boot mode detected":
+
+```bash
+nff flash sketches/<name> --manual-reset
+```
+
+Hold the BOOT button when prompted, release after upload starts.
+
+### Step 3 — Monitor serial output
+
+```bash
+nff monitor
+nff monitor --port COM3 --baud 115200
+```
+
+Ctrl+C to exit.
+
+**Baud rate:** always match `--baud` (and the value in `~/.nff/config.json`) to the rate passed to
+`Serial.begin()` in the sketch. Mismatched baud rates cause garbled or silent output and break
+all serial debugging.
+
+---
+
+## Debugging Workflow
+
+### Simulation issues
+
+1. Compilation error → fix the sketch, re-run `nff flash --sim`
+2. Serial output looks wrong → check `nff wokwi run --serial-log out.txt`, inspect `out.txt`
+3. Component not responding → check `diagram.json` wiring (pin names, connection direction)
+4. Servo wrong angle → verify duty cycle values match the 500–2500 µs Wokwi range
+5. Button not registering → ensure `INPUT_PULLUP` is set and wiring goes `gpio → btn:1.l`, `GND → btn:2.l`
+
+### Hardware issues
+
+1. Port not found → run `nff init` to re-detect
+2. Upload fails → try `--manual-reset`, check driver (CH340/CP210x)
+3. Wrong output → use `nff monitor` to inspect live serial
+
+---
+
+## Key File Locations
+
+| File | Purpose |
+|---|---|
+| `wokwi.toml` | Points to the compiled ELF for simulation |
+| `diagram.json` | Circuit schematic for Wokwi |
+| `sketches/<name>/<name>.ino` | Arduino sketch source |
+| `~/.nff/config.json` | Default board, port, baud, Wokwi token |

nff-0.2.4/nff/skills/wokwi-diagram.md

@@ -0,0 +1,213 @@
+# wokwi-diagram — Wokwi diagram.json Authoring Reference
+
+Use this skill whenever writing or editing a Wokwi `diagram.json` schematic.
+It is the ground-truth pin reference for all Wokwi components.
+
+---
+
+## diagram.json Structure
+
+```json
+{
+  "version": 1,
+  "author": "nff",
+  "editor": "wokwi",
+  "parts": [ ... ],
+  "connections": [ ... ]
+}
+```
+
+Each connection: `["partId:pin", "partId:pin", "color", [waypoints]]`
+- `color`: any CSS color string, or `""` for default
+- `waypoints`: `[]` for auto-route, or relative offsets like `["h30", "v-20"]`
+
+---
+
+## Serial Monitor (always wire this for ESP32/Arduino)
+
+```json
+["esp:TX0", "$serialMonitor:RX", "", []],
+["esp:RX0", "$serialMonitor:TX", "", []]
+```
+
+---
+
+## MCU Pin Reference
+
+### wokwi-esp32-devkit-v1
+
+| Pin group | Names |
+|---|---|
+| GPIO | `D0` `D1` `D2` `D4` `D5` `D12`–`D19` `D21`–`D23` `D25`–`D27` `D32`–`D35` |
+| UART | `TX` (GPIO1), `RX` (GPIO3) |
+| Analog-only | `VP` (GPIO36), `VN` (GPIO39), `D34`, `D35` |
+| Power | `3V3`, `VIN`, `GND.1` (left-column GND), `GND.2` (right-column GND) |
+| Other | `EN` |
+
+> Use `GND.1` for most circuits — it is the left-column GND between D12 and D13.
+
+### wokwi-arduino-uno
+
+| Pin group | Names |
+|---|---|
+| Digital | `D0`–`D13` |
+| Analog | `A0`–`A5` |
+| Power | `5V`, `3V3`, `GND.1`, `GND.2` |
+| Other | `AREF`, `IOREF`, `RESET` |
+
+### wokwi-arduino-nano
+
+Same as Uno plus `AREF`. Power: `5V`, `3V3`, `GND.1`, `GND.2`.
+
+---
+
+## Component Pin Reference
+
+### wokwi-led
+
+| Pin | Role |
+|---|---|
+| `A` | Anode (positive, connect toward GPIO via resistor) |
+| `C` | Cathode (negative, connect to GND) — **NOT `K`** |
+
+```json
+{ "type": "wokwi-led", "id": "led1", "top": 100, "left": 200, "attrs": { "color": "red" } }
+```
+
+Colors: `"red"`, `"green"`, `"blue"`, `"yellow"`, `"white"`, `"orange"`
+
+**Standard blink circuit (GPIO → R → LED → GND):**
+```json
+["esp:D2",  "r1:1",   "green", []],
+["r1:2",    "led1:A", "green", []],
+["led1:C",  "esp:GND.1", "black", []]
+```
+
+---
+
+### wokwi-resistor
+
+| Pin | Role |
+|---|---|
+| `1` | Terminal 1 |
+| `2` | Terminal 2 |
+
+```json
+{ "type": "wokwi-resistor", "id": "r1", "top": 100, "left": 150, "attrs": { "value": "220" } }
+```
+
+Common values: `"220"` (LED current limit), `"1000"`, `"10000"` (pull-up/down)
+
+Add `"rotate": 90` to orient vertically.
+
+---
+
+### wokwi-pushbutton
+
+| Pin | Role |
+|---|---|
+| `1.l` | Side 1 left lead |
+| `1.r` | Side 1 right lead |
+| `2.l` | Side 2 left lead |
+| `2.r` | Side 2 right lead |
+
+`1.*` and `2.*` are shorted when button is pressed. Typical wiring with `INPUT_PULLUP`:
+```json
+["esp:D4",  "btn1:1.l", "green", []],
+["esp:GND.1", "btn1:2.l", "black", []]
+```
+
+```json
+{ "type": "wokwi-pushbutton", "id": "btn1", "top": 100, "left": 200, "attrs": { "color": "blue" } }
+```
+
+---
+
+### wokwi-servo
+
+| Pin | Role |
+|---|---|
+| `PWM` | Signal (connect to GPIO) |
+| `V+` | Power (connect to 5V or 3V3) |
+| `GND` | Ground |
+
+```json
+{ "type": "wokwi-servo", "id": "srv1", "top": 100, "left": 200, "attrs": { "minAngle": "-90", "maxAngle": "90" } }
+```
+
+```json
+["esp:D18",    "srv1:PWM", "orange", []],
+["esp:3V3",    "srv1:V+",  "red",    []],
+["esp:GND.1",  "srv1:GND", "black",  []]
+```
+
+---
+
+### wokwi-ntc-temperature-sensor
+
+| Pin | Role |
+|---|---|
+| `VCC` | Power (3.3V or 5V) |
+| `GND` | Ground |
+| `OUT` | Analog output (connect to ADC pin) |
+
+```json
+["esp:3V3",   "tmp1:VCC", "red",   []],
+["esp:GND.1", "tmp1:GND", "black", []],
+["esp:D34",   "tmp1:OUT", "green", []]
+```
+
+---
+
+### wokwi-dht22
+
+| Pin | Role |
+|---|---|
+| `VCC` | Power |
+| `GND` | Ground |
+| `SDA` | Data (connect to GPIO, no extra resistor needed in Wokwi) |
+
+---
+
+### wokwi-ssd1306
+
+| Pin | Role |
+|---|---|
+| `VCC` | Power (3.3V) |
+| `GND` | Ground |
+| `SCL` | I2C clock |
+| `SDA` | I2C data |
+
+Default I2C on ESP32: `SCL = D22`, `SDA = D21`.
+
+---
+
+### wokwi-hc-sr04 (ultrasonic)
+
+| Pin | Role |
+|---|---|
+| `VCC` | 5V |
+| `GND` | Ground |
+| `TRIG` | Trigger pulse (GPIO output) |
+| `ECHO` | Echo return (GPIO input) |
+
+---
+
+## Positioning Tips
+
+- `top` / `left` are canvas pixels; `0,0` is top-left of the first placed part.
+- ESP32 DevKit V1 occupies roughly 160 × 400 px.
+- Place external components to the **right** of the ESP32 (left ≈ 200+) to align with the right-column pins (D2, GND.2, etc.).
+- Place components to the **left** (left ≈ -150) to align with left-column pins (D32, GND.1, etc.).
+- `"rotate": 90` rotates a component 90° clockwise.
+
+---
+
+## Common Mistakes
+
+| Mistake | Correct |
+|---|---|
+| `led1:K` | `led1:C` — Wokwi uses `C` for cathode, not the standard `K` |
+| `esp:GND` | `esp:GND.1` or `esp:GND.2` — always use the numbered suffix |
+| `esp:GPIO2` | `esp:D2` — Wokwi prefixes GPIO numbers with `D` |
+| `esp:TX0` in connections | `esp:TX` — omit the `0` suffix for UART pins |

{nff-0.2.3 → nff-0.2.4}/nff/tools/toolchain.py

@@ -368,6 +368,7 @@ def stream_compile(sketch_dir: pathlib.Path, fqbn: str) -> ProcessStream:
         ToolchainError: If arduino-cli is missing or fails to start.
     """
     exe = _require_arduino_cli()
+    #print(elf_path_for(sketch_dir, fqbn))
     return _stream_process([exe, "compile", "--fqbn", fqbn, str(sketch_dir), "--build-path", str(elf_path_for(sketch_dir, fqbn))])
 
 

{nff-0.2.3 → nff-0.2.4}/nff.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nff
-Version: 0.2.3
+Version: 0.2.4
 Summary: Claude Code IoT Bridge — connect Claude to hardware via USB
 Author-email: Gauthier Lechevalier <gauthier.lechevalier26@gmail.com>
 License-Expression: MIT

{nff-0.2.3 → nff-0.2.4}/nff.egg-info/SOURCES.txt

@@ -18,6 +18,8 @@ nff/commands/flash.py
 nff/commands/init.py
 nff/commands/monitor.py
 nff/commands/wokwi.py
+nff/skills/nff.md
+nff/skills/wokwi-diagram.md
 nff/tools/__init__.py
 nff/tools/boards.py
 nff/tools/installer.py

{nff-0.2.3 → nff-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nff"
-version = "0.2.3"
+version = "0.2.4"
 description = "Claude Code IoT Bridge — connect Claude to hardware via USB"
 readme = "README.md"
 license = "MIT"
@@ -55,6 +55,9 @@ where = ["."]
 include = ["nff*"]
 exclude = ["tests*", "scripts*"]
 
+[tool.setuptools.package-data]
+"nff" = ["skills/*.md"]
+
 [tool.black]
 line-length = 100