From b951bd97e154cc54142df083e1759eb457b9adc4 Mon Sep 17 00:00:00 2001 From: Alexandre Macabies Date: Tue, 21 Oct 2025 19:59:42 +0200 Subject: [PATCH] Document usb_host_hid component --- content/changelog/2025.10.0.md | 3 ++ content/components/_index.md | 1 + content/components/usb_host.md | 5 ++ content/components/usb_host_hid.md | 85 ++++++++++++++++++++++++++++++ 4 files changed, 94 insertions(+) create mode 100644 content/components/usb_host_hid.md diff --git a/content/changelog/2025.10.0.md b/content/changelog/2025.10.0.md index 96dff2468f..82b065368a 100644 --- a/content/changelog/2025.10.0.md +++ b/content/changelog/2025.10.0.md @@ -267,6 +267,7 @@ These optimizations benefit all platforms, but ESP8266 users will notice the mos - **Configurable Ethernet MAC address** in YAML - **QMC5883L DRDY pin** for maximum sampling rate - **USB host/UART** support on ESP32-P4 +- **USB HID host** support (i.e. USB keyboard events) on ESP-IDF platforms ## For Contributors @@ -392,6 +393,7 @@ continue working, but custom components and advanced setups may require updates. - [api] Add support for getting action responses from home-assistant [esphome#10948](https://github.com/esphome/esphome/pull/10948) by [@jesserockz](https://github.com/jesserockz) (new-feature) - [epaper_spi] New epaper component [esphome#10462](https://github.com/esphome/esphome/pull/10462) by [@jesserockz](https://github.com/jesserockz) (new-component) (new-feature) (new-platform) - [usb_host] Fix transfer slot exhaustion at high data rates and add configurable max_transfer_requests [esphome#11174](https://github.com/esphome/esphome/pull/11174) by [@bdraco](https://github.com/bdraco) (new-feature) +- [ush_host_hid] New USB Host HID component, allowing to receive USB keyboard inputs on ESP-IDF devices [esphome#9680](https://github.com/esphome/esphome/pull/9680) by [@zopieux](https://github.com/zopieux) (new-component) (new-feature) ### New Components @@ -681,6 +683,7 @@ continue working, but custom components and advanced setups may require updates. - [ota] Increase handshake timeout to 20s now that auth is non-blocking [esphome#11186](https://github.com/esphome/esphome/pull/11186) by [@bdraco](https://github.com/bdraco) - [esp32_improv] Fix state not transitioning to PROVISIONED when WiFi configured via captive portal [esphome#11181](https://github.com/esphome/esphome/pull/11181) by [@bdraco](https://github.com/bdraco) - [usb_host] Fix transfer slot exhaustion at high data rates and add configurable max_transfer_requests [esphome#11174](https://github.com/esphome/esphome/pull/11174) by [@bdraco](https://github.com/bdraco) (new-feature) +- [ush_host_hid] New USB Host HID component, allowing to receive USB keyboard inputs on ESP-IDF devices [esphome#9680](https://github.com/esphome/esphome/pull/9680) by [@zopieux](https://github.com/zopieux) (new-component) (new-feature) - [media_player.speaker] Dynamic auto load [esphome#11084](https://github.com/esphome/esphome/pull/11084) by [@jesserockz](https://github.com/jesserockz) - [core] Properly clean the build dir in the HA addon [esphome#11208](https://github.com/esphome/esphome/pull/11208) by [@swoboda1337](https://github.com/swoboda1337) - Fix log retrieval with FQDN when mDNS is disabled [esphome#11202](https://github.com/esphome/esphome/pull/11202) by [@bdraco](https://github.com/bdraco) diff --git a/content/components/_index.md b/content/components/_index.md index 0570e30e7e..cd133968bc 100644 --- a/content/components/_index.md +++ b/content/components/_index.md @@ -169,6 +169,7 @@ Create update entities simplifying management of OTA updates. "SPI Bus","components/spi","spi.svg","" "UART","components/uart","uart.svg","" "USB Host","components/usb_host","usb.svg","dark-invert" +"USB HID Host","components/usb_host_hid","usb.svg","dark-invert" "USB UART","components/usb_uart","usb.svg","dark-invert" {{< /imgtable >}} diff --git a/content/components/usb_host.md b/content/components/usb_host.md index 33a7968551..0fdf04d4a2 100644 --- a/content/components/usb_host.md +++ b/content/components/usb_host.md @@ -25,6 +25,11 @@ usb_host: pid: 0x1234 ``` +> [!NOTE] +> This component cannot be used in combination with the +> {{< docref "/components/usb_host_hid" >}} as both components need to assume +> control of the plugged USB devices, which would create a conflict. + ## Configuration variables - **id** (*Optional*, [ID](#config-id)): The id to use for this component. diff --git a/content/components/usb_host_hid.md b/content/components/usb_host_hid.md new file mode 100644 index 0000000000..67055e982d --- /dev/null +++ b/content/components/usb_host_hid.md @@ -0,0 +1,85 @@ +--- +description: "Instructions for setting up a USB HID Host interface on an ESP32 in ESPHome" +title: "USB HID Host Interface" +params: + seo: + description: Instructions for setting up a USB HID Host interface on an ESP32 in ESPHome + image: usb.svg +--- + +The USB HID Host interface on the ESP32-S2, ESP32-S3 and ESP32-P4 is used to +connect to USB HID (Human Interface Device) peripheral devices, that is, +keyboards and mouses. Multiple devices may be configured and connected at once. +By default, devices must be directly connected to the ESP32, but this can be +changed by setting the `enable_hubs` option to `true`. + +This component only supports **keyboards** today. Key presses, assuming a +standard US keyboard layout, will be accumulated internally. It is therefore +most useful in combination with a {{< docref "/components/key_collector" >}} to +do an action with the recorded keys, as illustrated below. + +```yaml +# Example configuration entry +usb_host_hid: + enable_hubs: true + keyboards: + - id: kbd_1 + vid: 0x1725 + pid: 0x1234 + +key_collector: + - id: reader_1 + source_id: kbd_1 + # Collects whole lines of text, up to . + end_keys: "\r" + timeout: 1s + # on_result: + # ... +``` + +> [!NOTE] +> This component cannot be used in combination with the +> {{< docref "/components/usb_host" >}} as both components need to assume +> control of the plugged USB devices, which would create a conflict. + +## Configuration variables + +- **id** (*Optional*, [ID](#config-id)): The id to use for this component. +- **enable_hubs** (*Optional*, boolean): Whether to include support for hubs. + Defaults to `false`. +- **keyboards** (*Optional*, list): A list of keyboard devices to configure. + +## Keyboard configuration options + +- **id** (*Optional*, [ID](#config-id)): An id to assign to the device. +- **check_class**: (*Optional*, boolean): Whether to check the device's HID + class is indeed “keyboard”. Defaults to `true`. +- **vid** (**Required**, int): The vendor ID of the device. Use 0 as a wildcard. +- **pid** (**Required**, int): The product ID of the device. Use 0 as a wildcard. + +If a device is configured and a device is connected that matches the +configuration, the device will be connected to the ESP32 and log entries will +appear at the DEBUG level. If the log level is set to VERBOSE, then individual +key presses will be logged. The device will remain connected until it is +disconnected or the ESP32 is reset. + +> [!WARNING] +> If multiple devices are plugged in that match the same wildcard +> configuration, only the first one will be correctly handled. A log entry at +> WARNING level will appear for subsequent conflicting devices. Make sure you +> have one `keyboards` configuration declared for each of the devices you intend +> to plug in, and that they do not overlap with each other. + +If a device is plugged in that does not match any configured device, it will be +ignored and a log entry will appear at the DEBUG level. + +If a configured device is plugged in that does *not* declare itself as a HID +keyboard, it will be ignored and a log entry will appear at the WARNING level. +Some devices may work just fine (they report key presses) with this component, +but do not declare themselves as keyboards, in which case you can set +`check_class` to `false`. + +### See Also + +- {{< docref "/components/usb_host" >}} +- {{< apiref "usb_host_hid/usb_hid.h" "usb_host_hid/usb_hid.h" >}}