rusb

The rusb crate provides a safe wrapper around the native libusb library by utilizing two core Rust principles:

1. RAII (Resource Acquisition Is Initialization): Ensures that all acquired resources (like device handles or contexts) are automatically released when they go out of scope.
2. Rust Lifetimes: Ensures that resources are released in the correct order and that references to resources do not outlive the resources themselves.

This prevents common issues found in C-based USB programming, such as memory leaks or use-after-free errors.

To use rusb in your project, add it to your Cargo.toml dependencies. By default, rusb will automatically download the libusb source and build it for you, so no extra system setup is required.

[dependencies]
rusb = "0.9"

In rusb, a USB Interface represents a specific functional part of a device. An interface can have multiple descriptors, each representing an 'alternate setting' (different configurations for the same interface).

You can use the Interface struct to retrieve its interface number and iterate through its available InterfaceDescriptors. Each descriptor provides details about the interface's class, subclass, protocol, and associated endpoints.

// Conceptual usage pattern
let interface_number = interface.number();

for descriptor in interface.descriptors() {
    println!("Setting: {}", descriptor.setting_number());
    println!("Class: {}", descriptor.class_code());
    
    // Iterate over endpoints for this specific setting
    for endpoint in descriptor.endpoint_descriptors() {
        println!("Endpoint address: {:x}", endpoint.address());
    }
}

The Registration<T> struct manages the lifecycle of a hotplug callback. It uses the RAII pattern: when the Registration instance is dropped, the underlying libusb_hotplug_deregister_callback is automatically called to stop monitoring.

To stop monitoring, you can either:

1. Let the Registration object go out of scope.
2. Explicitly drop the Registration object.
3. Use Context::unregister_callback (if available in the context API).

To interact with USB devices using rusb, you must first create a Context.

• Use Context::new() to create a standard new libusb context.
• Use Context::with_options(&[UsbOption]) to create a context with specific runtime options applied.

The Context type implements the UsbContext trait, which provides the primary interface for device discovery and management.

use rusb::Context;

// Create a new context
let context = Context::new().expect("Failed to create context");

If the automatic build of libusb fails, you can manually provide a native libusb installation. rusb can use a native library if it is discoverable via:

• pkg-config
• vcpkg

rusb supports all systems supported by the native libusb library, including Linux, macOS, and Windows.

The primary workflow in rusb begins with accessing the device list. You can iterate over available devices, access their descriptors to read metadata (like Vendor ID and Product ID), and retrieve bus/address information.

fn main() {
    for device in rusb::devices().unwrap().iter() {
        let device_desc = device.device_descriptor().unwrap();

        println!("Bus {:03} Device {:03} ID {:04x}:{:04x}",
            device.bus_number(),
            device.address(),
            device_desc.vendor_id(),
            device_desc.product_id());
    }
}

You can control the verbosity of libusb logs via the Context object.

1. Set Log Level: Use set_log_level(level: LogLevel) to change the verbosity. Available levels are LogLevel::None, LogLevel::Error, LogLevel::Warning, LogLevel::Info, and LogLevel::Debug.
2. Set Log Callback: Use set_log_callback to intercept logs. You must specify a LogCallbackMode:
   • LogCallbackMode::Global: Handles all log messages.
   • LogCallbackMode::Context: Handles logs related specifically to that context.

use rusb::{Context, LogLevel, LogCallbackMode};

let mut context = Context::new().unwrap();
context.set_log_level(LogLevel::Debug);

// Note: set_log_callback implementation details depend on providing a closure
// context.set_log_callback(|level, msg| { ... }, LogCallbackMode::Context);

Once you have a Language instance, use the following methods to inspect its components:

• lang_id() -> u16: Returns the original 16-bit LANGID.
• primary_language() -> PrimaryLanguage: Returns the primary language family (e.g., English, French, Chinese).
• sub_language() -> SubLanguage: Returns the specific dialect, region, or writing system (e.g., UnitedStates, Canada, Traditional).

let lang = Language::new(0x0409);
let id = lang.lang_id();
let primary = lang.primary_language();
let sub = lang.sub_language();

To perform I/O operations (like reading or writing to endpoints), you must call .open() on a Device instance. This returns a DeviceHandle<T>, which is the object used for actual data transfer.

let handle = device.open().expect("Failed to open device");