Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
13 changes: 7 additions & 6 deletions docs/guides/usb.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/usb-support.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
21 changes: 10 additions & 11 deletions packages/usb/usb-core/usb/core.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down