v0.2.0-beta.1

[kevinmehall]

This is a pre-release for anyone interested in testing the new functionality and APIs in v0.2.

New Features

• Redesigned Endpoint API. (Redesign endpoint and transfer API #117)
• Configuration functions that were previously blocking are available as blocking or async via MaybeFuture. If you are using them asynchronously, you will want 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.
• Queue has been replaced by Endpoint.
• Interface methods for single bulk and interupt transfers with TransferFuture have been removed -- use Endpoint or upcoming IO wrappers.
• 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.
• 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.
• Linux: Root hubs are no longer included in the device list.

Minimum Rust version is now 1.79.

Remaining for v0.2

• High-level transfer APIs wrapping Endpoint and managing transfers and buffers to implement BufRead, AsyncBufRead, Write, AsyncWrite to replace removed Interface methods for simple use cases.
• Comprehensive tests.
• Control transfer timeouts for Windows.
• Ensure API is compatible with WebUSB.

Contributors

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

---

This discussion was created from the release v0.2.0-beta.1.

[tuna-f1sh]

Thanks for work on this - looking good.

Minor documentation I noticed is incorrect whilst adapting to changes: [Interface::clear_halt][crate::Endpoint::clear_halt] -> [Endpoint::clear_halt][crate::Endpoint::clear_halt]

nusb/src/transfer/mod.rs

Line 31 in 4edb4a4

/// [`Interface::clear_halt`][crate::Endpoint::clear_halt]. For control

[wuwbobo2021]

Bulk and Interrupt IN transfers that are not a multiple of the max packet size return an error.

Would you like to explain more about this change here? What's the technical benefit? Please tell us.

[kevinmehall]

On Windows, it is a requirement with RAW_IO enabled.

But on all platforms, it doesn't make sense to request a size that is not a multiple of the packet size, because the size works differently than Read::read. You can think of an IN transfer request of N bytes to actually be a request of N / max_packet_size packets, returning early after any packet shorter than max_packet_size is received. The device, not the host, controls how many bytes are in that last packet, so you want to have space to store whatever it sends.