esptest.devices.usb_hub module

Control USB hub port power via the uhubctl command line tool.

This wraps uhubctl to switch USB hub ports on/off/cycle and to power-cycle a port only when nothing is enumerated on it (useful to recover devices that failed to come up after a flash/reset).

The USB location string understood by parse_hub_and_port() matches the sysfs path used elsewhere in this package (e.g. 1-6.1.2), so it can be fed directly from a serial port location.

exception esptest.devices.usb_hub.UsbHubError[source]

Bases: OSError

Raised when a uhubctl command fails.

esptest.devices.usb_hub.parse_hub_and_port(data)[source]

Split a USB location string into (hub, port) understood by uhubctl.

Examples

1-6.1.2 -> ('1-6.1', '2') 1-6.1.2:1.0 -> ('1-6.1', '2') (:1.0 interface suffix dropped) 1-6 -> ('1', '6')

Parameters:: data (str)
Return type:: Tuple[str, str]

esptest.devices.usb_hub.port_has_device(line)[source]

Return True if a uhubctl status line shows an enumerated device.

Parameters:: line (str)
Return type:: bool

esptest.devices.usb_hub.should_reset(line)[source]

Return True if the port has no enumerated device and should be reset.

Parameters:: line (str)
Return type:: bool

esptest.devices.usb_hub.find_port_line(output, hub, port)[source]

Return the Port <port>: status line that belongs to hub.

uhubctl may list several hubs (e.g. the USB2 and USB3 companion) so we only look at lines under the requested Current status for hub <hub> header.

Parameters:

output (str)
hub (str)
port (str)

Return type:

class esptest.devices.usb_hub.UsbPortStatus(hub: str, port: str, line: str)[source]

Bases: object

Parameters:

hub (str)
port (str)
line (str)

hub: str

port: str

line: str

property has_device: bool

property power_on: bool

class esptest.devices.usb_hub.UsbHubControl(timeout=15, sudo=False)[source]

Bases: object

Parameters:

timeout (float)
sudo (bool)

get_status_output(hub, port)[source]

Return the raw uhubctl -f -l <hub> -p <port> status output.

Parameters:

hub (str)
port (str)

Return type:

get_port_status(hub, port)[source]

Parameters:

hub (str)
port (str)

Return type:

UsbPortStatus

set_power(hub, port, action)[source]

Run uhubctl -a <action> on the port and return its stdout.

Parameters:

hub (str)
port (str)
action (str)

Return type:

smart_reset(hub, port)[source]

Power-cycle the port only when no device is currently enumerated.

Returns the uhubctl cycle output, or None if the reset was skipped because a device is already present on the port.

Parameters:

hub (str)
port (str)

Return type:

str | None