innogy SmartHome Binding

The binding integrates the innogy SmartHome system into openHAB. It uses the official API as provided by innogy as cloud service. As all status updates and commands have to go through the API, a permanent internet connection is required. Currently there is no API for a direct communication with the innogy SmartHome Controller (SHC).

Supported things

Bridge

The innogy SmartHome Controller (SHC) is the bridge, that provides the central communication with the devices. Without the SHC, you cannot communicate with the devices.

Devices

The following table shows all supported and tested devices and their channels. The channels are described in detail in the next chapter.

DeviceDescriptionSupported channels
BRC8Basic Remote Controllerbutton1 ... button8, button1_count ... button8_count, battery_low
ISC2In Wall Smart Controllerbutton1, button2, button1_count, button2_count
ISD2In Wall Smart Dimmerbutton1, button2, button1_count, button2_count, dimmer
ISR2In Wall Smart Rollershutterbutton1, button2, button1_count, button2_count, rollershutter
ISS2In Wall Smart Switchbutton1, button2, button1_count, button2_count, switch
PSDPluggable Smart Dimmerdimmer
PSSPluggable Smart Switch, indoorswitch
PSSOPluggable Smart Switch, outdoorswitch
RSTRadiator Mounted Smart Thermostatset_temperature, temperature, frost_warning, humidity, mold_warning, operation_mode, window_reduction_active, battery_low
RST2Radiator Mounted Smart Thermostat (newer two battery version since 2018)set_temperature, temperature, frost_warning, humidity, mold_warning, operation_mode, window_reduction_active, battery_low
VariableActuatorswitch
WDSWindow Door Sensorcontact, battery_low
WMDWall Mounted Motion Detector, indoormotion_count, luminance, battery_low
WMDOWall Mounted Motion Detector, outdoormotion_count, luminance, battery_low
WRTWall Mounted Room Thermostatset_temperature, temperature, humidity, battery_low
WSC2Wall Mounted Smart Controllerbutton1, button2, button1_count, button2_count, battery_low
WSDWall Mounted Smoke Detector, old versionsmoke, alarm, battery_low
WSD2Wall Mounted Smoke Detector, new versionsmoke, alarm, battery_low

Powermeter devices

DeviceDescriptionSupported channels
AnalogMeterThe Analog Meter from the innogy EnergyControl productenergy_consumption_month_kwh, absolute_energy_consumption, energy_consumption_month_euro, energy_consumption_day_euro, energy_consumption_day_kwh
GenerationMeterThe Generation Meter from the innogy PowerControlSolar productenergy_generation_month_kwh, total_energy_generation, energy_generation_month_euro, energy_generation_day_euro, energy_generation_day_kwh, power_generation_watt
SmartMeterThe Smart Meter from the innogy PowerControl product.energy_consumption_month_kwh, absolute_energy_consumption, energy_consumption_month_euro, energy_consumption_day_euro, energy_consumption_day_kwh, power_consumption_watt
Two-Way-MeterThe Two-Way-Meter from the innogy PowerControlSolar productenergy_month_kwh, total_energy, energy_month_euro, energy_day_euro, energy_day_kwh, energy_feed_month_kwh, total_energy_fed, energy_feed_month_euro, energy_feed_day_euro, energy_feed_day_kwh, power_watt

Discovery

If the bridge (SHC) is located in the same LAN as the openHAB server, the bridge should be discovered automatically by mDNS. However, this can sometimes take a couple of minutes. If the bridge is not found, it can be added manually (see below under "Configuration").

After the bridge is added, devices are discovered automatically. As there is no background discovery implemented at the moment, you have to start the discovery manually. However, only devices will appear that are added in the innogy SmartHome app before, as the innogy Binding does not support the coupling of devices to the bridge.

Channels

Channel Type IDItem TypeDescriptionAvailable on thing
alarmSwitchSwitches the alarm (ON/OFF)WSD, WSD2
battery_lowSwitchIndicates, if the battery is low (ON/OFF)BRC8, RST, WDS, WMD, WMD0, WRT, WSC2, WSD, WSD2
contactContactIndicates the contact state (OPEN/CLOSED)WDS
dimmerDimmerAllows to dimm a light deviceISD2, PSD
frost_warningSwitchactive, if the measured temperature is too low (ON/OFF)RST
humidityNumberRelative humidity in percentRST, WRT
button1-trigger channel for rules, fires with each pushBRC8, ISC2, ISD2, ISR2, ISS2, WSC2
button2-trigger channel for rules, fires with each pushBRC8, ISC2, ISD2, ISR2, ISS2, WSC2
button3-trigger channel for rules, fires with each pushBRC8
button4-trigger channel for rules, fires with each pushBRC8
button5-trigger channel for rules, fires with each pushBRC8
button6-trigger channel for rules, fires with each pushBRC8
button7-trigger channel for rules, fires with each pushBRC8
button8-trigger channel for rules, fires with each pushBRC8
button1_countNumbernumber of button pushes for button 1, increased with each pushBRC8, ISC2, ISD2, ISR2, ISS2, WSC2
button2_countNumbernumber of button pushes for button 2, increased with each pushBRC8, ISC2, ISD2, ISR2, ISS2, WSC2
button3_countNumbernumber of button pushes for button 3, increased with each pushBRC8
button4_countNumbernumber of button pushes for button 4, increased with each pushBRC8
button5_countNumbernumber of button pushes for button 5, increased with each pushBRC8
button6_countNumbernumber of button pushes for button 6, increased with each pushBRC8
button7_countNumbernumber of button pushes for button 7, increased with each pushBRC8
button8_countNumbernumber of button pushes for button 8, increased with each pushBRC8
luminanceNumberIndicates the measured luminance in percentWMD, WMD0
mold_warningSwitchactive, if the measured humidity is too low (ON/OFF)RST
motion_countNumberNumber of detected motions, increases with each detected motionWMD, WMDO
operation_modeStringthe mode of a thermostat (auto/manual)RST
rollershutterRollershutterControls a roller shutterISR2
set_temperatureNumberSets the target temperature in °CRST, WRT
smokeSwitchIndicates, if smoke was detected (ON/OFF)WSD, WSD2
switchSwitchA switch to turn the device or variable on/off (ON/OFF)ISS2, PSS, PSSO, VariableActuator
temperatureNumberHolds the actual temperature in °CRST, WRT
window_reduction_activeSwitchindicates if a linked window is open and temperature reduced (ON/OFF)RST

Thing configuration

Configuring the SmartHome Controller (SHC)

The SmartHome Controller (SHC) can be configured in the Paper UI as follows:

After the "innogy SmartHome Controller" is added via the Inbox, edit the controller and add the "Authorization code" by following the hints in the description. Save your changes. The SHC should now login and go online. Be sure it is connected to the Internet.

Obtaining the authorization code and tokens

Authorization is done as oauth2 workflow with the innogy API.

To receive the auth-code, go to one of the following URLs depending on your brand and login with your credentials (you can find this link also in the SHC thing in Paper UI, if you edit it):

You will be redirected to openhab.org and the auth-code will be displayed. Copy and paste it into your SHC configuration and you are done.

The binding then requests the access and refresh tokens and saves them in the SHC configuration. The auth-code can only be used once and therefore is dropped. The access token is then used to login at the innogy API, but is valid only for a couple of hours. The binding automatically requests a new access token as needed by using the refresh token. So the refresh token is the relevant credential. Never give it to anybody!

Discovering devices

All devices bound to the bridge are found by the discovery service once the SHC is online. As device discovery is not implemented as a background service, you should start it manually in the Inbox to find all devices. Now you can add all devices from your Inbox as things.

Manual configuration

As an alternative to the automatic discovery process and graphical configuration using Paper UI, innogy things can be configured manually. The innogy SmartHome Controller (SHC) can be configured using the following syntax:

Bridge innogysmarthome:bridge:<bridge-id> [ refreshtoken="<refresh-token>" ]

The easiest way is to retrieve the refresh-token using the Paper UI as described above. But you can do it manually by:

  1. Changing the log level to TRACE, as the refresh-token is not written into the logs in lower log levels*
  2. Retrieving the auth-code (see description above)
  3. Saving it once in the Bridge configuration like shown below
  4. Fishing the refresh-code from the openhab.log file.
Bridge innogysmarthome:bridge:<bridge-id> [ authcode="<authcode>" ]

** Security warning!* As the refresh-token is THE one and only credential one needs to access the innogy webservice with all device data, you have to make sure it is never given to another person. Thus it is recommended to remove the line from the openhab.log and/or make sure, the logfile is definitely never accessible by others!

All other innogy devices can be added using the following syntax:

Thing WDS <thing-id> "<thing-name>" @ "<room-name>" [ id="<the-device-id>" ]

The device ID (e.g. e9a74941a3807b57332214f346fb1129) can be found in the Paper UI inbox, as you find it below all things there in the form innogysmarthome:<device-type>:<bridge-id>:<the-device-id> (example: innogysmarthome:WSC2:SMARTHOME01:e9a74941a3807b57332214f346fb1129).

However, a full example .things configuration look like this:

Bridge innogysmarthome:bridge:mybride "innogy SmartHome Controller" [ refreshtoken="<insert-your-refresh-token-here>" ] {
    Thing ISD2 myDimmer "Dimmer Kitchen" @ "Kitchen" [ id="<device-id>" ]
    Thing ISS2 myLightSwitch "Light Livingroom" @ "Livingroom" [ id="<device-id>" ]
    Thing PSS myTVSwitch "TV" @ "Livingroom" [ id="<device-id>" ]
    Thing RST myHeating "Thermostat Livingroom" @ "Livingroom" [ id="<device-id>" ]
    Thing VariableActuator myInnogyVariable "My Variable" [ id="<device-id>" ]
    Thing WDS myWindowContact "Window Kitchen" @ "Kitchen" [ id="<device-id>" ]
    Thing WMD myMotionSensor "Motion entry" @ "Entry" [ id="<device-id>" ]
    Thing WSC2 myPushButton "Pushbutton" @ "Living" [ id="<device-id>" ]
    Thing WSD mySmokeDetector "Smoke detector Livingroom" @ "Living" [ id="<device-id>" ]
}

You can then configure your items in your *.items config files as usual, for example:

Contact myWindowContact       "Kitchen"     <window>  {channel="innogysmarthome:WDS:mybridge:myWindowContact:contact"}
Switch myWindowContactBattery "Battery low" <battery> {channel="innogysmarthome:WDS:mybridge:myWindowContact:battery_low"}