surban / usb-gadget

Expose standard or fully custom USB peripherals (gadgets) through a USB device controller (UDC) on Linux using Rust.

usb-gadget

This library allows implementation of USB peripherals, so called USB gadgets, on Linux devices that have a USB device controller (UDC). Both, pre-defined USB functions and fully custom implementations of the USB interface are supported.

The following pre-defined USB functions, implemented by kernel drivers, are available:

• network interface
  • CDC ECM
  • CDC ECM (subset)
  • CDC EEM
  • CDC NCM
  • RNDIS
• serial port
  • CDC ACM
  • generic
• human interface device (HID)
• mass-storage device (MSD)

In addition fully custom USB functions can be implemented in user-mode Rust code.

Support for OS-specific descriptors and WebUSB is also provided.

Features

This crate provides the following optional features:

• tokio: enables async support for custom USB functions on top of the Tokio runtime.

Requirements

The minimum support Rust version (MSRV) is 1.73.

A USB device controller (UDC) supported by Linux is required. Normally, standard PCs do not include an UDC. A Raspberry Pi 4 contains an UDC, which is connected to its USB-C port.

The following Linux kernel configuration options should be enabled for full functionality:

• CONFIG_USB_GADGET
• CONFIG_USB_CONFIGFS
• CONFIG_USB_CONFIGFS_SERIAL
• CONFIG_USB_CONFIGFS_ACM
• CONFIG_USB_CONFIGFS_NCM
• CONFIG_USB_CONFIGFS_ECM
• CONFIG_USB_CONFIGFS_ECM_SUBSET
• CONFIG_USB_CONFIGFS_RNDIS
• CONFIG_USB_CONFIGFS_EEM
• CONFIG_USB_CONFIGFS_MASS_STORAGE
• CONFIG_USB_CONFIGFS_F_FS
• CONFIG_USB_CONFIGFS_F_HID

root permissions are required to configure USB gadgets on Linux and the configfs filesystem needs to be mounted.

License

usb-gadget is licensed under the Apache 2.0 license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in usb-gadget by you, shall be licensed as Apache 2.0, without any additional terms or conditions.

usb-gadget's Issues

How to use

Hi there,

Seems like a silly question but I've managed to create a HID device using the hid function builder.

But I can't see a way of writing to it... Is it just a case of opening the filepath on the OS for that hid device or whatever and writing to it? Or is there a way to write to it from within this module?