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 on macOS when running as root) 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.