demus/openhab-addons
1
0
Fork 0
mirror of https://github.com/openhab/openhab-addons.git synced 2025-01-27 07:41:39 +01:00
Code Issues Packages Projects Releases Wiki Activity
253a634f0a
openhab-addons/bundles/org.openhab.binding.livisismarthome/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

215 lines
19 KiB
Markdown
Raw Blame History

# LIVISI SmartHome Binding
The binding integrates the [LIVISI (RWE/innogy) SmartHome](https://www.livisi.de) system into openHAB.
The binding is the successor of the innogy SmartHome openHAB binding, which was communicating with the LIVISI cloud servers over the Internet.
This binding communicates directly with LIVISI SmartHome Controllers (SHC) and not through the LIVISI cloud services.
On your SHC you need a minimum software version of 1.2.XX.XXX (SHC 2) or 1.914-3.1.XXXX.XX (SHC 1 / classic) with activated "Local SmartHome".
## Supported things
### Bridge
The LIVISI 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.
| Device | Description | Supported channels |
|--------|--------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
| SHC | SmartHome Controller (Bridge) | status, cpu, disk, memory (updated by events; SHC classic: Updated every minute) |
| BRC8 | Basic Remote Controller | button1 ... button8, button1Count ... button8Count, batteryLow |
| ISC2 | In Wall Smart Controller | button1, button2, button1Count, button2Count, batteryLow |
| ISD2 | In Wall Smart Dimmer | button1, button2, button1Count, button2Count, dimmer |
| ISR2 | In Wall Smart Rollershutter | button1, button2, button1Count, button2Count, rollershutter |
| ISS2 | In Wall Smart Switch | button1, button2, button1Count, button2Count, 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 | targetTemperature, currentTemperature, frostWarning, humidity, moldWarning, operationMode, windowReductionActive, batteryLow |
| RST2 | Radiator Mounted Smart Thermostat (newer two battery version since 2018) | targetTemperature, currentTemperature, frostWarning, humidity, moldWarning, operationMode, windowReductionActive, batteryLow |
| | VariableActuator | switch |
| WDS | Window Door Sensor | contact, batteryLow |
| WMD | Wall Mounted Motion Detector, indoor | motionCount, luminance, batteryLow |
| WMDO | Wall Mounted Motion Detector, outdoor | motionCount, luminance, batteryLow |
| WRT | Wall Mounted Room Thermostat | targetTemperature, currentTemperature, frostWarning, humidity, moldWarning, operationMode, windowReductionActive, batteryLow |
| WSC2 | Wall Mounted Smart Controller | button1, button2, button1Count, button2Count, batteryLow |
| WSD | Wall Mounted Smoke Detector, old version | smoke, alarm, batteryLow |
| WSD2 | Wall Mounted Smoke Detector, new version | smoke, alarm, batteryLow |
Powermeter devices
| Device | Description | Supported channels |
|-----------------|----------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| AnalogMeter | The Analog Meter from the LIVISI EnergyControl product | energyConsumptionMonthKwh, absoluteEnergyConsumption, energyConsumptionMonthEuro, energyConsumptionDayEuro, energyConsumptionDayKwh |
| GenerationMeter | The Generation Meter from the LIVISI PowerControlSolar product | energyGenerationMonthKwh, totalEnergyGeneration, energyGenerationMonthEuro, energyGenerationDayEuro, energyGenerationDayKwh, powerGenerationWatt |
| SmartMeter | The Smart Meter from the LIVISI PowerControl product. | energyConsumptionMonthKwh, absoluteEnergyConsumption, energyConsumptionMonthEuro, energyConsumptionDayEuro, energyConsumptionDayKwh, powerConsumptionWatt |
| Two-Way-Meter | The Two-Way-Meter from the LIVISI PowerControlSolar product | energyMonthKwh, totalEnergy, energyMonthEuro, energyDayEuro, energyDayKwh, energyFeedMonthKwh, totalEnergyFed, energyFeedMonthEuro, energyFeedDayEuro, energyFeedDayKwh, powerWatt |
## Discovery
The bridge (SHC) can not be discovered automatically. It must 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 LIVISI SmartHome app before, because the LIVISI 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 |
| batteryLow | Switch | Indicates, if the battery is low (ON/OFF) | BRC8, ISC2, RST, RST2, WDS, WMD, WMD0, WRT, WSC2, WSD, WSD2 |
| contact | Contact | Indicates the contact state (OPEN/CLOSED) | WDS |
| cpu | Number | CPU-Usage of the SHC in percent | SHC (bridge) |
| dimmer | Dimmer | Allows to dimm a light device | ISD2, PSD |
| disk | Number | Disk-Usage of the SHC in percent | SHC (bridge) |
| frostWarning | Switch | active, if the measured temperature is too low (ON/OFF) | RST, RST2, WRT |
| humidity | Number | Relative humidity in percent | RST, RST2, 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 |
| button1Count | Number | Number of button pushes for button 1, increased with each push | BRC8, ISC2, ISD2, ISR2, ISS2, WSC2 |
| button2Count | Number | Number of button pushes for button 2, increased with each push | BRC8, ISC2, ISD2, ISR2, ISS2, WSC2 |
| button3Count | Number | Number of button pushes for button 3, increased with each push | BRC8 |
| button4Count | Number | Number of button pushes for button 4, increased with each push | BRC8 |
| button5Count | Number | Number of button pushes for button 5, increased with each push | BRC8 |
| button6Count | Number | Number of button pushes for button 6, increased with each push | BRC8 |
| button7Count | Number | Number of button pushes for button 7, increased with each push | BRC8 |
| button8Count | Number | Number of button pushes for button 8, increased with each push | BRC8 |
| luminance | Number | Indicates the measured luminance in percent | WMD, WMD0 |
| memory | Number | Memory-Usage of the SHC in percent | SHC (bridge) |
| moldWarning | Switch | Active, if the measured humidity is too low (ON/OFF) | RST, RST2, WRT |
| motionCount | Number | Number of detected motions, increases with each detected motion | WMD, WMDO |
| operationMode | String | The mode of a thermostat (auto/manual) | RST, RST2, WRT |
| rollershutter | Rollershutter | Controls a roller shutter | ISR2 |
| targetTemperature | Number | Sets the target temperature in °C (min 6 °C, max 30 °C) | RST, RST2, WRT |
| smoke | Switch | Indicates, if smoke was detected (ON/OFF) | WSD, WSD2 |
| status | String | Status of the SHC (ACTIVE/NORMAL, INITIALIZING/REBOOTING or SHUTTINGDOWN) | SHC (bridge) |
| switch | Switch | A switch to turn the device or variable on/off (ON/OFF) | ISS2, PSS, PSSO, VariableActuator |
| currentTemperature | Number | Holds the actual temperature in °C | RST, RST2, WRT |
| windowReductionActive | Switch | Indicates if a linked window is open and temperature reduced (ON/OFF) | RST, RST2, WRT |
The `rollershutter` channel has a `boolean` parameter `invert`.
It is `false` by default.
This means `100` on LIVISI is `UP` and `0` is `DOWN`.
When `invert` is `true` than `0` on LIVISI is `UP` and `100` is `DOWN`.
## Triggers
| Trigger Type | Description | Available on thing |
|---------------|-----------------------------------------------|-------------------------------------|
| SHORT_PRESSED | Fired when you press a button short | BRC8, ISC2, ISD2, ISR2, ISS2, WSC2 |
| LONG_PRESSED | Fired when you press a button longer | BRC8, ISC2, ISD2, ISR2, ISS2, WSC2 |
| PRESSED | Fired when you press a button (short or long) | BRC8, ISC2, ISD2, ISR2, ISS2, WSC2 |
## Thing configuration
### Configuring the SmartHome Controller (SHC)
The SmartHome Controller (SHC) can be configured in the UI as follows:
When adding the "LIVISI SmartHome Controller" via the Inbox, you have to define the hostname or local IP address and the password for the local user.
Save your changes. The SHC should now login and go online.
### 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 the automatic discovery process and graphical configuration using the UI, LIVISI things can be configured manually.
The LIVISI SmartHome Controller (SHC) can be configured using the following syntax:
```
Bridge livisismarthome:bridge:<bridge-id> "Livisi: SmartHome Controller (SHC)" [ host="192.168.0.99", password="SomethingSecret", webSocketIdleTimeout=900]
```
** *Security warning!**
The communication between the binding and the SHC is not encrypted and can be traced.
So be careful and secure your local network from unauthorized access.
All other LIVISI 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 UI inbox, as you find it below all things there in the form `livisismarthome:<device-type>:<bridge-id>:<the-device-id>` (example: `livisismarthome:WSC2:SMARTHOME01:e9a74941a3807b57332214f346fb1129`).
However, a full example .things configuration look like this:
```
Bridge livisismarthome:bridge:mybride "LIVISI 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 ISR2 myRollerShutter1 "RollerShutter" @ "Livingroom" [ id="<device-id>" ]
Thing ISR2 myRollerShutter2 "RollerShutter (inverted)" @ "Livingroom" [ id="<device-id>" ] {Type rollershutterActuator : rollershutter [invert=true]}
Thing VariableActuator myLivisiVariable "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="livisismarthome:WDS:mybridge:myWindowContact:contact"}
Switch myWindowContactBattery "Battery low" <battery> {channel="livisismarthome:WDS:mybridge:myWindowContact:batteryLow"}
Number myHeatingTemp "Bath [%.1f °C]" <temperature> {channel="livisismarthome:RST:mybridge:myHeating:currentTemperature"}
Number myHeatingModeTempTarget "Settemp bath [%.1f °C]" <temperature> {channel="livisismarthome:RST:mybridge:myHeating:targetTemperature"}
String myHeatingMode "Mode bath [%s]" <temperature> {channel="livisismarthome:RST:mybridge:myHeating:operationMode"}
Number myHeatingHumidity "Bath [%.1f %%]" <humidity> {channel="livisismarthome:RST:mybridge:myHeating:humidity"}
```
## Sitemap configuration
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 push-buttons
Push-buttons provide trigger channels, that can only be used in rules.
Here is an example rule:
```
rule "Button triggered rule"
when
Channel 'livisismarthome:WSC2:mybridge:myPushButton:button1' triggered PRESSED
then
// do something...
logInfo("testlogger", "Button 1 pressed")
end
```
Reference in New Issue View Git Blame Copy Permalink