The EnOcean binding connects openHAB to the EnOcean ecosystem.
The binding uses an EnOcean gateway to retrieve sensor data and control actuators.
For _bidirectional_ actuators it is even possible to update the openHAB item state if the actuator gets modified outside of openHAB.
This binding has been developed on an USB300 gateway and was also tested with an EnOceanPi.
As this binding implements a full EnOcean stack, we have full control over these gateways.
This binding can enable the repeater function (level 1 or 2) of these gateways and retrieve detailed information about them.
## Concepts/Configuration
First of all you have to configure an EnOcean transceiver (gateway).
A directly connected USB300 can be auto discovered, an EnOceanPi has to be added manually to openHAB.
Both gateways are represented by an _EnOcean gateway_ in openHAB.
If you want to place the gateway for better reception apart from your openHAB server, you can forward its serial messages over TCP/IP (_ser2net_).
In this case you have to define the path to the gateway like this rfc2217://x.x.x.x:3001.
If everything is running fine you should see the _base id_ of your gateway in the properties of your bridge.
Another way to improve sending and reception reliability is to setup a wired connection.
In this case you directly connect to your RS485 EnOcean bus (use USB connection of an Eltako FAM14 e.g.).
However communication on RS485 bus is mostly done with an older ESP2 protocol which does not support advanced telegrams like VLD.
Furthermore you have to be aware that not all radio telegrams are published on the bus.
The vast majority of EnOcean messages are sent as broadcast messages without an explicit receiver address.
However each EnOcean device is identified by an unique id, called EnOceanId, which is used as the sender address in these messages.
To receive messages from an EnOcean device you have to determine its EnOceanId and add an appropriate thing to openHAB.
If the device is an actuator which you want to control with your gateway from openHAB, you also have to create an unique sender id and announce it to the actuator (_teach-in_).
For security reasons you cannot choose a random id, instead each gateway has 127 unique ids build in, from which you can choose.
A SenderId of your gateway is made up its base id and a number between 1 and 127.
This number can be chosen manually or the next free/unused number can be determined by the binding.
## Supported Things
This binding is developed on and tested with the following devices
* USB300 and EnOceanPi gateways
* The following Eltako actuators:
* FSR14 (light switch)
* FSB14 (rollershutter)
* FUD14 (dimmer)
* FSSA-230V (smart plug)
* FWZ12-65A (energy meter)
* FTKE (window / door contact)
* FPE-1 & FPE-2 (window / door contact)
* TF-FGB (window handle)
* TF-FKB (window contact)
* TF-AHDSB (outdoor brightness sensor)
* FAFT60 (outdoor temperature & humidity sensor)
* The following Opus actuators:
* GN-A-R12V-SR-4 (light)
* GN-A-R12V-MF-2 (light)
* GN-A-R12V-LZ/UD (dimmer)
* GN-A-R12V-JRG-2 (rollershutter)
* GN-A-U230V-JRG (rollershutter)
* OPUS-FUNK PLUS Jalousieaktor 1fach UP (rollershutter)
* OPUS-Funk PLUS Steckdosenleiste (smart multiple socket)
* NodOn:
* Smart Plug (ASP-2-1-10)
* In Wall Switch (SIN-2-2-00, SIN-2-1-0x)
* Temperature & humidity sensor (STPH-2-1-05)
* Permundo
* PSC234 (smart plug with metering) = Afriso APR234
* PSC132 (smart switch actor with metering)
* PSC152 (smart blinds control)
* Thermokon SR04 room control
* Hoppe SecuSignal window handles
* Rocker switches (NodOn, Eltako FT55 etc)
However, because of the standardized EnOcean protocol it is more important which EEP this binding supports.
Hence if your device supports one of the following EEPs the chances are good that your device is also supported by this binding.
|Thing type | EEP family | EEP Types | Channels¹ | Devices² | Pairing |
¹ Not all channels are supported by all devices, it depends which specific EEP type is used by the device, all thing types additionally support `rssi`, `repeatCount` and `lastReceived` channels
² These are just examples of supported devices
Furthermore following supporting EEP family is available too: A5-11, types 0x03 (rollershutter position status), 0x04 (extended light status) and D0-06 (battery level indication).
A `rockerSwitch` is used to receive messages from a physical EnOcean Rocker Switch.
A `classicDevice` is used for older EnOcean devices which react only on rocker switch messages (like Opus GN-A-R12V-SR-4).
As these devices do not send their current status, you have to add additional listener channels for each physical Rocker Switch to your thing.
In this way you can still sync your item status with the physical status of your device whenever it gets modified by a physical rocker switch.
The classic device simulates a physical Rocker Switch.
Per default the classic device uses the channel A of the simulated rocker switch.
If you want to use channel B you have to use virtualRockerswitchB in conjunction with rules to send commands.
## Pairing
Most of the EnOcean devices can be automatically created and configured as an openHAB thing through the discovery service.
The EnOcean protocol defines a so called "teach-in" process to announce the abilities and services of an EnOcean device and pair devices.
To pair an EnOcean device with its openHAB thing representation, you have to differentiate between sensors and actuators.
| rollershutter | Rollershutter | Shut time (shutTime) in seconds can be configured |
| angle | Number:Angle | The angle for blinds |
| instantpower | Number:Power | Instant power consumption in Watts |
| totalusage | Number:Energy | Used energy in Kilowatt hours |
| teachInCMD | Switch | Sends a teach-in msg, content can configured with parameter teachInMSG |
| virtualSwitchA | Switch | Used to convert switch item commands into rocker switch messages (channel A used)<br/>Time in ms between sending a pressed and release message can be defined with channel parameter duration.<br/>The switch mode (rocker switch: use DIR1 and DIR2, toggle: use just one DIR) can be set with channel parameter switchMode (rockerSwitch, toggleButtonDir1, toggleButtonDir2) |
| virtualRollershutterA | Rollershutter | Used to convert rollershutter item commands into rocker switch messages (channel A used) |
| rockerswitchListenerSwitch | Switch | Used to convert rocker switch messages into switch item state updates |
| rockerswitchListenerRollershutter | Rollershutter | Used to convert rocker switch messages into rollershutter item state updates |
| virtualRockerswitchB | String | Used to send plain rocker switch messages (channel B used) |
| batteryVoltage | Number:ElectricPotential | Battery voltage for things with battery |
| energyStorage | Number:ElectricPotential | Energy storage, don't know what this means... |
| batterLevel | Number | Battery level in percent |
| batterLow | Switch | Battery low indicator |
| smokeDetection | Switch | Smoke detected |
| sensorFault | Switch | Smoke sensor fault |
| timeSinceLastMaintenance | Number:Time | Time since last maintenance |
| remainingPLT | Number:Time | Remaining product life time |
| hygroComfortIndex | String | Hygrothermal Comfort Index |
| indoorAirAnalysis | String | Indoor Air Analysis |
| rollershutter | shutTime | Time (in seconds) to completely close the rollershutter | |
| dimmer | rampingTime | Duration of dimming | A5-38-08: Ramping Time (in seconds), 0 = default ramping, 1..255 = seconds to 100%; D2-01-01: 0 = switch, 1-3 = timer 1-3, 4 = stop |
| | eltakoDimmer | Flag for Eltako dimmers, because Eltako does interpret this EEP differently | True for Eltako dimmer, false otherwise. Defaults to true for compatibility purpose. |
| | storeValue | Store final value. For Eltako devices, block dimming value. | True or false. Defaults to false. |
| teachInCMD | manufacturerId | Id is used for 4BS teach in with EEP | HEX |
| | teachInMSG | Use this message if teach in type and/or manufacturer id are unknown | HEX |
| totalusage | validateValue | Filter out increases more than 10.0 kWh and decreases less than 1.0 kWh | true / false |
If an EnOcean device uses an unsupported EEP or _A5-3F-7F_, you have to create a `genericThing`.
Generic things support all channels like switch, number, string etc as generic channels.
However you have to specify how to convert the EnOcean messages of the device into openHAB state updates and how to convert the openHAB commands into EnOcean messages.
These conversion functions can be defined with the help of transformation functions like MAP.
|Thing type | Parameter | Meaning | Possible Values |
