RDP-FIRST • QEMU VALIDATED • OBSERVABLE
Make remote USB failures explainable.
USBCore is an RDP-first USB orchestration layer: it scans Linux USB, generates a reviewable attach plan, launches FreeRDP/URBDRC, and preserves the evidence needed to prove Windows PnP materialization.
No custom USB daemon or opened port for v1.
doctor scores FreeRDP, Remmina, USB visibility, and ADB conflict risk.
attach can dry-run, explain, execute, and journal the session.
Validated on QEMU + Windows Server 2025
ADB & MIDI materialization proven
Why existing tools fail
Legacy USB redirection breaks without explaining where the lifecycle failed.
Gap
Before
Opaque
After
Explainable
Traditional USB-over-IP
Opaque failures
Extra daemons & ports
Weak or no debugging
No virtualization awareness
No lifecycle understanding
One-size-fits-all
USBCore
Explainable failures
Existing secure transports
Evidence bundles & logs
Virtualization-aware
Re-enumeration aware
Device & stack aware
Live session log (xfreerdp + URBDRC)
session: 2025-11-15T12:44:03Z
BEFORE: CHANNEL_RC_BAD_INIT_HANDLE
AFTER: ADB DEVICE STARTED
12:44:02.123[urbdrc]URBDRC channel opened (id=0x13)
12:44:02.341[urbdrc]TS_URB_GET_OS_FEATURE_DESCRIPTOR_REQUEST[42]
12:44:02.563[libusb]Samsung composite re-enumerated on same path
12:44:02.564[urbdrc]DEVICE_LEFT received
12:44:02.564[urbdrc]Same-path rebind: keeping UDEVICE, rebinding to new dev=6
12:44:02.565[urbdrc]Reopening libusb handle
12:44:02.573[urbdrc]Control transfer retry across re-enumeration window
12:44:03.104[windows]Remote Desktop USB Hub enumerated
12:44:03.122[windows]USB Composite Device enumerated
12:44:03.189[windows]ADB Device started
12:44:03.422[windows]Samsung MI_00 (MIDI) started via wdma_usb.inf
Events Captured
128
cross-layer events
Evidence Files
12
exported artifacts
Session Duration
1m 42s
full lifecycle
Result
Materialized
ADB + MIDI online
Validated path, not a diagram
The failure is traced from USB attach to Windows PnP.
Architecture and validation sit together here: the same layer map that explains the path also shows the concrete rebind window and final Windows materialization proof.
Cross-layer observability stack
One correlated path from Linux sysfs discovery through FreeRDP selector mode, Terminal Services policy, URBDRC channel state, and Windows PnP materialization.
8 layers tracked
01
Linux USB
sysfs, udev topology
02
libusb
hotplug transfers
03
URBDRC
device lifecycle
04
RDPDR
virtual channel
05
Terminal Services
RDP stack policy
06
Windows PnP
drivers enumeration
07
QEMU Virtualization
virtual hw environment
08
Device Interfaces
MTP, ADB, MIDI, etc.
Selector/usb:id:<vid>:<pid> or /usb:addr:<bus>:<addr>
Windows roleRDS-RD-Server required on the validated Server 2025 target
PolicyfDisablePNPRedir=0 for supported Plug and Play redirection
Validation proof: Samsung A56 re-enumeration
One evidence path for the exact USB redirect window: RDS-enabled URBDRC opens, Samsung re-enumerates, FreeRDP keeps the same physical path, and Windows proves the ADB interface.
Window
1.3s
Rebind
Same path
Proof
ADB device
Trace
xfreerdp + urbdrc
FreeRDP clientWindows guest
01
12:44:02.123
URBDRC channel opens
FreeRDP client establishes the dynamic virtual channel before USB attach is announced.
02
12:44:02.341
Descriptor request
Samsung composite enters the OS feature descriptor path during enumeration.
03
12:44:02.564
Failure window captured
LIBUSB_ERROR_PIPE and DEVICE_LEFT mark the short re-enumeration break.
04
12:44:02.573
Same-path rebind
UDEVICE identity is kept, libusb handles reopen, and the control transfer is retried.
05
12:44:03.422
Materialized in Windows
Windows binds MI_03 as ADB Interface on WINUSB and adb reaches device state.
Result
From CHANNEL_RC_BAD_INIT_HANDLE to adb devices -l -> device.
PASS
Evidence workspace
Plan, execute, validate, and export one RDP-first USB session.
schema usbcore/v1alpha1
01Scan
02Plan
03Attach
04Validate
05Export
RDP-first: no custom USB transport, daemon, or opened port for v1.
doctor explains host readiness, FreeRDP /usb support, ADB risk, and fix suggestions.
sessions are journaled under ~/.usbcore/sessions and can be inspected, tailed, or exported.
$ adb kill-server$ usbcore attach --device android --target winbox:3389 --user Administrator \--rdp-usb-mode id --rdp-log-level DEBUG --rdp-cert-ignore \--skip-adb-check --execute
Resolved action
Execute FreeRDP with deterministic USB identity, skip local ADB churn, and preserve a reviewable session record.
ready
deviceSamsung A56 (04e8:6860)
backendrdp
identitystrong
compatibilityhigh
selector/usb:id:04e8:6860
next_actionvalidate Windows PnP materialization
scan, doctor, and attach expose versioned JSON envelopes. The current contract is still v1alpha1, but schema changes should be deliberate and versioned.
Windows
RDS-RD-Server installedURBDRC opens instead of normal DVC-only session.
Policy
fDisablePNPRedir=0Supported Plug and Play redirection is explicitly enabled.
Samsung
04e8:6860 mtp_acm_adbFinal ADB-capable profile used for the proven path.
FreeRDP
path rebind + retryDEVICE_LEFT is deferred and transient NO_DEVICE transfers are retried.
ADB
MI_03 on WINUSBadb devices -l reaches device for SM_A566B.
Current Samsung outcome
The proven path is Samsung `04e8:6860` with USB configuration `mtp_acm_adb`; Windows binds `MI_03` as `ADB Interface` on `WINUSB`, and `adb devices -l` reaches `device` for `SM_A566B`.
Still scoped
The FreeRDP rebind work is a validated field workaround, not yet an upstream-quality general fix across all Windows hosts and USB device classes.
session.json
plan + result
rdp.log
xfreerdp trace
pnp-filtered.txt
Windows proof
urbdrc-correlation
channel lifecycle
doctor.json
readiness report