openhab-addons/bundles/org.openhab.binding.bluetooth.enoceanble/README.md

# EnOcean BLE Binding

This binding adds support for the
[EnOcean BLE PTM215B](https://www.enocean.com/de/produkte/enocean_module_24ghz_ble/ptm-215b/) rocker.

**Currently, it does not work with the
[BlueZ Binding](https://www.openhab.org/addons/bindings/bluetooth.bluez)**.
The recommended / tested Bluetooth bridge binding is the
[BlueGiga Binding](https://www.openhab.org/addons/bindings/bluetooth.bluegiga).

## Supported Things

Only a single thing type is added by this extension:

| Thing Type ID   | Description               |
| --------------- | ------------------------- |
| ptm215b | The EnOcean PTM 215B Rocker |


These rockers are battery-less, the necessary energy for the BLE transmission is generated by the button click itself
and completely depleted after 3 attempts of a "fire & forget" (unidirectional) BLE transmission.
This means, the rockers are only "on" during the button click, so there is no possibility for openHAB to actively
retrieve the online status. Therefore, initial online status will always be "UNKNOWN" until the rocker is used.

## Discovery

As any other Bluetooth device, EnOcean BLE rockers are discovered automatically by the corresponding bridge. It's
necessary to click any button of the rocker up to 15 times in quick succession to get it discovered.

## Thing Configuration

There is only a single configuration parameter `address`, which corresponds to the Bluetooth address of the device
(in format "XX:XX:XX:XX:XX:XX"). Normally, the address is printed on the back of the rocker.

## Channels

An EnOcean PTM 215B Rocker has the following channels:

| Channel ID                | Item Type                | Description                    |
| ------------------------- | ------------------------ | ------------------------------ |
| rocker1                   | system.rawrocker         | In case of a dual rocker, the first rocker. In case of a single rocker, usually this channel has to be used. Anyhow, it depends from the implementation of the manufacturer of the rocker, so it could be that events are coming in on the second rocker channel. |
| rocker2                   | system.rawrocker         | In case of a dual rocker, the second rocker. |

## Example

demo.things:

```
Bridge bluetooth:bluegiga:bluegiga0 "Bluegiga Adapter" [ port="/dev/ttyBLUEGIGA", discovery=false ] {
    Thing ptm215b rocker_livingroom "Rocker Living Room" [ address = "E2:15:00:00:53:F9" ]
    Thing ptm215b rocker_kitchen "Rocker Kitchen" [ address = "E2:15:00:00:53:98" ]
}
```

demo.items:

```
Dimmer Light_LivingRoom  { channel="milight:rgbLed:milight2:4:ledbrightness", channel="bluetooth:ptm215b:bluegiga0:rocker_livingroom:rocker1" [profile="rawrocker-to-on-off"], channel="bluetooth:ptm215b:bluegiga0:rocker_kitchen:rocker1" [profile="rawrocker-to-on-off"] }  // 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="bluetooth:ptm215b:bluegiga0:rocker_kitchen:rocker2" [profile="rawrocker-to-on-off"] } 
```