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.
-
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.
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.
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.
When enabled, the integration emulates key_hold events in software for devices that do not send them natively. Disabled by default.
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.
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.
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, orkey_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
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:
- Restart Home Assistant to trigger the automatic import.
- Go to Settings > Devices & services and confirm that your Keyboard Remote entries have been created.
- 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 thekeyboard_remote:block. - 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
Path to the local event input device file that corresponds to the keyboard. Mutually exclusive with device_name.
Name of the keyboard device. Mutually exclusive with device_descriptor.
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 events when a key is held down. Some input devices do not send these natively.
Number of seconds to wait before firing the first emulated key hold event.
Troubleshooting
Device not listed during setup
If the device dropdown during setup is empty or does not include your device, try the following:
- Make sure the device is physically connected to your system. For Bluetooth devices, make sure they are paired and active.
- 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.
- 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
- Go to Settings > Devices & services and select the integration card.
- 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
- Depending on the integration, the entries are listed under one of the following headings:
- To confirm, select Delete.
- Home Assistant also deletes the devices and entities of the entry.
- If Home Assistant asks you to restart, restart Home Assistant.
- If Home Assistant asks whether to also delete the application credentials, select Remove or Keep.
- If you keep them, Home Assistant uses them automatically when you add the integration again.
- To delete them later, refer to Deleting application credentials.