Transparent Communication Device Solution

Overview

The CDC ACM (Abstract Control Model) class, a subclass of Communication Device Class (CDC), emulates COM ports for serial data transparent communication applications.

SDK provides:

  • Standard CDC ACM device class driver with following features:

    • Fully customizable descriptors

    • Configurable bulk IN/OUT transfer lengths

    • Optional interrupt IN endpoint flexible for compatibility and bandwidth optimization

  • CDC ACM device application example with following features:

    • Compatible with standard host terminal tools such as PuTTY/TeraTerm

    • Supports bidirectional communication through virtual COM port, supports synchronous or asynchronous echo

    • Supports hot-plug

    • Support speed mode configuration

Endpoint Configurations

Endpoint

Count

Description

Control IN/OUT

1

Handle host control requests

Interrupt IN

1

Status reporting

Bulk IN

1

Data transmission

Bulk OUT

1

Data reception

Class Driver

CDC ACM device class driver

Application Example

Location: {SDK}/component/example/usb/usbd_cdc_acm

The example defines an USB CDC ACM device, refer to the README.md in the example directory for details.

This example serves as a reference implementation for USB transparent communication device applcations.

HID Device Solution

Overview

The HID (Human Interface Device) class standardizes human input devices, Can be used as USB keyboard, mouse and other devices to achieve human-computer interaction functions.

SDK provides:

  • HID keyboard and mouse device class drivers with following features:

    • Fully customizable descriptors

  • HID keyboard and mouse device application example with following features:

    • Basic keyboard and mouse input event simulation

    • Hot-plug support

    • Support speed mode configuration

Endpoint Configurations

Keyboard device

Count

Description

Control IN/OUT

1

Handle host control requests

Interrupt IN

1

Keypress reporting

Interrupt OUT

1

Host commands reception

Mouse device

Count

Description

Control IN/OUT

1

Handle host control requests

Interrupt IN

1

Movement/Click reporting

Class Driver

HID device class drivers

Application Example

Location: {SDK}/component/example/usb/usbd_hid

The example defined a combined HID keyboard/mouse demo, refer to the README.md in the example directory for details.

HID keyboard example serves as a reference implementation for USB HID bidirectional communication devices, while the HID mouse example provides a reference implementation for USB HID unidirectional communication devices.

Mass Storage Device Solution

Overview

The MSC (Mass Storage Class) standard defines mass storage devices using SCSI command sets for read/write/erase operations on storage media.

SDK provides:

  • Standard MSC device class driver with following features:

    • Supports Bulk-Only Transport (BOT) protocol

    • Supports SD cards and RAM-based storage media

    • Fully customizable descriptors

  • MSC device application example with following features:

    • Supports USB hot-plug

    • Supports SD card hot-swap

    • Support speed mode configuration

Note

Use SD card hot-swap with caution, abrupt removal during transfers may cause filesystem corruption.

Endpoint Configurations

Endpoint

Count

Description

Control IN/OUT

1

Handle host control requests

Bulk IN

1

Data transmission

Bulk OUT

1

Data reception

Class Driver

MSC device class driver

Application Example

Location: {SDK}/component/example/usb/usbd_msc

The example defines an USB MSC device, refer to the README.md in the example directory for details.

This example serves as a reference implementation for USB MSC device applcations.

Audio Device Solution

Overview

The UAC (USB Audio Class) defines specifications for USB audio devices such as headsets, microphones and sound cards.

The audio parameters supported across UAC versions:

../../../_images/usb_uac_overview.png

SDK provides UAC device class driver and corresponding applcation examples :

  • UAC 1.0 (Full-Speed) class driver, speaker-only, supports following configurable audio parameters:

Sample Rate

(kHz)

Bit-depth

Channel Count

2

4

6

8

44.1

16

Y

Y

Y

Y

24/32

Y

Y

48

16

Y

Y

Y

Y

24/32

Y

Y

96

16

Y

Y

24/32

Y

192

16

Y

24/32

  • UAC 2.0 (High/Full-Speed) class driver, speaker-only, supports following configurable audio parameters:

Sample Rate

Bit-depth

Channel Count

2

4

6

8

44.1

16

Y

Y

Y

Y

24/32

Y

Y

Y

Y

48

16

Y

Y

Y

Y

24/32

Y

Y

Y

Y

96

16

Y

Y

24/32

Y

Y

192

16

Y

24/32

Y

  • Supports volume/mute control

  • Fully customizable descriptors

  • Supports hot-plug

  • Support speed mode configuration

Note

  • USB core driver doesn’t support UAC 2.0 high-bandwidth endpoints, max one isochronous OUT transfer per microframe is allowed.

  • The supported audio formats depend on the whole path of UAC host/device and hardware/software frameworks

Endpoint Configurations

Endpoint

Count

Description

Control IN/OUT

1

Handle host control requests

Isochronous OUT

1

Audio data reception

Class Driver

UAC device class driver

Application Example

Location: {SDK}/component/example/usb/usbd_uac

The example defines an USB UAC speaker, refer to the README.md in the example directory for details.

This example serves as a reference implementation for USB audio device applcations.

FullMAC Device Solution

Overview

The INIC (Internet Network Interface Controller) enables a USB-based FullMAC implementation, functioning as a network interface card to provide host connectivity via USB.

For FullMAC details, refer to Wi-Fi Card Mode .

SDK provides:

  • INIC device class driver with following features:

    • Supports WiFi-only mode

    • Fully customizable descriptors

  • INIC device application example with following features:

    • Compatible with dedicated Linux FullMAC drivers (contact Realtek FAE)

    • Supports USB hot-plug

    • Support speed mode configuration

Endpoint Configurations

Endpoint

Count

Description

Control IN/OUT

1

Handle host control requests

Bulk IN

1

Data transmission

Bulk OUT

2

Data reception

Class Driver

INIC device class driver

Application Example

Location: {SDK}/component/example/usb/usbd_inic

The example defines an USB INIC device, refer to the README.md in the example directory for details.

This example serves as a reference implementation for USB FullMAC applcations.

Composite Device Solution

Overview

A USB composite device integrates multiple independent functions through a single physical USB interface. By combining distinct USB functional units as separate interfaces, the host system recognizes them as a collection of virtual devices, effectively addressing physical interface expansion limitations.

SDK provides:

  • composite device drivers and corresponding applcation examples with following function combinations:

    • CDC ACM + HID

    • CDC ACM + UAC

    • HID + UAC

  • Fully customizable descriptors

  • Supports hot-plug

  • Support speed mode configuration

Class Driver

Composite device drivers

Application Example

Location: {SDK}/component/example/usb/

SDK provides following composite device applcation examples:

Folder

Description

usbd_composite_cdc_acm_hid

CDC ACM virtual serial port and HID mouse composite device

usbd_composite_cdc_acm_uac

CDC ACM virtual serial port and UAC speaker composite device

usbd_composite_uac_hid

HID and UAC speaker composite device example

Refer to the README.md in corresponding example directory for details.

These examples serve as reference implementations for USB composite device applcations.

Vendor-Specific Device Solution

Overview

The vendor-specific class and corresponding example provide reference design for USB vendor-specific device applications.

SDK provides:

  • Vendor-specific device class driver with following features:

    • Fully customizable descriptors

  • Vendor-specific device application example with following features:

    • Co-work with vendor-specific host class defined in usb_host_vendor

    • Supports bulk/interrupt/isochronous synchronous or asynchronous echo test

    • Supports hot-plug

    • Support speed mode configuration

Endpoint Configurations

Endpoint

Count

Description

Control IN/OUT

1

Handle host control requests

Bulk IN

1

Bulk IN transfer

Bulk OUT

1

Bulk OUT transfer

Interrupt IN

1

Interrupt IN transfer

Interrupt OUT

1

Interrupt OUT transfer

Isochronous IN

1

Isochronous IN transfer

Isochronous OUT

1

Isochronous OUT transfer

Class Driver

Vendor-specific device class driver

Application Example

Location: {SDK}/component/example/usb/usbd_vendor

The example defines an USB vendor-specific device, refer to the README.md in the example directory for details.

This example serves as a reference implementation for USB vendor-specific device applcations.

Device Descriptor Customization

Overview

USB devices define their functionality through descriptors. The hierarchical structure of USB descriptors is illustrated below:

../../../_images/usb_device_descriptors.svg

Where:

  • Each USB device contains exactly 1 Device Descriptor

  • One or multiple Configuration Descriptors (specified by bNumConfigurations), with only 1 active at any time

  • One or multiple Interface Descriptors per configuration (specified by bNumInterfaces), which can operate simultaneously

  • Zero, one or multiple Endpoint Descriptors per interface (specified by bNumEndPoints), which can operate simultaneously

Additional descriptor types include:

  • String Descriptors: Localized text descriptions for device/configuration/interface

  • Device Qualifier Descriptor: Required for dual-speed (HS/FS) devices

  • Other Speed Configuration Descriptor: Required for dual-speed (HS/FS) devices, alternate configuration for different speeds

  • Interface Association Descriptor (IAD): Mandatory for composite devices

  • Class-specific Descriptors: e.g., HID Report Descriptor

Note

Refer to USB specifications for complete descriptor definitions.

Data Structure

Standard host enumeration sequence:

  • Device Descriptor

  • Configuration Descriptor chain (active Configuration Descriptor and all subordinate descriptors)

  • String Descriptors (language ID, serial number, manufacturer, product)

Optional host requests:

  • Device Qualifier Descriptor (for dual-speed devices)

  • Other Speed Configuration chain (for dual-speed devices)

  • Class-specific descriptors (e.g., HID Report Descriptor for HID devices)

  • OS-specific descriptors (e.g., Microsoft OS String Descriptor @ index 0xEE)

Note

Unsupported descriptors should return STALL status without affecting functionality.

Based on standard USB host enumeration behavior, USB devices shall implement the following independent descriptor arrays:

  • Device Descriptor: Contains only the Device Descriptor

  • Configuration Descriptor:

    • One array per configuration

    • Includes the Configuration Descriptor plus all subordinate descriptors, e.g., Interface Descriptors and Endpoint Descriptors

  • String Descriptor

    • Language ID descriptor

    • Individual arrays for each string descriptor

  • Device Qualifier Descriptor: Contains only the Device Qualifier Descriptor

  • Other Speed Configuration Descriptor

    • One array per alternate speed configuration descriptor

    • Includes the Other Speed Configuration Descriptor plus all subordinate descriptors, e.g., Interface Descriptors and Endpoint Descriptors

    • May reuse Configuration Descriptor memory through dynamic descriptor type field replacement

  • Class-Specific Descriptor: Defined per device class specifications

  • Host-Specific Descriptor: Implemented per host requirements and application needs

Descriptor Customization

All the USB descriptors defined in USB device class drivers are open for modification, but for better compatibility, it is recommended to limit changes to:

VID/PID

  • Default: Realtek VID/PID

  • Custom VID: Requires USB-IF membership (https://www.usb.org/members)

  • Custom PID with Realtek VID: Contact Realtek FAE

Note

Using Realtek VID/PID doesn’t imply USB-IF compliance - certification still required.

String Descriptors

Customizable indices in:

  • Device Descriptor

    • iManufacturer

    • iProduct

    • iSerialNumber

  • Configuration Descriptor

    • iConfiguration

  • Interface Descriptor

    • iInterface

Note

  • USB device core driver provides ASCII-to-UNICODE conversion API (usbd_get_str_desc)

  • USB stack currently supports English strings only - other languages require custom language ID definitions

Endpoint Descriptor

Customizable parameters:

  • bEndpointAddress

  • wMaxPacketSize (recommend max specification-compliant value)

  • bInterval

Note

Default configurations guarantee SoC and USB specification compatibility. Any modifications require:

  • Thorough understanding of SoC limitations, refer to Hardware Features

  • Compliance with USB specifications

Device Connection Status Detection

For self-powered USB devices, when the USB connection status changes, the USB device class driver and application layer must promptly detect these events and implement corresponding handling procedures for hot-plug support and/or power consumption reduction.

The USB device core driver provides following APIs for connection status monitoring:

These APIs require USB register access after USB power on to return valid data, thus they should only be invoked after USB core driver initialization.

For pre-power status detection, external circuitry shall be employed - such as GPIO interrupt monitoring VBUS power events, refer to the reference design of USB insert detection circuit in Hardware Design Guide.

This hybrid hardware/software solution enables detection of the following USB connection status change events:

Event

usbd_get_status

status_changed

VBUS GPIO Interrupt

VBUS Status

Reset (attached to host)

ATTACHED

INIT -> ATTACHED

N/A

ON

Reset (detached from host)

INIT

N/A

N/A

OFF

Reset (attached to charger)

INIT

N/A

N/A

ON

Attach to host

ATTACHED

DETACHED -> ATTACHED

Y (rising edge)

OFF -> ON

Detach from host

DETACHED

ATTACHED -> DETACHED

Y (falling edge)

ON -> OFF

Attach to charger

INIT

or

DETACHED

N/A

Y (rising edge)

OFF -> ON

Detach from charger

INIT

or

DETACHED

N/A

Y (falling edge)

ON -> OFF

Suspend

DETACHED

ATTACHED -> DETACHED

By USB host configuration

By USB host configuration

Resume

ATTACHED

DETACHED -> ATTACHED

By USB host configuration

By USB host configuration

​​Two typical application scenarios:

Software-Only Implementation (Recommended for Non-Power-Sensitive Applications)

When maintaining constant USB power is acceptable, the status_changed API provides sufficient software-based detection capability. Typical workflow includes:

  • Upon USB host disconnection: Terminate USB communications, deinitialize / re-initialize USB device, then await reconnection

  • Upon USB host connection: Resume USB communications

../../../_images/usb_status_detection_sw.svg

Hardware-Assisted Implementation (For Power-Critical Applications)

When minimizing power consumption during USB idle states is required, hardware solution such as GPIO-interrupt VBUS monitoring shall be implemented. Typical workflow includes:

  • Upon USB host disconnection or USB charger connection: Terminate USB communications, deinitialize USB device to enter low-power state

  • Upon USB host connection: Initialize USB device and resume communications

../../../_images/usb_status_detection_hw.svg