Note

This is the documentation for the latest development branch and may refer to features that are not available in released versions. If you are looking for the documentation for a specific release, use the drop-down menu on the left and select the desired version.

USB HID Samples and Test Notes

Overview

The RTOS SDK provides USB HID input access based on drv_input, covering keyboards, mice, and USB touch devices. The current repository already includes keyboard and mouse test programs that can be used to verify:

• blocking reads

• non-blocking reads

• poll() event notification

• automatic reconnect after device unplug and replug

Related source files:

• src/rtsmart/examples/peripheral/usb_hid_kbd/test_hid.c

• src/rtsmart/examples/peripheral/usb_hid_mouse/test_hid_mouse.c

Device Nodes

Common device nodes include:

• keyboard: /dev/hidk0

• mouse: /dev/hidm0

• USB touch: usually exposed through the same drv_input pointer interface, with the exact node name depending on the registered device

If you are not sure which node to use, call drv_input_reconnect_by_type() to locate a device of the required class automatically.

Keyboard Test

Source Location

src/rtsmart/examples/peripheral/usb_hid_kbd/test_hid.c

Sample Content

This sample includes three test modes:

1. blocking read: call drv_input_poll(inst, -1) first, then read a full keyboard frame

2. non-blocking read: loop on reads and verify the empty-read path when no data is available

3. poll() read: wait for POLLIN with a timeout and then continue reading the current frame

Run

./test_hid [dev_path]

Parameters:

• dev_path: optional, defaults to /dev/hidk0

Representative Output

=== Test 1: Blocking Read ===
Opening /dev/hidk0 in blocking mode...
Device opened successfully (fd=3)
Press keys on USB keyboard...
    EV_KEY: G -> PRESSED
    EV_KEY: G -> RELEASED
    EV_SYN: --- frame 1 end ---

Hot-Plug Behavior

If poll() or read() returns a disconnect-related error, the test program repeatedly calls drv_input_reconnect_by_type() or drv_input_reconnect_path() until the device is available again.

Mouse Test

Source Location

src/rtsmart/examples/peripheral/usb_hid_mouse/test_hid_mouse.c

Sample Content

The mouse test also includes three modes:

1. blocking read

2. non-blocking read

3. poll() read

The output includes:

• button press and release events

• relative movement REL_X / REL_Y

• wheel events REL_WHEEL / REL_HWHEEL

• absolute coordinates ABS_X / ABS_Y

• pressure ABS_PRESSURE

Run

./test_hid_mouse [dev_path]

Parameters:

• dev_path: optional, usually /dev/hidm0 by default

Representative Output

=== Test 3: Poll Read ===
    EV_KEY: LEFT -> PRESSED
    EV_REL: REL_X -> 15
    EV_REL: REL_Y -> -4
    EV_SYN: --- frame end ---

USB Touch Integration Notes

The drv_input pointer-frame structure is compatible with both mice and USB touch devices. If your USB touch device uses the HID protocol, you can reuse the following interfaces:

• drv_input_poll()

• drv_input_read_pointer_frame()

• drv_input_reconnect_by_type(..., DRV_INPUT_DEV_TOUCH, ...)

For USB touch, the most relevant fields are usually:

• has_abs

• abs_x / abs_y

• pressure

• touch_seen

• touch_down

Recommended Development Flow

1. Use the sample programs first to verify the device node, hot-plug behavior, and event format.

2. Use drv_input_read_keyboard_frame() for keyboard devices.

3. Use drv_input_read_pointer_frame() for mice and USB touch devices.

4. In production applications, combine drv_input_poll() with reconnect logic instead of waiting indefinitely on a single read.

FAQ

Why are keyboard characters displayed incorrectly?

If an upper-layer application needs to convert keycodes to characters, do not assume that KEY_A through KEY_Z are contiguous. Linux input-event keycodes are not arranged in alphabetical order, so an explicit mapping table should be used.

Why does the application stop receiving data after the device is unplugged?

When a timed poll or read fails, check drv_input_is_disconnect_error(ret) and actively enter the reconnect path.

Related Documentation

• USB HID API reference

• USB HID keyboard sample