embassy-usb

Crates

git

Versions

default

Flavors

Skip to main content

Crate embassy_usb

Crate embassy_usb 

Source
Expand description

§embassy-usb

Async USB device and host stack for embedded devices in Rust.

§Features

  • Native async.
  • Fully lock-free: endpoints are separate objects that can be used independently without needing a central mutex. If the driver supports it, they can even be used from different priority levels.
  • Suspend/resume, remote wakeup.
  • USB composite devices.
  • Ergonomic descriptor builder.
  • Ready-to-use implementations for common USB classes (note you can still implement any class yourself outside the crate). See Class features for the full list and role support.
    • Serial ports (CDC ACM)
    • Ethernet (CDC NCM)
    • Human Interface Devices (HID)
    • MIDI
    • Generic USB Display (GUD)
    • Mass Storage (MSC)
    • Test & Measurement (USBTMC)

The host module provides USB host enumeration, descriptor parsing, and class drivers for devices including HID, CDC ACM, mass storage, MIDI, and USB Audio Class.

§Class features

Every class driver is behind its own Cargo feature, and each submodule is gated by the role it belongs to:

  • device — the device stack (UsbDevice, Builder, Handler, and class device modules).
  • host — the host stack (host and class host modules).
  • class-all — every class driver listed below. It is enabled by default.
  • class-<name> — one class driver, for example class-cdc-acm or class-hid.
  • embedded-io — the embedded-io-async trait implementations and the ClassError mapping. Enabled by class-cdc-acm and class-vcp.
  • test-utils — mock host allocator, loopback pipes, and golden descriptors for downstream class tests. Implies host.
FeatureDeviceHost
class-bthyesno
class-ccidyesyes
class-cdc-acmyesyes
class-cdc-ncmyesno
class-cmsis-dap-v2yesno
class-dfuyesno
class-gipnoyes
class-gudyesno
class-hidyesyes
class-hubnoyes
class-midiyesyes
class-mscyesyes
class-mtpyesno
class-uacyesyes
class-usbtmcyesno
class-uvcyesno
class-vcpnoyes
class-web-usbyesno

class-vcp also enables class-cdc-acm, because the CP210x driver reuses the CDC ACM line coding types.

The default features are device, host, and class-all, so existing users keep the full class set. For a minimal build, disable default features and select only what you need:

[dependencies]
embassy-usb = { version = "0.6", default-features = false, features = ["device", "class-cdc-acm"] }

A class that can be built for both roles needs at least one of device or host; enabling it without either is a compile error. Device-only and host-only class features enable their role automatically.

Device classes that own interfaces can register with Builder::interface_handler instead of Builder::handler. Interface- and endpoint-recipient control requests are then delivered only to the owning handler. CDC ACM, HID, and MSC already use this path.

§Adding support for new hardware

To add embassy-usb support for new hardware (i.e. a new MCU chip), you have to write a driver that implements the embassy-usb-driver traits.

Before writing a new driver, you can first verify whether the chip uses a common USB IP. Several widely used USB IPs already have implementations available, such as:

  • Synopsys OTG (dwc2): Available at embassy-usb-synopsys-otg. This IP is used by vendors like STMicroelectronics, Espressif, and others.
  • Musbmhdrc (musb): Available at musb. This IP is used by vendors like TI, MediaTek, Puya, and others.

Driver crates should depend only on embassy-usb-driver, not on the main embassy-usb crate. This allows existing drivers to continue working for newer embassy-usb major versions, without needing an update, if the driver trait has not had breaking changes.

§Configuration

embassy-usb has some configuration settings that are set at compile time, affecting sizes and counts of buffers.

They can be set in two ways:

  • Via Cargo features: enable a feature like <name>-<value>. name must be in lowercase and use dashes instead of underscores. For example. max-interface-count-3. Only a selection of values is available, check Cargo.toml for the list.
  • Via environment variables at build time: set the variable named EMBASSY_USB_<value>. For example EMBASSY_USB_MAX_INTERFACE_COUNT=3 cargo build. You can also set them in the [env] section of .cargo/config.toml. Any value can be set, unlike with Cargo features.

Environment variables take precedence over Cargo features. If two Cargo features are enabled for the same setting with different values, compilation fails.

§MAX_INTERFACE_COUNT

Max amount of interfaces that can be created in one device. Default: 4.

§Interoperability

This crate can run on any executor.

Re-exports§

pub use device::Builder;
pub use device::CONFIGURATION_NONE;
pub use device::CONFIGURATION_VALUE;
pub use device::Config;
pub use device::EndpointOptions;
pub use device::FunctionBuilder;
pub use device::Handler;
pub use device::HandlerFull;
pub use device::InterfaceAltBuilder;
pub use device::InterfaceBuilder;
pub use device::InterfaceHandler;
pub use device::RemoteWakeupError;
pub use device::UsbBufferReport;
pub use device::UsbDevice;
pub use device::UsbDeviceSpeed;
pub use device::UsbDeviceState;
pub use device::UsbVersion;
pub use device::msos;
pub use embassy_usb_driver as driver;

Modules§

class
Implementations of well-known USB classes.
control
USB control data types.
descriptor
Utilities for writing USB descriptors.
device
USB device stack.
host
USB host support. Async USB host stack.
types
USB types.

Structs§

EndpointInterval
Polling interval of an endpoint.