devusb

Agent-friendly USB power control for the embedded bench, built for the Agentic Firmware Workbench. Switch, monitor, and power-cycle devices attached to Yepkit YKUSH-family switchable USB hubs — from the command line or from an AI agent via MCP.

Typical use: an agent flashing and testing firmware hits a hung debug probe or wedged dev board. Instead of asking a human to unplug it, the agent runs power_cycle and carries on.

Supported hardware

Hub	Switched ports	Status
YKUSH3	3	verified on hardware
YKUSH	3	same protocol, untested
YKUSH XS	1	same protocol, untested

The hub is driven directly over USB HID (hidapi) — no vendor utility needed. Multiple hubs can be attached at once; target one with --serial <SN> (CLI) or the serial argument (MCP).

Install

pip install .

Requires Python 3.10+.

Linux: udev rules

On Linux, non-root access to the hub's HID interface needs a udev rule:

sudo cp udev/99-devusb.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger

Then unplug and replug the hub. macOS and Windows need no extra setup.

CLI

devusb list                 # attached hubs: model, serial, port count
devusb status               # power state of each port
devusb off 1                # cut power to port 1
devusb on 1                 # restore power
devusb cycle 1 --hold 10    # power-cycle: off 10 s, back on
devusb on all               # every port
devusb --json status        # machine-readable output
devusb --serial Y3N14127 off 2   # pick a hub when several are attached

MCP server

devusb-mcp runs an MCP server over stdio exposing list_hubs, port_status, port_on, port_off, and power_cycle — with agent-facing safety guidance (don't cut power mid-flash, wait for re-enumeration) baked into the tool descriptions.

Register with Claude Code:

claude mcp add --scope user devusb devusb-mcp

Any MCP-capable agent host works the same way — point it at the devusb-mcp executable.

Safety notes

• Never cut power to a device mid-flash.
• After power returns, give the device a few seconds to re-enumerate before talking to it.

Interoperability with uhubctl

The YKUSH3 is built on Microchip hub silicon (USB5744/USB2744) that also supports generic per-port power switching, so tools like uhubctl can see and switch its ports directly. Don't drive the same hub through both devusb and uhubctl at once: the YKUSH firmware doesn't track changes made behind its back, and the port numbering differs between the two paths (e.g. YKUSH port 1 is internal hub port 3). Pick one controller per hub.

Roadmap

devusb is YKUSH-only today, but the CLI verbs and MCP tools are vendor-neutral by design; new hub backends slot in without changing the agent-facing contract. Planned:

• Generic USB hubs (uhubctl-style) — many ordinary hubs and docks support per-port power switching through standard USB hub commands. Approach validated on real hardware: Realtek RTS5411-based hubs switch port power reliably (tested cycling a YKUSH3 — including its downstream devices — from an upstream RTS5411 port), and the YKUSH3's own internal Microchip hub silicon accepts the same commands (see interoperability note below). A backend needs to pair each physical port's USB 2.0 and USB 3.x hub instances, as uhubctl does.
• Acroname programmable hubs — the premium lab option.

Development

pip install -e ".[dev]"
pytest

The test suite runs against a fake HID layer — no hub required.

License

MIT