From af6a6543371e9f9a575da6c7ac8e69c505f0b3a3 Mon Sep 17 00:00:00 2001 From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com> Date: Sat, 21 Nov 2026 14:53:09 -0600 Subject: [PATCH] usb.core: the ESP32-P4 needs no full_speed=True behind a high-speed hub The P4's firmware now builds the registry's USB host library with split transactions, as the S31's does, so keyboards and MIDI controllers work behind a high-speed hub. start()'s docstring, the support table, the USB guide and the WIFI6 DEV-KIT board config say so, and keep full_speed=True for P4 firmware on ESP-IDF's own host library. Checked on the DEV-KIT's onboard hub: an Arturia KeyStep Pro at full speed and a flash drive at high speed together, with no full_speed. --- .../board_peripherals.py | 7 ++++--- docs/guides/usb.md | 13 ++++++------ docs/reference/usb-support.md | 2 +- packages/usb/usb-core/usb/core.py | 21 +++++++++---------- 4 files changed, 22 insertions(+), 21 deletions(-) diff --git a/board_configs/nodisplay/esp32-p4-wifi6-dev-kit/board_peripherals.py b/board_configs/nodisplay/esp32-p4-wifi6-dev-kit/board_peripherals.py index c89ebbf0..9039ade4 100644 --- a/board_configs/nodisplay/esp32-p4-wifi6-dev-kit/board_peripherals.py +++ b/board_configs/nodisplay/esp32-p4-wifi6-dev-kit/board_peripherals.py @@ -44,9 +44,10 @@ speaker connector, the end labelled DEVICE (the labels read the opposite way to what they do), it goes to the onboard CH334F hub: J8's upper socket and both J2 sockets work at once and J8's lower one goes dead. - Behind that hub only high-speed devices enumerate, unless the host is - started at full speed (``usb.core.start(full_speed=True)``), which lets keyboards, - MIDI controllers and other full-speed devices through. J8's 5 V is not + The hub is high speed, and keyboards, MIDI controllers and other + full-speed devices behind it work through its transaction translator; a + firmware built on ESP-IDF's own host library can't do that, and needs the + host started at full speed (``usb.core.start(full_speed=True)``). J8's 5 V is not switched, so a device stays powered through a board reset, and so does the hub (it runs from the 3.3 V rail): don't change the host's speed between two starts in one run, because restarting it at the other speed can leave diff --git a/docs/guides/usb.md b/docs/guides/usb.md index ff31b910..e3fbf651 100644 --- a/docs/guides/usb.md +++ b/docs/guides/usb.md @@ -362,12 +362,13 @@ the interpreter: `Speaker.c_sink()` hands that module a sink it writes from its own task. A microphone can too: `Microphone.start(ring)` with an audiodsp `audiopump.Ring` feeds the pump straight from the bus. -On the ESP32-P4 the host's port is high speed, so a keyboard or MIDI -controller behind a hub needs `usb.core.start(full_speed=True)`. The -ESP32-S31's host does split transactions, so there they work behind a -high-speed hub, and a camera on the same hub keeps its high speed. On the -ESP32-P4 WIFI6 DEV-KIT, whose onboard hub nothing in software can power off, -choose that speed once per power-up: a restart at the other speed can leave +The ESP32-P4's and the ESP32-S31's host ports are high speed, and their hosts +do split transactions, so a keyboard or MIDI controller works behind a +high-speed hub and a drive or camera on the same hub keeps its high speed. A +P4 firmware built on ESP-IDF's own host library can't, and there a keyboard +behind a hub needs `usb.core.start(full_speed=True)`. On the ESP32-P4 WIFI6 +DEV-KIT, whose onboard hub nothing in software can power off, choose the +speed once per power-up: a restart at the other speed can leave the hub dead until the board loses power, so `usb.core.start()` refuses it and says so. Stopping and starting at the same speed is fine. diff --git a/docs/reference/usb-support.md b/docs/reference/usb-support.md index efd69232..12442305 100644 --- a/docs/reference/usb-support.md +++ b/docs/reference/usb-support.md @@ -45,7 +45,7 @@ are in | A high-speed link | ESP32-S2, S3, GIGA | Their host ports are full speed | | A webcam and a USB Audio 2.0 speaker in one session | ESP32 | The controller's FIFO split is fixed for each `usb.core.start()`, and a camera and a speaker need different splits | | Every device at once | ESP32-S3 | The host has eight channels (the P4 and S31 have sixteen). A device's control pipe takes one, a bulk pair two and an interrupt IN one, so a drive and a keyboard fit and a drive and a MIDI controller don't | -| Full- and low-speed devices behind a hub | ESP32-P4 | The port runs at high speed, and the host there can't send split transactions to a hub's transaction translator. Start the host with `usb.core.start(full_speed=True)`, which slows the whole bus. The S31's host sends them, so it doesn't need this | +| Full- and low-speed devices behind a high-speed hub | ESP32-P4 firmware on ESP-IDF's own host library | That host can't send split transactions to a hub's transaction translator, so start it with `usb.core.start(full_speed=True)`, which slows the whole bus. Firmware with the registry's host library sends them on the P4 and the S31 | ## Device: what a board can present diff --git a/packages/usb/usb-core/usb/core.py b/packages/usb/usb-core/usb/core.py index cfc8ff85..3f3b9605 100644 --- a/packages/usb/usb-core/usb/core.py +++ b/packages/usb/usb-core/usb/core.py @@ -18,11 +18,11 @@ # endpoint's interface is claimed the first time you use it. # # The host starts with the first find(), or with start(), which takes -# full_speed=True to hold the port to full speed: on an ESP32-P4, whose port -# is high speed, that's how full- and low-speed devices behind a hub work -# (ESP-IDF 5.5's host there can't send split transactions). The ESP32-S31's -# host does split transactions, so they work behind a high-speed hub as they -# are. Underneath is ESP-IDF's USB host library, driven by the firmware's +# full_speed=True to hold the port to full speed. The ESP32-P4's and the +# ESP32-S31's hosts do split transactions, so full- and low-speed devices +# work behind a high-speed hub as they are; a P4 firmware built on ESP-IDF +# 5.5's own host library can't send them, and there full_speed=True is how +# they work. Underneath is ESP-IDF's USB host library, driven by the firmware's # _usbhost C module (omnipython-builds' modules/usbhost). # # One speed per power-up on the ESP32-P4 WIFI6 DEV-KIT: its onboard hub can't @@ -125,9 +125,10 @@ def start(full_speed=False, classes=None, force=False): None asks for everything, which leans to IN. ``full_speed=True`` holds the port to full speed, and every high-speed - device with it. On an ESP32-P4 a keyboard or MIDI controller behind a - hub needs it, because the host there can't send split transactions. On - an ESP32-S31 they work behind a high-speed hub without it. + device with it. A keyboard or MIDI controller behind a high-speed hub + doesn't need it on an ESP32-P4 or S31, whose hosts send split + transactions; a P4 firmware built on ESP-IDF's own host library can't, + and there it needs ``full_speed=True``. ``full_speed`` can't change after the host has run on the ESP32-P4 WIFI6 DEV-KIT. Its onboard hub gets its power from the board's 3.3 V rail and @@ -136,9 +137,7 @@ def start(full_speed=False, classes=None, force=False): both speeds, until the board is power-cycled. There ``start()`` raises ``USBError`` instead, before it touches the host, and the running host is left as it was. Stopping and starting at the same speed is fine, and - so is a different ``classes``. Choose the speed once per power-up: - ``full_speed=True`` if a keyboard or MIDI controller will be behind the - hub, False otherwise. The memory is the interpreter's: a soft reset + so is a different ``classes``. Choose the speed once per power-up. The memory is the interpreter's: a soft reset forgets it, and the hub doesn't. ``force=True`` skips the check, for a board whose host jumper sends the port straight to a socket, past the hub.""" global _started, _full_speed, _classes, _ran_full_speed