Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/fpagliughi/yusb

A Rust wrapper for libusb
https://github.com/fpagliughi/yusb

Last synced: about 1 month ago
JSON representation

A Rust wrapper for libusb

Awesome Lists containing this project

README 

        
# yusb



Yet another fork of a fork of a Rust [libusb](https://libusb.info/) wrapper!



Pronounced _yoo-ess-bee_.



This is an update to Ilya Averyanov's [rusb](https://crates.io/crates/rusb) crate, which itself is a fork of David Cuddeback's [libusb](https://crates.io/crates/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` and `DeviceList` 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:

```text

    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](https://docs.rs/yusb)



## 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](libusb1-sys/README.md#cross-compiling).



## Usage



Add `yusb` as a dependency in `Cargo.toml`:



```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:



```rust

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).



### License note.



If you link native `libusb` (by example using `vendored` features) library statically then

you must follow [GNU LGPL](https://github.com/libusb/libusb/blob/master/COPYING) from libusb.