Crate rawusb 

Dependency-free, cross-platform USB device access in the spirit of libusb.

rawusb talks to the operating system’s native USB stack directly: usbfs on Linux, WinUSB on Windows and IOKit on macOS. There are no external crates and no C library to install. The API mirrors libusb’s concepts so that existing knowledge carries over, while staying idiomatic Rust.

Layers

• Context owns a session and the event thread that drives completion.
• Device is an enumerated device with its descriptors; Device::open yields a DeviceHandle.
• DeviceHandle configures the device (configuration, interfaces, alternate settings, kernel drivers) and offers synchronous control, bulk and interrupt transfers.
• Transfer is the asynchronous primitive underneath: allocate once, submit, cancel, wait, or .await its completion. Isochronous transfers are only available through it.

Features

Everything below is off by default.

• hotplug adds the hotplug module, which reports devices arriving and leaving. See Context::hotplug.

Class helpers, ready-made drivers for common device classes built on the public API above. Each claims the interfaces it needs (detaching the kernel driver on Linux) and gives them back when dropped:

• hid: hid::HidDevice and a report descriptor parser.
• msc: msc::MassStorage (bulk-only transport, SCSI commands) and a Read + Write + Seek msc::BlockDevice.
• serial: serial::SerialPort for CDC-ACM devices and FTDI chips.
• uvc: uvc::Camera for webcams: formats, controls, frame streaming.
• net: net::NetDevice for USB Ethernet functions (CDC-ECM, CDC-NCM, RNDIS).
• pktkit: implements pktkit::L2Device for net::NetDevice. The only feature with a dependency, the pktkit crate.

On a composite device, take the whole device first with DeviceHandle::claim_all_interfaces, then start whatever helpers you need on clones of that handle. Each helper drives its own interfaces (a second one on the same interface fails with ErrorKind::Busy), and helpers can be dropped and reopened while the device stays taken:

let handle = dev.open()?;
handle.claim_all_interfaces()?; // detaches every kernel driver
let console = rawusb::serial::SerialPort::open_all(&handle)?;
let raw_hid = rawusb::hid::HidDevice::open_all(&handle)?;

Example

use rawusb::{Context, Direction, ControlType, Recipient, request_type};
use std::time::Duration;

let ctx = Context::new()?;
for dev in ctx.devices()? {
    let d = dev.device_descriptor();
    println!("{:03}:{:03} {:04x}:{:04x}", dev.bus_number(), dev.address(), d.vendor_id, d.product_id);
}

let handle = ctx.open_device_with_vid_pid(0x1234, 0x5678)?;
handle.set_auto_detach_kernel_driver(true);
handle.claim_interface(0)?;
let mut buf = [0u8; 64];
let n = handle.bulk_read(0x81, &mut buf, Duration::from_secs(1))?;
println!("got {n} bytes");

// A vendor control request.
let rt = request_type(Direction::In, ControlType::Vendor, Recipient::Device);
let n = handle.control_read(rt, 0x01, 0, 0, &mut buf, Duration::from_secs(1))?;

Re-exports

pub use descriptors::ConfigDescriptor;

pub use descriptors::DeviceDescriptor;

pub use descriptors::EndpointDescriptor;

pub use descriptors::Interface;

pub use descriptors::InterfaceDescriptor;

pub use hotplug::HotplugEvent;

pub use hotplug::HotplugRegistration;

pub use hotplug::HotplugWatcher;

pub use transfer::Transfer;

pub use transfer::TransferFlags;

pub use types::ControlSetup;

pub use types::ControlType;

pub use types::Direction;

pub use types::IsoPacket;

pub use types::NO_TIMEOUT;

pub use types::Recipient;

pub use types::Speed;

pub use types::TransferStatus;

pub use types::TransferType;

pub use types::Version;

pub use types::request_type;

Modules

descriptors

Standard USB descriptors and a tolerant parser for configuration trees.

hid

Human Interface Devices (HID 1.11) over raw USB: keyboards, mice, game controllers, FIDO tokens, UPS and PSU telemetry, vendor HID gadgets.

hotplug

Hotplug notifications: learning when devices are plugged in or unplugged.

msc

USB Mass Storage: the Bulk-Only Transport and the SCSI commands that USB flash drives, card readers and external disks understand.

net

USB Ethernet adapters: CDC-ECM, CDC-NCM and RNDIS devices (phones sharing their connection, single-board computers in gadget mode, docks, LTE modems, many USB NICs’ standard configurations) as one NetDevice that sends and receives Ethernet frames.

serial

USB serial adapters: CDC-ACM devices (Arduino-style boards, modems, most microcontroller USB stacks) and FTDI chips, behind one SerialPort type.

transfer

Asynchronous transfers: the low-level building block every I/O operation in this crate is made of.

types

Small value types: directions, transfer kinds, speeds, control setup packets, and the standard-request constants from the USB specification.

uvc

USB Video Class (UVC 1.0-1.5): webcams, capture cards, USB microscopes.

Structs

Context

A library session. Everything else is created from one.

Device

A USB device known to the system.

DeviceHandle

An open USB device.

Error

The error type returned by every fallible operation in this crate.

Enums

ErrorKind

Broad classification of a failure, modelled on libusb’s error codes.

Type Aliases

Result

Convenience alias used throughout the crate.