API reference

The public API lives in st_uhubm; the implementation is in st_uhubm.cli_backend.

Hubs and the manager

class st_uhubm.cli_backend.HubManager(binary: str = 'cusbi', use_sudo: bool = True, password: str = '', persist: bool = False, timeout: int = 10, logger: Callable[[str], None] | None = None)

Configuration and command execution for one or more managed hubs.

A HubManager holds how to invoke StarTech’s cusbi / cusba binary — path, sudo, password, persistence, timeout — and turns its output into Hub objects. It is the single entry point to the hardware: discover() enumerates connected hubs and hub() returns one known hub with its state populated. Every Hub it produces is attached back to this manager, so the hub’s own methods reuse this config.

binary

Binary name or path ("cusbi" on x86/AMD64, "cusba" on ARM).

Type:

str

use_sudo

Run the binary via sudo (needed to open the tty unless a udev rule grants access).

Type:

bool

password

Hub password; sent with mutating commands when non-empty.

Type:

str

persist

When True, writes go straight to flash (/F) instead of the volatile /S form.

Type:

bool

timeout

Per-command timeout in seconds.

Type:

int

logger

Optional callable invoked with the exact argv and the binary’s output; used by the CLI --verbose flag and the GUI console.

Type:

Callable[[str], None] | None

Example

Discover hubs and turn every port on:

mgr = HubManager(binary="cusbi", use_sudo=True)
for hub in mgr.discover():
    hub.set_all(True)

discover() → list[Hub]

Find connected managed hubs and read their current state.

hub(port: str) → Hub

Return a Hub for a known control port, reading its state.

class st_uhubm.cli_backend.Hub(port: str, n_ports: int = 0, states: dict[int, bool]=<factory>, firmware: str = '?', serial: str = '?', model: str = '?', manager: HubManager | None = None)

A single managed USB hub, addressed by its serial control port.

A Hub is normally obtained from HubManager.discover() or HubManager.hub() rather than built directly, so it arrives attached to a HubManager that runs the binary on its behalf. The query and mutation methods go through that manager and keep states in sync, so reading states (or is_on()) right after a call reflects the change with no extra round-trip. Call refresh() to re-read the live state from hardware.

port

Control-port path the hub is addressed by, e.g. "/dev/ttyUSB0".

Type:

str

n_ports

Number of switchable downstream ports.

Type:

int

states

Map of 1-based port number to True (on) / False (off).

Type:

dict[int, bool]

firmware

Firmware revision reported by the hub, e.g. "v04".

Type:

str

serial

Hub serial number, or "?" if the hub did not report one.

Type:

str

model

Human-readable model string, or "?" if unknown.

Type:

str

manager

HubManager used to run commands; None until attached.

Type:

st_uhubm.cli_backend.HubManager | None

Example

Read a hub and switch one port off (cached state updates in place):

mgr = HubManager(use_sudo=False)
hub = mgr.hub("/dev/ttyUSB0")
hub.set_port(3, False)
assert hub.is_on(3) is False

change_password(old: str, new: str) → None

Change the hub password (/P). Updates the manager’s password.

is_on(n: int) → bool

Return whether port n is currently on, per cached state.

refresh() → Hub

Re-read live port states from the hub.

reset() → None

Hardware-reset the hub (/R).

restore_defaults() → None

Restore factory defaults: all ports on, password pass (/D).

save() → None

Save current port states to flash as the power-on default (/W).

set_all(on: bool, persist: bool | None = None) → None

Turn every port on or off in one command.

set_port(n: int, on: bool, persist: bool | None = None) → None

Turn a single port on or off (convenience wrapper for one port).

set_ports(ports: list[int], on: bool, persist: bool | None = None) → None

Turn a list of ports on or off in a single command.

toggle(n: int, persist: bool | None = None) → None

Invert port n and update its cached state.

Parsers

st_uhubm.cli_backend.parse_query_all(raw: str) → list[str]

Parse cusbi /Q -F output into a list of control ports (firmware v04+).

The record is the 4-digit hub count, a comma, then the full device paths:

"0001,/dev/ttyUSB0"               -> ["/dev/ttyUSB0"]
"0002,/dev/ttyUSB0,/dev/ttyUSB1"  -> ["/dev/ttyUSB0", "/dev/ttyUSB1"]

Returns an empty list if the input is empty or malformed; discovery falls back to device enumeration in that case rather than raising.

st_uhubm.cli_backend.parse_hub_info(raw: str) → tuple[int, dict[int, bool], str, str, str]

Parse cusbi /Q:<port> -F output (firmware v04+).

The comma-delimited record is:

"FBFFFFFF,7,v04,00020000149E,7-port Managed USB Hub"
# bitmap(hex), port count(dec), firmware, serial, model

Returns (n_ports, states, firmware, serial, model). The port-state bitmap is 32 bits, little-endian by byte; bit n-1 corresponds to port n (1 = on).

Raises HubParseError on malformed input.

st_uhubm.cli_backend.discover(**kwargs) → list[Hub]

Build a HubManager from kwargs and discover hubs.

Errors

Exception hierarchy for st_uhubm.

exception st_uhubm.errors.BinaryNotFound(binary: str)

The StarTech binary (cusbi/cusba) could not be located.

exception st_uhubm.errors.HubCommandError(argv: list[str], returncode: int, stderr: str = '')

The Startech binary returned a non-zero exit code.

exception st_uhubm.errors.HubParseError

The Startech binary’s output could not be parsed.

exception st_uhubm.errors.HubTimeout

A command exceeded the configured timeout.

exception st_uhubm.errors.ManagedHubError

Base class for all errors raised by this package.

class st_uhubm.cli_backend.ManagedHubAttachmentError