USB

Control programmable USB hub ports through the Lager CLI for power management and device connectivity.

Syntax

lager usb [OPTIONS] [NET_NAME] [COMMAND]

Global Options

Option	Description
`--box TEXT`	Lager Box name or IP address
`--help`	Show help message and exit

Arguments

Argument	Description
`NET_NAME`	USB net name (optional - lists nets if omitted)
`COMMAND`	Power command: `enable`, `disable`, `toggle`, `state`, `cycle`, or `recover`

Commands

Command	Description
`enable`	Enable (power on) the USB port
`disable`	Disable (power off) the USB port
`toggle`	Toggle the current power state
`state`	Show whether the port is enabled or disabled (read-only)
`cycle`	Power-cycle the port: off, wait, on
`recover`	Restore power after an interrupted command left a port off

`cycle` options

Option	Description
`--off-time SECONDS`	How long to hold the port unpowered. Default `1.0`, range `0.5`-`10`.

Usage

List USB Nets

When invoked without a net name, lists all USB nets on the box:

lager usb --box my-lager-box

Output:

Name    Net Type  Instrument    Channel  Address
USB1    usb       Acroname_Hub  0        USB::123456
USB2    usb       Acroname_Hub  1        USB::123456
CAM_USB usb       YKUSH         0        USB::789012

Control USB Port Power

lager usb NET_NAME COMMAND [--box BOX]

Examples:

# Enable USB port
lager usb USB1 enable --box my-lager-box

# Disable USB port
lager usb USB1 disable --box my-lager-box

# Toggle USB port state
lager usb USB1 toggle --box my-lager-box

# Read the current state without changing it
lager usb USB1 state --box my-lager-box

# Power-cycle the port to cold-boot the device
lager usb USB1 cycle --box my-lager-box

# Hold the port off longer for a device with large capacitors
lager usb USB1 cycle --off-time 3 --box my-lager-box

Power cycle a device

cycle cuts power, waits, and restores it. Then it waits up to 5 seconds for the device to come back:

lager usb USB1 cycle --box my-lager-box
# [OK] USB port 'USB1' power-cycled; device re-enumerated

If no device was on the port, it says so rather than claiming a device returned:

lager usb USB2 cycle --box my-lager-box
# [OK] USB port 'USB2' power-cycled; no device on this port to watch for, so
#      re-enumeration was not confirmed

Two other results are possible:

# The device did not return within 5 seconds (exit code 1)
# Error: USB port 'USB1' power-cycled, but the device did not come back before the timeout

# The box could not read its own USB topology
# [OK] USB port 'USB1' power-cycled (re-enumeration not verified: the box's USB topology could not be read)

cycle exits 1 when the device did not come back. The other three results exit 0. An empty port and an unreadable topology confirm nothing about a device. A script that needs the device must check the output text for those two results. A box too old to report whether the device came back makes cycle exit 0 for all four results. How cycle decides that the device came back depends on the hub:

Acroname and YKUSH hubs: the box reads the kernel USB topology before the power cut and again while the port is off. A device that left the bus must return to it.
Plugable docks: the box watches the connect status that the hub reports for the port.

On a Plugable dock, cycle returns as soon as the hub reports the device reconnecting, which is a few hundred milliseconds. Linux does not finish re-enumerating at that instant. A device node or /dev/ttyUSB* can still be absent, and a /sys read taken immediately still shows the pre-cycle values. On Acroname and YKUSH hubs, cycle returns when the device is back in the kernel USB topology. On every hub, wait for the device node before the next step opens the device. A return from cycle does not mean that the device is ready.

“No device on this port” is not the same as “the port is unused”. A hub only sees a device that pulls up its data lines. A charge-only cable powers a DUT but makes no data connection, so it looks exactly like an empty socket. The port was still cut and restored. Confirm the DUT by its own behavior: its UART, or a current measurement. Prefer it over a scripted disable/sleep/enable, for these reasons:

It restores power on every failure path, so a command that dies partway through cannot strand a port.
It reports whether the device actually came back, so you do not have to guess.
On a Plugable dock, it holds the hub for the whole sequence, so nothing else can switch the port while it is dark. On Acroname and YKUSH hubs, it opens the hub twice. Another process can switch the port during the off time.

--off-time defaults to 1 second, comfortably above the slowest cold boot measured on real hardware. Too short an off time is the failure that matters: the device’s rails do not fully discharge. The device then warm-starts, but it looks like a device that was reset. Raise the off time for a device with large bulk capacitance. A value below 0.5s or above 10s is refused.

On a Plugable dock, a powered-off port still appears in lsusb and still has its /dev/ttyUSB*. The hub raises no change notification while a port is unpowered, so the kernel never processes the disconnect until power returns. disable on such a port says so in its output. Do not script “is the device gone?” as a check that a port is off — it is wrong in both directions. Use state, which reads the hub’s own power bit.

Recover a port left unpowered

If a command was interrupted between powering a port down and back up, recover restores power:

lager usb USB1 recover --box my-lager-box
# [OK] USB port 'USB1': power restored on port(s) 1, 2, 3, 4

On a hub where lager can identify the whole device (such as a Plugable dock), recover re-powers every port on it. You usually reach for recover because something is off and it is not obvious what.

Read port state (read-only)

state reports whether a port is currently enabled or disabled without changing it. The value is read live from the hub hardware, so it always reflects the real port state — nothing is cached or stored:

lager usb USB1 state --box my-lager-box
# [OK] USB port 'USB1' is enabled

This is the read-only counterpart to toggle: use state to check a port, toggle to flip it (which also reports the resulting state).

toggle reports the resulting state so you can tell which way it flipped:

[OK] USB port 'USB1' toggled → disabled

enable and disable confirm the action explicitly (USB port 'USB1' enabled).

Examples

# List all USB nets
lager usb --box my-lager-box

# Power on a USB port for a camera
lager usb CAM_USB enable --box my-lager-box

# Power off USB port to reset a device
lager usb USB1 disable --box my-lager-box

# Toggle power state (useful for power cycling)
lager usb USB1 toggle --box my-lager-box

# Power cycle a device
lager usb USB1 cycle --box my-lager-box

# Re-power a port after an interrupted command
lager usb USB1 recover --box my-lager-box

Supported Hardware

Manufacturer	Model	Description
Acroname	USBHub3+	Programmable USB 3.0 hub
Acroname	USBHub2x4	4-port programmable hub
YKUSH	YKUSH3	USB switchable hub
Plugable	RTS5411 docks (e.g. UD-CAM)	4 external Type-A sockets; standard USB hub-class switching

See Supported Instruments for which ports on a Plugable dock switch power and which do not.

Notes

Net names (e.g., USB1, CAM_USB) refer to USB ports configured on your testbed
Commands are case-sensitive. Type them in lowercase (enable, not ENABLE)
Useful for power cycling USB devices during testing
USB hubs must be connected to the box and configured as instruments
Default net can be set with lager defaults add --usb-net
Create USB nets with lager nets add <name> usb <channel> <address>

Lager Box Management

Configuration

Power & Simulation

Measurement

I/O & Communication

Development

Utilities

Syntax

Global Options

Arguments

Commands

`cycle` options

Usage

List USB Nets

Control USB Port Power

Power cycle a device

Recover a port left unpowered

Read port state (read-only)

Examples

Supported Hardware

Notes

​Syntax

​Global Options

​Arguments

​Commands

​cycle options

​Usage

​List USB Nets

​Control USB Port Power

​Power cycle a device

​Recover a port left unpowered

​Read port state (read-only)

​Examples

​Supported Hardware

​Notes

Syntax

Global Options

Arguments

Commands

`cycle` options

Usage

List USB Nets

Control USB Port Power

Power cycle a device

Recover a port left unpowered

Read port state (read-only)

Examples

Supported Hardware

Notes