mirror of
https://github.com/openhab/openhab-addons.git
synced 2025-01-10 23:22:02 +01:00
90 lines
2.8 KiB
Markdown
90 lines
2.8 KiB
Markdown
# Linux Input Binding
|
|
|
|
This binding allows to you use a keyboard to control your openHAB instance.
|
|
It works by exposing all keys on the keyboard as channels.
|
|
|
|
As indicated by the name of the binding this only works on Linux.
|
|
(It uses the libevdev library the receive events from the kernel)
|
|
As all the low-level protocols are handled by the Linux kernel it works for any
|
|
kind of keyboard; USB, Bluetooth, etc.
|
|
|
|
## Supported Things
|
|
|
|
All keyboards supported by the Linux kernel.
|
|
|
|
## Discovery
|
|
|
|
The discovery feature finds all cold- or hotplugged keyboards by watching the
|
|
`/dev/input/` directory.
|
|
The discovery uses the numeric ids for the devices. (`/dev/input/event0`,
|
|
etc...).
|
|
This can lead to issues when the kernel autodiscovery enumerates devices in a
|
|
nondeterministic order. This problem can be circumvented by using predictable
|
|
device names in `/dev/input/by-id/` or `/dev/input/by-path/` or by using Udev
|
|
facilities (out of scope for this document).
|
|
|
|
## Binding Configuration
|
|
|
|
openHAB will need rights on the `/dev/input/` files it is supposed to access.
|
|
This can be implemented by group-memberships, (custom) initscripts or Udev
|
|
rules.
|
|
The exact configurations possible depend on your system (out of scope for this document).
|
|
|
|
The `libevdev` library has to be installed for this plugin to work.
|
|
(It should be available via your package manager)
|
|
|
|
## Thing Configuration
|
|
|
|
Each thing has has to be explicitly enabled after it is configured.
|
|
While it is enabled _all_ of the generated events will be consumed by openHAB.
|
|
The device will not be available for normal input processing!
|
|
|
|
### Static configuration
|
|
|
|
#### Thing
|
|
|
|
```java
|
|
Thing linuxinput:input-device:some-keyboard [ enable=true, path="/dev/input/eventXX" ]
|
|
```
|
|
|
|
#### Item
|
|
|
|
```java
|
|
Contact SomeButton "Some Button" { channel="linuxinput:input-device:event17:keypresses#KEY_0" }
|
|
```
|
|
|
|
## Channels
|
|
|
|
Each Thing provides multiple channels
|
|
|
|
- A `key` channel that aggregates all events.
|
|
- Per physical key channels.
|
|
|
|
### Events
|
|
|
|
The following happens when pressing and releasing a key:
|
|
|
|
#### Press
|
|
|
|
1. State of global key channel updated to new key.
|
|
1. State of per-key channel updated to `"CLOSED"`.
|
|
1. Global key channel triggered with the current key name.
|
|
1. Per-key channel triggered with `"PRESSED"`".
|
|
1. State of global key channel updated to `""` (Empty string)
|
|
|
|
#### Release
|
|
|
|
1. State of per-key channel updated to `"OPEN"`
|
|
1. Per-key channel triggered with `"RELEASED"`
|
|
|
|
#### Rationale
|
|
|
|
Channel states are updated first to allow rules triggered by channel triggers to access the new state.
|
|
|
|
#### Channel names
|
|
|
|
The binding tries to translate the numeric event codes to their symbolic names; `KEY_1`, `KEY_A`, `KEY_BACKSPACE` etc.
|
|
|
|
If the currently installed version of libevdev does not know the symbolic name of a key, the numeric value is used.
|
|
Please note that future versions of libevdev may start translating the symbolic names.
|