Invert the port’s power state.Returns:true if the port is now enabled, false if now disabled — the
state after the toggle, not before.
state() -> Result<bool>
Read whether the port is powered.
assert!(port.state()?, "port should be up");
Returns:true when enabled.
state() needs box software 0.29.0 or newer. Older boxes reject the action, and
the crate turns that specific rejection into Error::UnsupportedByBox with the
message
the 'state' action on /usb/command requires box software >= 0.29.0; update the box or use toggle/enable/disable.
cycle() -> Result<Option<bool>>
Power the port off, wait, and power it on again. The box watches for the device to
re-enumerate. It requires box software 0.39.0 or later.
match port.cycle()? { Some(true) => println!("the DUT came back"), Some(false) => panic!("the DUT did not re-enumerate"), None => println!("the port was empty, or the hub cannot watch for the device"),}
The port is powered at the end on every path, including failures. The default off
time is 1 s. cycle_with_off_time(secs) takes another value from 0.5 to 10 s. When in
doubt, choose a longer time: a short one lets the DUT warm-start without a real reset.
Like cycle(), and the report also carries the box’s outcome (box 0.49.0 or later).
A UsbCycleReport has three fields: reconnected, the same value that cycle() returns;
outcome; and the box’s message.
The outcome tells an empty port apart from a port the box did not watch:
UsbCycleOutcome
Meaning
Reconnected
The device re-enumerated after power returned
NotReconnected
The device did not come back before the box’s timeout
NoDevice
Nothing on the port was on the bus when the cycle started
TopologyUnreadable
The box did not read its USB topology
recover() -> Result<()>
Power the port on again after a command stopped partway through. On a Plugable dock,
this powers every port of that dock.
recover_report() -> Result<UsbRecoverReport>
Do the same as recover(), and return what the box reports.
Field
Meaning
ports
The hub ports the driver powered on, or None
message
The box’s message
ports is set only when the driver powers more than the net’s own port, as on a
Plugable dock. It needs box software 0.62.0 or later. An older box sends no list, so
ports is None.
Examples
Force a DUT to re-enumerate and wait for it to come back
use lager::{LagerBox, UsbDeviceFilter};use std::time::{Duration, Instant};let lager = LagerBox::from_env()?;let port = lager.usb("usb3");port.disable()?;std::thread::sleep(Duration::from_millis(500));port.enable()?;// Poll the bus until the DUT reappears. usb_devices() is cheap and takes no// exclusive access, so this loop is safe.let filter = UsbDeviceFilter { vid: Some("0483".into()), ..Default::default() };let deadline = Instant::now() + Duration::from_secs(10);loop { if !lager.usb_devices_matching(&filter)?.is_empty() { break; } assert!(Instant::now() < deadline, "DUT did not re-enumerate"); std::thread::sleep(Duration::from_millis(200));}
On a Plugable dock, a device on a powered-off port stays listed on the bus until
power returns. The loop above can then match the old entry at once, before the DUT
re-enumerates. Use cycle() instead, which waits for the hub to report the
reconnect.
Supported Hardware
Instrument
Ports
Acroname USBHub3+
8 or 4, depending on model
YKUSH hub
Per model
Plugable USB hub
Addressed by topology rather than serial
Notes
One net is one port. Cycling usb1 leaves the hub’s other ports alone.
The port’s devnum on the bus changes across a re-enumeration. Match a device by
serial or vid/pid, never by devnum, when checking that it came back.
Powering a port down can remove a device that the box uses for another net. A
debug probe or serial adapter behind that port will disappear mid-test.