yusb

Yet another fork of a fork of a Rust libusb wrapper!

Pronounced yoo-ess-bee.

This is an update to Ilya Averyanov's rusb crate, which itself is a fork of David Cuddeback's libusb crate.

The initial versions of this crate differ from rusb in a number of ways:

• Removes the UsbContext trait
  • Consolidates Context and GenericContext types into a single, concrete Context type.
  • Now the global context is just an instance of Context with a null inner pointer.
• The Device<T> and DeviceList<T> no longer need to be generic over the Context type (since there is now only a single context type), and are now just Device and DeviceList, respectively.
• There is a Port type which uniquely identified the physical USB port to which a device in the system is attached.
  • It is a combination of the bus number and ordered list of hub ports
  • This helps to uniquely identify a device when multiple ones are attached with the same VID:PID and no serial number or other distinguishing feature.
  • Individual ports are comparable and can be converted to/from strings that use the Linux syspath format, like 2-1.4.3.
• The Speed type updated:
  • It can be converted to floating-point speed in Mbps, and directly displayed as such.
  • It is ordered and comparable like:

    if (device.speed() < Speed::Super) { println!("Plug the device into a faster port");

• DeviceList implements IntoIterator so can be used directly by for loops without .iter()
• Some general cleanup and modernization of the code base.

This crate provides a safe wrapper around the native libusb library. It applies the RAII pattern and Rust lifetimes to ensure safe usage of all libusb functionality. The RAII pattern ensures that all acquired resources are released when they're no longer needed, and Rust lifetimes ensure that resources are released in a proper order.

• Documentation

Dependencies

To use yusb, no extra setup is required as yusb will automatically download the source for libusb and build it.

However if building libusb fails you can also try setting up the native libusb library where it can be found by pkg-config or vcpkg.

All systems supported by the native libusb library are also supported by the libusb crate. It's been tested on Linux, OS X, and Windows.

Cross-Compiling

The yusb crate can be used when cross-compiling to a foreign target. Details on how to cross-compile yusb are explained in the libusb1-sys crate's README.

Usage

Add yusb as a dependency in Cargo.toml:

[dependencies]
yusb = "0.1"

Import the yusb crate. The starting point for nearly all yusb functionality is to create a context object. With a context object, you can list devices, read their descriptors, open them, and communicate with their endpoints:

fn main() {
    for device in yusb::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());
    }
}

License

Distributed under the MIT License.

License note.

If you link native libusb (by example using vendored features) library statically then you must follow GNU LGPL from libusb.