This repository was archived by the owner on May 17, 2021. It is now read-only.
This repository was archived by the owner on May 17, 2021. It is now read-only.
[Plugwise] Add support for Scan, Sense, Stealth and Switch #4565
Description
Adding support for other Plugwise device types would make migrating to openHAB (and Linux) a more viable option for people with currently unsupported of Plugwise device types. This is a feature I've already been working on myself because it is blocking for me to use openHAB.
The protocol is pretty straightforward. By handling several more message types (and adding some configuration), support can be added for:
- Scan
- Sense
- Stealth
- Switch
Feature requirements
Below follows the list of requirements I currently have for this feature:
- Configuration remains backwards compatible so people can easily test and upgrade
- Static configuration of non-Circle device types through the configuration (.cfg) file to keep things simple for now
- Binding keeps working with openHAB 1.8.x+ and does not introduce new issues when used with openHAB 2.0
- Battery powered devices (Scan, Sense, Switch) push their information and are not polled for it
- Performance of the binding stays the same or is improved
Feature limitations
- Adding new devices to the network and updating device settings (Scan, Sense) is not part of this feature and should be done via Source (similar to the current Circle implementation)
- Automatic device type detection is not part of this feature. That is something that should be added when the binding supports the new Inbox feature of openHAB 2.0. Detected devices are assumed to be Circles for backwards compatibility
- Status values are based on messages pushed from online devices. I.e. when messages are missed because a device is offline, no historic lookup is done in the Scan or Sense memory buffers when it rejoins the network.
- The switching groups defined in the Source are unknown to the binding. Devices will still react to them when configured
Configuration examples
Device type configuration in the configuration file
Below follows an example on how to configure device types in your configuration file.
openHAB 1.8: configurations/openhab.cfg
openHAB 2.0: conf/services/plugwise.cfg
############################## Plugwise Binding #######################################
#
# "stick" is reserved plug wise id
plugwise:stick.port=/dev/ttyUSB0
# interval in ms to wait between messages sent on the ZigBee network
#plugwise:stick.interval=150
#plugwise:<plugwise-id-1>.mac=
# you can also name your device circleplus and omit the line specifying the circleplus type (backwards compatibility)
plugwise:lamp.mac=000D6F0000011111
plugwise:lamp.type=circleplus
# the default device type is circle, so in this case the type could be ommitted (backwards compatibility)
plugwise:fan.mac=000D6F0000022222
plugwise:fan.type=circle
plugwise:motionsensor.mac=000D6F0000033333
plugwise:motionsensor.type=scan
plugwise:climatesensor.mac=000D6F0000044444
plugwise:climatesensor.type=sense
plugwise:fridge.mac=000D6F0000055555
plugwise:fridge.type=stealth
plugwise:lightswitches.mac=000D6F0000066666
plugwise:lightswitches.type=switch
Item configuration in the items file
New status variables introduced by this feature are:
| Variable | Item Type | Purpose | Supported devices |
| lastseen | DateTime | Date/Time stamp of the last received message. Because there is no battery level indication this is a helpful value to determine if a battery powered device is still operating properly even when no state changes occur. | Scan, Sense, Switch |
| triggered | OnOff | Most recent switch action initiated by the device. When daylight override is enabled on a Scan this corresponds one to one with motion detection | Scan, Sense |
| triggered-stamp | DateTime | Date/Time stamp of the last trigger state change | Scan, Sense |
| humidity | Number | Current relative humidity (%) | Sense |
| humidity-stamp | DateTime | Date/Time stamp of the last relative humidity measurement | Sense |
| temperature | Number | Current temperature (°C) | Sense |
| temperature-stamp | DateTime | Date/Time stamp of the last temperature measurement | Sense |
| left-button-state | OnOff | Current state of the left button | Switch |
| left-button-state-stamp | DateTime | Date/Time stamp of the last left button state change | Switch |
| right-button-state | OnOff | Current state of the right button | Switch |
| right-button-state-stamp | DateTime | Date/Time stamp of the last right button state change | Switch |
Below follows an example on how to use all possible new (and existing) item values in an item file.
openHAB 1.8: configurations/items/plugwise.items
openHAB 2.0: conf/items/plugwise.items
/* Circle+ */
Switch Lamp_Switch "Switch" <switch> { plugwise="[ON:lamp:state:15], [OFF:lamp:state:15]" }
String Lamp_Clock "Clock [%s]" <clock> { plugwise="[lamp:clock:15]"}
Number Lamp_Power "Power [%.1f W]" <energy> { plugwise="[lamp:power:10]"}
DateTime Lamp_Power_Stamp "Power stamp [%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS]" <calendar> { plugwise="[lamp:power-stamp:15]"}
Number Lamp_Last_Hour "Last hour [%.3f kWh]" <chart> { plugwise="[lamp:lasthour:60]"}
DateTime Lamp_Last_Hour_Stamp "Last hour stamp [%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS]" <calendar> { plugwise="[lamp:lasthour-stamp:60]"}
DateTime Lamp_Real_Time_Clock "Real time clock [%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS]" <clock> { plugwise="[lamp:realtime-clock:60]"}
/* Circle or Stealth */
Switch Fan_Switch "Switch" <switch> { plugwise="[ON:fan:state:15], [OFF:fan:state:15]" }
String Fan_Clock "Clock [%s]" <clock> { plugwise="[fan:clock:15]"}
Number Fan_Power "Power [%.1f W]" <energy> { plugwise="[fan:power:10]"}
DateTime Fan_Power_Stamp "Power stamp [%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS]" <calendar> { plugwise="[fan:power-stamp:15]"}
Number Fan_Last_Hour "Last hour [%.3f kWh]" <chart> { plugwise="[fan:lasthour:60]"}
DateTime Fan_Last_Hour_Stamp "Last hour stamp [%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS]" <calendar> { plugwise="[fan:lasthour-stamp:60]"}
/* Scan */
Switch Motion_Sensor_Switch "Triggered [%s]" <switch> { plugwise="[ON:motionsensor:triggered], [OFF:motionsensor:triggered]" }
DateTime Motion_Sensor_Triggered_Stamp "Triggered stamp [%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS]" <calendar> { plugwise="[motionsensor:triggered-stamp]" }
DateTime Motion_Sensor_Last_Seen "Last seen [%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS]" <clock> { plugwise="[motionsensor:lastseen]" }
/* Sense */
Switch Climate_Sensor_Switch "Triggered [%s]" <switch> { plugwise="[ON:climatesensor:triggered], [OFF:climatesensor:triggered]" }
DateTime Climate_Sensor_Triggered_Stamp "Triggered stamp [%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS]" <calendar> { plugwise="[climatesensor:triggered-stamp]" }
Number Climate_Sensor_Humidity "Humidity [%.1f %%]" <humidity> { plugwise="[climatesensor:humidity]" }
DateTime Climate_Sensor_Humidity_Stamp "Humidity stamp [%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS]" <calendar> { plugwise="[climatesensor:humidity-stamp]" }
Number Climate_Sensor_Temperature "Temperature [%.1f °C]" <temperature> { plugwise="[climatesensor:temperature]" }
DateTime Climate_Sensor_Temperature_Stamp "Temperature stamp [%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS]" <calendar> { plugwise="[climatesensor:temperature-stamp]" }
DateTime Climate_Sensor_Last_Seen "Last seen [%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS]" <clock> { plugwise="[climatesensor:lastseen]" }
/* Switch */
Switch Light_Switches_Left_Button_State "Left button [%s]" <switch> { plugwise="[ON:lightswitches:left-button-state], [OFF:lightswitches:left-button-state]" }
DateTime Light_Switches_Left_Button_State_Stamp "Left button stamp [%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS]" <calendar> { plugwise="[lightswitches:left-button-state-stamp]" }
Switch Light_Switches_Right_Button_State "Right button [%s]" <switch> { plugwise="[ON:lightswitches:right-button-state], [OFF:lightswitches:right-button-state]" }
DateTime Light_Switches_Right_Button_State_Stamp "Right button stamp [%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS]" <calendar> { plugwise="[lightswitches:right-button-state-stamp]" }
DateTime Light_Switches_Last_Seen "Last seen [%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS]" <clock> { plugwise="[lightswitches:lastseen]" }
Sitemap showing all possible items
Below follows an example on how to use all the items in a sitemap.
openHAB 1.8: configurations/sitemaps/default.sitemap
openHAB 2.0: conf/sitemaps/default.sitemap
sitemap default label="Main Menu"
{
Frame label="Lamp (Circle+)" {
Switch item=Lamp_Switch
Text item=Lamp_Clock
Text item=Lamp_Power
Text item=Lamp_Power_Stamp
Text item=Lamp_Last_Hour
Text item=Lamp_Last_Hour_Stamp
Text item=Lamp_Real_Time_Clock
}
Frame label="Fan (Circle)" {
Switch item=Fan_Switch
Text item=Fan_Clock
Text item=Fan_Power
Text item=Fan_Power_Stamp
Text item=Fan_Last_Hour
Text item=Fan_Last_Hour_Stamp
}
Frame label="Motion Sensor (Scan)" {
Text item=Motion_Sensor_Switch
Text item=Motion_Sensor_Triggered_Stamp
Text item=Motion_Sensor_Last_Seen
}
Frame label="Climate Sensor (Sense)" {
Text item=Climate_Sensor_Switch
Text item=Climate_Sensor_Triggered_Stamp
Text item=Climate_Sensor_Humidity
Text item=Climate_Sensor_Humidity_Stamp
Text item=Climate_Sensor_Temperature
Text item=Climate_Sensor_Temperature_Stamp
Text item=Climate_Sensor_Last_Seen
}
Frame label="Light Switches (Switch)" {
Text item=Light_Switches_Left_Button_State
Text item=Light_Switches_Left_Button_State_Stamp
Text item=Light_Switches_Right_Button_State
Text item=Light_Switches_Right_Button_State_Stamp
Text item=Light_Switches_Last_Seen
}
}
Sitemap in openHAB 1.8 Classic UI
This is what the sitemap will look like in the openHAB 1.8 Classic UI.
Classic UI in openHAB 2.0
Things look very similar in the openHAB 2.0 Classic UI.
Basic UI in openHAB 2.0
It looks even better in the openHAB 2.0 Basic UI.
To do
The implementation changes already work very well for me. So depending on the feedback, I'll soon commit the code to a feature branch, put up a JAR and other people can start testing/using this fork as well. Besides that the changes need to be added to the binding documentation.