MicroPython and CircuitPython skill for Codex

Done well means: the code is deployed with a repeatable command, main.py cannot lock the user out of the REPL, the board recovers on its own from Wi-Fi loss and exceptions, and memory stays flat over a long run.

Identify the runtime first

Clue	Runtime	Deploy with
main.py, boot.py, REPL banner “MicroPython v1.2x”	MicroPython	mpremote
code.py, a CIRCUITPY USB drive, lib/adafruit_*.mpy	CircuitPython	Copy to the drive; circup for libraries

The two share syntax but not APIs: MicroPython uses machine.Pin, CircuitPython uses board plus digitalio/busio. Never mix examples. Read AGENTS.md and the repo layout, then ask the user for the board and firmware version (import sys; sys.implementation).

MicroPython workflow with mpremote

pip install mpremote                       # network
mpremote devs                              # list serial devices
mpremote connect /dev/ttyACM0 fs ls
mpremote cp -r lib/ :                      # copy the lib folder to the board root
mpremote cp main.py :main.py
mpremote run scratch.py                    # run without saving to the board
mpremote mount .                           # board sees the local folder; fast iteration
mpremote mip install aioble                # install from micropython-lib (board needs no network; host does)
mpremote reset
mpremote repl                              # Ctrl-] or Ctrl-x to exit

Codex rarely has the serial port in its sandbox. Prepare files and the exact commands; let the user run them and paste the REPL output.

Flashing firmware itself: .uf2 drag-and-drop for RP2040/RP2350 (hold BOOTSEL); for ESP32 use esptool (esptool.py --chip esp32 erase_flash, then write_flash 0x1000 firmware.bin; the offset is 0x0 for S3 and C3). Erasing wipes the file system; confirm with the user that nothing on the board needs saving first.

Project layout

boot.py      # minimal: nothing that can hang
main.py      # tiny entry point: import app; app.run()
app.py       # real code, importable and testable
lib/         # drivers, ideally precompiled .mpy
config.py    # pins and constants; secrets.py kept out of git

Give main.py an escape hatch so a crashing loop never needs a reflash:

# main.py
import time
from machine import Pin

if Pin(0, Pin.IN, Pin.PULL_UP).value() == 0:   # hold button at boot to skip
    print("safe start: app not launched")
else:
    time.sleep(2)                              # window to Ctrl-C from the REPL
    import app
    app.run()

Structure with asyncio

import asyncio
from machine import Pin, WDT

led = Pin("LED", Pin.OUT)          # Pico W naming; ESP32 uses a number

async def blink():
    while True:
        led.toggle()
        await asyncio.sleep_ms(500)

async def sample(q):
    while True:
        q.append(read_sensor())
        await asyncio.sleep(10)

async def main():
    wdt = WDT(timeout=8000)            # cannot be stopped once started; feed it
    q = []
    asyncio.create_task(blink())
    asyncio.create_task(sample(q))
    while True:
        wdt.feed()
        await asyncio.sleep(1)

def run():
    try:
        asyncio.run(main())
    finally:
        asyncio.new_event_loop()       # clean state if run() is called again from the REPL

On firmware older than 1.21 the module is uasyncio. Any blocking call (time.sleep, synchronous socket I/O) inside a task freezes every task.

Interrupts

import micropython
micropython.alloc_emergency_exception_buf(100)   # tracebacks from ISRs

count = 0
def _bump(_):
    global count
    count += 1

def on_edge(pin):                                # hard ISR on some ports: no allocation
    micropython.schedule(_bump, None)

Pin(15, Pin.IN, Pin.PULL_UP).irq(trigger=Pin.IRQ_FALLING, handler=on_edge)

No allocation (no lists, floats, string formatting) inside a hard ISR. Defer real work with micropython.schedule or set a flag that a task checks.

Memory

Symptom	Fix
MemoryError on import	Precompile modules with mpy-cross (version must match the firmware’s .mpy format) or freeze them into firmware
Free memory shrinks over hours	Allocations in the loop: preallocate bytearray buffers, use readinto, avoid string concatenation
Fragmentation, large allocations fail though mem_free is high	Allocate big buffers once at start; call gc.collect() before them
Slow numeric loop	@micropython.native or @micropython.viper on that function only

import gc
gc.collect()
print("free", gc.mem_free(), "alloc", gc.mem_alloc())

Log gc.mem_free() every minute during soak tests; a downward trend is a leak.

Wi-Fi (Pico W, ESP32)

import network, time

def connect(ssid, pw, timeout=20):
    wlan = network.WLAN(network.STA_IF)
    wlan.active(True)
    if not wlan.isconnected():
        wlan.connect(ssid, pw)
        t0 = time.ticks_ms()
        while not wlan.isconnected():
            if time.ticks_diff(time.ticks_ms(), t0) > timeout * 1000:
                raise OSError("wifi timeout")
            time.sleep_ms(200)
    return wlan.ifconfig()[0]

Re-check isconnected() before every send and reconnect with backoff. Use time.ticks_diff, never raw subtraction, because tick counters wrap.

CircuitPython specifics

• Libraries: circup install adafruit_bme280 then circup update (needs network on host).
• Wi-Fi credentials go in settings.toml as CIRCUITPY_WIFI_SSID and CIRCUITPY_WIFI_PASSWORD; read other keys with os.getenv.
• The drive auto-reloads on save; writing files from code needs boot.py to remount (storage.remount("/", readonly=False)), which makes the drive read-only to the host.
• Use the asyncio library from the Adafruit bundle (circup install asyncio) or a time.monotonic() scheduler instead of time.sleep loops.

Deep sleep

machine.deepsleep(60_000) resets the board on wake; state lives only in RTC memory (machine.RTC().memory() on ESP32) or flash. Check machine.reset_cause() at boot. Deep sleep disconnects USB, so the REPL disappears; keep a safe-start path.

Verification

• Files deployed with one documented mpremote (or copy) command
• Safe-start path tested: board boots to REPL with the button held
• Soak test of at least an hour with gc.mem_free() logged: no downward trend
• Wi-Fi off and on during the run: device reconnects without reset
• Unhandled exception path leads to a watchdog reset, not a silent hang

Report

**Board:** Pico W, MicroPython v1.24.1
**Change:** loop rewritten as 3 asyncio tasks; ISR defers via micropython.schedule; WDT 8 s
**Memory:** free heap stable at 142-146 KB over 2 h (was falling 3 KB/min)
**Deploy:** `mpremote cp -r lib/ : + cp app.py main.py :`
**Open:** BME280 driver still .py; precompile with mpy-cross if heap gets tight