feat(ota): Python OTA-over-USB host tool + idf.py ota-usb build target

[finger563]

Adds espp_ota, a pure-Python host tool that OTA-updates an espp device over
USB using the existing stream_frame framing + OTA stream protocol (dispatcher
module 0) — the same protocol the ota example
serves and ota_console.html drives from
the browser. No device-side changes; this is the missing host counterpart, plus
a build-system hook so it's painless.

Seamless: build → OTA with one command

components/ota/project_include.cmake registers an ota-usb build target, so any
project that uses the ota component gets the OTA counterpart to idf.py flash:

pip install pyusb          # once (needs a libusb backend)
idf.py ota-usb            # builds the app, then OTAs it over USB

The build dependency on gen_project_binary is wired via a deferred call (that
target is created after project_include.cmake runs); on CMake < 3.19 the
explicit idf.py build ota-usb form works. Device/port overrides come from
ESPP_OTA_* env vars.

The tool (components/ota/python/espp_ota/)

Layered like espp_odrive:

• frame.py — stream_frame v2 codec + resynchronizing StreamParser (stdlib only).
• protocol.py — OTA opcodes (Begin/Data/Finish/Abort → Ok/Error/Progress).
• transport.py — pyusb vendor-interface transport (discovers the 0xFF
  interface + its bulk IN/OUT endpoints; VID/PID default 0x1209:0x0d32). pyusb
  is imported lazily so the codec/protocol stay stdlib-only.
• client.py — the session driver (one request in flight, progress, error handling).
• cli.py — python -m espp_ota {flash,list,discover}.

Also shipped in the espp wheel (wheel.packages) with a usb extra (pyusb)
and an espp-ota console script.

Testing

• Host tests (components/ota/python/tests/test_ota_host.py, plain python3):
  codec round-trips + resync, CRC against the C++ golden 0xCBF43926, and a
  full OTA against a mock device (correct chunking, progress, FINISH, and the
  ERROR path).
• The CMake target + deferred app-build dependency validated in an isolated
  harness (ninja ota-usb runs the build step before the flash step).
• Graceful, actionable error when pyusb is absent.
• On-device USB flash end-to-end

🤖 Generated with Claude Code

[github-actions]

✅Static analysis result - no issues found! ✅

[Copilot]

🟡 Changes recommended

Unresolved moderate findings affect OTA cleanup, reply validation, USB lifecycle and error handling, timeout propagation, and serial filtering.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a pure-Python OTA-over-USB host tool and integrates it with ESP-IDF through an idf.py ota-usb target.

Changes:

• Adds framing, protocol, PyUSB transport, client, and CLI layers.
• Packages the tool with an optional pyusb dependency and console entry point.
• Adds documentation, host tests, and deferred CMake integration.

File summaries

File	Reviewed changes and findings
pyproject.toml	Packages espp_ota, its USB extra, and CLI entry point.
components/ota/README.md	Documents build-to-OTA usage.
components/ota/python/tests/test_ota_host.py	Adds mock-device OTA tests. Nit (2 votes): add independent CRC golden and resynchronization fixtures.
components/ota/python/README.md	Documents installation, CLI, library, and protocol usage.
components/ota/python/espp_ota/transport.py	Implements PyUSB transport. Moderate: address configuration selection, driver reattachment, failed-open cleanup, USB error conversion, and timeout classification.
components/ota/python/espp_ota/protocol.py	Defines OTA messages and payload helpers.
components/ota/python/espp_ota/frame.py	Implements frame encoding and parsing.
components/ota/python/espp_ota/client.py	Implements OTA sessions and discovery. Moderate: add abort cleanup, validate reply/discovery frames, preserve original errors during abort, and pass transaction timeouts to writes.
components/ota/python/espp_ota/cli.py	Provides CLI commands. Moderate (1 vote): apply --serial to device listing.
components/ota/python/espp_ota/__main__.py	Enables module execution.
components/ota/python/espp_ota/__init__.py	Exposes the public API.
components/ota/project_include.cmake	Registers the ota-usb build target.

Review details

Suppressed comments (9)

components/ota/python/espp_ota/cli.py:111

• The list parser exposes --serial, but this call drops args.serial, so espp-ota list --serial ... prints every matching VID/PID device instead of applying the documented selector. Thread the serial predicate through list_devices (or filter each device by serial) before producing the list.

    found = list_devices(vid=args.vid, pid=pid)

components/ota/python/espp_ota/client.py:110

• This method is marked best-effort but suppresses only OtaError. A USB transport can raise TransportError (or another I/O exception), so failure cleanup through abort() can itself escape and mask the original flash error; suppress transport-side exceptions here as well.

    def abort(self) -> None:
        try:
            self._transact(_p.make_abort(), self._data_to)
        except OtaError:
            pass  # best-effort

components/ota/python/espp_ota/client.py:61

• The timeout selected by each transaction is not used for the USB write: BEGIN and FINISH calls pass their 60-second timeouts into _transact, but this line always uses the DATA timeout instead. Pass timeout_ms here so the transport honors the timeout configured for the current operation.

        self._t.write(request, timeout_ms=self._data_to)

components/ota/python/espp_ota/transport.py:110

• open() assumes that libusb already selected a configuration and calls get_active_configuration() immediately. A freshly enumerated device can have no active configuration, causing the CLI to fail before it discovers the vendor interface; the browser path explicitly selects configuration 1 when needed. Handle the no-active-configuration case by selecting the device's configuration before walking its interfaces.

        cfg = dev.get_active_configuration()

components/ota/python/espp_ota/transport.py:158

• open() may detach a kernel driver at lines 115-120, but close() only releases the interface and disposes resources. libusb does not automatically reattach a detached Linux kernel driver, so closing after a flash can leave that interface unavailable until the device is replugged; track whether detachment succeeded and reattach it after release.

            if self._claimed and self._itf_num is not None:
                self._util.release_interface(self._dev, self._itf_num)
        except Exception:
            pass
        try:

components/ota/python/espp_ota/transport.py:113

• After _dev is assigned, an exception from get_active_configuration(), interface discovery, or claim_interface() exits open() without cleanup. _cmd_flash only closes after _open_transport() succeeds, and __enter__ does not call __exit__ when open() fails, so a failed open can leak USB resources and leave a detached kernel driver unrecovered.

        cfg = dev.get_active_configuration()
        itf, ep_in, ep_out = self._find_vendor_interface(cfg)
        self._itf_num = itf.bInterfaceNumber
        self._ep_in, self._ep_out = ep_in, ep_out

components/ota/python/espp_ota/transport.py:185

• Non-timeout USB errors are re-raised as the backend's USBError, but cli.main() catches only OtaError and TransportError. A disconnect or access failure during a read therefore escapes as a traceback instead of the CLI's actionable error path; wrap non-timeout failures in TransportError here.

        except self._core.USBError as exc:
            # errno 110 == ETIMEDOUT; pyusb>=1.1 raises the USBTimeoutError subclass.
            if getattr(exc, "errno", None) in (110, None) or "timeout" in str(exc).lower():
                return b""
            raise

components/ota/python/espp_ota/transport.py:175

• Endpoint.write() can also raise a raw USBError, which bypasses the CLI's TransportError handler and produces a traceback instead of the normal actionable error path. Convert the endpoint exception to TransportError, matching the read-side error contract.

    def write(self, data: bytes, timeout_ms: int = 5000) -> None:
        n = self._ep_out.write(data, timeout_ms)
        if n != len(data):
            raise TransportError(f"short write: {n}/{len(data)} bytes")

components/ota/python/espp_ota/transport.py:183

• Treating errno is None as a timeout hides non-timeout USBError instances, since backend/disconnect errors can also omit an errno. The client then spins until the deadline and reports a misleading reply timeout instead of surfacing the transport failure; only accept a timeout-specific errno/subclass/message here.

            if getattr(exc, "errno", None) in (110, None) or "timeout" in str(exc).lower():

• Files reviewed: 12/12 changed files
• Comments generated: 4
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 5 comments.

[Copilot]

🟡 Changes recommended

Retry recovery and routine USB-error handling have unresolved failure paths.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 14/14 changed files
• Comments generated: 3
• Review effort level: Balanced