|
| 1 | +--- |
| 2 | +description: "Instructions for setting up a USB HID Host interface on an ESP32 in ESPHome" |
| 3 | +title: "USB HID Host Interface" |
| 4 | +params: |
| 5 | + seo: |
| 6 | + description: Instructions for setting up a USB HID Host interface on an ESP32 in ESPHome |
| 7 | + image: usb.svg |
| 8 | +--- |
| 9 | + |
| 10 | +The USB HID Host interface on the ESP32-S2, ESP32-S3 and ESP32-P4 is used to |
| 11 | +connect to USB HID (Human Interface Device) peripheral devices, that is, |
| 12 | +keyboards and mouses. Multiple devices may be configured and connected at once. |
| 13 | +By default, devices must be directly connected to the ESP32, but this can be |
| 14 | +changed by setting the `enable_hubs` option to `true`. |
| 15 | + |
| 16 | +This component only supports **keyboards** today. Key presses, assuming a |
| 17 | +standard US keyboard layout, will be accumulated internally. It is therefore |
| 18 | +most useful in combination with a {{< docref "/components/key_collector" >}} to |
| 19 | +do an action with the recorded keys, as illustrated below. |
| 20 | + |
| 21 | +```yaml |
| 22 | +# Example configuration entry |
| 23 | +usb_host_hid: |
| 24 | + enable_hubs: true |
| 25 | + keyboards: |
| 26 | + - id: kbd_1 |
| 27 | + vid: 0x1725 |
| 28 | + pid: 0x1234 |
| 29 | + |
| 30 | +key_collector: |
| 31 | + - id: reader_1 |
| 32 | + source_id: kbd_1 |
| 33 | + # Collects whole lines of text, up to <Return>. |
| 34 | + end_keys: "\r" |
| 35 | + timeout: 1s |
| 36 | + # on_result: |
| 37 | + # ... |
| 38 | +``` |
| 39 | + |
| 40 | +> [!NOTE] |
| 41 | +> This component cannot be used in combination with the |
| 42 | +> {{< docref "/components/usb_host" >}} as both components need to assume |
| 43 | +> control of the plugged USB devices, which would create a conflict. |
| 44 | +
|
| 45 | +## Configuration variables |
| 46 | + |
| 47 | +- **id** (*Optional*, [ID](#config-id)): The id to use for this component. |
| 48 | +- **enable_hubs** (*Optional*, boolean): Whether to include support for hubs. |
| 49 | + Defaults to `false`. |
| 50 | +- **keyboards** (*Optional*, list): A list of keyboard devices to configure. |
| 51 | + |
| 52 | +## Keyboard configuration options |
| 53 | + |
| 54 | +- **id** (*Optional*, [ID](#config-id)): An id to assign to the device. |
| 55 | +- **check_class**: (*Optional*, boolean): Whether to check the device's HID |
| 56 | + class is indeed “keyboard”. Defaults to `true`. |
| 57 | +- **vid** (**Required**, int): The vendor ID of the device. Use 0 as a wildcard. |
| 58 | +- **pid** (**Required**, int): The product ID of the device. Use 0 as a wildcard. |
| 59 | + |
| 60 | +If a device is configured and a device is connected that matches the |
| 61 | +configuration, the device will be connected to the ESP32 and log entries will |
| 62 | +appear at the DEBUG level. If the log level is set to VERBOSE, then individual |
| 63 | +key presses will be logged. The device will remain connected until it is |
| 64 | +disconnected or the ESP32 is reset. |
| 65 | + |
| 66 | +> [!WARNING] |
| 67 | +> If multiple devices are plugged in that match the same wildcard |
| 68 | +> configuration, only the first one will be correctly handled. A log entry at |
| 69 | +> WARNING level will appear for subsequent conflicting devices. Make sure you |
| 70 | +> have one `keyboards` configuration declared for each of the devices you intend |
| 71 | +> to plug in, and that they do not overlap with each other. |
| 72 | +
|
| 73 | +If a device is plugged in that does not match any configured device, it will be |
| 74 | +ignored and a log entry will appear at the DEBUG level. |
| 75 | + |
| 76 | +If a configured device is plugged in that does *not* declare itself as a HID |
| 77 | +keyboard, it will be ignored and a log entry will appear at the WARNING level. |
| 78 | +Some devices may work just fine (they report key presses) with this component, |
| 79 | +but do not declare themselves as keyboards, in which case you can set |
| 80 | +`check_class` to `false`. |
| 81 | + |
| 82 | +### See Also |
| 83 | + |
| 84 | +- {{< docref "/components/usb_host" >}} |
| 85 | +- {{< apiref "usb_host_hid/usb_hid.h" "usb_host_hid/usb_hid.h" >}} |
0 commit comments