[flicbutton] Initial contribution FlicButton Binding (#9234)
* [flicbutton] Initial contribution FlicButton Binding Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Add config parameter address for FlicButton thing Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Run spotless Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Code cleanup & docs improvement Signed-off-by: Patrick Fink <mail@pfink.de> * Apply suggestions from code review Co-authored-by: Fabian Wolter <github@fabian-wolter.de> * [flicbutton] Update LICENSE Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Apply suggestions from code review (2) & update to 3.1-SNAPSHOT Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Apply suggestions from code review (3) & fix offline status Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Fix 3rd party source for proper IDE integration Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Simplify config parsing Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Move everything to internal package Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Remove hyphens from port parameter docs example Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Change maintainer to openHAB project Signed-off-by: Patrick Fink <mail@pfink.de> * Apply docs suggestions + update to 3.2.0-SNAPSHOT Signed-off-by: Patrick Fink <mail@pfink.de> Co-authored-by: Matthew Skinner <matt@pcmus.com> * [flicbutton] Fix bridge offline & reconnect handling Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Close open socket on dispose Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Improve exception error message in ThingStatus Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Fix README title Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Improve exception error message in ThingStatus Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Style fixes Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Use trace log level for button clicks & status changes Signed-off-by: Patrick Fink <mail@pfink.de> * Apply doc improvements from code review Signed-off-by: Patrick Fink <mail@pfink.de> Co-authored-by: Matthew Skinner <matt@pcmus.com> * [flicbutton] Add binding to bom/openhab-addons Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Cleanup / remove guava leftover Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Remove online status description Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Improve flicd hostname label Signed-off-by: Patrick Fink <mail@pfink.de> Co-authored-by: Fabian Wolter <github@fabian-wolter.de> * [flicbutton] Do not catch IllegalArgumentException anymore as its not neeed Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Use debug log level instead of info Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Update version and license Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Fix SAT warnings, e.g. add null handling annotations Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Fix SAT warnings (2) Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Concurrency refactoring & fixes Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Cancel initialization task also when already running Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Add javadoc and move FLIC_OPENHAB_EVENT_TRIGGER_MAP constant to constants class Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Use ThingStatusDetail.OFFLINE.GONE when Flic button was removed from bridge Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Fix FlicSimpleclientDiscoveryServiceImpl javadoc Signed-off-by: Patrick Fink <mail@pfink.de> * [flicbutton] Fix required definition of thing types Signed-off-by: Patrick Fink <mail@pfink.de> Co-authored-by: Fabian Wolter <github@fabian-wolter.de> Co-authored-by: Matthew Skinner <matt@pcmus.com>
This commit is contained in:
Patrick Fink
GitHub
130
bundles/org.openhab.binding.flicbutton/README.md
Normal file
130
bundles/org.openhab.binding.flicbutton/README.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# Flic Button Binding
|
||||
|
||||
openHAB binding for using [Flic Buttons](https://flic.io/)
|
||||
with a [fliclib-linux-hci](https://github.com/50ButtonsEach/fliclib-linux-hci) bridge.
|
||||
|
||||
Currently, although Flic Buttons are BLE devices, this binding only supports fliclib-linux-hci (flicd) as a bridge.
|
||||
The openHAB Bluetooth Bindings are not supported.
|
||||
Flicd requires a seperate Bluetooth adapter to work, so if you use this binding together with e.g. the
|
||||
[Bluez Binding](https://www.openhab.org/addons/bindings/bluetooth.bluez/),
|
||||
two physical Bluetooth adapters are required (one for Bluez and one for flicd).
|
||||
Be aware that flicd requires an initial internet connection for the verification of the buttons.
|
||||
After buttons are initially added to flicd, an internet connection is not required anymore.
|
||||
|
||||
## Supported Things
|
||||
|
||||
| Thing Type ID | Description |
|
||||
| --------------- | ------------------------- |
|
||||
| flicd-bridge | The bridge representing a running instance of [fliclib-linux-hci (flicd)](https://github.com/50ButtonsEach/fliclib-linux-hci) on the server. |
|
||||
| button | The Flic button (supports Flic 1 buttons as well as Flic 2 buttons) |
|
||||
|
||||
## Discovery
|
||||
|
||||
* There is no automatic discovery for flicd-bridge available.
|
||||
* After flicd-bridge is (manually) configured, buttons will be automatically discovered via background discovery as soon
|
||||
as they're added with [simpleclient](https://github.com/50ButtonsEach/fliclib-linux-hci).
|
||||
|
||||
If they're already attached to the flicd-bridge before configuring this binding, they can be discovered by triggering an
|
||||
active scan.
|
||||
|
||||
## Thing Configuration
|
||||
|
||||
### flicd-bridge
|
||||
|
||||
Example for textual configuration:
|
||||
|
||||
```
|
||||
Bridge flicbutton:flicd-bridge:mybridge
|
||||
```
|
||||
|
||||
The default host is localhost:5551 (this should be sufficient if flicd is running with default settings on the same server as openHAB).
|
||||
If your flicd service is running somewhere else, specify it like this:
|
||||
|
||||
```
|
||||
Bridge flicbutton:flicd-bridge:mybridge [ hostname="<YOUR_HOSTNAME>", port=<YOUR_PORT>]
|
||||
```
|
||||
|
||||
If flicd is running on a remote host, please do not forget to start it with the parameter `-s <openHAB IP>`, otherwise it won't be accessible for openHAB (more details on [fliclib-linux-hci](https://github.com/50ButtonsEach/fliclib-linux-hci)).
|
||||
|
||||
### button
|
||||
|
||||
For the button, the only config parameter is the MAC address.
|
||||
Normally, no textual configuration is necessary as buttons are auto discovered as soon as the bridge is configured.
|
||||
If you want to use textual configuration anyway, you can do it like this:
|
||||
|
||||
```
|
||||
Bridge flicbutton:flicd-bridge:mybridge [ hostname="<YOUR_HOSTNAME>", port=<YOUR_PORT>] {
|
||||
Thing button myflic1 "<YOUR_LABEL>" [address ="<MAC_ADDRESS>"]
|
||||
Thing button myflic2 "<YOUR_LABEL>" [address ="<MAC_ADDRESS>"]
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
You can lookup the MAC addresses of your buttons within the inbox of the UI.
|
||||
You're free to choose any label you like for your button.
|
||||
|
||||
## Channels
|
||||
|
||||
| Channel ID | Channel Type | Item Type | Description |
|
||||
| ------------------------- | ------------------------ | --------------------------| ------------------------------ |
|
||||
| rawbutton | [System Trigger Channel](https://www.openhab.org/docs/developer/bindings/thing-xml.html#system-trigger-channel-types) `system.rawbutton` | Depends on the [Trigger Profile](https://www.openhab.org/docs/configuration/items.html#profiles) used | Raw Button channel that triggers `PRESSED` and `RELEASED` events, allows to use openHAB profiles or own implementations via rules to detect e.g. double clicks, long presses etc. |
|
||||
| button | [System Trigger Channel](https://www.openhab.org/docs/developer/bindings/thing-xml.html#system-trigger-channel-types) `system.button` | Depends on the [Trigger Profile](https://www.openhab.org/docs/configuration/items.html#profiles) used | Button channel that is using Flic's implementation for detecting long, short or double clicks. Triggers `SHORT_PRESSED`,`DOUBLE_PRESSED` and `LONG_PRESSED` events. |
|
||||
| battery-level | [System State Channel](https://www.openhab.org/docs/developer/bindings/thing-xml.html#system-state-channel-types) `system.battery-level` | Number | Represents the battery level as a percentage (0-100%).
|
||||
## Example
|
||||
|
||||
### Initial setup
|
||||
|
||||
1. Setup and run flicd as described in [fliclib-linux-hci](https://github.com/50ButtonsEach/fliclib-linux-hci).
|
||||
Please consider that you need a separate Bluetooth adapter. Shared usage with other Bluetooth services (e.g. Bluez)
|
||||
is not possible.
|
||||
1. Connect your buttons to flicd using the simpleclient as described in
|
||||
[fliclib-linux-hci](https://github.com/50ButtonsEach/fliclib-linux-hci). Flicd has to run in background the whole
|
||||
time, simpleclient can be killed after you successfully test the button connects.
|
||||
1. Add a flicd-bridge via the UI or textual configuration. Please consider that flicd only accepts connections from
|
||||
localhost by default, to enable remote connections from openHAB you have to use the `--server-addr` parameter as
|
||||
described in [fliclib-linux-hci](https://github.com/50ButtonsEach/fliclib-linux-hci).
|
||||
1. When the bridge is online, buttons newly added via simpleclient will automatically get discovered via background
|
||||
discovery. To discover buttons that were set up before the binding was setup, please run an active scan.
|
||||
|
||||
### Configuration Example using Profiles
|
||||
|
||||
[Profiles](https://www.openhab.org/docs/configuration/items.html#profiles) are the recommended way to use this binding.
|
||||
|
||||
demo.things:
|
||||
|
||||
```
|
||||
Bridge flicbutton:flicd-bridge:local-flicd {
|
||||
Thing button flic_livingroom "Yellow Button Living Room" [address = "60:13:B3:02:18:BD"]
|
||||
Thing button flic_kitchen "Black Button Kitchen" [address = "B5:7E:59:78:86:9F"]
|
||||
}
|
||||
```
|
||||
|
||||
demo.items:
|
||||
|
||||
```
|
||||
Dimmer Light_LivingRoom { channel="milight:rgbLed:milight2:4:ledbrightness", channel="flicbutton:button:local-flicd:flic_livingroom:rawbutton" [profile="rawbutton-toggle-switch"], channel="flicbutton:button:local-flicd:flic_kitchen:rawbutton" [profile="rawbutton-toggle-switch"] } // We have a combined kitchen / livingroom, so we control the living room lights with switches from the living room and from the kitchen
|
||||
Switch Light_Kitchen { channel="hue:group:1:kitchen-bulbs:switch", channel="flicbutton:button:local-flicd:flic_kitchen:rawbutton" [profile="rawbutton-toggle-switch"] }
|
||||
```
|
||||
|
||||
### Configuration Example using Rules
|
||||
|
||||
It's also possible to setup [Rules](https://www.openhab.org/docs/configuration/rules-dsl.html).
|
||||
The following rules help to initially test your setup as they'll trigger log messages on incoming events.
|
||||
|
||||
```
|
||||
rule "Button rule using the button channel"
|
||||
|
||||
when
|
||||
Channel "flicbutton:button:local-flicd:flic_livingroom:button" triggered SHORT_PRESSED
|
||||
then
|
||||
logInfo("Flic", "Flic 'short pressed' triggered")
|
||||
end
|
||||
|
||||
rule "Button rule directly using the rawbutton channel"
|
||||
|
||||
when
|
||||
Channel "flicbutton:button:local-flicd:flic_livingroom:rawbutton" triggered
|
||||
then
|
||||
logInfo("Flic", "Flic pressed: " + receivedEvent.event)
|
||||
end
|
||||
```
|
||||
Reference in New Issue
Block a user