# 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
1. non-blocking read: loop on reads and verify the empty-read path when no data is available
1. `poll()` read: wait for `POLLIN` with a timeout and then continue reading the current frame

### Run

```shell
./test_hid [dev_path]
```

Parameters:

- `dev_path`: optional, defaults to `/dev/hidk0`

### Representative Output

```text
=== 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
1. non-blocking read
1. `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

```shell
./test_hid_mouse [dev_path]
```

Parameters:

- `dev_path`: optional, usually `/dev/hidm0` by default

### Representative Output

```text
=== 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.
1. Use `drv_input_read_keyboard_frame()` for keyboard devices.
1. Use `drv_input_read_pointer_frame()` for mice and USB touch devices.
1. 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](../../api_reference/peripheral/usb_hid.md)
- [USB HID keyboard sample](usb_hid_kbd.md)