MicroPython 1.28 → 1.29 pin move: retool checklist

[bdbarnett]

MicroPython v1.29.0 shipped 2026-08 (we pin 1.28.0 in cmods). Brad's headline: the new manifest c_module() — declaring user C modules in manifest.py, intended to replace USER_C_MODULES — is the better story for 'cmods is optional' and the reason to retool. Checklist of everything else in the notes that touches us, for whenever the pin moves (a deliberate phase, not a drive-by):

The retool opportunity

• c_module() in manifests replaces the USER_C_MODULES symlink-glob discovery — this can retire workspace-craft's entire symlink include/exclude section (new-module drift, stale-symlink persistence) in favor of explicit per-build declarations. Design the cmods shape around it.
• micropython#19667 (BUILD= qstr pollution) is still OPEN upstream — the never-pass-BUILD= rule survives 1.29; watch for the promised community PR.

Patch-series re-port risks

• TinyUSB bumped to 0.21.0 — usbif's patches (extension header, IAD policy, speed-aware descriptor service, PHY handoff) sit directly on this; expect a re-port pass, coordinate with the usbif program.
• IDF v5.5.2 — re-test usbif's open P4 defects against it (P4 HS-host detects nothing — 'suspect IDF P4 host support'; P4 FS-device EP0 stall). The bump may resolve or reshape them.
• Verify all series profiles apply/reverse cleanly against v1.29.0 before it becomes the pin.

New upstream capability with completeness implications

• network.USBD_NCM (Ethernet-over-USB, off by default) — a new USB device class exists upstream; usbif's costume roster should deliver it or record the exclusion with cause (org design principle 1).

Breaking changes to sweep for

• machine.SDCard.readblocks/writeblocks return semantics reversed (bool → 0/negative) — grep board code and examples.
• Encoding validation strict: only utf-8/utf8/ascii; latin-1 now raises LookupError — grep the tree.
• esp32 firmware ~+1.6% — check the P4/S3 partition headroom with usbif + LVGL aboard.

Consumers to re-verify after the move

• lvgl-bindings/fonts regenerate (standing rule on any pin move)
• wasm port / Workbench simulator boot
• vst3 engine build (unix/windows make ports; MICROPY_FORCE_32BIT was removed from unix — confirm nothing references it)
• rp2 pico-sdk 2.3.0 — Pico 2 W BLE still green

No date; the pin moves when a program needs it, per house practice.

[bdbarnett]

Decision: usbif's MicroPython patches move here — at the pin move, not before

Brad routed this one to me as a whole-board call. Recording it here rather than in a transcript, because the pin move is where it gets executed.

They belong here. All four usbif patches modify the MicroPython tree — shared/tinyusb/tusb_config.h, shared/tinyusb/mp_usbd.h (×2), and ports/esp32/usb.c. That is precisely what this repo's README says it carries: every downstream patch, usermod, and variant PyDevices maintains on top of a pinned upstream release.

The "but they serve one module" objection is already answered by precedent. 0009-micropython-esp32s3-add-SPIRAM_OCT_JTAG-debug-variant.patch serves exactly one narrow workflow — JTAG debugging — and is exposed through a one-line profile, esp32-s3-debug.series. And vst3-engine.series shows profiles being used for deliberate exclusion. A usbif.series profile is the idiomatic shape here, not a special case.

It also collapses a two-copy arrangement. The modernization ledger's ownership rule (§8.5) is that no patch has two undocumented source-of-truth copies. Today the queue is authored in usbif/patches/ and hand-mirrored into cmods/patches/usbif-NN-*. That is now documented in cmods/patches/README.md, so it satisfies the rule narrowly — but it satisfies it by writing the exception down, not by removing it. Moving here leaves one authoring home with a mechanical consumer.

Why not now

Moving today puts a three-repo hop — author here, publish, bump MICROPYTHON_PYDEVICES_COMMIT in cmods — on every iteration of a queue that changed six times in two days, on the critical path of a program that is roughly 80% delivered. That is real friction bought for no benefit that expires.

Why the pin move is the free moment

• This repo's own rule: moving UPSTREAM re-validates every patch anyway.
• usbif's patches need a re-port pass against TinyUSB 0.21.0 at that same moment, which is already on this checklist.
• By then usbif will be through its remaining gates and the queue will have stopped moving.

Doing the migration while every patch is already being re-validated costs almost nothing extra. Doing it now costs friction on every commit until then.

What this adds to this checklist

• Migrate usbif's four patches from usbif/patches/ into this series, renumbered into the mailbox order.
• Add a usbif.series profile (and fold in the two board-header patches that currently live only in cmods).
• Retire cmods/patches/usbif-NN-* and the hand-mirror note in cmods/patches/README.md.
• Point usbif's README and apply_patches.sh at the overlay as the authoring home.
• Keep the per-patch discipline the completeness inspection praised — purpose, provenance, upstream-version range, test — which is the reason this queue is worth moving rather than copying.

Interim: nothing changes. The current usbif-NN- split stays; it is stable, documented, and outside the glob sync_from_overlay.sh owns. Reversible if Brad disagrees — no code has moved.

[bdbarnett]

Refinement to the trigger: "the queue has stopped moving," not the calendar

Sharpened by the usbif session, and it corrects my framing above. I wrote at the pin move, which reads as a date. The actual precondition is queue stability; the pin move is simply the moment when the migration is nearly free, because UPSTREAM moving re-validates every patch anyway.

The six-changes-in-two-days figure that argued against moving now is not decoration — the queue moved because hardware kept teaching things: MSC on the S3 board, the hub Kconfig, the P4 board header. Every one of those was a discovery, not a revision.

So the rule for whoever executes this: if usbif is mid-stretch of hardware-driven churn when the pin move arrives, wait again. Migrating a queue that is still learning means re-doing the migration, and the three-repo hop makes each redo more expensive than the last. If the pin move and a quiet queue do not coincide, the quiet queue wins and the migration follows separately.

Recorded on the usbif side too, in usbif/docs/phase0-findings.md (usbif b5a0a43).

[bdbarnett]

ESP-IDF moves with this pin move (Brad, 2026-09-07): the IDF pin (cmods/esp-idf, v5.5.2 today) is to move at the same time as the MicroPython 1.29 move, and the P4 USB host defect (usbif#3) is re-tested on the new pair as part of it.

On the version: MicroPython master's esp32 README now reads "The current recommended version of ESP-IDF for MicroPython is v5.5.5. MicroPython also supports v5.3, v5.4, v5.4.1, v5.4.2, v5.5.1, v5.5.2 and v5.5.4." v5.5.3 is not in that list, and IDF's own v5.5.4 notes say why: "Fixed the issue of potential NimBLE host connection loss in ESP-IDF v5.5.3 release on ESP32 / ESP32C3 / ESP32S3." So the target is whichever of v5.5.4 / v5.5.5 the 1.29 tag's README names, not v5.5.3. What the later 5.5 patches change in components/usb is being read from the tags now and will be recorded on usbif#3.

Two USB facts that do not move with any 5.5.x pin, for the P4: the host stack's external-hub driver has no transaction translator (no FS/LS devices behind a hub on the HS host — still in the latest esp-usb docs), and only the HS OTG instance is a host in 5.5; the latest esp-usb brings up the FS instance too, which is an IDF 6 question.

[bdbarnett]

Read from the esp-idf tags (`git log v5.5.2..v5.5.5 -- components/usb …`), the USB changes the later 5.5 patches carry:

• v5.5.3: 6e972acc987 feat(esp_hal_usb): Add remote wakeup support; c5b01fc6276 fix(usb_host): Dont abort on unsupported client events (suspend/resume client events).
• v5.5.4: 33794f6b52c feat(esp_hw_support): set USB2.0 phy to suspend mode at startup for active power saving — ESP32-P4 only: at boot clk.c now forces the HS PHY into suspend (GOTGCTL.BvalidOvEn=1, PCGCCTL.StopPclk=1) and usb_dwc_hal_init clears both again. Anything that touches the P4's HS USB without going through that HAL init will find the PHY asleep after the move. 63f020f8e23 fix(host/usb): Fixed deadlock that prevented closing devices from high priority tasks.
• v5.5.5: USB as a light-sleep wakeup source; SOC_USB_FSLS_PHY_NUM; 57c4a88ac2f fix(usb/host): Fix incorrect IAD descriptor length; USB security fixes from esp-usb.

None of them is a fix for the P4 root port never reporting an attach (usbif#3). The re-test item stands, and the 5.5.4 PHY-suspend change is a second thing to watch on the P4 at the move: both the usbif host and the TinyUSB device path must go through the DWC HAL init that wakes the PHY.