TinyUSB Keyboard

The tinyusb_keyboard component makes the device appear to a USB host as a keyboard with media keys, built on TinyUSB. Actions press and release keys, so a button, a sensor or any other automation can type on the connected computer or control its volume and playback.

You must have TinyUSB in your device’s configuration to use this component. It cannot be combined with USB CDC-ACM, because the keyboard supplies the only USB configuration descriptor.

The following ESP32 microcontroller variants are currently supported:

ESP32-H4
ESP32-P4
ESP32-S2
ESP32-S3
ESP32-S31

# Example configuration entry
tinyusb:

tinyusb_keyboard:
  id: kb

binary_sensor:
  - platform: gpio
    pin: GPIOXX
    name: "Shift + H"
    on_press:
      - tinyusb_keyboard.press:
          id: kb
          key: h
          modifiers: 0x02  # Left Shift
    on_release:
      - tinyusb_keyboard.release: kb

Configuration Variables

id (Optional, ID): Manually specify the ID for this component.

Actions

`tinyusb_keyboard.press` Action

Presses one key, releasing any key pressed before. The key stays pressed until tinyusb_keyboard.release is called. Only the latest state is kept, so put a short delay of at least 20ms between consecutive key actions in one automation, otherwise a press can replace a release that the host has not received yet.

- tinyusb_keyboard.press:
    id: kb
    key: a

id (Required, ID): The ID of the keyboard.
key (Required, templatable, string or int): The key to press, as a single lowercase letter or digit, or as a HID keyboard usage id (for example 0x28 for Enter). Quote digits, since an unquoted number is taken as a usage id.
modifiers (Optional, templatable, int): Bitmask of modifier keys held with the key: 0x01 Left Ctrl, 0x02 Left Shift, 0x04 Left Alt, 0x08 Left GUI, and the same four bits shifted left by four for the right-hand keys. Defaults to 0.

`tinyusb_keyboard.release` Action

Releases all keys.

- tinyusb_keyboard.release: kb

id (Required, ID): The ID of the keyboard.

`tinyusb_keyboard.media_press` Action

Presses one media key, releasing any media key pressed before.

- tinyusb_keyboard.media_press:
    id: kb
    usage: 0xE9  # Volume Up

id (Required, ID): The ID of the keyboard.
usage (Required, templatable, int): The HID consumer control usage id, for example 0xE9 Volume Up, 0xEA Volume Down, 0xE2 Mute, 0xCD Play/Pause, 0xB5 Next Track, 0xB6 Previous Track.

`tinyusb_keyboard.media_release` Action

Releases all media keys.

- tinyusb_keyboard.media_release: kb

id (Required, ID): The ID of the keyboard.

See Also