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 API reference

Overview

The USB HID input interface in the RTOS SDK is provided by drv_input, which unifies the abstract keyboard, mouse and USB touch input devices.

Header file location:

#include "drv_input.h"

Corresponding source code:

• src/rtsmart/libs/rtsmart_hal/drivers/input/drv_input.h

• src/rtsmart/libs/rtsmart_hal/drivers/input/drv_input.c

Device type

enum drv_input_device_type {
    DRV_INPUT_DEV_UNKNOWN = 0,
    DRV_INPUT_DEV_KEYBOARD,
    DRV_INPUT_DEV_MOUSE,
    DRV_INPUT_DEV_TOUCH,
};

Key data structures

struct drv_input_info

Device capability information:

• kind: device type

• ev_bits: Supported event bitmap

• key_bits: Supported key bitmap

• rel_bits: Supported relative coordinate bitmap

• abs_bits: Supported absolute coordinate bitmap

• name: device name

drv_input_inst_t

Input device instance handle, including:

• id: device number

• fd: device file descriptor

• button_state: Current button status bit

• path: device path

The application layer should only use it as a handle, and it is not recommended to modify the members directly.

struct drv_keyboard_frame

Keyboard frame:

• keycodes[]: key code array

• values[]: Key value array, corresponding to KEY_PRESSED / KEY_RELEASED / KEY_REPEAT

• count: Number of events in this frame

• complete: Whether the synchronization end event has been read

struct drv_pointer_frame

Pointer frames, for mouse and USB touch devices:

• complete

• has_rel

• has_abs

• touch_seen

• touch_down

• rel_x / rel_y

• wheel / hwheel

• abs_x / abs_y

• pressure

• buttons

• pressed_mask

• released_mask

Basic instance API

drv_input_inst_create

int drv_input_inst_create(int id, drv_input_inst_t **inst);

Open the input device by event number, for example event0.

drv_input_inst_create_path

int drv_input_inst_create_path(const char *path, drv_input_inst_t **inst);

Open the input device by path, for example /dev/hidk0.

drv_input_inst_destroy

void drv_input_inst_destroy(drv_input_inst_t **inst);

Close and destroy the instance.

Read and write API

drv_input_poll

int drv_input_poll(drv_input_inst_t *inst, int timeout_ms);

Wait for input events.

Return value:

• > 0: There is an event

• 0: timeout

• < 0: error code

drv_input_read_event

int drv_input_read_event(drv_input_inst_t *inst, struct input_event *event);

Read a single raw input_event.

drv_input_read_frame

int drv_input_read_frame(drv_input_inst_t *inst, struct drv_input_frame *frame);

Read one frame of raw input events until a synchronization event is encountered or there is no more data.

drv_input_read_keyboard_frame

int drv_input_read_keyboard_frame(drv_input_inst_t *inst, struct drv_keyboard_frame *frame);

Read the keyboard frame.

Return value:

• > 0: Number of key-value pairs in the frame

• 0: There are currently no complete keyboard events

• < 0: error code

drv_input_read_pointer_frame

int drv_input_read_pointer_frame(drv_input_inst_t *inst, struct drv_pointer_frame *frame);

Read pointer frames for mouse and USB touch.

Information and Discovery API

drv_input_get_info

int drv_input_get_info(drv_input_inst_t *inst, struct drv_input_info *info);

Query device capability information.

drv_input_find_first_by_type

int drv_input_find_first_by_type(uint32_t kind,
                                 char *path,
                                 size_t path_size,
                                 struct drv_input_info *info);

Finds the first input device of the specified type and returns path and capability information.

Applicable to the following scenarios:

• Automatically discover USB keyboard on startup

• Rebind similar devices after hot swapping

Hot plug related API

drv_input_is_disconnect_error

bool drv_input_is_disconnect_error(int ret);

Determine whether an error code indicates that the device has been disconnected.

Currently the following errors are mainly identified:

• -ENODEV

• -EIO

• -ENXIO

drv_input_reconnect_path

int drv_input_reconnect_path(drv_input_inst_t **inst,
                             const char *path,
                             struct drv_input_info *info);

Reopen the device according to the fixed path.

drv_input_reconnect_by_type

int drv_input_reconnect_by_type(drv_input_inst_t **inst,
                                uint32_t kind,
                                char *path,
                                size_t path_size,
                                struct drv_input_info *info);

Rediscover and reconnect devices by device type.

This is the most commonly used interface in USB HID hot plug scenarios.

Event auxiliary judgment API

drv_input_is_key_event

bool drv_input_is_key_event(const struct input_event *event);

drv_input_is_rel_event

bool drv_input_is_rel_event(const struct input_event *event);

drv_input_is_abs_event

bool drv_input_is_abs_event(const struct input_event *event);

drv_input_is_sync_event

bool drv_input_is_sync_event(const struct input_event *event);

Used to determine the original input_event type.

Recommended calling process

keyboard

1. Open the device using drv_input_inst_create_path() or drv_input_reconnect_by_type()

2. Call drv_input_poll() to wait for data

3. Call drv_input_read_keyboard_frame() to read the frame

4. If an error is returned, use drv_input_is_disconnect_error() to determine whether reconnection is required.

5. Call drv_input_inst_destroy() on exit

Mouse/USB touch

1. Open input instance

2. Call drv_input_poll() to wait for data

3. Call drv_input_read_pointer_frame() to read the pointer frame

4. Use fields such as has_rel / has_abs / buttons / touch_down to process input

5. Reconnect when disconnected

Sample code snippet

drv_input_inst_t *inst = NULL;
struct drv_input_info info;

if (drv_input_reconnect_by_type(&inst,
                                DRV_INPUT_DEV_KEYBOARD,
                                NULL,
                                0,
                                &info) == 0) {
    printf("keyboard ready: %s\n", info.name);
}

struct drv_keyboard_frame frame;
int ret = drv_input_read_keyboard_frame(inst, &frame);
if (ret > 0) {
    for (size_t i = 0; i < frame.count; i++) {
        printf("key=%u value=%d\n", frame.keycodes[i], frame.values[i]);
    }
}

Things to note

1. Do not treat Linux input keycodes as consecutive character numbers, especially alphabetic keys.

2. For hot-swappable devices, it is recommended to always combine drv_input_is_disconnect_error() and drv_input_reconnect_by_type().

3. The reading interfaces of keyboard and pointing devices are different, do not mix drv_input_read_keyboard_frame() and drv_input_read_pointer_frame().

Related documents

• USB HID Examples and Test Instructions