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)
- printer device
- musical instrument digital interface (MIDI)
- audio device (UAC1 and UAC2)
- video device (UVC)
In addition fully custom USB functions can be implemented in user-mode Rust code.
Support for OS-specific descriptors and WebUSB is also provided.
The usb-gadget CLI tool allows you to configure USB gadgets from TOML configuration
files without writing any Rust code.
cargo install usb-gadget --features cli
Create a TOML configuration file describing your gadget, then use the CLI to manage it:
usb-gadget up gadget.toml # register and bind a gadget
usb-gadget list # list registered gadgets
usb-gadget down my-gadget # remove a gadget by name
usb-gadget down --all # remove all gadgets
usb-gadget check gadget.toml # validate a config file
You can also pass a directory to up or check to process all .toml files in it.
name = "serial-debug"
[device]
vendor = 0x1209
product = 0x0002
manufacturer = "Example Inc."
product_name = "Debug Console"
serial = "0001"
[[config]]
description = "Serial Config"
[[config.function]]
type = "serial"
class = "acm"Multiple functions can be combined in a single gadget by adding more [[config.function]]
entries. Run usb-gadget template --list to see all available templates.
This crate provides the following optional features:
cli: builds theusb-gadgetCLI tool for configuring gadgets from TOML files.tokio: enables async support for custom USB functions on top of the Tokio runtime.
The minimum supported Rust version (MSRV) is 1.77.
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_GADGETCONFIG_USB_CONFIGFSCONFIG_USB_CONFIGFS_SERIALCONFIG_USB_CONFIGFS_ACMCONFIG_USB_CONFIGFS_NCMCONFIG_USB_CONFIGFS_ECMCONFIG_USB_CONFIGFS_ECM_SUBSETCONFIG_USB_CONFIGFS_RNDISCONFIG_USB_CONFIGFS_EEMCONFIG_USB_CONFIGFS_MASS_STORAGECONFIG_USB_CONFIGFS_F_FSCONFIG_USB_CONFIGFS_F_HIDCONFIG_USB_CONFIGFS_F_PRINTERCONFIG_USB_CONFIGFS_F_MIDICONFIG_USB_CONFIGFS_F_UAC1CONFIG_USB_CONFIGFS_F_UAC2CONFIG_USB_CONFIGFS_F_UVC
root permissions are required to configure USB gadgets on Linux and
the configfs filesystem needs to be mounted.
usb-gadget is licensed under the Apache 2.0 license.
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.