Skip to content

feat(rp2040,windows): preflight PICOBOOT WinUSB driver binding and classify code-28 failures #1163

Description

@zackees

Problem

On the #1161 reproduction host, the BOOTSEL device's PICOBOOT interface (2E8A:0003 MI_01) shows Windows problem code 28 (no compatible driver). fbuild's managed picotool fallback (crates/fbuild-deploy/src/rp2040_picotool.rs) does not detect this state — it just runs picotool load and surfaces whatever error text comes back, plus a generic hint appended in format_failure.

If PICOBOOT becomes the primary transport (sibling sub-issue), a missing WinUSB binding turns into the first failure every affected Windows host hits, so it needs first-class detection and guidance.

Proposal

  1. Preflight: before attempting a PICOBOOT load on Windows, enumerate the VID_2E8A&PID_0003 MI_01 devnode and read its problem code (fbuild already has devnode enumeration machinery from fix(windows): enumerate problem devices by USB enumerator, not setup class #1157).
  2. Classify: problem code 28 (or CM_PROB_FAILED_INSTALL-family codes) → fail fast with the Raspberry Pi-documented WinUSB binding guidance ("bind WinUSB to RP2 Boot (Interface 1)"), instead of letting picotool emit a libusb open error. Distinguish this cleanly from device/transport failures in deploy error classification.
  3. Investigate auto-binding: modern RP2040 boot ROMs expose MS OS 2.0 descriptors that should auto-bind WinUSB on Windows 10+. The observed code 28 may be a stale driver cache / INF ranking issue rather than expected behavior. One investigation pass to determine why auto-binding failed on this host, and whether fbuild can detect or remediate that state (fbuild must not silently install drivers; guidance only unless a safe, documented remediation exists).

Acceptance

  • On a host with no WinUSB binding, fbuild deploy fails in under a few seconds with a specific, actionable driver message naming the exact devnode, not a generic picotool/libusb error.
  • On a healthy host, the preflight adds negligible latency.
  • Error classification is unit-tested (driver-missing vs device failure vs transport failure).

Part of the meta issue tracking the #1161 transport strategy change. Defaults chosen by the drafting agent are listed inline — edit as needed.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Status
    Triage

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions