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:

    • Configurable bulk IN/OUT transfer lengths

    • Optional interrupt IN endpoint flexible for compatibility and bandwidth optimization

    • Endpoint configuration:

      • 1 control IN/OUT endpoint to handle host control requests

      • 1 interrupt IN endpoint for status reporting

      • 1 bulk IN endpoint for data transmission

      • 1 bulk OUT endpoint for data reception

  • CDC ACM device application example with following features:

    • Supports virtual COM port echo

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

    • Supports hot-plug

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, using report descriptors to define data formats and control/interrupt transfers for host communication.

SDK provides:

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

    • For keyboard usage, endpoint configuration:

      • 1 control IN/OUT endpoint for host control requests

      • 1 interrupt IN endpoint for keypress reporting

      • 1 interrupt OUT endpoint for host commands

    • For mouse usage, endpoint configuration:

      • 1 control IN/OUT endpoint for host control requests

      • 1 interrupt IN endpoint for movement/click reporting

    • Fully customizable descriptors

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

    • Basic keyboard and mouse input event simulation

    • Hot-plug support

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

    • Configurable descriptors

    • ​Endpoint configuration​​:

      • 1 control IN/OUT endpoint

      • 1 bulk IN endpoint for data transmission

      • 1 bulk OUT endpoint for data reception

  • MSC device application example with following features:

    • Supports USB hot-plug

    • Supports SD card hot-swap

Note

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

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

  • Endpoint configuration​:

    • 1 control IN/OUT endpoint for host requests

    • 1 isochronous OUT endpoint for audio data

  • Supports volume/mute control

  • Fully customizable descriptors

  • Supports hot-plug

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

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 Supported Chips.

SDK provides:

  • INIC device class driver with following features:

    • Supports WiFi-only mode

    • Configurable descriptors

    • ​Endpoint configuration​​:

      • 1 control IN/OUT endpoint

      • 1 bulk IN endpoint for data transmission

      • 2 bulk OUT endpoints for data reception

  • INIC device application example with following features:

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

    • Supports USB hot-plug

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

Class Driver

Composite device drivers

Application Example

SDK provides following composite device applcation examples:

Path

Description

{SDK}/component/example/usb/usbd_composite_cdc_acm_hid/

CDC ACM virtual serial port and HID mouse composite device example

{SDK}/component/example/usb/usbd_composite_cdc_acm_uac/

CDC ACM virtual serial port and UAC speaker composite device example

{SDK}/component/example/usb/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 configurable device descriptor

    • Endpoint configuration:

      • 1 control IN/OUT endpoint for enumeration

      • 1 pair of bulk IN/OUT endpoints for bulk transfer test

      • 1 pair of interrupt IN/OUT endpoints for interrupt transfer test

      • 1 pair of isochronous IN/OUT endpoints for isochronous transfer test

  • Vendor-specific device application example with following features:

    • Co-work with vendor-specific host class defined in Vendor-Specific Host Solution

    • Supports bulk/interrupt/isochronous echo test

    • Supports hot-plug

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 USB host)

USBD_ATTACH_STATUS_ATTACHED

USBD_ATTACH_STATUS_INIT -> USBD_ATTACH_STATUS_ATTACHED

N/A

ON

Reset (detached from USB host)

USBD_ATTACH_STATUS_INIT

N/A

N/A

OFF

Reset (attached to USB charger)

USBD_ATTACH_STATUS_INIT

N/A

N/A

ON

Attach to USB host

USBD_ATTACH_STATUS_ATTACHED

USBD_ATTACH_STATUS_DETACHED -> USBD_ATTACH_STATUS_ATTACHED

Y (rising edge)

OFF -> ON

Detach from USB host

USBD_ATTACH_STATUS_DETACHED

USBD_ATTACH_STATUS_ATTACHED -> USBD_ATTACH_STATUS_DETACHED

Y (falling edge)

ON -> OFF

Attach to USB charger

USBD_ATTACH_STATUS_INIT

or

USBD_ATTACH_STATUS_DETACHED

N/A

Y (rising edge)

OFF -> ON

Detach from USB charger

USBD_ATTACH_STATUS_INIT

or

USBD_ATTACH_STATUS_DETACHED

N/A

Y (falling edge)

ON -> OFF

Suspend

USBD_ATTACH_STATUS_DETACHED

USBD_ATTACH_STATUS_ATTACHED -> USBD_ATTACH_STATUS_DETACHED

By USB host configuration

By USB host configuration

Resume

USBD_ATTACH_STATUS_ATTACHED

USBD_ATTACH_STATUS_DETACHED -> USBD_ATTACH_STATUS_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