---
name: adom-usb
description: >
  USB device mesh dashboard. See every USB device across the whole Adom
  ecosystem — your laptop, its WSL2 / Hydrogen Desktop, this cloud container,
  the Azure VM and its WSL2, and workcells — in one Hydrogen webview, with
  Local/Cloud filters and per-device mount/unmount/reset/test/force-class/sniff.
  Trigger words: usb, usb devices, usb dashboard, list usb, mount usb, unmount
  usb, attach usb, usbip, usb/ip, slingshot usb, mount my dev board, rp2040 to
  wsl2, mount device to container, usb mesh, where is my usb device, force hid,
  force mass storage, sniff usb, usb passthrough, plug in dev board.
---

# adom-usb — USB device mesh dashboard

One table of every USB device across the Adom ecosystem and the controls to
route each one. Built as a Hydrogen webview app (see `app-creator`); every UI
action is also a plain HTTP endpoint, so the AI drives it exactly like the human.

## Run it

```bash
adom-usb app                 # live: real lsusb on this container + registered agents
adom-usb app --demo          # seed a representative cross-ecosystem set (RP2040, ST-Link, CP2102, FTDI, CH340)
adom-usb list --demo         # print the unified inventory as JSON (no server)
```

The dashboard opens as a Hydrogen tab named "USB Devices". Columns: name ·
VID:PID · serial · class · source/location · current mount · actions. Filter
chips: **Local / Cloud / All**.

## Drive it (same endpoints the buttons fire)

```bash
adom-usb mount  laptop:2e8a:0003 laptop-wsl2     # RP2040 → laptop WSL2 (usbipd attach --wsl)
adom-usb mount  laptop:2e8a:0003 this-container  # RP2040 → cloud container (reverse tunnel)
adom-usb unmount laptop:2e8a:0003
curl -s localhost:8896/state | jq            # full snapshot: hosts, devices, targets, actions
curl -sX POST localhost:8896/reset  -d '{"device_id":"..."}'
curl -sX POST localhost:8896/sniff  -d '{"device_id":"..."}'
```

## Routing matrix (v1)

Windows is **source + local-only**: a Windows machine can export its USB and
natively use devices physically plugged into it, but a *remote* device cannot be
mounted *into* a native Windows desktop yet (needs the test-signed usbip-win
client driver — those targets show as blocked). Linux targets (cloud container,
laptop WSL2/HD, Azure WSL2, workcells) accept remote mounts via `usbipd attach
--wsl` (local) or the adom-desktop reverse tunnel (cross-machine).

reset / test / force-class / sniff operate on the virtual device in a **Linux
target** — they are greyed out until the device is mounted on one.

## Status

M1 ships the unified inventory + the mount overlay; each action emits the exact
agent command it will run (visible in the action log) and is wired to the live
agents (usbipd-win over the relay, `usbip attach` in the target, usbmon) as
those land. See the project plan for the M1→M5 sequence.