v0.2.0

[kevinmehall]

v0.2 is an API redesign based on what we learned in v0.1. It makes the API less error prone, enables new optimizations, and prepares the API for a planned WebUSB backend.

New Features

• EndpointRead / EndpointWrite adapters that manage transfers and implement std::io and corresponding async IO traits. These are now the "high-level" API recommended unless you want to manage individual transfers. (Add EndpointRead and EndpointWrite #141)
• Functions that were previously blocking are available as blocking or async via MaybeFuture. If you are using them asynchronously, you need to enable the smol or tokio features to defer the blocking syscalls to the corresponding runtime's blocking thread pool. (Make blocking APIs optionally async #100)
• Add DeviceInfo::port_chain with the path of port numbers from the root hub to this device. (Add DeviceInfo::port_chain #71)
• Add list_buses() and BusInfo for information on USB buses. (List root hubs function #77)
• Include error code in TransferError::Unknown. (TransferError::Unknown should contain OS error #64)
• Add Device::device_descriptor for access to device details from an opened device. (Add support for getting device information from opened device on Linux #102)
• Windows: Enable RAW_IO for bulk IN endpoints for improved performance. (Use RAW_IO on Windows for bulk and interrupt IN endpoints #6)
• Linux: Enable zero-copy IO with buffers allocated by Endpoint::allocate. (Linux usbfs zero-copy support #11)

Fixes

• Windows: Allow claiming associated interfaces of multi-interface functions.
• Windows: List interfaces of composite devices that are bound to WinUSB at the device level.
• Windows: Include hubs in the device list. (Windows: include hub devices in list like other platforms #85)

Breaking Changes

• list_devices DeviceInfo::open, Device::from_fd, Device::set_configuration, Device::reset, Interface::set_alt_setting, Device::claim_interface Device::detach_and_claim_interface, and Endpoint::clear_halt now return impl MaybeFuture. Add use nusb::MaybeFuture and call .wait() for previous blocking functionality. Or, to use them from async code, enable the tokio or smol cargo feature of nusb and use .await.
• Queue has been replaced by Endpoint with changes to the buffer type. (Redesign endpoint and transfer API #117)
• Interface methods for single bulk and interrupt transfers and TransferFuture have been removed because they had subtle pitfalls regarding cancellation. Use Endpoint::submit followed by next_complete, or switch to the EndpointRead / EndpointWrite adapters.
• Interface and Device methods control_in_blocking + control_out_blocking have been replaced with control_in / control_out with .wait() from MaybeFuture.
• Interface and Device methods control_in + control_out now accept a timeout. Dropping the returned Future no longer cancels the transfer.
• Bulk and Interrupt IN transfers that are not a multiple of the max packet size return an error. (Error handling fixes #135)
• DeviceInfo::bus_number (integer) has been replaced with DeviceInfo::bus_id (string).
• Renamed EndpointType to TransferType.
• Renamed descriptor types (Descriptor API changes #115)
• Use NonZeroU8 for string descriptor indexes.
• Descriptor constructors return Option instead of panic.
• TransferError::Unknown has an integer field for the error code.
• nusb::Error is now a custom error type instead of a re-export of std::io::Error. It still implements Into<std::io::Error> for ?.
• Linux: Root hubs are no longer included in the device list.

Minimum Rust version is now 1.79.

Contributors

@kevinmehall @pgorgon-hem @kirisauce @tuna-f1sh @CCnut @cstrahan @martinling

---

This discussion was created from the release v0.2.0.