openhab-addons/bundles/org.openhab.binding.flicbutton/README.md
Patrick Fink 6c104e241a
[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>
2022-02-20 21:53:30 +01:00

6.9 KiB

Flic Button Binding

openHAB binding for using Flic Buttons with a 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, 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) 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.

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).

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 system.rawbutton Depends on the Trigger Profile 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 system.button Depends on the Trigger Profile 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 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. Please consider that you need a separate Bluetooth adapter. Shared usage with other Bluetooth services (e.g. Bluez) is not possible.
  2. Connect your buttons to flicd using the simpleclient as described in fliclib-linux-hci. Flicd has to run in background the whole time, simpleclient can be killed after you successfully test the button connects.
  3. 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.
  4. 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 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. 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