# EnOcean Binding

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.

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)
• 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), Permundo PSC234 (smart plug with metering)
• 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.

¹ Not all channels are supported by all devices, it depends which specific EEP type is used by the device, all thing types additionally support receivingState channel

² These are just examples of supported devices

Furthermore following supporting EEP family is available too: A5-11, types 0x03 (rollershutter position status) and 0x04 (extended light status).

A rockerSwitch is used to receive messages from a physical EnOcean Rocker Switch. A classicDevice is used to 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.

# Sensors

To pair a sensor with its thing, you first have to start the discovery scan for this binding in PaperUI. Then press the "teach-in" button of the sensor. The sensor sends a teach-in message which contains the information about the EEP and the EnOceanId of the sensor. If the EEP is known by this binding the thing representation of the device is created. The corresponding channels are created dynamically, too.

# Actuators

If the actuator supports UTE teach-in, the corresponding thing can be created and paired automatically. First you have to start the discovery scan for a gateway in PaperUI. Then press the teach-in button of the actuator. If the EEP of the actuator is known, the binding sends an UTE teach-in response with a new SenderId and creates a new thing with its channels.

If the actuator does not support UTE teach-ins, you have to create, configure and choose the right EEP of the thing manually. It is important to link the teach-in channel of this thing to a switch item. Afterwards you have to activate the pairing mode of the actuator. Then switch on the teach-in item to send a teach-in message to the actuator. If the pairing was successful, you can control the actuator and unlink the teach-in channel now. The content of this teach-in message is device specific and can be configured through the teach-in channel.

To pair a classicDevice with an EnOcean device, you first have to activate the pairing mode of the actuator. Then switch the virtualRockerSwitchA On/Off.

Each EnOcean gateway supports 127 unique SenderIds. The SenderId of a thing can be set manually or determined automatically by the binding. In case of an UTE teach-in the next unused SenderId is taken automatically. To set this SenderId to a specific one, you have to use the nextSenderId parameter of your gateway.

# Thing Configuration

The pairing process of an openHAB thing and an EnOcean device has to be triggered within Paper UI. Therefore if you do not want to use Paper UI, a mixed mode configuration approach has to be done. To determine the EEP and EnOceanId of the device and announce a SenderId to it, you first have to pair an openHAB thing with the EnOcean device. Afterwards you can delete this thing and manage it with its necessary parameters through a configuration file. If you change the SenderId of your thing, you have to pair again the thing with your device.

¹ multiple values possible, EEPs have to be of different EEP families. If you want to receive messages of your EnOcean devices you have to set the enoceanId to the EnOceanId of your device.

# Channels

The channels of a thing are determined automatically based on the chosen EEP.

# Rules and Profiles

The rockerSwitch things use system:rawrocker channel types. So they trigger DIR1[/2]_PRESSED and DIR1[/2]__RELEASED events. These channels can be directly linked to simple items like Switch, Dimmer or Player with the help of profiles. If you want to do more advanced stuff, you have to implement rules which react to these events

rule "Advanced rocker rule"
when
    Channel 'enocean:rockerSwitch:gtwy:AABBCC00:rockerswitchA' triggered DIR1_PRESSED
then
    // do some advanced stuff
end

# Example

Bridge enocean:bridge:gtwy "EnOcean Gateway" [ path="/dev/ttyAMA0" ] {
   Thing rockerSwitch rs01 "Rocker" @ "Kitchen" [ enoceanID="aabbcc01", receivingEEPId="F6_02_01" ]
   Thing mechanicalHandle mh01 "Door handle" @ "Living room" [ enoceanID="aabbcc02", receivingEEPId="F6_10_00" ]
   Thing roomOperatingPanel p01 "Panel" @ "Floor" [ enoceanID="aabbcc03", receivingEEPId="A5_10_06" ]
   Thing centralCommand cc01 "Light" @ "Kitchen" [ enoceanID="aabbcc04", senderIdOffset=1, sendingEEPId="A5_38_08_01", receivingEEPId="F6_00_00", broadcastMessages=true, suppressRepeating=false ]
   Thing centralCommand cc02 "Dimmer" @ "Living room" [ enoceanID="aabbcc05", senderIdOffset=2, sendingEEPId="A5_38_08_02", receivingEEPId="A5_38_08_02", broadcastMessages=true, suppressRepeating=false ]
   Thing rollershutter r01 "Rollershutter" @ "Kitchen" [ enoceanID="aabbcc06", senderIdOffset=3, sendingEEPId="A5_3F_7F_EltakoFSB", receivingEEPId="A5_3F_7F_EltakoFSB", broadcastMessages=true, suppressRepeating=false ] {Channels: Type rollershutter:rollershutter [shutTime=25]}
   Thing measurementSwitch ms01 "TV Smart Plug" @ "Living room" [ enoceanID="aabbcc07", senderIdOffset=4, sendingEEPId="D2_01_09", broadcastMessages=false, receivingEEPId="D2_01_09","A5_12_01", suppressRepeating=false, pollingInterval=300]
   Thing classicDevice cd01 "Garage_Light" @ "Garage" [ 
        senderIdOffset=5, 
        sendingEEPId="F6_02_01", 
        broadcastMessages=true, 
        receivingEEPId="F6_02_01",
        suppressRepeating=false 
   ] {
        Type virtualSwitchA             : virtualSwitchA              [duration=300, switchMode="rockerSwitch"]
        Type rockerswitchListenerSwitch : Listener1 "Schalter links"  [enoceanId="aabbcc08", channel="channelA", switchMode="toggleButtonDir1"]
        Type rockerswitchListenerSwitch : Listener2 "Schalter rechts" [enoceanId="aabbcc09", channel="channelB", switchMode="toggleButtonDir2"]
   }
}

Player Kitchen_Sonos "Sonos" (Kitchen) {channel="sonos:PLAY1:ID:control", channel="enocean:rockerSwitch:gtwy:rs01:rockerswitchA" [profile="system:rawrocker-to-play-pause"]}
Dimmer Kitchen_Hue "Hue" <light> {channel="enocean:rockerSwitch:gtwy:rs01:rockerswitchB" [profile="system:rawrocker-to-dimmer"], channel="hue:0220:0017884f6626:9:brightness"}
Switch Garage_Light "Switch" {
        channel="enocean:classicDevice:gtwy:cd01:virtualRockerswitchA", 
        channel="enocean:classicDevice:gtwy:cd01:Listener1", 
        channel="enocean:classicDevice:gtwy:cd01:Listener2"
}

# Generic Things

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.

Supported channels: genericSwitch, genericRollershutter, genericDimmer, genericNumber, genericString, genericColor, genericTeachInCMD. You have to define the transformationType (e.g. MAP) and transformationFunction (e.g. for MAP: file name of mapping file) for each of these channels.

For an inbound transformation (EnOcean message => openHAB state) you receive the channel id and the EnOcean data in hex separated by a pipe. Your transformation function has to return the openHAB State type and value separated by a pipe. If you want to use a mapping transformation, your mapping file has to look like this for a genericThing using EEP F6_FF_FF:

ChannelId|EnoceanData(Hex)=openHABState|Value
genericSwitch|70=OnOffType|ON
genericSwitch|50=OnOffType|OFF
genericRollershutter|70=PercentType|0
genericRollershutter|50=PercentType|100

For an outbound transformation (openHAB command => EnOcean message) you receive the channel id and the command separated by a pipe. Your transformation function has to return the payload of the EnOcean message. You do not have to worry about CRC and header data. If you want to use a mapping transformation, your mapping file has to look like this for a genericThing using EEP A5_FF_FF:

ChannelId|openHABCommand=EnoceanData(Hex)
genericSwitch|ON=01000009
genericSwitch|OFF=01000008