micropython-skills

# micropython-skills

AI Agent programmable co-processor skill collection. You (the Agent) generate MicroPython code,
push it to devices via REPL, parse structured output, and iterate — turning hardware into your
extended capability.

## Quick Start

> **Python command**: Use `python3` on macOS/Linux, `python` on Windows.
> On Windows, `python3` is often a Microsoft Store stub that silently fails (exit code 49).
> On macOS/Linux, `python` may not exist or may point to Python 2.

Every interaction follows this flow:

1. **Probe** — Run `python3 {SKILL_DIR}/scripts/device_probe.py` to discover connected devices
   - `status: "ok"` → Device has MicroPython, proceed to step 2
   - `status: "no_firmware"` → ESP chip detected but no MicroPython. Ask user to confirm, then flash: `python3 {SKILL_DIR}/scripts/firmware_flash.py --port PORT --yes`
   - `status: "no_device"` → No device connected. Guide user to connect hardware.
   - `status: "permission_denied"` → Serial port not accessible. On Linux: `sudo chmod 666 /dev/ttyACM0`. On Windows: check Device Manager for driver issues.
2. **Connect** — Default: USB via mpremote. Optional: WiFi via WebREPL (user must request)
3. **Execute** — Generate MicroPython code and push to device
4. **Parse** — Scan stdout for tagged lines (RESULT:/ERROR:/STATUS:/LOG:)
5. **Iterate** — Adjust code based on results, repeat steps 3-5

Where `{SKILL_DIR}` is the directory containing this SKILL.md file.

## Connection Management

### Default: USB (mpremote)

Always start by probing for devices:
```bash
python3 {SKILL_DIR}/scripts/device_probe.py
```

Execute code on device:
```bash
mpremote exec "import machine; print('RESULT:' + str(machine.freq()))"
```

Run a script file:
```bash
mpremote run script.py
```

For multi-line code, write a temporary `.py` file locally, then `mpremote run /path/to/task.py`.

Serial port names vary by platform:

| Platform | Port Format | Example |
|----------|------------|---------|
| Linux | /dev/ttyUSB0, /dev/ttyACM0 | `mpremote connect /dev/ttyACM0` |
| macOS | /dev/cu.usbserial-*, /dev/cu.usbmodem* | `mpremote connect /dev/cu.usbmodem14101` |
| Windows | COM3, COM4, ... | `mpremote connect COM3` |

The scripts auto-detect the port — you rarely need to specify it manually.

### Optional: WiFi (WebREPL)

Only switch to WiFi when the user explicitly requests it. The switch flow:

1. Ask user for WiFi SSID and password
2. Push WiFi + WebREPL config to device via USB:
   ```bash
   python3 {SKILL_DIR}/scripts/wifi_setup.py --ssid "SSID" --password "PASS" --webrepl-password "repl123"
   ```
3. Note the IP address from the output
4. From now on, execute code over WiFi:
   ```bash
   python3 {SKILL_DIR}/scripts/webrepl_exec.py --host 192.168.1.100 --password repl123 --code "print('hello')"
   ```
5. USB cable can be disconnected

For detailed command reference, read `./references/connections.md`.

## Sub-skill Router

Based on user intent, read the corresponding sub-skill for domain-specific templates:

| User Intent Keywords | Sub-skill Path | Safety Tier |
|---------------------|----------------|-------------|
| temperature, humidity, DHT, BME280, pressure, IMU, accelerometer, ADC, analog, ultrasonic, light sensor, photoresistor, read sensor | `./skills/sensor/SKILL.md` | Safe |
| GPIO, LED, blink, PWM, servo, motor, stepper, relay, NeoPixel, WS2812, buzzer, output, control, drive | `./skills/actuator/SKILL.md` | Cautious |
| WiFi, MQTT, HTTP, BLE, Bluetooth, NTP, WebSocket, AP mode, network, connect internet, publish, subscribe | `./skills/network/SKILL.md` | Cautious |
| PID, filter, Kalman, state machine, scheduler, data logging, moving average, control loop, algorithm | `./skills/algorithm/SKILL.md` | Safe |
| scan I2C, scan SPI, device info, memory, filesystem, diagnose, health check, benchmark, pin state, what's connected | `./skills/diagnostic/SKILL.md` | Safe |
| save to device, 保存到设备, 开机自启, auto start, 下次还能用, persist, 断电保存 | See "Program Persistence" section below | Cautious/Dangerous |
| flash firmware, burn firmware, install MicroPython, no firmware, 烧录, 刷固件, 刷机 | `scripts/firmware_flash.py` | Dangerous |
| recovery, not responding, stuck, boot.py, main.py, reflash, brick | `./references/safety.md` | Dangerous |

When a task spans multiple domains (e.g., "read sensor and publish via MQTT"), read all relevant sub-skills.

## Structured Output Protocol

All MicroPython code you generate for the device MUST use tagged output lines:

| Tag | Purpose | Example |
|-----|---------|---------|
| `RESULT:` | Success data (JSON) | `RESULT:{"temp":23.5,"hum":61}` |
| `ERROR:` | Error info | `ERROR:OSError: [Errno 19] ENODEV` |
| `STATUS:` | Status indicator | `STATUS:ok` |
| `LOG:` | Debug info | `LOG:sampling at 100Hz` |

Code template — every snippet you generate should follow this pattern:
```python
import json
from machine import Pin
try:
    # ... your operation here ...
    print("RESULT:" + json.dumps({"key": value}))
except Exception as e:
    print("ERROR:" + str(e))
```

Parse rules:
- Scan device stdout line by line
- Extract lines starting with `RESULT:`, `ERROR:`, `STATUS:`, `LOG:`
- Ignore all other output (MicroPython boot messages, REPL prompts, etc.)
- If `ERROR:` is found, diagnose and retry with adjusted code

## Safety Rules

| Tier | Operations | Agent Behavior |
|------|-----------|----------------|
| Safe | Sensor read, I2C/SPI scan, memory check, pin read, diagnostics | Execute directly |
| Cautious | GPIO output, PWM, WiFi connect, file write on device | Inform user what you're about to do, then execute |
| Dangerous | Overwrite boot.py/main.py, format filesystem, OTA update, flash firmware | **Must get explicit user confirmation**. Always backup first: `mpremote fs cp :boot.py /tmp/boot.py.bak` |

Hard constraints:
- Never hardcode WiFi passwords in scripts saved to device — use variables or prompt user
- All loops must have iteration limits or timeouts — never generate infinite loops without exit conditions
- Before overwriting boot.py or main.py, always backup the existing file first
- Before controlling high-current devices (motors, relays), ask user to confirm wiring

For complete recovery procedures, read `./references/safety.md`.

## Workflow

As the Agent operating this co-processor, follow this mental model:

1. **Understand intent** — What does the user want to achieve with the hardware?
2. **Check connection** — Run device_probe.py if you haven't yet. Know your device's platform and capabilities.
3. **Route to sub-skill** — Read the relevant sub-skill SKILL.md for code templates and domain knowledge
4. **Generate code** — Write MicroPython code following the output protocol. Adapt pin numbers and parameters to the target platform.
5. **Push and capture** — Execute via mpremote or WebREPL, capture full stdout
6. **Parse results** — Extract RESULT:/ERROR: lines, parse JSON data
7. **Decide next step** — If ERROR, diagnose and adjust. If RESULT, present to user or use for next operation.
8. **Maintain state** — Remember which pins are in use, which peripherals are initialized, what the device's platform is
9. **Offer persistence** — After a program runs successfully, ask the user if they want to save it to the device or set it to auto-start on boot

## Program Persistence

After a program runs successfully, offer the user two options:

### Option 1: Save to Device (for later manual use)

Save the script to the device's filesystem so it can be run anytime without re-uploading:

```bash
# Save script to device
mpremote fs cp local_script.py :my_program.py

# List saved scripts on device
mpremote fs ls

# Run a saved script
mpremote exec "exec(open('my_program.py').read())"
```

This is a **Cautious** operation — inform the user before writing files to the device.

### Option 2: Auto-start on Boot (write to main.py)

If the user wants the program to run automatically every time the device powers on:

1. **Always ask first** — "要设置为开机自动运行吗？注意：如果程序有问题可能导致设备无法正常连接。"
2. **Backup existing main.py** (if any):
   ```bash
   mpremote fs cp :main.py ./main.py.bak
   ```
3. **Upload as main.py**:
   ```bash
   mpremote fs cp local_script.py :main.py
   ```
4. **Important**: For auto-start scripts, wrap the main logic in a try/except and add a short startup delay so the user can interrupt if needed:
   ```python
   import time
   time.sleep(2)  # 2s window for Ctrl-C interrupt
   # ... main logic ...
   ```

This is a **Dangerous** operation — require explicit user confirmation.

### Disable Auto-start

If the device becomes hard to access due to a problematic main.py:
```bash
# Rename to disable (if mpremote can still connect)
mpremote exec "import os; os.rename('main.py', 'main.py.disabled')"
mpremote reset

# Or delete it
mpremote exec "import os; os.remove('main.py')"
mpremote reset
```

If the device is completely unresponsive, follow the recovery steps in `./references/safety.md`.

## Platform Adaptation

After probing, adapt code to the detected platform:

| Platform | Key Capabilities |
|----------|-----------------|
| esp32 / esp32s3 | WiFi, BLE, Touch Pad, Deep Sleep, ULP, Hall Sensor |
| rp2040 | PIO state machines, dual core, no WiFi (unless Pico W) |
| stm32 | More timers, CAN bus, DAC |
| Generic | Standard `machine` module API only |

For ESP32-specific pin maps and APIs, read `./references/esp32.md`.

## Reference Files

Read these on demand — not every interaction needs them:

| File | When to Read |
|------|-------------|
| `./references/connections.md` | Troubleshooting connection issues, mpremote advanced usage, WebREPL protocol details |
| `./references/esp32.md` | ESP32-specific pin maps, strapping pin warnings, deep sleep, NVS, BLE/WiFi API details |
| `./references/safety.md` | Device recovery, boot.py restore, filesystem repair, electrical safety |

## Dependencies

Agent-side requirements:
- `mpremote` — `pip install mpremote` (required for USB connection)
- `esptool` — `pip install esptool` (required for chip detection and firmware flashing)
- `pyserial` — `pip install pyserial` (required on **Windows** for COM port auto-detection; recommended on all platforms)
- `websocket-client` — `pip install websocket-client` (only needed for WiFi/WebREPL mode)
- Python 3.8+

> **Windows notes**:
> - Use `python` instead of `python3` to run scripts. On many Windows systems, `python3` is a Microsoft Store stub that returns exit code 49. On macOS/Linux, use `python3`.
> - Without `pyserial`, the scripts fall back to parsing the `mode` command output for COM port detection, which provides less detail (no VID/PID info). Install `pyserial` for best results.

Device-side requirements:
- MicroPython firmware v1.19+ (v1.22+ recommended) — auto-installed by `firmware_flash.py` if missing
- USB connection or WiFi reachability

## External Endpoints

This skill accesses external services during specific operations:

| Endpoint | When Accessed | Purpose | Required? |
|----------|--------------|---------|-----------|
| `https://micropython.org/download/{board}/` | Firmware flashing only (`firmware_flash.py`) | Download latest stable MicroPython firmware binary for the detected chip | Only when flashing firmware |
| `https://micropython.org/resources/firmware/...` | Firmware flashing only | Direct firmware `.bin` download URL | Only when flashing firmware |

No telemetry, analytics, or data is sent to any external service. The skill operates entirely locally except for firmware downloads.

## Security & Privacy

- **No data collection**: This skill does not collect, transmit, or store any user data
- **No telemetry**: No usage analytics, crash reports, or tracking of any kind
- **Local-only operation**: All device communication happens over local USB serial or local WiFi (WebREPL). No cloud relay or proxy is used
- **WiFi credentials**: When provided by the user, WiFi credentials are passed directly to the device via `mpremote` and written to the device's `boot.py`. They are never logged, stored on the host machine, or transmitted to external services
- **Firmware source**: Firmware binaries are downloaded exclusively from `micropython.org`, the official MicroPython project site
- **File system access**: Helper scripts only access serial ports and the system temp directory (for firmware caching). No other host files are read or modified

## Trust & Verification

- **Open source**: Full source code is available at the homepage repository
- **No obfuscation**: All Python scripts and Markdown files are human-readable
- **Auditable**: The `scripts/` directory contains 4 self-contained Python scripts with no external dependencies beyond `mpremote`, `esptool`, `pyserial`, and `websocket-client`
- **Evals included**: The `evals/evals.json` file contains 5 test scenarios covering device probe, sensor read, actuator control, diagnostics, and recovery