openhab-addons/bundles/org.openhab.binding.innogysmarthome/README.md
Sven Strohschein 25660991e6
[livisismarthome] New binding (successor of innogysmarthome with local API and some improvements) (#12440)
- Initial version added (copied and renamed from the innogysmarthome binding)
- The local API is now used, authorization, bridge initialization and discovery is already working
- Potential NullPointerExceptions fixed
- Adding battery-low-Channel support for ISC2
- More optimizations and local API changes in the ReadMe
- The key button counter channels are now updated correctly. The according trigger channels should now also work fine.
- Bug fixes regarding button pressed event. The pressed event is now executed along with short and long press events, so if someone want to react on a button press (short or long), the PRESSED trigger event can get checked. And the pressed event isn't senseless executed on a binding restart anymore.
- Error messages improved
- Deprecation-Notice
- New deprecation warning integrated in the innogysmarthome binding
- Livisi renamed to LIVISI
- SHC channels are now initialized correctly
- New "status" channel for the SHC with the values ACTIVE, INITIALIZING and SHUTTINGDOWN
- Code and documentation optimizations
- Fix for PT-PSS action
- Support for SHC classic - The websocket is hosted on another port.
- Update for Temperature-Channel-Definitions and Translations (de)
- Update for Power-Channel-Definitions
- Further translations (de) for devices and channels
- Refactoring branch integrated (some tests added and a lot of code optimizations for example smaller methods, better method names, more simple flows without continue and return in void methods, improved NULL handling, etc.)
- Code optimization (special handling for VariableActuator removed which seems to be not required anymore)
- The thing status is now set to offline when the device is not reachable (even on binding start up)
- The thing status is now set to online again when the device is reachable again
- Clearer description of the invert switch of the RollerShutter (ISR2)
- Copyright notices corrected
- Imports optimized
- Changed handling of pointTemperature (QuantityType instead of DecimalType)
- Code optimization (device status listeners are now registered with device id, so it isn't necessary anymore to call all listeners to find the right matching listener for the device event).
- Code optimization (not working mDNS bridge discovery removed).
- Explicit idle timeout removed (seems not to be required anymore for the local API and may cause problems with SHC 1, there occur EOFExceptions)
- Code optimizations (Debug code removed which isn't required anymore)
- Warn message added which is logged when the temperature to set is not between min and max temperature (this can happen when the user uses the REST-API instead of MainUI or probably also when set via a rule).
- Code optimizations (stronger/consequent use of QuantityType instead of DecimalType)
- Temperature values outside the possible range of 6 - 30 °C are now set to 6 / 30 °C. Therefore a temperature channel can get set to 0 °C for example by a rule and this is automatically changed to 6 °C (and causes a debug message).
- Code optimizations
- Bug fixes regarding UnitsOfMeasurements (Number:Power)
- Tests repaired
- The local API returns "[]" for empty objects which should only get used for arrays... This is now handled by the binding with replacing "[]" by "null". This error occurred with SHC 1, it isn't known if SHC 2 is also affected.
- Number:Dimensionless (percent) introduced for humidity and luminance
- Button events are now supported for SHC 1 (Classic), but without information about short or long press (isn't available for this SHC model).
- Button events are now supported for SHC 1 (Classic), but without information about short or long press (isn't available for this SHC model).
- The configVersion is now also available for SHC 1 bridges.
- More changes to Descriptions, Translations, Icons, Channel-Order, Channel-Config
- Trace logging of responses added to increase the traceability
- The SHC channels should now also get filled for SHC classic
- cpu, memory and disc channels are now defined as percentage (Number:Dimensionless)
- Jetty-HttpClient replaced by simple UrlConnection, because Jetty-HttpClient has problems with high frequency execution of requests. There were EOFExceptions with SHC classic when 2 or more requests were executed within the same second...
- Readme updated
- Copyright notices corrected
- Additions in ReadMe for RST2 / WRT
- The bridge channels (cpu, memory, disc and operation state) are now updated every minute for SHC 1 / classic (because there are no such events for SHC 1 / classic)
- Bug-fix for SHC 1 / classic: Device attributes are now updated correctly for SHC 1 / classic (there is another response structure, which caused that some attributes were not found / update). This should have affected battery low and reachable (thing status) information.
- There are also raw events which report changes regarding the bridge channels (cpu, memory, disc and operation status). There are now processed.
- Token request JSON changed to lower-case (to be compatible with the new SHC firmware update and this should enable to use the standard logics)
- SHC 2 can now get authenticated with the OAuth 2.0 standard logics of OpenHAB (with x-www-form-urlencoded instead of json). The old special json logic is still there to support SHC 1 (but SHC 1 will also get updated soon).
- SHC 1 supports now short and long button pressed events
- Outdated custom login logics removed. SHC 2 and SHC 1 / classic supports now OAuth 2.0 login requests, therefore the default login logics of OpenHAB can now get used.
- README updated for the required software version of SHC 1 / classic
- Code review findings fixed
- Code review findings fixed (Channel Ids renamed to lowerCamelCase)
- Unused code removed
- Code review findings fixed (Device status messages localized)
- Code review findings fixed (label of BooleanStateActuator renamed)
- Code review findings fixed (hard-coded units resolved)
- Code review findings fixed (unit of measurements changed form Power to Energy when it is unit Wh instead of W)
- Code review findings fixed (thing status BRIDGE_OFFLINE changed to COMMUNICATION_ERROR, because BRIDGE_OFFLINE is intended for sub/child devices, not for the bridge thing)
- Code review findings fixed ("initialize" is now returned faster and all requests are executed asynchronously)
- Code review findings fixed ("initialize" is now returned faster and all requests are executed asynchronously)
- Compiler warnings fixed
- Code review findings fixed
- Code review findings fixed (channel ids renamed)
- Code review findings fixed (tags for temperature and humidity added)
- Code review findings fixed (properties renamed to lowerCamelCase like the default properties)
- Code review findings fixed (non-null warnings fixed, performance increased by reducing requests)
- Code review findings fixed (non-null warnings fixed)
- Code review findings fixed (non-null warnings fixed in tests)
- Copyright notices updated
- Unnecessary log line removed
- Code review findings fixed (non-null warnings fixed in tests)
- Test fixed (WebSocketClient can't get mocked completely which caused an Exception)
- Code review findings fixed (various code optimizations)
- Code review findings fixed (channel-type-ids renamed to lowerCamelCase)
- Code review findings fixed (translation simplified)
- Code review findings fixed (temperature point handling converted in UoM)
- Code review findings fixed (Exception handling improved)
- Code review findings fixed (offline state precised when the bridge isn't found/configured)
- Code review findings fixed (exception logs deactivated within tests to reduce to console output when running the tests)
- Code review findings fixed (thing status is now checked instead of bridge status)
- Code review findings fixed (DeviceStructureManager can now be marked as NonNull because it is initialized within the initialize method)
- Code review findings fixed (LivisiClient can now be marked as NonNull because it is initialized within the initialize method)
- Code review findings fixed (OAuthService can now be marked as NonNull because it is initialized within the initialize method)
- Code review findings fixed (unnecessary type check removed)
- Code review findings fixed (warning messages within tests reduced)
- Code review findings fixed (more when the bridge connection state changes)
- Code review findings fixed (reconnect job changed from scheduleAtFixedRate to scheduleWithFixedDelay - recommended by the SAT warnings).
- Code review findings fixed (unused method removed).
- Representation property introduced to auto-ignore textual defined things at discovery/scan
- Code review findings fixed (more detailed error message for SHC not reachable added).
- Fix ChannelTypeID in Readme.md sample
- Code review findings fixed ("/event/ControllerConnectivityChanged" doesn't change the bridge thing to offline anymore, because it isn't important for the local API anymore).
- Code review findings fixed (point temperature commands with DecimalType instead of QuantityType can now also get handled).
- Tests added regarding handleCommand
- Code optimization (constant for the "invert" channel parameter added)
- Code optimization (log messages within tests avoided)

Signed-off-by: Sven Strohschein <sven.strohschein@gmail.com>
Co-authored-by: RalphSester <ralph.sester@sester-edv.de>
2022-06-14 23:21:39 +02:00

252 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# innogy SmartHome Binding
The binding integrates the [innogy SmartHome](https://innogy.com/smarthome) system into openHAB.
It uses the official API 1.1 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.
*Notice!*
*This binding is deprecated!*
*LIVISI (formally innogy) has implemented a local API on their SHC from Software Version 1.2.XX.XXX.
Please migrate to the "LIVISI SmartHome Binding" which is using the new local API and requires neither the LIVISI-cloud-servers nor an internet connection.*
## 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.
This binding supports both the SHC and the SHC2 (with support for Bluetooth devices).
### Devices
The following table shows all supported and tested devices and their channels.
The channels are described in detail in the next chapter.
| Device | Description | Supported channels |
|--------|--------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| BRC8 | Basic Remote Controller | button1 ... button8, button1_count ... button8_count, battery_low |
| ISC2 | In Wall Smart Controller | button1, button2, button1_count, button2_count |
| ISD2 | In Wall Smart Dimmer | button1, button2, button1_count, button2_count, dimmer |
| ISR2 | In Wall Smart Rollershutter | button1, button2, button1_count, button2_count, rollershutter |
| ISS2 | In Wall Smart Switch | button1, button2, button1_count, button2_count, switch |
| PSD | Pluggable Smart Dimmer | dimmer |
| PSS | Pluggable Smart Switch, indoor | switch |
| PSSO | Pluggable Smart Switch, outdoor | switch |
| BT-PSS | Bluetooth Pluggable Smart Switch, indoor | switch |
| RST | Radiator Mounted Smart Thermostat | set_temperature, temperature, frost_warning, humidity, mold_warning, operation_mode, window_reduction_active, battery_low |
| RST2 | Radiator Mounted Smart Thermostat (newer two battery version since 2018) | set_temperature, temperature, frost_warning, humidity, mold_warning, operation_mode, window_reduction_active, battery_low |
| | VariableActuator | switch |
| WDS | Window Door Sensor | contact, battery_low |
| WMD | Wall Mounted Motion Detector, indoor | motion_count, luminance, battery_low |
| WMDO | Wall Mounted Motion Detector, outdoor | motion_count, luminance, battery_low |
| WRT | Wall Mounted Room Thermostat | set_temperature, temperature, humidity, battery_low |
| WSC2 | Wall Mounted Smart Controller | button1, button2, button1_count, button2_count, battery_low |
| WSD | Wall Mounted Smoke Detector, old version | smoke, alarm, battery_low |
| WSD2 | Wall Mounted Smoke Detector, new version | smoke, alarm, battery_low |
Powermeter devices
| Device | Description | Supported channels |
|-----------------|----------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| AnalogMeter | The Analog Meter from the innogy EnergyControl product | energy_consumption_month_kwh, absolute_energy_consumption, energy_consumption_month_euro, energy_consumption_day_euro, energy_consumption_day_kwh |
| GenerationMeter | The Generation Meter from the innogy PowerControlSolar product | energy_generation_month_kwh, total_energy_generation, energy_generation_month_euro, energy_generation_day_euro, energy_generation_day_kwh, power_generation_watt |
| SmartMeter | The 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-Meter | The Two-Way-Meter from the innogy PowerControlSolar product | energy_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 ID | Item Type | Description | Available on thing |
|-------------------------|---------------|-----------------------------------------------------------------------|-------------------------------------------------|
| alarm | Switch | Switches the alarm (ON/OFF) | WSD, WSD2 |
| battery_low | Switch | Indicates, if the battery is low (ON/OFF) | BRC8, RST, WDS, WMD, WMD0, WRT, WSC2, WSD, WSD2 |
| contact | Contact | Indicates the contact state (OPEN/CLOSED) | WDS |
| dimmer | Dimmer | Allows to dimm a light device | ISD2, PSD |
| frost_warning | Switch | active, if the measured temperature is too low (ON/OFF) | RST |
| humidity | Number | Relative humidity in percent | RST, WRT |
| button1 | - | trigger channel for rules, fires with each push | BRC8, ISC2, ISD2, ISR2, ISS2, WSC2 |
| button2 | - | trigger channel for rules, fires with each push | BRC8, ISC2, ISD2, ISR2, ISS2, WSC2 |
| button3 | - | trigger channel for rules, fires with each push | BRC8 |
| button4 | - | trigger channel for rules, fires with each push | BRC8 |
| button5 | - | trigger channel for rules, fires with each push | BRC8 |
| button6 | - | trigger channel for rules, fires with each push | BRC8 |
| button7 | - | trigger channel for rules, fires with each push | BRC8 |
| button8 | - | trigger channel for rules, fires with each push | BRC8 |
| button1_count | Number | number of button pushes for button 1, increased with each push | BRC8, ISC2, ISD2, ISR2, ISS2, WSC2 |
| button2_count | Number | number of button pushes for button 2, increased with each push | BRC8, ISC2, ISD2, ISR2, ISS2, WSC2 |
| button3_count | Number | number of button pushes for button 3, increased with each push | BRC8 |
| button4_count | Number | number of button pushes for button 4, increased with each push | BRC8 |
| button5_count | Number | number of button pushes for button 5, increased with each push | BRC8 |
| button6_count | Number | number of button pushes for button 6, increased with each push | BRC8 |
| button7_count | Number | number of button pushes for button 7, increased with each push | BRC8 |
| button8_count | Number | number of button pushes for button 8, increased with each push | BRC8 |
| luminance | Number | Indicates the measured luminance in percent | WMD, WMD0 |
| mold_warning | Switch | active, if the measured humidity is too low (ON/OFF) | RST |
| motion_count | Number | Number of detected motions, increases with each detected motion | WMD, WMDO |
| operation_mode | String | the mode of a thermostat (auto/manual) | RST |
| rollershutter* | Rollershutter | Controls a roller shutter | ISR2 |
| set_temperature | Number | Sets the target temperature in °C | RST, WRT |
| smoke | Switch | Indicates, if smoke was detected (ON/OFF) | WSD, WSD2 |
| switch | Switch | A switch to turn the device or variable on/off (ON/OFF) | ISS2, PSS, PSSO, VariableActuator |
| temperature | Number | Holds the actual temperature in °C | RST, WRT |
| window_reduction_active | Switch | indicates if a linked window is open and temperature reduced (ON/OFF) | RST |
The `rollershutter` channel has a `boolean` parameter `invert`.
It is `false` by default.
This means `100` on innogy is `UP` and `0` is `DOWN`.
When `invert` is `true` than `0` on innogy is `UP` and `100` is `DOWN`.
## Thing configuration
### Configuring the SmartHome Controller (SHC)
The SmartHome Controller (SHC) can be configured in the 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 the UI, if you edit it):
https://auth.services-smarthome.de/AUTH
* [innogy SmartHome authorization page](https://auth.services-smarthome.de/AUTH/authorize?response_type=code&client_id=24635748&redirect_uri=https%3A%2F%2Fwww.openhab.org%2Foauth%2Finnogy%2Finnogy-smarthome.html&scope&lang=de-DE)
* [SmartHome Austria authorization page](https://auth.services-smarthome.de/AUTH/authorize?response_type=code&client_id=24635749&redirect_uri=https%3A%2F%2Fwww.openhab.org%2Foauth%2Finnogy%2Fsmarthome-austria.html&scope&lang=de-DE)
* [Start SmartHome authorization page](https://auth.services-smarthome.de/AUTH/authorize?response_type=code&client_id=24635750&redirect_uri=https%3A%2F%2Fwww.openhab.org%2Foauth%2Finnogy%2Fstart-smarthome.html&scope&lang=de-DE)
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.
### File based configuration
As an alternative to using automatic discovery, innogy things can be configured using .things files.
The innogy SmartHome Controller (SHC) can be configured using the following syntax:
```
Bridge innogysmarthome:bridge:<bridge-id> []
```
Then the required authcode is retrieved and set **automatically**:
```
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 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" {
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>" ]
}
```
## Items configuration
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"}
Number myHeatingTemp "Bath [%.1f °C]" <temperature> {channel="innogysmarthome:RST:mybridge:myHeating:temperature"}
Number myHeatingModeTempTarget "Settemp bath [%.1f °C]" <temperature> {channel="innogysmarthome:RST:mybridge:myHeating:set_temperature"}
String myHeatingMode "Mode bath [%s]" <temperature> {channel="innogysmarthome:RST:mybridge:myHeating:operation_mode"}
Number myHeatingHumidity "Bath [%.1f %%]" <humidity> {channel="innogysmarthome:RST:mybridge:myHeating:humidity"}
```
## Sitemap configuration
The site configuration works a usual. One special example
```
sitemap default label="Home" {
Frame {
Text item=myHeatingTemp label="Temperature"
Text item=myHeatingHumidity label="Humidity"
Switch item=myHeatingMode label="Mode" mappings=[Manu="Manual", Auto="Auto"]
Setpoint item=myHeatingModeTempTarget label="Target temperature" minValue=16 maxValue=25 step=1
}
}
```
## Rules example for pushbuttons
Pushbuttons provide trigger channels, that can only be used in rules.
Here is an example rule:
```
rule "Button triggered rule"
when
Channel 'innogysmarthome:WSC2:mybridge:myPushButton:button1' triggered PRESSED
then
// do something...
logInfo("testlogger", "Button 1 pressed")
end
```
## Resolving certificate issues
If the bridge stays offline with the following status shown in the UI, the reason could be an expired certificate:
`OFFLINE - COMMUNICATION_ERROR sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target`
To solve this on a Linux system, follow this steps:
1. Download the certificates (.cer-files) of https://home.innogy-smarthome.de and https://innogy.com including the "DigiCert Global Root G2" to your computer.
As this depends on the used browser and operating system, please use a web search engine to find out how to achieve this for your situation.
2. On your Linux system, goto your Java Machine's certificate store, e.g. `/usr/lib/jvm/jdk-8-oracle-arm32-vfp-hflt/jre/lib/security`.
The path should include a file called `cacerts` (this is the certificate store) and may differ depending on the system used.
3. Copy the .cer-files from step 1 into this directory.
4. Import each certificate with the command: `sudo keytool importcert alias “innogysmarthome” keystore cacerts file innogy.cer`
(alias can be freely chosen but must be unique; replace innogy.cer with the filename of the downloaded certificate)
5. Restart the JVM and openHAB.
The default password of the certificate store is "changeit".