USB Host Function

Experiment Objective

In this experiment, you will learn how to implement the USB host function on the MicroROS-V2 control board, connecting a USB keyboard, mouse, or gamepad through the ESP32-S3's USB OTG interface. Through this example, you will master the use of the USB Host Library and the HID (Human Interface Device) class driver in ESP-IDF.

Experiment Principle

1. Keywords

2. Technical Architecture

The program adopts a multitasking architecture: the USB library task handles USB bus events, the HID host task handles HID device events, and the application entry is responsible for initialization and startup. When a USB HID device is connected, the program automatically identifies the device type (keyboard/mouse/gamepad) and parses the data of the corresponding protocol. The keyboard and mouse are parsed using the Boot protocol, while the gamepad is parsed through a custom 9-byte report format. Key files are located in ~/esp/base_samples/usb_host/hid/, including main/hid_host_example.c (main program entry), main/joydata_gamepad.h (gamepad data structure) and main/joydata_gamepad.c (gamepad data parsing), main/CMakeLists.txt (build configuration) and main/idf_component.yml (component dependencies).

Experiment Steps

1. Hardware Preparation

2. Prerequisites

1. ESP32-IDF development environment set up

2. MicroROS-V2 control board connected to the PC via USB

3. Connect the USB HID device to the control board using the USB OTG adapter cable

3. Compile and Flash

​x

cd ~/esp/base_samples/usb_host/hid
source ~/esp/esp-idf/export.sh
idf.py build flash monitor

Note: This example depends on the espressif/usb_host_hid component (version 1.0.0), which is automatically downloaded from the Espressif Component Registry on the first compilation.

4. How to Stop

Press the Boot button (GPIO0) on the control board to exit the program, or press Ctrl+] in the terminal to exit the serial monitor.

Experiment Result

After compiling and flashing successfully, when a keyboard is connected, the serial output is:

xxxxxxxxxx
I (xxx) example: HID Host example
I (xxx) example: HID Device, protocol 'KEYBOARD' CONNECTED
Keyboard
Hello, ESP32 USB HID Keyboard is here!

When a mouse is connected, the output is:

xxxxxxxxxx
Mouse
X: 000883       Y: 000058       |o| |

When a gamepad is connected, the output is:

xxxxxxxxxx
JOYDATA LJ(h= 1 v= 0 btn=0) RJ(h= 0 v= 0 btn=0) DPAD(h= 0 v= 0) A=0 B=0 X=0 Y=0 L1=0 L2=0 R1=0 R2=0 SEL=0 START=0 ts=12345 ms

Press the Boot button (GPIO0) on the control board to exit the program.

Code Explanation

Source code paths:

• Firmware source code: ~/esp/base_samples/usb_host/hid/main/hid_host_example.c

• Gamepad data: ~/esp/base_samples/usb_host/hid/main/joydata_gamepad.h, joydata_gamepad.c

1. Main Program Logic

main/hid_host_example.c is the program entry, and the overall architecture is divided into three tasks:

1. USB library task (usb_lib_task):

   • Configure GPIO0 as input (Boot button, press to exit)

   • Call usb_host_install() to install the USB host library

   • Loop calling usb_host_lib_handle_events() to handle USB events

   • When GPIO0 becomes low, call usb_host_uninstall() to uninstall the USB library

2. HID host task (hid_host_task):

   • Create the event queue hid_host_event_queue

   • Receive events from the HID driver and call hid_host_device_event() to handle them

3. Application entry (app_main):

   • Create the USB library task and wait for its initialization to complete

   • Call hid_host_install() to install the HID host driver (with a built-in background task)

   • Create the HID host task to handle device events

2. Key Components

USB hardware pins (see the README):

xxxxxxxxxx
ESP32-S3      USB Type-A connector
GPIO19  --->  D-
GPIO20  --->  D+

Exit button: GPIO0 (Boot button), press to exit the program.

main/hid_host_example.c — main program file, core functions:

HID driver configuration:

Parameter definition file: ~/esp/base_samples/usb_host/hid/main/hid_host_example.c

xxxxxxxxxx
const hid_host_driver_config_t hid_host_driver_config = {
    .create_background_task = true,   // Create the background event handling task
    .task_priority = 5,
    .stack_size = 4096,
    .core_id = 0,
    .callback = hid_host_device_callback,
    .callback_arg = NULL
};

Device connection handling:

When a HID device is connected, the HID_HOST_DRIVER_EVENT_CONNECTED event in hid_host_device_event() is triggered, and the following operations are performed:

1. Call hid_host_device_open() to open the device

2. For Boot subclass devices, call hid_class_request_set_protocol() to set the Boot protocol

3. For keyboard devices, call hid_class_request_set_idle() to set the idle rate

4. Call hid_host_device_start() to start receiving data

3. Keyboard Data Processing

The keyboard uses the Boot protocol and is parsed through the hid_keyboard_input_report_boot_t structure. hid_host_keyboard_report_callback() maintains an array of the previous frame's key states, detects press and release events by comparing the old and new key arrays, and converts the key code to an ASCII character for output via hid_keyboard_get_char().

4. Mouse Data Processing

The mouse uses the Boot protocol and is parsed through the hid_mouse_input_report_boot_t structure. hid_host_mouse_report_callback() accumulates the absolute X/Y position and displays the left/right button states of the mouse.

5. Gamepad Data Processing

main/joydata_gamepad.h — gamepad data structure definitions:

xxxxxxxxxx
typedef struct {
    int8_t left_joystick_h;           // Left joystick horizontal (left=+1, right=-1, center=0)
    int8_t left_joystick_v;           // Left joystick vertical (up=+1, down=-1, center=0)
    uint8_t left_joystick_button;     // Left joystick button
    int8_t right_joystick_h;          // Right joystick horizontal
    int8_t right_joystick_v;          // Right joystick vertical
    uint8_t right_joystick_button;    // Right joystick button
    int8_t left_button_upper_plane_h; // D-pad horizontal
    int8_t left_button_upper_plane_v; // D-pad vertical
    uint8_t right_button_upper_plane_a, b, x, y;  // ABXY buttons
    uint8_t left_button_frontal_plane_l1, l2;     // L1/L2 buttons
    uint8_t right_button_frontal_plane_r1, r2;    // R1/R2 buttons
    uint8_t select, start;
    uint32_t timestamp_ms;            // Timestamp
} joy_data_t;

main/joydata_gamepad.c — gamepad data parsing (9-byte report format):

main/CMakeLists.txt — component registration:

xxxxxxxxxx
idf_component_register(
    SRCS
        "hid_host_example.c"
        "joydata_gamepad.c"
    INCLUDE_DIRS "."
    PRIV_REQUIRES driver usb
)

main/idf_component.yml — component dependency declarations:

xxxxxxxxxx
dependencies:
  idf: ">=4.4"
  usb_host_hid: "1.0.0"

Common Problems