Keyboard Remote

The Keyboard Remote integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] lets you use a USB or Bluetooth keyboard, remote control, or any Linux evdev-compatible input device to trigger automations in Home Assistant. Instead of creating entities, the integration fires events whenever a key is pressed, released, or held down. You can listen for these events in your automations to control lights, media players, or anything else in your smart home.

Each input device is added as a separate integration entry, so you can connect multiple keyboards or remotes and configure them independently.

Because the integration uses the Linux evdev interface, it works only on Linux-based Home Assistant installations. The integration captures the device exclusively. This means a keyboard you add here can no longer be used for regular typing.

Prerequisites

Before setting up the integration, make sure you meet the following requirements:

  • Your Home Assistant instance runs on a Linux-based system (Home Assistant OS, or Home Assistant Container on Linux).
  • The input device you want to use is connected to your system and recognized by Linux. For Bluetooth devices, pair them first using your operating system’s Bluetooth settings.
  • The Home Assistant process has read and write access to the device files under /dev/input/. On Home Assistant Operating System this is handled for you. For Home Assistant Container you have to pass the devices in yourself.

Configuration

To add the Keyboard Remote hub to your Home Assistant instance, use this My button:

Manual configuration steps

If the above My button doesn’t work, you can also perform the following steps manually:

  • Browse to your Home Assistant instance.

  • Go to Settings > Devices & services.

  • In the bottom right corner, select the Add Integration button.

  • From the list, select Keyboard Remote.

  • Follow the instructions on screen to complete the setup.

Input device

The input device to use. The dropdown lists the connected devices that can send key events and are not set up yet. A device with a /dev/input/by-id/ link is shown as Device Name (link-name) and is identified by that link. A device without one, such as a Bluetooth remote or a PS/2 keyboard, is shown as Device Name (address) and is identified by its address and name. If it reports no address, it is shown as Device Name (eventN) and is identified by name alone. If your device is not listed, see Device not listed during setup. Add a separate integration entry for each device you want to use.

Configuration options

After setup, you can adjust the following options for each device. To access them, go to Settings > Devices & services, find your Keyboard Remote entry, and select Configure.

Key event types

Which key events the integration listens for. You can select one or more of: key_up (key released), key_down (key pressed), and key_hold (key held down). By default, only key_up is enabled. Be aware that key_hold can generate a large number of events very quickly.

Emulate key hold

When enabled, the integration emulates key_hold events in software for devices that do not send them natively. Disabled by default.

Key hold delay

The number of seconds to wait before the first emulated key hold event is fired (0.01 to 5.0 seconds). Only applies when Emulate key hold is enabled. Default: 0.250 seconds.

Key hold repeat interval

The number of seconds to wait between subsequent emulated key hold events (0.001 to 1.0 seconds). Only applies when Emulate key hold is enabled. Default: 0.033 seconds.

Events

The integration does not create any entities. Instead, it fires events on the Home Assistant event bus that you can use as triggers in your automations.

Tip

To discover the key codes for your device, go to Settings > Tools > Events. In the Listen to events section, enter keyboard_remote_command_received and select Start listening. Then press a key on your device to see its key code and other event data.

Keyboard remote command received

The keyboard_remote_command_received event is fired whenever a key event occurs that matches your configured event types.

  • key_code — The numeric key code (evdev) for the key involved in the event
  • type — The event type: key_up, key_down, or key_hold
  • device_descriptor — The configured path of the device
  • device_name — The human-readable name of the device

For a device set up through the UI with a /dev/input/by-id/ link, device_descriptor is that link. For a device without one, it is the /dev/input/event* node the device is connected on, which can change when the device reconnects, so match on device_name instead. An entry imported from YAML reports the device_descriptor from your YAML configuration, or the node the device is connected on if it was configured by device_name. Copy the exact value from Settings > Tools > Events when matching on it in an automation.

Keyboard remote connected

The keyboard_remote_connected event is fired when a configured device is detected or reconnected. This is useful for Bluetooth devices that turn off automatically to save battery.

  • device_descriptor — The configured path of the device
  • device_name — The human-readable name of the device

Keyboard remote disconnected

The keyboard_remote_disconnected event is fired when a configured device is disconnected or removed.

  • device_descriptor — The configured path of the device
  • device_name — The human-readable name of the device

Automation examples

Automation: Turning on all lights with a key

The following example turns on all lights when a specific key is released on a specific device:

automation:
  - alias: "Keyboard all lights on"
    triggers:
      - trigger: event
        event_type: keyboard_remote_command_received
        event_data:
          # Target a specific device by its path, as shown in the event data
          device_descriptor: "/dev/input/by-id/usb-Example_Keyboard-event-kbd"
          # Find your key code in Settings > Tools > Events
          key_code: 107
          # Only trigger on key released events
          type: key_up
    actions:
      - action: light.turn_on
        target:
          entity_id: all

You can include device_descriptor or device_name in the event data to target a specific keyboard. This is especially useful when you have multiple Bluetooth remotes controlling different devices. Omit both to trigger the automation for any connected keyboard.

You can also include type to limit the trigger to a specific event type, such as key_down, key_up, or key_hold.

Automation: Responding to device connections and disconnections

The integration automatically handles reconnections without requiring a restart. The following example plays a sound through a media player whenever a keyboard connects or disconnects, which is useful for Bluetooth devices that power off to save battery:

automation:
  - alias: "Keyboard connected"
    triggers:
      - trigger: event
        event_type: keyboard_remote_connected
    actions:
      - action: media_player.play_media
        target:
          entity_id: media_player.speaker
        data:
          media_content_id: "keyboard_connected.wav"
          media_content_type: music

  - alias: "Bluetooth keyboard disconnected"
    triggers:
      - trigger: event
        event_type: keyboard_remote_disconnected
        event_data:
          device_name: "00:58:56:4C:C0:91"
    actions:
      - action: media_player.play_media
        target:
          entity_id: media_player.speaker
        data:
          media_content_id: "keyboard_disconnected.wav"
          media_content_type: music

Migrating from YAML configuration

Important

YAML configuration for the Keyboard Remote integration is deprecated and will be removed in Home Assistant 2027.4.0. When you upgrade, your existing YAML configuration is automatically imported as one integration entry per device. Please remove the keyboard_remote key from your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] after confirming the import was successful.

To complete the migration:

  1. Restart Home Assistant to trigger the automatic import.
  2. Go to Settings > Devices & services and confirm that your Keyboard Remote entries have been created.
  3. Open your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file and remove the keyboard_remote: block.
  4. Restart Home Assistant again.

Your automations do not need to change, because the events fired by the integration remain the same.

If a hold timing in your YAML configuration is outside the range the options accept, it is adjusted to fit, and an empty type list uses key_up. Home Assistant logs a warning when it does either.

The following reference shows the previous YAML configuration options:

Configuration Variables

device_descriptor string (Optional)

Path to the local event input device file that corresponds to the keyboard. Mutually exclusive with device_name.

device_name string (Optional)

Name of the keyboard device. Mutually exclusive with device_descriptor.

type string | list (Optional, default: key_up)

Key event types to listen for. Possible values are key_up, key_down, and key_hold. Can be a single value or a list.

emulate_key_hold boolean (Optional, default: false)

Emulate key hold events when a key is held down. Some input devices do not send these natively.

emulate_key_hold_delay float (Optional, default: 0.25)

Number of seconds to wait before firing the first emulated key hold event.

emulate_key_hold_repeat float (Optional, default: 0.033)

Number of seconds to wait between subsequent emulated key hold events.

Troubleshooting

Device not listed during setup

If the device dropdown during setup is empty or does not include your device, try the following:

  1. Make sure the device is physically connected to your system. For Bluetooth devices, make sure they are paired and active.
  2. Make sure the device can send key events. Devices that only report movement or switches, such as a mouse or a lid switch, are not listed.
  3. Restart the setup flow after connecting the device.

Devices on the system’s own bus, such as the power button, the lid switch, or GPIO buttons and IR receivers, are not listed either, because taking them over would stop them from working for the system. A YAML configuration for such a device is still imported.

Identical USB devices

USB devices without a serial number, such as two keyboards of the same model, share a single /dev/input/by-id/ link, which points at the one connected last. The other one is listed by its name instead. You can set up both, but which physical device each entry uses can swap when they reconnect. Bluetooth devices are told apart by their address, so this does not affect them.

Permission denied errors

If the integration fails to access the device, the Home Assistant process may not have read and write permissions on the input device file. You can grant permissions with:

sudo setfacl -m u:HASS_USER:rw /dev/input/event*

Replace HASS_USER with the user that runs Home Assistant.

To make this permanent, create a udev rule that applies permissions for all event input devices. Add a file /etc/udev/rules.d/99-userdev-input.rules with the following content:

KERNEL=="event*", SUBSYSTEM=="input", RUN+="/usr/bin/setfacl -m u:HASS_USER:rw $env{DEVNAME}"

You can verify the current permissions with:

getfacl /dev/input/event*

Running on Home Assistant Operating System

Home Assistant Operating System needs no additional configuration. The host /dev is already available to Home Assistant, including the /dev/input/by-id/ symlinks this integration uses, and devices that are connected or disconnected while Home Assistant is running are picked up without a restart.

Running in a container

If you are running Home Assistant Container, you need to pass input devices to the container. You can pass a specific device using the --device flag (you can repeat this flag to pass multiple devices). However, restarting the container or unplugging the keyboard will break the connection, as only the device instance that existed when the container started is available inside it.

The following incomplete docker-compose.yml example shows how to give Home Assistant persistent access to input devices in a container:

version: '3.7'

services:
  homeassistant:
    image: ghcr.io/homeassistant/home-assistant:stable
    volumes:
      - config:/config/
      - /dev/input:/dev/input/ # This is needed to read input events.
    restart: unless-stopped
    device_cgroup_rules:
      # Allow creation of /dev/input/* with mknod
      - 'c 13:* rmw'
    devices:
      # Since input IDs may change, pass them all in
      - "/dev/input/"
    ...

Removing the integration

This integration follows standard integration removal. Each device you configured appears as a separate integration entry, so remove each one individually if you want to stop using all keyboard remotes.

To remove an integration instance from Home Assistant

  1. Go to Settings > Devices & services and select the integration card.
  2. Next to the entry you want to remove, select the three dots menu. Then, select Delete.
    • Depending on the integration, the entries are listed under one of the following headings:
      • Devices
      • Hubs
      • Services
      • Integration entries
  3. To confirm, select Delete.
    • Home Assistant also deletes the devices and entities of the entry.
  4. If Home Assistant asks you to restart, restart Home Assistant.
  5. If Home Assistant asks whether to also delete the application credentials, select Remove or Keep.