Host Solution

In USB host mode, the USB OTG controller can enumerate connected USB devices and initiate USB transfers.

This section describes only a few host classes. For more information, refer to usb v5.4 or usb v6.18.

CDC ACM Host Solution

Configuration

In addition to the basic USB configuration, additional configuration is required to support the USB CDC ACM class driver, which can be configured as a built-in feature or as a separate kernel module.

The following configuration provides an example for supporting typical CDC ACM devices (such as USB serial ports).

Adjust the configuration as needed.

Built-in Configuration:

Enter the USB support menu and press Y to select:

Device Drivers  --->
    USB support  --->
        [*] USB Modem (CDC ACM) support
        [*] USB Serial Converter support

Module Configuration:

Enter the USB support menu and press M to select:

Device Drivers  --->
    USB support  --->
        [M] USB Modem (CDC ACM) support
        [M] USB Serial Converter support

After loading the common USB host modules, load the CDC ACM class kernel modules.

insmod /lib/modules/<kernel_ver>/kernel/drivers/usb/serial/usbserial.ko
insmod /lib/modules/<kernel_ver>/kernel/drivers/usb/class/cdc-acm.ko

Application APIs

CDC ACM devices are exposed as Linux serial ports (/dev/ttyACM*). Standard Linux serial tools and the termios API apply. For more information, refer to Linux Serial Drivers.

Usage Example

Once configured as a CDC ACM host, the SoC will recognize the connected CDC ACM device as a TTY device and can communicate with the CDC ACM device through the TTY interface.

Connect the CDC ACM device to the SoC via a USB cable. The console will print the following logs:

dwc2 40080000.usb: Set speed to high-speed
usb 1-1: new high-speed USB device number 2 using dwc2
dwc2 40080000.usb: Set speed to high-speed
cdc_acm 1-1:1.0: ttyACM0: USB ACM device

Communicate with the CDC ACM device through the device node /dev/ttyACM0. For example:
1. Send data to the CDC ACM device:
```
echo helloworld > /dev/ttyACM0
```
2. Receive data from the CDC ACM device:
```
cat /dev/ttyACM0
```

Refer to <sdk>/tests/usbh_cdc_acm for the CDC ACM host demo.

MSC Host Solution

Configuration

In addition to the basic USB configuration, additional configuration is required to support the USB MSC class driver, which can be configured as a built-in feature or as a separate kernel module.

The following configuration provides an example for supporting typical MSC devices: a UDISK using a Realtek card reader solution, formatted with a FAT32 file system.

Common configuration required for the USB MSC class driver:

SCSI device support:

Device Drivers  --->
    SCSI device support  --->
        [*] SCSI device support
        [*] SCSI disk support

VFAT file system support:

File systems  --->
    DOS/FAT/NT Filesystems  --->
        [*] VFAT (Windows-95) fs support

Native language support:

File systems  --->
    Native language support  --->
        [*] Codepage 437(United States, Canada)
        [*] NLS ISO 8859-1 (Latin 1; Western European Languages)

USB Mass Storage support:

Device Drivers  --->
    USB support  --->
        [*] USB Mass Storage support
        [*] Realtek Card Reader support

Adjust the configuration as needed.

Built-in Configuration:

Enter the USB support menu and press Y to select:

Device Drivers  --->
    USB support  --->
        [*] USB Mass Storage support
        [*] Realtek Card Reader support

Module Configuration:

Enter the USB support menu and press M to select:

Device Drivers  --->
    USB support  --->
        [M] USB Mass Storage support
        [M] Realtek Card Reader support

After loading the common USB host modules, load the MSC class kernel modules.
```
insmod /lib/modules/<kernel_ver>/kernel/drivers/usb/storage/usb-storage.ko
```

Application APIs

Refer to usb guide x498.

Usage Example

The following is an example of testing the USB host MSC driver using a supported UDISK.

Prerequisites:

Prepare a UDISK formatted with a FAT32 file system.

Connect the UDISK to the SoC. The console will output the following logs:

dwc2 40080000.usb: Set speed to high-speed
usb 1-1: new high-speed USB device number 3 using dwc2
dwc2 40080000.usb: Set speed to high-speed
usb-storage 1-1:1.0: USB Mass Storage device detected
scsi host0: usb-storage 1-1:1.0
scsi 0:0:0:0: Direct-Access TOSHIBA USB FLASH DRIVE PMAP PQ: 0 ANSI: 6
sd 0:0:0:0: [sda] 30253056 512-byte logical blocks: (15.5 GB/14.4 GiB)
sd 0:0:0:0: [sda] Write Protect is off
sd 0:0:0:0: [sda] Write cache: disabled, read cache: enabled, doesn't support DPO or FUA
sda: sda1
sd 0:0:0:0: [sda] Attached SCSI removable disk

[sda] Attached SCSI removable disk indicates successful enumeration.

Mount the UDISK device:

mkdir /mnt/udisk
mount -t vfat /dev/sda1 /mnt/udisk

Verify the mount:
```
df -h | grep sda1
```
Expected output shows /dev/sda1 mounted at /mnt/udisk.
Access the UDISK device. Create a file and perform read/write operations:
```
cd /mnt/udisk
echo hello >> test.txt
cat test.txt
hello
```
Unmount the UDISK device:
```
umount /mnt/udisk
```
After disconnecting the UDISK, the console is expected to output the following logs:
```
usb 1-1: USB disconnect, device number 3
```
Test pass criteria: The UDISK is recognized, mounted successfully, and written data can be read correctly.

UVC Host Solution

Configuration

In addition to the basic USB configuration, supporting the USB UVC class driver requires additional configuration, which can be configured as a built-in feature or as a separate kernel module.

The following configuration provides an example for supporting typical UVC devices (such as a UVC camera).

Common configuration required for UVC cameras, which is selected by default in the SDK:

Enable Multimedia support:

Device Drivers  --->
    [*] Multimedia support

Select multimedia options:

Device Drivers  --->
    Multimedia support  --->
        [*] Cameras/video grabbers support
        [*] Media Controller API
        [*] V4L2 sub-device userspace API
        [*] Media USB Adapters

Built-in Configuration:

Enter Media USB Adapters and press Y to select:

Device Drivers  --->
    Multimedia support  --->
        Media USB Adapters  --->
            [*] USB Video Class (UVC)

Module Configuration:

Enter Media USB Adapters and press M to select:

Device Drivers  --->
    Multimedia support  --->
        Media USB Adapters  --->
            [M] USB Video Class (UVC)

After loading the common USB host modules, load the UVC class kernel module and its dependencies.

insmod /lib/modules/<kernel_ver>/kernel/drivers/media/mc/mc.ko
insmod /lib/modules/<kernel_ver>/kernel/drivers/media/v4l2-core/videodev.ko
insmod /lib/modules/<kernel_ver>/kernel/drivers/media/usb/uvc/uvcvideo.ko

Application APIs

It exposes UVC devices as V4L2 devices. Refer to linux video for more information on the V4L2 API.

Usage Example

The following steps demonstrate testing the USB host UVC driver using a typical UVC camera.

Prerequisites:

An SD card is inserted and mounted (captured images will be saved to the SD card).
A UVC camera is connected to the development board via a USB cable.

After connecting the UVC camera, the console will print the following logs:

dwc2 40080000.usb: Set speed to high-speed
usb 1-1: new high-speed USB device number 2 using dwc2
dwc2 40080000.usb: Set speed to high-speed
uvcvideo: Found UVC 1.00 device USB Camera (0bda:5842)
input: USB Camera: USB Camera as /devices/platform/ocp/40080000.usb/usb1/1-1/1-1:1.0/input/input1

uvcvideo: Found UVC ... indicates successful enumeration.

Confirm the video device node:
```
ls /dev/video0
```
Run the UVC host test program to capture images:
```
rtk_usbh_uvc_test /dev/video0
```
The test captures images in 1024x768 MJPEG format and saves them to the mounted SD card.
Verify the captured images on the SD card:
```
ls /mnt/sd/
```
The presence of captured image files confirms that the UVC host driver is working correctly.

Note

The rtk_usbh_uvc_test binary is included in the packagegroup-rtk-test package, which is available in the rtk-fwk-full distro. For custom firmware, add rtk-app-usbh-uvc-test to IMAGE_INSTALL. The source code for this test is located at <sdk>/tests/usbh_uvc.

HID Host Solution

Configuration

In addition to the basic USB configuration, additional configuration is required to support the USB HID class driver, which can be configured as a built-in feature or as a separate kernel module.

The following configuration provides an example for supporting typical HID devices (such as a USB mouse or keyboard).

Adjust the configuration as needed.

Built-in Configuration:

Enter the HID support menu and press Y to select:

Device Drivers  --->
    HID support  --->
        [*] USB HID support

Module Configuration:

Enter the HID support menu and press M to select:

Device Drivers  --->
    HID support  --->
        [M] USB HID support

After loading the common USB host modules, load the HID class kernel module.
```
insmod /lib/modules/<kernel_ver>/kernel/drivers/hid/usbhid/usbhid.ko
```

Application APIs

HID devices are exposed as Linux input devices. For more information on the input API, refer to Linux Input Subsystem. For raw HID access, the /sys/class/hidraw/ interface is also available.

Usage Example

The following steps demonstrate testing the USB host HID driver using a USB mouse or keyboard.

Prerequisites:

Prepare a USB mouse or keyboard.

Connect the USB mouse or keyboard to the SoC. The console will print the following logs:

dwc2 40080000.usb: Set speed to full-speed
usb 1-1: new full-speed USB device number 2 using dwc2
hid-generic 0003:0BDA:5842.0001: hiddev0,hidraw0: USB HID v1.11 Device [USB Camera: USB Camera] on usb-40080000.usb-1/input0

hid-generic ... or usbhid: USB HID v1.11 Device ... indicates successful enumeration.

Confirm the input device node:

ls /dev/input/event*
ls /sys/class/hidraw/

Test the HID device:
- Mouse: Move the mouse and observe HID events using evtest /dev/input/eventX (replace X with the actual event number).
- Keyboard: Press keys and observe HID events using evtest /dev/input/eventX.
```
evtest /dev/input/event1
```
Note

evtest is provided by the kmodtool or util-linux package. Ensure it is included in the Yocto firmware.
Test pass criteria: The HID device is recognized (dmesg shows successful enumeration), /dev/input/event* nodes are created, and input events can be captured correctly.

UAC Host Solution

Configuration

The following configuration provides an example for supporting typical USB audio devices.

Adjust the configuration as needed.

Built-in Configuration:

Enter the Sound card support menu and press Y to select:

Device Drivers  --->
    Sound card support  --->
        USB sound devices  --->
            [*] USB Audio/MIDI drivers

Module Configuration:

Enter the Sound card support menu and press M to select:

Device Drivers  --->
    Sound card support  --->
        USB sound devices  --->
            [M] USB Audio/MIDI drivers

After loading the common USB host modules, load the USB audio class kernel modules.

insmod /lib/modules/<kernel_ver>/kernel/sound/core/snd-hwdep.ko
insmod /lib/modules/<kernel_ver>/kernel/sound/core/snd-rawmidi.ko
insmod /lib/modules/<kernel_ver>/kernel/sound/usb/snd-usbmidi-lib.ko
insmod /lib/modules/<kernel_ver>/kernel/sound/usb/snd-usb-audio.ko

Application APIs

USB audio devices are exposed as ALSA sound cards. The following standard ALSA tools are available:

``arecord``: Capture audio from a recording device.
``aplay``: Play audio to a playback device.
``amixer``: Control mixer settings (volume, mute).
``alsamixer``: Interactive mixer control (terminal interface).

Refer to Linux ALSA documentation for more details.

Usage Example

The following steps demonstrate testing the USB host UAC driver using a USB audio device.

Prerequisites:

Prepare a USB audio device (such as a USB sound card, USB microphone, or USB headset).

Connect the USB audio device to the SoC. The console will print the following logs:

dwc2 40080000.usb: Set speed to full-speed
usb 1-1: new full-speed USB device number 2 using dwc2
usbcore: registered new interface driver snd-usb-audio

snd-usb-audio indicates that the driver has bound successfully.

Confirm the ALSA sound card:
```
cat /proc/asound/cards
aplay -l
arecord -l
```
In the expected output, the USB audio device will appear as an additional sound card (e.g., card 1).

Note

The onboard audio codec typically occupies card 0. The USB audio device will be assigned the next available sound card number.
Test audio recording:
```
arecord -D plughw:CARD=1,DEV=0 -f S16_LE -r 48000 -c 2 -d 5 /tmp/usb_audio_test.wav
```
Parameter description:
- -D plughw:CARD=1,DEV=0: Use the ALSA plugin device, Card 1 (USB audio device), Device 0. plughw automatically performs format conversion and has better compatibility than hw.
- -f S16_LE: Sample format, 16-bit signed little-endian.
- -r 48000: Sample rate 48000 Hz (UAC standard sample rate).
- -c 2: Number of channels 2 (stereo).
- -d 5: Recording duration 5 seconds.
After recording completes, verify the file size:
```
ls -lh /tmp/usb_audio_test.wav
```
A 5-second stereo 48 kHz 16-bit WAV file should be approximately 960 KB (excluding the WAV header).
Test audio playback (play the just-recorded file):
```
aplay -D plughw:CARD=1,DEV=0 /tmp/usb_audio_test.wav
```
Parameter description:
- -D plughw:CARD=1,DEV=0: Use the ALSA plugin device, Card 1 (USB audio device), Device 0.
- /tmp/usb_audio_test.wav: Path to the WAV file to play.
Confirm sound output from the device. If aplay reports an underrun error, try changing plughw to hw, or check the volume settings with amixer -c 1 contents.
Volume and mute control:
```
amixer -c 1 contents
amixer -c 1 cset name='PCM Playback Volume' 80
amixer -c 1 cset name='PCM Playback Switch' off
amixer -c 1 cset name='PCM Playback Switch' on
```
Parameter description:
- amixer -c 1 contents: List all mixer controls for card 1.
- amixer -c 1 cset name='PCM Playback Volume' 80: Set playback volume to 80. Volume range is typically 0-100.
- amixer -c 1 cset name='PCM Playback Switch' off: Set playback switch to off (mute).
- amixer -c 1 cset name='PCM Playback Switch' on: Set playback switch to on (unmute).
Note

Mixer control names vary by USB audio device. Use amixer -c 1 contents to find the exact control names for your device.
Test pass criteria: The USB audio device is recognized, arecord captures successfully (non-zero file size),

and aplay playback produces sound output.

Vendor Host Solution

Configuration

In addition to the basic USB configuration, additional configuration is required to support the USB Vendor class driver, which can be configured as a built-in feature or as a separate kernel module.

Built-in Configuration:

Enter the USB support menu and press Y to select:

Device Drivers  --->
    USB support  --->
        [*] USB testing driver

Module Configuration:

Enter the USB support menu and press M to select:

Device Drivers  --->
    USB support  --->
        [M] USB testing driver

After loading the common USB host modules, load the Vendor class kernel module.
```
insmod /lib/modules/<kernel_ver>/kernel/drivers/usb/misc/usbtest.ko
```

Application APIs

None.

Usage Example

This example demonstrates testing a custom USB device using the USB vendor driver.

Prerequisites:

Prepare a USB vendor device to connect to the development board.

Compile the test program:

The SDK provides test source code testusb.c under <sdk>/tests/usbh_vendor/. Compile it in the SDK root directory:

cd <sdk>/tests/usbh_vendor
make

The compiled binary is rtk_usbh_vendor_test.

Run the test:

Loopback test (case 30):

rtk_usbh_vendor_test -a -c1 -t30 -s256 -g32 -v1

Sourcesink test (other cases):

testusb -a

Parameter description:

-t30: Select the Loopback test case.
-s256: Transfer data block size 256 bytes.
-g32: Loop count 32.
-v1: Verbose output.
-a: Auto-enumerate devices.

Composite Host Solution

Configuration

A composite host solution reuses the kernel configuration of each function class and requires no additional options. Using a HID + USB audio combination as an example, both function classes must be enabled simultaneously (refer to their respective configuration sections):

Built-in Configuration:

Device Drivers  --->
    HID support  --->
        USB HID support  --->
            [*] USB HID transport layer
    Sound card support  --->
        USB sound devices  --->
            [*] USB Audio/MIDI drivers

Module Configuration:

Configure the following options:

Device Drivers  --->
    HID support  --->
        USB HID support  --->
            [M] USB HID transport layer
    Sound card support  --->
        USB sound devices  --->
            [M] USB Audio/MIDI drivers

After loading the common USB host modules, load the function-specific kernel modules:

insmod /lib/modules/$(uname -r)/kernel/drivers/hid/usbhid/usbhid.ko
insmod /lib/modules/$(uname -r)/kernel/sound/core/snd-hwdep.ko
insmod /lib/modules/$(uname -r)/kernel/sound/core/snd-rawmidi.ko
insmod /lib/modules/$(uname -r)/kernel/sound/usb/snd-usbmidi-lib.ko
insmod /lib/modules/$(uname -r)/kernel/sound/usb/snd-usb-audio.ko

Application APIs

None.

Example

The Linux USB host handles composite USB devices automatically — during enumeration, the corresponding class driver is bound to each interface independently, with no additional configuration required. This example uses a USB headset with media control keys (HID + UAC composite device).

Connect the composite USB device (e.g., a USB headset) to the SoC. The console will print enumeration logs for each interface:

usb 1-1: new full-speed USB device number 2 using dwc2
hid-generic 0003:xxxx:xxxx.0001: hiddev0,hidraw0: USB HID v1.11 Device on usb-40080000.usb-1/input3
usbcore: registered new interface driver snd-usb-audio

Each class driver binds independently and does not interfere with the other.

Confirm the HID interface:
```
ls /dev/input/event*
```
Confirm the UAC audio interface:
```
cat /proc/asound/cards
aplay -l
arecord -l
```
The USB audio device will appear as a separate sound card (e.g., card 1).
Test HID functionality (using media keys as an example):
```
evtest /dev/input/event1
```
Press a volume key on the device; the corresponding HID input event should be observed.

Test UAC audio functionality:

arecord -D plughw:CARD=1,DEV=0 -f S16_LE -r 48000 -c 2 -d 5 /tmp/test.wav
aplay -D plughw:CARD=1,DEV=0 /tmp/test.wav

Pass criteria: the composite USB device enumerates successfully; the HID interface (/dev/input/event*) and UAC audio interface (ALSA sound card) are available simultaneously with each function operating independently.