Update keyboard_remote.markdown (home-assistant#1878)

MrMep · emlove · commit ab01a36a245c · 2017-01-25T13:59:05.000-05:00
Documentation updated regarding PR home-assistant#5535
diff --git a/source/_components/keyboard_remote.markdown b/source/_components/keyboard_remote.markdown
@@ -23,14 +23,35 @@ The `evdev` package is used to interface with the keyboard and thus this is Linu
 ```yaml
 # Example configuration.yaml entry
 keyboard_remote:
-  device_descriptor: '/dev/input/event12'
   type: 'key_up'
 ```
 
 Configuration variables:
 
-- **device_descriptor** (*Required*): Path to the local event input device file that corresponds to the keyboard.
 - **type** (*Required*): Possible values are `key_up`, `key_down`, and `key_hold`. Be careful, `key_hold` will fire a lot of events.
+- **device_descriptor** (*Optional*): Path to the local event input device file that corresponds to the keyboard.
+- **device_name** (*Optional*): Name of the keyboard device.
+
+Either `device_name` or `device_descriptor` must be present in the configuration entry. Indicating a device name is useful in case of repeating disconnections and re-connections of the device (for example, a bluetooth keyboard): the local input device file might change, thus breaking the configuration, while the name remains the same.
+In case of presence of multiple devices of the same model, `device_descriptor` must be used.
+
+A list of possible device descriptors and names is reported in the debug log at startup when the device indicated in the configuration entry could not be found.
+
+A full configuration for Keyboard Remote could look like the one below:
+
+```yaml
+keyboard_remote:
+  device_descriptor: '/dev/input/by-id/bluetooth-keyboard'
+  type: 'key_up'
+```
+
+or like the following:
+
+```yaml
+keyboard_remote:
+  device_name: 'Bluetooth Keyboard'
+  type: 'key_down'
+```
 
 And an automation rule to breathe life into it:
 
@@ -51,7 +72,7 @@ automation:
 This component manages disconnections and re-connections of the keyboard, for example in the case of a bluetooth device that turns off automatically to preserve battery.
 
 If the keyboard disconnects, the component will fire an event `keyboard_remote_disconnected`.
-When the keyboard reconnects an event `keyboard_remote_connected` will be fired.
+When the keyboard reconnects, an event `keyboard_remote_connected` will be fired.
 
 Here's an automation example that plays a sound through a media player whenever the keyboard connects/disconnects:
 ```yaml
@@ -83,14 +104,14 @@ There might be permissions problems with the event input device file. If this is
 ```
 sudo setfacl -m u:HASS_USER:rw /dev/input/event*
 ```
-where `HASS_USER` is the user hass runs as and `event*` is the event input device file your keyboard is connected to.
+where `HASS_USER` is the user hass runs as.
 
-If you want to make this permanent, you can use a udev rule that sets it for your event input device. Add a file `/etc/udev/rules.d/99-userdev-input.rules` containing:
+If you want to make this permanent, you can use a udev rule that sets it for all event input devices. Add a file `/etc/udev/rules.d/99-userdev-input.rules` containing:
 ```
 KERNEL=="event*", SUBSYSTEM=="input", RUN+="/usr/bin/setfacl -m u:HASS_USER:rw $env{DEVNAME}"
 ```
 
-You can check the ACLs permission with
+You can check ACLs permissions with
 ```
 getfacl /dev/input/event*
 ```
