Document usb_host_hid component

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)

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 >}}
 

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.

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 <Return>.
+    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" >}}