public/openhab-addons
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[deconz] Add Pairing/Scene actions, new devices and improve code (#14622)

Browse Source 
* port changes
* update instructions
* Incorporate review comments from #14134
* new improvements (mostly Java 17 changes)
* further improvements

Signed-off-by: Jan N. Klug <github@klug.nrw>
This commit is contained in:
J-N-K
2023-03-18 16:06:55 +01:00
committed by GitHub
parent 23f3374ea9
commit ee1de11864
48 changed files with 1814 additions and 824 deletions
Download Patch File Download Diff File Expand all files Collapse all files

217
bundles/org.openhab.binding.deconz/README.md
View File

@@ -9,27 +9,28 @@ deCONZ offers a documented real-time channel that this binding makes use of to b
There is one bridge (`deconz`) that manages the connection to the deCONZ software instance.
These sensors are supported:
| Device type | Resource Type | Thing type |
|-----------------------------------|-----------------------------------|----------------------|
| Presence Sensor | ZHAPresence, CLIPPresence | `presencesensor` |
| Power Sensor | ZHAPower, CLIPPower | `powersensor` |
| Consumption Sensor | ZHAConsumption | `consumptionsensor` |
| Switch | ZHASwitch | `switch` |
| Light Sensor | ZHALightLevel | `lightsensor` |
| Temperature Sensor | ZHATemperature | `temperaturesensor` |
| Humidity Sensor | ZHAHumidity | `humiditysensor` |
| Pressure Sensor | ZHAPressure | `pressuresensor` |
| Open/Close Sensor | ZHAOpenClose | `openclosesensor` |
| Water Leakage Sensor | ZHAWater | `waterleakagesensor` |
| Alarm Sensor | ZHAAlarm | `alarmsensor` |
| Fire Sensor | ZHAFire | `firesensor` |
| Vibration Sensor | ZHAVibration | `vibrationsensor` |
| deCONZ Artificial Daylight Sensor | deCONZ specific: simulated sensor | `daylightsensor` |
| Carbon-Monoxide Sensor | ZHACarbonmonoxide | `carbonmonoxide` |
| Air quality Sensor | ZHAAirQuality | `airqualitysensor` |
| Color Controller | ZBT-Remote-ALL-RGBW | `colorcontrol` |
| Device type | Resource Type | Thing type |
|-----------------------------------|-----------------------------------|------------------------|
| Presence Sensor | ZHAPresence, CLIPPresence | `presencesensor` |
| Power Sensor | ZHAPower, CLIPPower | `powersensor` |
| Consumption Sensor | ZHAConsumption | `consumptionsensor` |
| Switch | ZHASwitch | `switch` |
| Light Sensor | ZHALightLevel | `lightsensor` |
| Temperature Sensor | ZHATemperature | `temperaturesensor` |
| Humidity Sensor | ZHAHumidity | `humiditysensor` |
| Pressure Sensor | ZHAPressure | `pressuresensor` |
| Open/Close Sensor | ZHAOpenClose | `openclosesensor` |
| Water Leakage Sensor | ZHAWater | `waterleakagesensor` |
| Alarm Sensor | ZHAAlarm | `alarmsensor` |
| Fire Sensor | ZHAFire | `firesensor` |
| Vibration Sensor | ZHAVibration | `vibrationsensor` |
| deCONZ Artificial Daylight Sensor | deCONZ specific: simulated sensor | `daylightsensor` |
| Carbon-Monoxide Sensor | ZHACarbonmonoxide | `carbonmonoxidesensor` |
| Airquality Sensor | ZHAAirquality | `airqualitysensor` |
| Moisture Sensor | ZHAMoisture | `moisturesensor` |
| Color Controller | ZBT-Remote-ALL-RGBW | `colorcontrol` |
Additionally lights, window coverings (blinds), door locks and thermostats are supported:
Additionally, lights, window coverings (blinds), door locks and thermostats are supported:
| Device type | Resource Type | Thing type |
|--------------------------------------|-----------------------------------------------|-------------------------|
@@ -43,6 +44,8 @@ Additionally lights, window coverings (blinds), door locks and thermostats are s
| Warning Device (Siren) | Warning device | `warningdevice` |
| Door Lock | A remotely operatable door lock | `doorlock` |
**Note**: `windowcovering` might require updating your deCONZ software since the support changed.
Currently only light-groups are supported via the thing-type `lightgroup`.
## Discovery
@@ -57,13 +60,14 @@ If your device is not discovered, please check the DEBUG log for unknown devices
These configuration parameters are available:
| Parameter | Description | Type | Default |
|-----------|---------------------------------------------------------------------------------|---------|---------|
| host | Host address (hostname / ip) of deCONZ interface | string | n/a |
| httpPort | Port of deCONZ HTTP interface | string | 80 |
| port | Port of deCONZ Websocket (optional, can be filled automatically) **(Advanced)** | string | n/a |
| apikey | Authorization API key (optional, can be filled automatically) | string | n/a |
| timeout | Timeout for asynchronous HTTP requests (in milliseconds) | integer | 2000 |
| Parameter | Description | Type | Default |
|------------------|-------------------------------------------------------------------------------------------------------------------------|---------|---------|
| host | Host address (hostname / ip) of deCONZ interface | string | n/a |
| httpPort | Port of deCONZ HTTP interface | string | 80 |
| port | Port of deCONZ Websocket (optional, can be filled automatically) **(Advanced)** | string | n/a |
| apikey | Authorization API key (optional, can be filled automatically) | string | n/a |
| timeout | Timeout for asynchronous HTTP requests (in milliseconds) | integer | 2000 |
| websocketTimeout | Timeout for the websocket connection (in s). After this time, the connection is considered dead and tries to re-connect | integer | 120 |
The deCONZ bridge requires the IP address or hostname as a configuration value in order for the binding to know where to access it.
If needed you can specify an optional port for the HTTP interface or the Websocket.
@@ -120,42 +124,45 @@ Bridge deconz:deconz:homeserver [ host="192.168.0.10", apikey="ABCDEFGHIJ" ]
The sensor devices support some of the following channels:
| Channel Type ID | Item Type | Access Mode | Description | Thing types |
|-----------------|--------------------------|-------------|-------------------------------------------------------------------------------------------|---------------------------------------------------|
| presence | Switch | R | Status of presence: `ON` = presence; `OFF` = no-presence | presencesensor |
| enabled | Switch | R/W | This channel activates or deactivates the sensor | presencesensor |
| last_updated | DateTime | R | Timestamp when the sensor was last updated | all, except daylightsensor |
| last_seen | DateTime | R | Timestamp when the sensor was last seen | all, except daylightsensor |
| power | Number:Power | R | Current power usage in Watts | powersensor, sometimes for consumptionsensor |
| consumption | Number:Energy | R | Current power usage in Watts/Hour | consumptionsensor |
| voltage | Number:ElectricPotential | R | Current voltage in V | some powersensors |
| current | Number:ElectricCurrent | R | Current current in mA | some powersensors |
| button | Number | R | Last pressed button id on a switch | switch, colorcontrol |
| gesture | Number | R | A gesture that was performed with the switch | switch |
| lightlux | Number:Illuminance | R | Current light illuminance in Lux | lightsensor |
| light_level | Number | R | Current light level | lightsensor |
| dark | Switch | R | Light level is below the darkness threshold | lightsensor, sometimes for presencesensor |
| daylight | Switch | R | Light level is above the daylight threshold | lightsensor |
| temperature | Number:Temperature | R | Current temperature in ˚C | temperaturesensor, some Xiaomi sensors,thermostat |
| humidity | Number:Dimensionless | R | Current humidity in % | humiditysensor |
| pressure | Number:Pressure | R | Current pressure in hPa | pressuresensor |
| open | Contact | R | Status of contacts: `OPEN`; `CLOSED` | openclosesensor |
| waterleakage | Switch | R | Status of water leakage: `ON` = water leakage detected; `OFF` = no water leakage detected | waterleakagesensor |
| fire | Switch | R | Status of a fire: `ON` = fire was detected; `OFF` = no fire detected | firesensor |
| alarm | Switch | R | Status of an alarm: `ON` = alarm was triggered; `OFF` = no alarm | alarmsensor |
| tampered | Switch | R | Status of a zone: `ON` = zone is being tampered; `OFF` = zone is not tampered | any IAS sensor |
| vibration | Switch | R | Status of vibration: `ON` = vibration was detected; `OFF` = no vibration | alarmsensor |
| light | String | R | Light level: `Daylight`; `Sunset`; `Dark` | daylightsensor |
| value | Number | R | Sun position: `130` = dawn; `140` = sunrise; `190` = sunset; `210` = dusk | daylightsensor |
| battery_level | Number | R | Battery level (in %) | any battery-powered sensor |
| battery_low | Switch | R | Battery level low: `ON`; `OFF` | any battery-powered sensor |
| carbonmonoxide | Switch | R | `ON` = carbon monoxide detected | carbonmonoxide |
| airquality | String | R | Current air quality level | airqualitysensor |
| airqualityppb | Number:Dimensionless | R | Current air quality ppb (parts per billion) | airqualitysensor |
| color | Color | R | Color set by remote | colorcontrol |
| windowopen | Contact | R | `windowopen` status is reported by some thermostats | thermostat |
| Channel Type ID | Item Type | Access Mode | Description | Thing types |
|--------------------|--------------------------|-------------|-------------------------------------------------------------------------------------------|---------------------------------------------------|
| presence | Switch | R | Status of presence: `ON` = presence; `OFF` = no-presence | presencesensor |
| enabled | Switch | R/W | This channel activates or deactivates the sensor | presencesensor |
| last_updated | DateTime | R | Timestamp when the sensor was last updated | all, except daylightsensor |
| last_seen | DateTime | R | Timestamp when the sensor was last seen | all, except daylightsensor |
| power | Number:Power | R | Power usage in Watts | powersensor, sometimes for consumptionsensor |
| consumption | Number:Energy | R | Energy in Watt*Hour | consumptionsensor |
| voltage | Number:ElectricPotential | R | Voltage in V | some powersensors |
| current | Number:ElectricCurrent | R | Current in mA | some powersensors |
| button | Number | R | Last pressed button id on a switch | switch, colorcontrol |
| gesture | Number | R | A gesture that was performed with the switch | switch |
| lightlux | Number:Illuminance | R | Light illuminance in Lux | lightsensor |
| light_level | Number | R | Light level | lightsensor |
| dark | Switch | R | Light level is below the darkness threshold | lightsensor, sometimes for presencesensor |
| daylight | Switch | R | Light level is above the daylight threshold | lightsensor |
| temperature | Number:Temperature | R | Temperature in ˚C | temperaturesensor, some Xiaomi sensors,thermostat |
| humidity | Number:Dimensionless | R | Humidity in % | humiditysensor |
| pressure | Number:Pressure | R | Pressure in hPa | pressuresensor |
| open | Contact | R | Status of contacts: `OPEN`; `CLOSED` | openclosesensor |
| waterleakage | Switch | R | Status of water leakage: `ON` = water leakage detected; `OFF` = no water leakage detected | waterleakagesensor |
| fire | Switch | R | Status of a fire: `ON` = fire was detected; `OFF` = no fire detected | firesensor |
| alarm | Switch | R | Status of an alarm: `ON` = alarm was triggered; `OFF` = no alarm | alarmsensor |
| tampered | Switch | R | Status of a zone: `ON` = zone is being tampered; `OFF` = zone is not tampered | any IAS sensor |
| vibration | Switch | R | Status of vibration: `ON` = vibration was detected; `OFF` = no vibration | alarmsensor |
| light | String | R | Light level: `Daylight`; `Sunset`; `Dark` | daylightsensor |
| value | Number | R | Sun position: `130` = dawn; `140` = sunrise; `190` = sunset; `210` = dusk | daylightsensor |
| battery_level | Number | R | Battery level (in %) | any battery-powered sensor |
| battery_low | Switch | R | Battery level low: `ON`; `OFF` | any battery-powered sensor |
| carbonmonoxide | Switch | R | `ON` = carbon monoxide detected | carbonmonoxide |
| color | Color | R | Color set by remote | colorcontrol |
| windowopen | Contact | R | `windowopen` status is reported by some thermostats | thermostat |
| externalwindowopen | Contact | R/W | forward a status to a theromastat (some devices) | thermostat |
| locked | Switch | R/W | reports/sets the childlock on some thermostats | thermostat |
| airquality | String | R | Airquality as string | airqualitysensor |
| airqualityppb | Number:Dimensionless | R | Airquality (in parts-per-billion) | airqualitysensor |
| moisture | Number:Dimensionless | R | Moisture | moisturesensor |
**NOTE:** Beside other non mandatory channels, the `battery_level` and `battery_low` channels will be added to the Thing during runtime if the sensor is battery-powered.
**NOTE:** Beside other non-mandatory channels, the `battery_level` and `battery_low` channels will be added to the Thing during runtime if the sensor is battery-powered.
The specification of your sensor depends on the deCONZ capabilities.
Have a detailed look for [supported devices](https://github.com/dresden-elektronik/deconz-rest-plugin/wiki/Supported-Devices).
@@ -163,25 +170,25 @@ The `last_seen` channel is added when it is available AND the `lastSeenPolling`
Other devices support
| Channel Type ID | Item Type | Access Mode | Description | Thing types |
|-------------------|--------------------------|:-----------:|---------------------------------------|-------------------------------------------------|
| brightness | Dimmer | R/W | Brightness of the light | `dimmablelight`, `colortemperaturelight` |
| switch | Switch | R/W | State of an ON/OFF device | `onofflight` |
| color | Color | R/W | Color of a multi-color light | `colorlight`, `extendedcolorlight`, `lightgroup`|
| color_temperature | Number | R/W | Color temperature in Kelvin. The value range is determined by each individual light | `colortemperaturelight`, `extendedcolorlight`, `lightgroup` |
| effect | String | R/W | Effect selection. Allowed commands are set dynamically | `colorlight` |
| effectSpeed | Number | W | Effect Speed | `colorlight` |
| lock | Switch | R/W | Lock (ON) or unlock (OFF) the doorlock| `doorlock` |
| ontime | Number:Time | W | Timespan for which the light is turned on | all lights |
| position | Rollershutter | R/W | Position of the blind | `windowcovering` |
| heatsetpoint | Number:Temperature | R/W | Target Temperature in °C | `thermostat` |
| valve | Number:Dimensionless | R | Valve position in % | `thermostat` |
| mode | String | R/W | Mode: "auto", "heat" and "off" | `thermostat` |
| offset | Number | R | Temperature offset for sensor | `thermostat` |
| alert | String | W | Turn alerts on. Allowed commands are `none`, `select` (short blinking), `lselect` (long blinking) | `warningdevice`, `lightgroup`, `dimmablelight`, `colorlight`, `extendedcolorlight`, `colortemperaturelight` |
| all_on | Switch | R | All lights in group are on | `lightgroup` |
| any_on | Switch | R | Any light in group is on | `lightgroup` |
| scene | String | W | Recall a scene. Allowed commands are set dynamically | `lightgroup` |
| Channel Type ID | Item Type | Access Mode | Description | Thing types |
|-------------------|----------------------|:-----------:|---------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
| brightness | Dimmer | R/W | Brightness of the light | `dimmablelight`, `colortemperaturelight` |
| switch | Switch | R/W | State of a ON/OFF device | `onofflight` |
| color | Color | R/W | Color of an multi-color light | `colorlight`, `extendedcolorlight`, `lightgroup` |
| color_temperature | Number | R/W | Color temperature in Kelvin. The value range is determined by each individual light | `colortemperaturelight`, `extendedcolorlight`, `lightgroup` |
| effect | String | R/W | Effect selection. Allowed commands are set dynamically | `colorlight` |
| effectSpeed | Number | W | Effect Speed | `colorlight` |
| lock | Switch | R/W | Lock (ON) or unlock (OFF) the doorlock | `doorlock` |
| ontime | Number:Time | W | Timespan for which the light is turned on | all lights |
| position | Rollershutter | R/W | Position of the blind | `windowcovering` |
| heatsetpoint | Number:Temperature | R/W | Target Temperature in °C | `thermostat` |
| valve | Number:Dimensionless | R | Valve position in % | `thermostat` |
| mode | String | R/W | Mode: "auto", "heat" and "off" | `thermostat` |
| offset | Number | R | Temperature offset for sensor | `thermostat` |
| alert | String | W | Turn alerts on. Allowed commands are `none`, `select` (short blinking), `lselect` (long blinking) | `warningdevice`, `lightgroup`, `dimmablelight`, `colorlight`, `extendedcolorlight`, `colortemperaturelight` |
| all_on | Switch | R | All lights in group are on | `lightgroup` |
| any_on | Switch | R | Any light in group is on | `lightgroup` |
| scene | String | W | Recall a scene. Allowed commands are set dynamically | `lightgroup` |
**NOTE:** For groups `color` and `color_temperature` are used for sending commands to the group.
Their state represents the last command send to the group, not necessarily the actual state of the group.
@@ -211,6 +218,26 @@ Both will be added during runtime if supported by the switch.
| GESTURE_ROTATE_CLOCKWISE | 7 |
| GESTURE_ROTATE_COUNTER_CLOCKWISE | 8 |
## Thing Actions
Thing actions can be used to manage the network and its content.
The `deconz` thing supports a thing action to allow new devices to join the network:
| Action name | Input Value | Return Value | Description |
|------------------------|----------------------|--------------|----------------------------------------------------------------------------------------------------------------|
| `permitJoin(duration)` | `duration` (Integer) | - | allows new devices to join for `duration` seconds. Allowed values are 1-240, default is 120 if no value given. |
The `lightgroup` thing supports thing actions for managing scenes:
| Action name | Input Value | Return Value | Description |
|---------------------|-----------------|--------------|-------------------------------------------------------------------------------------------|
| `createScene(name)` | `name` (String) | `newSceneId` | Creates a new scene with the name `name` and returns the new scene's id (if successfull). |
| `deleteScene(id)` | `id` (Integer) | - | Deletes the scene with the given id. |
| `storeScene(id)` | `id` (Integer) | - | Store the current group's state as scene with the given id. |
The return value refers to a key of the given name within the returned Map. See [example](#thing-actions-example).
## Full Example
### Things file
@@ -260,8 +287,34 @@ then
end
```
# Thing Actions Example
:::: tabs
::: tab JavaScript
```javascript
deconzActions = actions.get("deconz", "deconz:lightgroup:00212E040ED9:5");
retVal = deconzActions.createScene("TestScene");
deconzActions.storeScene(retVal["newSceneId"]);
```
:::
::: tab DSL
```java
val deconzActions = getActions("deconz", "deconz:lightgroup:00212E040ED9:5");
var retVal = deconzActions.createScene("TestScene");
deconzActions.storeScene(retVal.get("newSceneId"));
```
:::
::::
### Troubleshooting
By default state updates are ignored for 250ms after a command.
By default, state updates are ignored for 250ms after a command.
If your light takes more than that to change from one state to another, you might experience a problem with jumping sliders/color pickers.
In that case the `transitiontime` parameter should be changed to the desired time.