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:

python3 {SKILL_DIR}/scripts/device_probe.py

Execute code on device:

mpremote exec "import machine; print('RESULT:' + str(machine.freq()))"

Run a script file:

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:

   python3 {SKILL_DIR}/scripts/wifi_setup.py --ssid "SSID" --password "PASS" --webrepl-password "repl123"
   

   python3 {SKILL_DIR}/scripts/webrepl_exec.py --host 192.168.1.100 --password repl123 --code "print('hello')"
   

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:

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:

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:

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:

# 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):

   mpremote fs cp :main.py ./main.py.bak
   

   mpremote fs cp local_script.py :main.py
   

   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:

# 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:

> 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:

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

Trust & Verification

> 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.