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

[shelly] Improved documentation and first use case description (#9390) 

Signed-off-by: Markus Michels <markus7017@gmail.com>
This commit is contained in:
Markus Michels 2020-12-19 15:43:34 +01:00 committed by GitHub
parent a156f3ca15
commit 712f1163de
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 607 additions and 181 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

451
bundles/org.openhab.binding.shelly/README.md
View File

@ -1,24 +1,25 @@
# Shelly Binding
This Binding integrates [Alterco Shelly devices](https://shelly.cloud).
This Binding integrates [Shelly devices](https://shelly.cloud) devloped by Allterco.
![](https://shop.shelly.cloud/image/cache/catalog/shelly_1/s1_x1-80x80.jpg) ![](https://shop.shelly.cloud/image/cache/catalog/shelly_dimmer2/shelly_dimmer2_x1-80x80.jpg) ![](https://shop.shelly.cloud/image/cache/catalog/shelly_vintage/shelly_vintage_A60-80x80.jpg) ![](https://shop.shelly.cloud/image/cache/catalog/shelly_plug_s/s_plug_s_x1-80x80.jpg) ![](https://shop.shelly.cloud/image/cache/catalog/shelly_button1/shelly_button1_x1-80x80.jpg) ![](https://shop.shelly.cloud/image/cache/catalog/shelly_gas/shelly_gas_eu-80x80.jpg) ![](https://shop.shelly.cloud/image/cache/catalog/shelly_ht/s_ht_x1-80x80.jpg)
Alterco provides a rich set of smart home devices. All of them are WiFi enabled (2,4GHz, IPv4 only) and provide a documented API.
The binding is officially acknowledged by Alterco and openHAB is listed as a reference.
Alterco directly supports this project.
Allterco provides a rich set of smart home devices. All of them are WiFi enabled (2,4GHz, IPv4 only) and provide a documented API.
The binding is officially acknowledged by Allterco and openHAB is listed as a reference and directly supports the openHAB community.
The binding controls the devices independently from the Alterco Shelly Cloud (in fact it can be disabled).
The binding controls the devices independently from the Allterco Shelly Cloud (in fact it can be disabled).
The binding co-exists with Shelly App for Smartphones, Shelly Web App, Shelly Cloud, mqqt and other 3rd party Apps.
The binding focuses on reporting the device status and device control.
Initial setup and device configuration has to be performed using the Shelly Apps.
Initial setup and device configuration has to be performed using the Shelly Apps (Web or Smartphone App).
The binding gets in sync with the next status refresh.
Refer to [Advanced Users](doc/AdvancedUsers.md) for more information on openHAB Shelly integration, e.g. firmware update, network communication or log filtering.
## Supported Devices
| Thing Type | Model | Vendor ID |
|--------------------|--------------------------------------------------------|-----------|
| shelly1 | Shelly Single Relay Switch | SHSW-1 |
| shelly1 | Shelly 1 Single Relay Switch | SHSW-1 |
| shelly1pm | Shelly Single Relay Switch with integrated Power Meter | SHSW-PM |
| shelly2-relay | Shelly Double Relay Switch in relay mode | SHSW-21 |
| shelly2-roller | Shelly2 in Roller Mode | SHSW-21 |
@ -38,7 +39,7 @@ The binding gets in sync with the next status refresh.
| shellyvintage | Shelly Vintage (White Mode) | SHVIN-1 |
| shellyht | Shelly Sensor (temp+humidity) | SHHT-1 |
| shellyflood | Shelly Flood Sensor | SHWT-1 |
| shellysmoke | Shelly Smoke Sensor | |
| shellysmoke | Shelly Smoke Sensor | SHSM-1 |
| shellygas | Shelly Gas Sensor | SHGS-1 |
| shellydw | Shelly Door/Window | SHDW-1 |
| shellydw2 | Shelly Door/Window 2 | SHDW-2 |
@ -57,40 +58,37 @@ The binding has the following configuration options:
| autoCoIoT |Auto-enable CoIoT events when firmware 1.6+ is enabled. | no |true |
The binding defaults to CoIoT events when firmware 1.6 or newer is detected. CoIoT provides near-realtime updates on device status changes.
This mode also overrules event settings in the thing configuration.
This mode also overrules event settings in the Thing configuration.
Disabling this feature allows granular control, which event types will be used. This is also required when the Shelly devices are not located on the same IP subnet (e.g. using a VPN).
In this case autoCoIoT should be disabled, CoIoT events will not work, because the underlying CoAP protocol is based on Multicast IP, which usually doesn't passes a VPN or routed network.
## Firmware
The binding requires firmware version 1.7.0 or newer to enable all features, version 1.9.2 is recommended.
Some of the features are enabled dynamically or are not available depending on device type and firmware release.
The Web UI of the Shelly device displays the current firmware version under Settings:Firmware and shows an update option when a newer version is available.
The current firmware version is reported in the Thing Properties.
A dedicated channel (device#updateAvailable) indicates the availability of a newer firmware.
Use the device's Web UI or the Shelly App to perform the update.
Check [Advanced Users](doc/AdvancedUsers.md) for information how to update your device.
Once you have updated the device **you should delete and re-discover** the openHAB Thing.
This makes sure that the Thing is correctly initialized and all supported channels are created.
openHAB will restore the channel/item linkage from the previous configuration, there is no need to re-create those manually.
## Discovery
In general devices need to be powered to be discovered by the binding.
In general devices need to be active to be discovered by the binding.
Battery powered devices need to wake up by pressing the button, they will stay active for a minute or so, which gives you enough time to start the discovery.
The binding uses mDNS to discover the Shelly devices.
They periodically announce their presence, which is used by the binding to find them on the local network.
Sometimes you need to run the manual discovery multiple times until you see all your devices.
## Firmware
The binding requires firmware version 1.7.0 or newer to enable all features.
Some of the features are enabled dynamically or are not available depending on device type and firmware release.
The Web UI of the Shelly device displays the current firmware version under Settings:Firmware and shows an update option when a newer version is available.
|Version|Notes |
|-------|--------------------------------------------------------------------------------------------------|
|1.5.7 |Minimum supported version. Older versions work in general, but have impacts to functionality (e.g. no events for battery powered devices). The binding displays a WARNING in the log if the firmware is older.|
|1.6.x |First stable CoIoT implementation. AutoCoIoT is enabled when firmware version >= 1.6 is detected. |
|1.7.x |Add additional status update values, fixes various issues |
|1.8.0 |Brings CoIoT version 2, which fixes a lot issues and gaps of version 1. |
The current firmware version is reported in the Thing Properties.
A dedicated channel (device#updateAvailable) indicates the availability of a newer firmware. Use the device's Web UI or the Shelly App to perform the update.
Once you have updated the device **you should delete and re-discover** the openHAB Thing.
Battery powered devices need to wake up by pressing the button.
This makes sure that the Thing is correctly initialized and all supported channels are created. openHAB will kill the item linkage.
At a minimum you should restart the binding on the openHAB console if you don't want to re-discover the things.
### Password Protected Devices
The Shelly devices can be configured to require authorization through a user id and password.
@ -98,34 +96,39 @@ In this case you need to set these values in the Thing configuration after appro
If you have multiple devices protected by the same credentials it's recommended to set the default user id and password in the binding configuration BEFORE running the discovery.
In this case the binding could directly access the device to retrieve the required information using those credentials.
Otherwise a thing of type shellyprotected is created in the Inbox and you could set the credentials while adding the thing. In this case the credentials are persisted as part of the thing configuration.
Otherwise a Thing of type shellyprotected is created in the Inbox and you could set the credentials while adding the Thing.
In this case the credentials are persisted as part of the Thing configuration.
### Dynamic creation of channels
The Shelly series of devices has many combinations of relays, meters (different versions), sensors etc.
For this the binding creates various channels dynamically based on the status information provided by the device at initialization time.
If a channel is missing make sure the Thing was discovered correctly and is ONLINE.
If a channel is missing delete the Thing and re-discover it.
Creation of those channels takes about 5-10sec, maybe you need to reload the page to update the browser status.
### Important for battery powered devices
Make sure to wake up battery powered devices, so that they show up on the network.
The device has a push button inside. Open the case, press that button and the LED starts flashing.
The Shelly Button 1 needs to be connected to USB, other devices like Flood have a push button inside.
For those open the case, press that button and the LED starts flashing.
Wait a moment and then start the discovery. The device should show up in the Inbox and can be added.
Sometimes you need to run the discovery multiple times.
### Dynamic creation of channels
The Shelly series of devices has many combinations of relays, meters (different versions), sensors etc. For this the binding creates various channels dynamically based on the status information provided by the device at initialization time.
If a channel is missing make sure the thing was discovered correctly and is ONLINE. If a channel is missing delete the thing and re-discover it.
### Thing Status
The binding sets the following thing status depending on the device status:
The binding sets the following Thing status depending on the device status:
| Status |Description |
|--------------|------------------------------------------------------------------|
| INITIALIZING | This is the default status while initializing the thing. Once the initialization is triggered the thing switches to Status UNKNOWN. |
| UNKNOWN | Indicates that the status is currently unknown, which must not show a problem. Usually the thing stays in this status when the device is in sleep mode. Once the device is reachable and was initialized the thing switches to status ONLINE.|
| ONLINE | ONLINE indicates that the device can be accessed and is responding properly. Battery powered devices also stay ONLINE when in sleep mode. The binding has an integrated watchdog timer supervising the device, see below. The thing switches to status OFFLINE when some type of communication error occurs. |
| OFFLINE | Communication with the device failed. Check the thing status in the UI and openHAB's log for an indication of the error. Try restarting OH or deleting and re-discovering the thing. You could also post to the community thread if the problem stays. |
| INITIALIZING | This is the default status while initializing the Thing. Once the initialization is triggered the Thing switches to Status UNKNOWN. |
| UNKNOWN | Indicates that the status is currently unknown, which must not show a problem. Usually the Thing stays in this status when the device is in sleep mode. Once the device is reachable and was initialized the Thing switches to status ONLINE.|
| ONLINE | ONLINE indicates that the device can be accessed and is responding properly. Battery powered devices also stay ONLINE when in sleep mode. The binding has an integrated watchdog timer supervising the device, see below. The Thing switches to status OFFLINE when some type of communication error occurs. |
| OFFLINE | Communication with the device failed. Check the Thing status in the UI and openHAB's log for an indication of the error. Try restarting OH or deleting and re-discovering the Thing. You could also post to the community thread if the problem persists. |
`Battery powered devices:`
If the device is in sleep mode and can't be reached by the binding, the thing will change into UNKNOWN state.
Once the device wakes up, the thing will perform initialization and the state will change to ONLINE.
If the device is in sleep mode and can't be reached by the binding, the Thing will change into UNKNOWN state.
Once the device wakes up, the Thing will perform initialization and the state will change to ONLINE.
The first time a device is discovered and initialized successfully, the binding will be able to perform auto-initialization when OH is restarted. Waking up the device triggers the event URL and/or CoIoT packet, which is processed by the binding and triggers initialization. Once a device is initialized, it is no longer necessary to manually wake it up after an openHAB restart unless you change the battery. In this case press the button and run the discovery again.
@ -149,43 +152,14 @@ Once the timer expires the device switches to OFFFLINE and the bindings starts t
You could also create a rule to catch those status changes or device alarms (see rule examples).
## Trouble Shooting
### Network Settings
Shelly devices do only support IPv4.
This implies that the openHAB host system has IPv4 bound to the network interface.
The binding is only able to discover devices on the local subnet.
Add things manually with the given IP if you have a routed network in between or using a VPN connection.
The binding enables CoIoT protocol by default if the device is running firmware 1.6 or newer.
CoIoT is based on CoAP and uses a UDP based signaling using IP Multicast (224.0.1.187, port 5683).
Again if the device is not on the same local IP subnet you need special router/switch configurations to utilized CoAP via IP Multicast.
Otherwise disable the Auto-CoIoT feature in the binding config (not the thing config), disable CoIoT events in the thing configuration and enable sensors events (http callback).
Nevertheless in this setup the binding can communicate the device, but you are loosing the benefits of CoIoT.
Refer to openHAB's general documentation when running openHAB in a docker container. Enabling mDNS discovery has additional setup requirements.
### Re-discover when IP address has changed
Important: The IP address should not be changed after the device is added to openHAB.
This can be achieved by
- assigning a static IP address (recommended for battery powered devices) or
- using DHCP and setup the router to always assign the same IP address to the device
When the IP address changes for a device you need to delete the Thing and then re-discover the device.
In this case channel linkage gets lost and you need to re-link the channels/items.
## Thing Configuration
|Parameter |Description |Mandatory|Default |
|------------------|--------------------------------------------------------------|---------|--------------------------------------------------|
|deviceIp |IP address of the Shelly device | yes |none |
|userId |The user id used for HTTP authentication | no |none |
|password |Password for HTTP authentication* | no |none |
|password |Password for HTTP authentication | no |none |
|brightnessAutoOn |true: Output will be activated when brightness > 0 is set | no |true |
|lowBattery |Threshold for battery level. Set alert when level is below. | no |20 (=20%), only for battery powered devices |
|updateInterval |Interval for the background status check in seconds. | no |1h for battery powered devices, 60s for all others|
|eventsButton |true: register event "trigger when a button is pushed" | no |false |
@ -193,15 +167,11 @@ In this case channel linkage gets lost and you need to re-link the channels/item
|eventsSwitch |true: register event "trigger of switching the relay output" | no |true |
|eventsSensorReport|true: register event "posted updated sensor data" | no |true for sensor devices |
|eventsCoIoT |true: Listen for CoIoT/COAP events | no |true for battery devices, false for others |
|eventsRoller |true: register event "trigger" when the roller updates status | no |true for roller devices |
### General Notes
- channels `input` and `input1`/`input2` get only updated with firmware 1.5.6+.
- channel button: Short push and long push events require firmware version 1.5.6+.
- Use the channel `rollerpos` only if you need the inverted roller position, otherwise use the `control` channel with item type `Number`
- The different devices have different types of power meters, which are mapped in different sets of channels.
Every device has a channel group `device` with the following channels:
|Group |Channel |Type |read-only|Description |
@ -209,14 +179,14 @@ Every device has a channel group `device` with the following channels:
|device |deviceName |String |yes |Device name as configured in the Shelly App |
| |uptime |Number |yes |Number of seconds since the device was powered up |
| |wifiSignal |Number |yes |WiFi signal strength (4=excellent, 3=good, 2=not string, 1=unreliable, 0=none) |
| |innerTemp |Number |yes |Internal device temperature (when provided by the device) |
| |internalTemp |Number |yes |Internal device temperature (when provided by the device) |
| |selfTest |String |yes |Result from device self-test (pending/not_completed/running/completed/unknown) |
| |alarm |Trigger |yes |Self-Test result not_completed/completed/running/pending |
| |accumulatedWatts |Number |yes |Accumulated power in W of the device (including all meters) |
| |accumulatedTotal |Number |yes |Accumulated total power in kw/h of the device (including all meters) |
| |accumulatedReturned|Number |yes |Accumulated returned power in kw/h of the device (including all meters) |
| |accumulatedTotal |Number |yes |Accumulated total power in kwh of the device (including all meters) |
| |accumulatedReturned|Number |yes |Accumulated returned power in kwh of the device (including all meters) |
| |heartBeat |DateTime|yes |Timestamp of the last successful device communication |
| |updateAvailable |Switch |yes |ON: A firmware update is available (use Shelly App to perform update) |
| |updateAvailable |Switch |yes |ON: A firmware update is available |
| |statusLed |Switch |r/w |ON: Status LED is disabled, OFF: LED enabled |
| |powerLed |Switch |r/w |ON: Power LED is disabled, OFF: LED enabled |
@ -235,16 +205,16 @@ Depending on the firmware release the Shelly devices supports 2 different mechan
1. Action URLs
Usually the binding polls the device to update the status and maps the returned values to the various channels.
In addition the binding can register so-called Action URLs. Those a events triggered by the device to report special events.
In addition the binding can register so-called Action URLs. Those events are triggered by the device to report special events.
You need to disable autoCoIoT in the binding configuration to make specific selections for the Action events.
The following event types could be registered when enabled in the thing configuration:
The following event types could be registered when enabled in the Thing configuration:
|Event Type |Description |
|------------------|---------------------------------------------------------------------------------------------------------------|
|eventsButton |This event is triggered when the device is in button mode. The device reports the ON/OFF status oh the button. |
|eventsButton |This event is triggered when the device is in button mode. The device reports the ON/OFF status of the button. |
|eventsSwitch |This event reports the status of the relay output. This could change by the button or API calls. |
|eventsPush |The device reports the short/longpush events when in button mode momentary, momentary_on_release or detached. |
|eventsPush |The device reports the short/longpush events when in button mode momentary, momentary_on_release, one_button or two_button |
|eventsSensorReport|Sensor devices (like H&T) provide sensor updates when this action URL is enabled. |
Important: The binding defaults to CoIoT when firmware 1.6 or newer is detected.
@ -257,9 +227,9 @@ CoIoT provides near-realtime updates and better event support.
Firmware 1.7 adds additional status values, also supported by the binding.
Version 1.8 introduces CoIoT version 2, which fixes various issues with version 1 and provides almost all relevant status updates.
If there is no specific reason you should enable CoIoT. See Network Settings for more information.
If there is no specific reason you should enable CoIoT. Check section Network Settings [here](doc/AdvancedUsers.md) for more information.
Enable the autoCoIoT option in the binding configuration or eventsCoIoT is the thing configuration to activate CoIoT.
Enable the autoCoIoT option in the binding configuration or eventsCoIoT in the Thing configuration to activate CoIoT.
### Button events
@ -312,26 +282,23 @@ A new alarm will be triggered on a new condition or every 5 minutes if the condi
|TEMP_OVER |Above "temperature over" threshold |
```
rule "Shelly Alarm"
when
Channel "shelly:shelly1:XXXXXX:device#alarm" triggered
then
logInfo("Shelly", "n alarm condition was detected:" + receivedEvent.toString())
end
```
Refer to section [Full Example:shelly.rules](#shelly-rules) for examples how to catch alarm triggers in openHAB rules
## Channels
Depending on the device type and firmware release channels might be not available or
Depending on the device type and firmware release channels might be not available or stay with value NaN.
### Shelly 1 (thing-type: shelly1)
### Shelly 1(thing-type: shelly1)
|Group |Channel |Type |read-only|Description |
|----------|-------------|---------|---------|---------------------------------------------------------------------------------|
|relay |output |Switch |r/w |Controls the relay's output channel (on/off) |
| |input |Switch |yes |ON: Input/Button is powered, see General Notes on Channels |
| |outputName |String |yes |Logical name of this relay output as configured in the Shelly App |
| |input |Switch |yes |ON: Input/Button is powered, see general notes on channels |
| |button |Trigger |yes |Event trigger with payload, see SHORT_PRESSED or LONG_PRESSED |
| |autoOn |Number |r/w |Relay #1: Sets a timer to turn the device ON after every OFF command; in seconds|
| |autoOff |Number |r/w |Relay #1: Sets a timer to turn the device OFF after every ON command; in seconds|
| |timerActive |Switch |yes |Relay #1: ON: An auto-on/off timer is active |
|sensors |temperature1 |Number |yes |Temperature value of external sensor #1 (if connected to temp/hum addon) |
| |temperature2 |Number |yes |Temperature value of external sensor #2 (if connected to temp/hum addon) |
| |temperature3 |Number |yes |Temperature value of external sensor #3 (if connected to temp/hum addon) |
@ -342,13 +309,12 @@ Depending on the device type and firmware release channels might be not availabl
|Group |Channel |Type |read-only|Description |
|----------|-------------|---------|---------|---------------------------------------------------------------------------------|
|relay |output |Switch |r/w |Controls the relay's output channel (on/off) |
| |outputName |String |yes |Logical name of this relay output as configured in the Shelly App |
| |input |Switch |yes |ON: Input/Button is powered, see General Notes on Channels |
| |button |Trigger |yes |Event trigger with payload SHORT_PRESSED or LONG_PRESSED (FW 1.5.6+) |
| |button |Trigger |yes |Event trigger, see section Button Events |
| |outputName |String |yes |Logical name of this relay output as configured in the Shelly App |
|meter |currentWatts |Number |yes |Current power consumption in Watts |
| |lastPower1 |Number |yes |Energy consumption in Watts for a round minute, 1 minute ago |
| |lastPower2 |Number |yes |Energy consumption in Watts for a round minute, 2 minutes ago |
| |lastPower3 |Number |yes |Energy consumption in Watts for a round minute, 3 minutes ago |
| |lastPower1 |Number |yes |Energy consumption for a round minute, 1 minute ago |
| |totalKWH |Number |yes |Total energy consumption in Watts since the device powered up (resets on restart)|
| |lastUpdate |DateTime |yes |Timestamp of the last measurement |
|sensors |temperature1 |Number |yes |Temperature value of external sensor #1 (if connected to temp/hum addon) |
@ -361,18 +327,21 @@ Depending on the device type and firmware release channels might be not availabl
|Group |Channel |Type |read-only|Description |
|----------|-------------|---------|---------|---------------------------------------------------------------------------------|
|relay |output |Switch |r/w |Controls the relay's output channel (on/off) |
| |input |Switch |yes |ON: Input/Button is powered, see General Notes on Channels |
| |button |Trigger |yes |Event trigger with payload SHORT_PRESSED or LONG_PRESSED (FW 1.5.6+) |
| |outputName |String |yes |Logical name of this relay output as configured in the Shelly App |
| |input |Switch |yes |ON: Input/Button is powered, see general notes on channels |
| |button |Trigger |yes |Event trigger, see section Button Events |
| |autoOn |Number |r/w |Relay #1: Sets a timer to turn the device ON after every OFF command; in seconds|
| |autoOff |Number |r/w |Relay #1: Sets a timer to turn the device OFF after every ON command; in seconds|
| |timerActive |Switch |yes |Relay #1: ON: An auto-on/off timer is active |
|meter1 |currentWatts |Number |yes |Current power consumption in Watts |
| |totalKWH |Number |yes |Total energy consumption in Watts since the device powered up (resets on restart)|
| |returnedKWH |Number |yes |Total returned energy, kw/h |
| |returnedKWH |Number |yes |Total returned energy, kwh |
| |reactiveWatts|Number |yes |Instantaneous reactive power, Watts |
| |voltage |Number |yes |RMS voltage, Volts |
| |lastUpdate |DateTime |yes |Timestamp of the last measurement |
|meter2 |currentWatts |Number |yes |Current power consumption in Watts |
| |totalKWH |Number |yes |Total energy consumption in Watts since the device powered up (resets on restart)|
| |returnedKWH |Number |yes |Total returned energy, kw/h |
| |returnedKWH |Number |yes |Total returned energy, kwh |
| |reactiveWatts|Number |yes |Instantaneous reactive power, Watts |
| |voltage |Number |yes |RMS voltage, Volts |
| |lastUpdate |DateTime |yes |Timestamp of the last measurement |
@ -380,17 +349,20 @@ Depending on the device type and firmware release channels might be not availabl
### Shelly 3EM (thing-type: shellyem3)
Please note: The product is called Shelly 3EM whereas the device propagates the service under shellyem3.
The thing id is derived from the service name, so that's the reason why the thing is named shelly**em3** and not shelly3em.
The Thing id is derived from the service name, so that's the reason why the Thing is named shelly**em3** and not shelly3em.
|Group |Channel |Type |read-only|Description |
|----------|-------------|---------|---------|---------------------------------------------------------------------------------|
|relay |output |Switch |r/w |Controls the relay's output channel (on/off) |
| |input |Switch |yes |ON: Input/Button is powered, see General Notes on Channels |
| |button |Trigger |yes |Event trigger with payload SHORT_PRESSED or LONG_PRESSED (FW 1.5.6+) |
| |outputName |String |yes |Logical name of this relay output as configured in the Shelly App |
| |input |Switch |yes |ON: Input/Button is powered, see general notes on channels |
| |button |Trigger |yes |Event trigger, see section Button Events |
| |autoOn |Number |r/w |Relay #1: Sets a timer to turn the device ON after every OFF command; in seconds|
| |autoOff |Number |r/w |Relay #1: Sets a timer to turn the device OFF after every ON command; in seconds|
| |timerActive |Switch |yes |Relay #1: ON: An auto-on/off timer is active |
|meter1 |currentWatts |Number |yes |Current power consumption in Watts |
| |totalKWH |Number |yes |Total energy consumption in Watts since the device powered up (resets on restart)|
| |returnedKWH |Number |yes |Total returned energy, kw/h |
| |returnedKWH |Number |yes |Total returned energy, kwh |
| |reactiveWatts|Number |yes |Instantaneous reactive power, Watts |
| |voltage |Number |yes |RMS voltage, Volts |
| |current |Number |yes |Current in A |
@ -398,7 +370,7 @@ The thing id is derived from the service name, so that's the reason why the thin
| |lastUpdate |DateTime |yes |Timestamp of the last measurement |
|meter2 |currentWatts |Number |yes |Current power consumption in Watts |
| |totalKWH |Number |yes |Total energy consumption in Watts since the device powered up (resets on restart)|
| |returnedKWH |Number |yes |Total returned energy, kw/h |
| |returnedKWH |Number |yes |Total returned energy, kwh |
| |reactiveWatts|Number |yes |Instantaneous reactive power, Watts |
| |voltage |Number |yes |RMS voltage, Volts |
| |current |Number |yes |Current in A |
@ -406,7 +378,7 @@ The thing id is derived from the service name, so that's the reason why the thin
| |lastUpdate |DateTime |yes |Timestamp of the last measurement |
|meter3 |currentWatts |Number |yes |Current power consumption in Watts |
| |totalKWH |Number |yes |Total energy consumption in Watts since the device powered up (resets on restart)|
| |returnedKWH |Number |yes |Total returned energy, kw/h |
| |returnedKWH |Number |yes |Total returned energy, kwh |
| |reactiveWatts|Number |yes |Instantaneous reactive power, Watts |
| |voltage |Number |yes |RMS voltage, Volts |
| |current |Number |yes |Current in A |
@ -419,21 +391,23 @@ The thing id is derived from the service name, so that's the reason why the thin
|Group |Channel |Type |read-only|Description |
|----------|-------------|---------|---------|---------------------------------------------------------------------------------|
|relay1 |output |Switch |r/w |Relay #1: Controls the relay's output channel (on/off) |
| |outputName |String |yes |Logical name of this relay output as configured in the Shelly App |
| |input |Switch |yes |ON: Input/Button is powered, see General Notes on Channels |
| |autoOn |Number |r/w |Relay #1: Sets a timer to turn the device ON after every OFF command; in seconds|
| |autoOff |Number |r/w |Relay #1: Sets a timer to turn the device OFF after every ON command; in seconds|
| |timerActive |Switch |yes |Relay #1: ON: An auto-on/off timer is active |
| |button |Trigger |yes |Event trigger with payload SHORT_PRESSED or LONG_PRESSED (FW 1.5.6+) |
| |button |Trigger |yes |Event trigger, see section Button Events |
| |outputName |String |yes |Logical name of this relay output as configured in the Shelly App |
|relay2 |output |Switch |r/w |Relay #2: Controls the relay's output channel (on/off) |
| |outputName |String |yes |Logical name of this relay output as configured in the Shelly App |
| |input |Switch |yes |ON: Input/Button is powered, see General Notes on Channels |
| |autoOn |Number |r/w |Relay #2: Sets a timer to turn the device ON after every OFF command; in seconds|
| |autoOff |Number |r/w |Relay #2: Sets a timer to turn the device OFF after every ON command; in seconds|
| |timerActive |Switch |yes |Relay #2: ON: An auto-on/off timer is active |
| |button |Trigger |yes |Event trigger with payload SHORT_PRESSED or LONG_PRESSED (FW 1.5.6+) |
| |button |Trigger |yes |Event trigger, see section Button Events |
| |outputName |String |yes |Logical name of this relay output as configured in the Shelly App |
|meter |currentWatts |Number |yes |Current power consumption in Watts |
| |lastPower1 |Number |yes |Energy consumption in Watts for a round minute, 1 minute ago |
| |lastPower1 |Number |yes |Energy consumption for a round minute, 1 minute ago |
| |totalKWH |Number |yes |Total energy consumption in Watts since the device powered up (resets on restart)|
| |lastUpdate |DateTime |yes |Timestamp of the last measurement |
@ -443,20 +417,25 @@ The thing id is derived from the service name, so that's the reason why the thin
|----------|-------------|---------|---------|--------------------------------------------------------------------------------------|
|roller |control |Rollershutter|r/w |can be open (0%), stop, or close (100%); could also handle ON (open) and OFF (close) |
| |input |Switch |yes |ON: Input/Button is powered, see General Notes on Channels |
| |event |Trigger |yes |Roller event/trigger with payload ROLLER_OPEN / ROLLER_CLOSE / ROLLER_STOP |
| |rollerpos |Number |r/w |Roller position: 100%=open...0%=closed; gets updated when the roller stops, see Notes |
| |state |String |yes |Roller state: open/close/stop |
| |stopReason |String |yes |Last stop reasons: normal, safety_switch or obstacle |
| |event |Trigger |yes |Roller event/trigger with payload ROLLER_OPEN / ROLLER_CLOSE / ROLLER_STOP |
| |safety |Switch |yes |Indicates status of the Safety Switch, ON=problem detected, powered off |
|meter |currentWatts |Number |yes |Current power consumption in Watts |
| |lastPower1 |Number |yes |Accumulated energy consumption in Watts for the full last minute |
| |totalKWH |Number |yes |Total energy consumption in Watts since the device powered up (reset on restart) |
| |lastUpdate |DateTime |yes |Timestamp of the last measurement |
The roller positioning calibration has to be performed using the Shelly App before the position can be set in percent.
The roller positioning calibration has to be performed using the Shelly App before the position can be set in percent.
Refer to [Smartify Roller Shutters with openHAB and Shelly](doc/UseCaseSmartRoller.md) for more information on roller integration.
### Shelly 2.5 - relay mode (thing-type:shelly25-relay)
The Shelly 2.5 includes 2 meters, one for each channel.
Firmware 1.9.2 or newer is required to use the roller position favorites, which are defined in the Shelly App.
|Group |Channel |Type |read-only|Description |
|----------|-------------|---------|---------|---------------------------------------------------------------------------------|
@ -478,11 +457,15 @@ For this the binding aggregates the power consumption of both relays and include
| |input |Switch |yes |ON: Input/Button is powered, see General Notes on Channels |
| |state |String |yes |Roller state: open/close/stop |
| |stopReason |String |yes |Last stop reasons: normal, safety_switch or obstacle |
| |safety |Switch |yes |Indicates status of the Safety Switch, ON=problem detected, powered off |
| |event |Trigger |yes |Roller event/trigger with payload ROLLER_OPEN / ROLLER_CLOSE / ROLLER_STOP |
|meter | | | |See group meter1 for Shelly 2 |
|meter1 | | | |See group meter1 for Shelly 2 |
|meter2 | | | |See group meter1 for Shelly 2 |
The roller positioning calibration has to be performed using the Shelly App before the position can be set in percent.
Refer to [Smartify Roller Shutters with openHAB and Shelly](doc/UseCaseSmartRoller.md) for more information on roller integration.
### Shelly4 Pro (thing-type: shelly4pro)
The Shelly 4Pro provides 4 relays and 4 power meters.
@ -505,43 +488,29 @@ The Shelly 4Pro provides 4 relays and 4 power meters.
|relay | | | |See group relay1 for Shelly 2 |
|meter | | | |See group meter1 for Shelly 2 |
### Shelly Dimmer (thing-type: shellydimmer)
### Shelly Dimmer 1 + 2 (thing-type: shellydimmer, shellydimmer2)
|Group |Channel |Type |read-only|Description |
|----------|-------------|---------|---------|---------------------------------------------------------------------------------|
|relay |brightness |Dimmer |r/w |Currently selected brightness. |
| |input1 |Switch |yes |State of Input 1 (S1) |
| |input2 |Switch |yes |State of Input 2 (S2) |
| |autoOn |Number |r/w |Sets a timer to turn the device ON after every OFF command; in seconds |
| |autoOff |Number |r/w |Sets a timer to turn the device OFF after every ON command; in seconds |
| |button |Trigger |yes |Event trigger with payload SHORT_PRESSED or LONG_PRESSED (FW 1.5.6+) |
| |outputName |String |yes |Logical name of this relay output as configured in the Shelly App |
| |input1 |Switch |yes |ON: Input/Button for input 1 is powered, see general notes on channels |
| |input2 |Switch |yes |ON: Input/Button for input 1 is powered, see general notes on channels |
| |button |Trigger |yes |Event trigger, see section Button Events |
| |autoOn |Number |r/w |Relay #1: Sets a timer to turn the device ON after every OFF command; in seconds|
| |autoOff |Number |r/w |Relay #1: Sets a timer to turn the device OFF after every ON command; in seconds|
| |timerActive |Switch |yes |Relay #1: ON: An auto-on/off timer is active |
|meter |currentWatts |Number |yes |Current power consumption in Watts |
| |lastPower1 |Number |yes |Energy consumption in Watts for a round minute, 1 minute ago |
| |lastPower2 |Number |yes |Energy consumption in Watts for a round minute, 2 minutes ago |
| |lastPower3 |Number |yes |Energy consumption in Watts for a round minute, 3 minutes ago |
| |lastPower1 |Number |yes |Energy consumption for a round minute, 1 minute ago |
| |totalKWH |Number |yes |Total energy consumption in Watts since the device powered up (resets on restart)|
| |lastUpdate |DateTime |yes |Timestamp of the last measurement |
### Shelly Dimmer2 (thing-type: shellydimmer2)
|Group |Channel |Type |read-only|Description |
|----------|-------------|---------|---------|---------------------------------------------------------------------------------|
|relay |brightness |Dimmer |r/w |Currently selected brightness. |
| |input1 |Switch |yes |State of Input 1 (S1) |
| |input2 |Switch |yes |State of Input 2 (S2) |
| |autoOn |Number |r/w |Sets a timer to turn the device ON after every OFF command; in seconds |
| |autoOff |Number |r/w |Sets a timer to turn the device OFF after every ON command; in seconds |
| |button |Trigger |yes |Event trigger with payload SHORT_PRESSED or LONG_PRESSED (FW 1.5.6+) |
| |outputName |String |yes |Logical name of this relay output as configured in the Shelly App |
|meter |currentWatts |Number |yes |Current power consumption in Watts |
| |lastPower1 |Number |yes |Energy consumption in Watts for a round minute, 1 minute ago |
| |lastPower2 |Number |yes |Energy consumption in Watts for a round minute, 2 minutes ago |
| |lastPower3 |Number |yes |Energy consumption in Watts for a round minute, 3 minutes ago |
| |totalKWH |Number |yes |Total energy consumption in Watts since the device powered up (resets on restart)|
| |lastUpdate |DateTime |yes |Timestamp of the last measurement |
`Note: The Dimmer should be calibrated using the Shelly App.`
The Dimmer should be calibrated using the Shelly App.
Using the Thing configuration option `brightnessAutoOn` you could decide if the light is turned on when a brightness > 0 is set.
`true`: Brightness will be set and device output is powered = light turns on with the new brightness
`false`: Brightness will be set, but output stays unchanged so light will not be switched on when it's currently off.
### Shelly ix3 (thing-type: shellyix3)
@ -550,7 +519,7 @@ The Dimmer should be calibrated using the Shelly App.
|status |input1 |Switch |yes |State of Input 1 |
| |input2 |Switch |yes |State of Input 2 |
| |input3 |Switch |yes |State of Input 3 |
| |button |Trigger |yes |Event trigger: SHORT_PRESSED, DOUBLE_PRESSED, TRIPLE_PRESSED, LONG_PRESSED, SHORT_LONG_PRESSED or LONG_SHORT_PRESSED |
| |button |Trigger |yes |Event trigger: Event trigger, see section Button Events |
| |lastEvent |String |yes |S/SS/SSS for 1/2/3x Shortpush or L for Longpush |
| |eventCount |Number |yes |Number of button events |
@ -568,9 +537,9 @@ The Dimmer should be calibrated using the Shelly App.
| |full |String |r/w |Set Red / Green / Blue / Yellow / White mode and switch mode |
| | | |r/w |Valid settings: "red", "green", "blue", "yellow", "white" or "r,g,b,w" |
| |red |Dimmer |r/w |Red brightness: 0..100% or 0..255 (control only the red channel) |
| |green |Dimmer |r/w |Green brightness: 0..100% or 0..255 (control only the red channel) |
| |blue |Dimmer |r/w |Blue brightness: 0..100% or 0..255 (control only the red channel) |
| |white |Dimmer |r/w |White brightness: 0..100% or 0..255 (control only the red channel) |
| |green |Dimmer |r/w |Green brightness: 0..100% or 0..255 (control only the green channel) |
| |blue |Dimmer |r/w |Blue brightness: 0..100% or 0..255 (control only the blue channel) |
| |white |Dimmer |r/w |White brightness: 0..100% or 0..255 (control only the white channel) |
| |gain |Dimmer |r/w |Gain setting: 0..100% or 0..100 |
| |effect |Number |r/w |Puts the light into effect mode: 0..6) |
| | | | | 0=No effect, 1=Meteor Shows, 2=Gradual Change, 3=Breath |
@ -589,12 +558,10 @@ The Dimmer should be calibrated using the Shelly App.
|white | | | |Color settings: only valid in WHITE mode |
| |temperature |Number |r/w |color temperature (K): 0..100% or 2700..6500 |
| |brightness |Dimmer | |Brightness: 0..100% or 0..100 |
|meter |currentWatts |Number |yes |Current power consumption in Watts |
| |lastPower1 |Number |yes |Energy consumption in Watts for a round minute, 1 minute ago |
| |lastPower2 |Number |yes |Energy consumption in Watts for a round minute, 2 minutes ago |
| |lastPower3 |Number |yes |Energy consumption in Watts for a round minute, 3 minutes ago |
|meter |currentWatts |Number |yes |Current power consumption in Watts |
| |lastPower1 |Number |yes |Energy consumption in Watts for a round minute, 1 minute ago |
| |totalKWH |Number |yes |Total energy consumption in Watts since the device powered up (resets on restart)|
| |lastUpdate |DateTime |yes |Timestamp of the last measurement |
| |lastUpdate |DateTime |yes |Timestamp of the last measurement |
#### Shelly Vintage (thing-type: shellyvintage)
@ -602,15 +569,13 @@ The Dimmer should be calibrated using the Shelly App.
|----------|-------------|---------|---------|-----------------------------------------------------------------------|
|control |autoOn |Number |r/w |Sets a timer to turn the device ON after every OFF; in sec |
| |autoOff |Number |r/w |Sets a timer to turn the device OFF after every ON: in sec |
| |timerActive |Switch |yes |ON: An auto-on/off timer is active |
| |timerActive |Switch |yes |ON: An auto-on/off timer is active |
|white | | | |Color settings: only valid in WHITE mode |
| |brightness |Dimmer | |Brightness: 0..100% or 0..100 |
|meter |currentWatts |Number |yes |Current power consumption in Watts |
| |lastPower1 |Number |yes |Energy consumption in Watts for a round minute, 1 minute ago |
| |lastPower2 |Number |yes |Energy consumption in Watts for a round minute, 2 minutes ago |
| |lastPower3 |Number |yes |Energy consumption in Watts for a round minute, 3 minutes ago |
|meter |currentWatts |Number |yes |Current power consumption in Watts |
| |lastPower1 |Number |yes |Energy consumption for a round minute, 1 minute ago |
| |totalKWH |Number |yes |Total energy consumption in Watts since the device powered up (resets on restart)|
| |lastUpdate |DateTime |yes |Timestamp of the last measurement |
| |lastUpdate |DateTime |yes |Timestamp of the last measurement |
## Shelly RGBW2 in Color Mode (thing-type: shellyrgbw2-color)
@ -618,7 +583,7 @@ The Dimmer should be calibrated using the Shelly App.
|Group |Channel |Type |read-only|Description |
|----------|-------------|---------|---------|-----------------------------------------------------------------------|
|control |power |Switch |r/w |Switch light ON/OFF |
| |button |Trigger |yes |Event trigger with payload SHORT_PRESSED or LONG_PRESSED (FW 1.5.6+) |
| |button |Trigger |yes |Event trigger, see section Button Events |
| |autoOn |Number |r/w |Sets a timer to turn the device ON after every OFF command; in seconds|
| |autoOff |Number |r/w |Sets a timer to turn the device OFF after every ON command; in seconds|
| |timerActive |Switch |yes |ON: An auto-on/off timer is active |
@ -627,36 +592,40 @@ The Dimmer should be calibrated using the Shelly App.
| |full |String |r/w |Set Red / Green / Blue / Yellow / White mode and switch mode |
| | | |r/w |Valid settings: "red", "green", "blue", "yellow", "white" or "r,g,b,w" |
| |red |Dimmer |r/w |Red brightness: 0..100% or 0..255 (control only the red channel) |
| |green |Dimmer |r/w |Green brightness: 0..100% or 0..255 (control only the red channel) |
| |blue |Dimmer |r/w |Blue brightness: 0..100% or 0..255 (control only the red channel) |
| |white |Dimmer |r/w |White brightness: 0..100% or 0..255 (control only the red channel) |
| |green |Dimmer |r/w |Green brightness: 0..100% or 0..255 (control only the green channel) |
| |blue |Dimmer |r/w |Blue brightness: 0..100% or 0..255 (control only the blue channel) |
| |white |Dimmer |r/w |White brightness: 0..100% or 0..255 (control only the white channel) |
| |gain |Dimmer |r/w |Gain setting: 0..100% or 0..100 |
| |effect |Number |r/w |Puts the light into effect mode: 0..3) |
| | | | |0=No effect, 1=Meteor Shower, 2=Gradual Change, 3=Flash |
|meter |currentWatts |Number |yes |Current power consumption in Watts |
Using the Thing configuration option `brightnessAutoOn` you could decide if the light is turned on when a brightness > 0 is set.
`true`: Brightness will be set and device output is powered = light turns on with the new brightness
`false`: Brightness will be set, but output stays unchanged so light will not be switched on when it's currently off.
### Shelly RGBW2 in White Mode (thing-type: shellyrgbw2-white)
|Group |Channel |Type |read-only|Description |
|----------|-------------|---------|---------|-----------------------------------------------------------------------|
|control |input |Switch |yes |State of Input |
|channel1 |brightness |Dimmer |r/w |Channel 1: Brightness: 0..100, control power state with ON/OFF |
| |button |Trigger |yes |Event trigger with payload SHORT_PRESSED or LONG_PRESSED (FW 1.5.6+) |
| |button |Trigger |yes |Event trigger, see section Button Events |
| |autoOn |Number |r/w |Sets a timer to turn the device ON after every OFF command; in seconds|
| |autoOff |Number |r/w |Sets a timer to turn the device OFF after every ON command; in seconds|
| |timerActive |Switch |yes |ON: An auto-on/off timer is active |
|channel2 |brightness |Dimmer |r/w |Channel 2: Brightness: 0..100, control power state with ON/OFF |
| |button |Trigger |yes |Event trigger with payload SHORT_PRESSED or LONG_PRESSED (FW 1.5.6+) |
| |button |Trigger |yes |Event trigger, see section Button Events |
| |autoOn |Number |r/w |Sets a timer to turn the device ON after every OFF command; in seconds|
| |autoOff |Number |r/w |Sets a timer to turn the device OFF after every ON command; in seconds|
| |timerActive |Switch |yes |ON: An auto-on/off timer is active |
|channel3 |brightness |Dimmer |r/w |Channel 3: Brightness: 0..100, control power state with ON/OFF |
| |button |Trigger |yes |Event trigger with payload SHORT_PRESSED or LONG_PRESSED (FW 1.5.6+) |
| |button |Trigger |yes |Event trigger, see section Button Events |
| |autoOn |Number |r/w |Sets a timer to turn the device ON after every OFF command; in seconds|
| |autoOff |Number |r/w |Sets a timer to turn the device OFF after every ON command; in seconds|
| |timerActive |Switch |yes |ON: An auto-on/off timer is active |
|channel4 |brightness |Dimmer |r/w |Channel 5: Brightness: 0..100, control power state with ON/OFF |
| |button |Trigger |yes |Event trigger with payload SHORT_PRESSED or LONG_PRESSED (FW 1.5.6+) |
| |button |Trigger |yes |Event trigger, see section Button Events |
| |autoOn |Number |r/w |Sets a timer to turn the device ON after every OFF command; in seconds|
| |autoOff |Number |r/w |Sets a timer to turn the device OFF after every ON command; in seconds|
| |timerActive |Switch |yes |ON: An auto-on/off timer is active |
@ -685,7 +654,6 @@ You can define 2 items (1 Switch, 1 Number) mapping to the same channel, see exa
| |charger |Number |yes |ON: USB charging cable is |
| |lastUpdate |DateTime |yes |Timestamp of the last update (any sensor value changed) |
|battery |batteryLevel |Number |yes |Battery Level in % |
| |voltage |Number |yes |Voltage of the battery |
| |lowBattery |Switch |yes |Low battery alert (< 20%) |
### Shelly Flood (thing type: shellyflood)
@ -696,7 +664,6 @@ You can define 2 items (1 Switch, 1 Number) mapping to the same channel, see exa
| |flood |Switch |yes |ON: Flooding condition detected, OFF: no flooding |
| |lastUpdate |DateTime |yes |Timestamp of the last update (any sensor value changed) |
|battery |batteryLevel |Number |yes |Battery Level in % |
| |voltage |Number |yes |Voltage of the battery |
| |lowBattery |Switch |yes |Low battery alert (< 20%) |
### Shelly Door/Window (thing type: shellydw)
@ -706,12 +673,11 @@ You can define 2 items (1 Switch, 1 Number) mapping to the same channel, see exa
|sensors |state |Contact |yes |OPEN: Contact is open, CLOSED: Contact is closed |
| |lux |Number |yes |Brightness in Lux |
| |illumination |String |yes |Current illumination: dark/twilight/bright |
| |titl |Number |yes |Tilt in ° (angle), -1 indicates that the sensor is not calibrated |
| |tilt |Number |yes |Tilt in ° (angle), -1 indicates that the sensor is not calibrated |
| |vibration |Switch |yes |ON: Vibration detected |
| |lastUpdate |DateTime |yes |Timestamp of the last update (any sensor value changed) |
| |lastError |String |yes |Last device error. |
|battery |batteryLevel |Number |yes |Battery Level in % |
| |voltage |Number |yes |Voltage of the battery |
| |lowBattery |Switch |yes |Low battery alert (< 20%) |
### Shelly Button 1 (thing type: shellybutton1)
@ -724,7 +690,6 @@ You can define 2 items (1 Switch, 1 Number) mapping to the same channel, see exa
| |button |Trigger |yes |Event trigger with payload SHORT_PRESSED, DOUBLE_PRESSED... |
| |lastUpdate |DateTime |yes |Timestamp of the last update (any value changed) |
|battery |batteryLevel |Number |yes |Battery Level in % |
| |voltage |Number |yes |Voltage of the battery |
| |lowBattery |Switch |yes |Low battery alert (< 20%) |
You should calibrate the sensor using the Shelly App to get information on the tilt status.
@ -738,7 +703,6 @@ You should calibrate the sensor using the Shelly App to get information on the t
| |lastUpdate |DateTime |yes |Timestamp of the last update (any sensor value changed) |
| |lastError |String |yes |Last device error. |
|battery |batteryLevel |Number |yes |Battery Level in % |
| |voltage |Number |yes |Voltage of the battery |
| |lowBattery |Switch |yes |Low battery alert (< 20%) |
### Shelly Smoke(thing type: shellygas)
@ -756,7 +720,7 @@ You should calibrate the sensor using the Shelly App to get information on the t
|----------|-------------|---------|---------|-----------------------------------------------------------------------|
|control |key |String |r/w |Send a IR key to the sense. There a 3 different types supported |
| | | | |Stored key: send the key code defined by the App , e.g. 123_1_up |
| | | | |Pronto hex: send a Pronto Code in ex format, e.g. 0000 006C 0022 ... |
| | | | |Pronto hex: send a Pronto Code in hex format, e.g. 0000 006C 0022 ... |
| | | | |Pronto base64: in base64 format, will be send 1:1 to the Sense |
| |motionTime |Number |r/w |Define the number of seconds when the Sense should report motion |
| |motionLED |Switch |r/w |Control the motion LED: ON when motion is detected or OFF |
@ -764,7 +728,7 @@ You should calibrate the sensor using the Shelly App to get information on the t
|sensors |temperature |Number |yes |Temperature in °C |
| |humidity |Number |yes |Relative humidity in % |
| |lux |Number |yes |Brightness in Lux |
| |motion |Switch |yes |ON: Motion detected, OFF: No motion (check also motionTimer) |
| |motion |Switch |yes |ON: Motion detected, OFF: No motion (check also motionTime) |
| |lastUpdate |DateTime |yes |Timestamp of the last update (any sensor value changed) |
|battery |batteryLevel |Number |yes |Battery Level in % |
| |batteryAlert |Switch |yes |Low battery alert |
@ -823,7 +787,132 @@ Number Shelly_Power "Bath Room Light Power" {channel="shelly:
### shelly.rules
reading colors from color picker:
#### Catch alarms
```
rule "Monitor Shelly Restart"
when
Channel "shelly:shelly2-relay:XXXXXX:device#alarm" triggered OVERTEMP
then
logInfo("Shelly1", "Device is getting to hot!!")
end
```
#### Trigger scene with Button-1
```
rule "Button-1 SHORT_PRESSED"
when
Channel "shelly:shellybutton1:d8f15bXXXXXX:status#button" triggered SHORT_PRESSED
then
logInfo("Button", "Shelly Button reported SHORT_PRESSED")
if (MyTV.state != OFF) {
logInfo("Button", " switch TV OFF")
sendCommand(MyTV, "OFF")
} else {
logInfo("Button", " switch TV to ON")
sendCommand(MyTV, ON)
}
end
rule "Button-1 TRIPLE_PRESSED"
when
Channel "shelly:shellybutton1:d8f15bXXXXXX:status#button" triggered TRIPLE_PRESSED
then
logInfo("Button", "Shelly Button reported TRIPLE_PRESSED")
end
```
#### Observe battery status
pre-requisites:
- Install Send Mail Action
- Define a group called gBatteries
'Group gBattery "Batterien" <battery> (All)'
- Link battery channel for all your Shelly battery powered devices
- Add battery items to group gBattery
```
val String mailTo = "alarm@openhab.me"
/* ------------- Battery Monitor ----------- */
rule "Battery Monitor"
when
System started or
Time cron "0 0 10 * * ?"
then
logInfo("BatteryMon", "Check Battery state")
if (! gBattery.allMembers.filter([state < lowBatteryThreshold]).empty) {
message = "Battery levels:\n"
var report = gBattery.allMembers.filter([ state instanceof DecimalType ]).sortBy([ state instanceof DecimalType ]).map[
name + ": " + state.format("%d%%\n") ]
message = message + report
message = message + "\nBattery Level:\n"
gBattery?.allMembers.forEach([sw|
message = message + sw.name + ": " + state.format("%d%%\n")
])
sendMail(mailTo, "Home: LOW Battery Alert!", message)
}
logInfo("BatteryMon", "Batteries checked.")
end
```
#### Control CCT LED stripes
Usage & Requirements:
- 4 Items per Thing required. Example:
```
Group gCCT_LED "All CCT LEDs"
Dimmer LED1_brightness "Brightness" (gCCT_LED)
Dimmer LED1_temperature "Temperature" (gCCT_LED)
Dimmer LED1_cw "cold white Channel"
Dimmer LED1_ww "warm white Channel"
```
- Items "LED1" and "LED1_temperature" are proxy items and to be used in sitemaps. Both have to be a member of group "gCCT_LED"
- Items "LED1_cw" and "LED_ww" are items linked to Thing channel. Not required in sitemaps. Do NOT include in this group
- Prefix: needs to be constant per Thing.
```
val String strSuffixSeparator = "_" //Separator: 1 unique separator
val String strSuffixBrightness = "brightness" //Suffix: at your choice
val String strSuffixTemperature = "temperature" //Suffix: at your choice
rule "CCT_LED"
when
Member of gCCT_LED changed
then
logInfo("CCT_LED", "Item '{}' received command {}",triggeringItem.name,triggeringItem.state)
var Number iNewCwState //New value for cold white channel
var Number iNewWwState //New value for warm white channel
val String strThing = triggeringItem.name.toString.split(strSuffixSeparator).get(0) //Get Name of "Thing", i.e. LED1 or LED2 or...
val String strType = triggeringItem.name.toString.split(strSuffixSeparator).get(1) //Get Type (brightness oder temperature)
if ((strType == strSuffixBrightness) && (triggeringItem.state as Number) == 0) { //no math required. just switch off
iNewCwState = 0
iNewWwState = 0
}
else {
var iBrightness = gCCT_LED.members.findFirst[ t | t.name == strThing+strSuffixSeparator+strSuffixBrightness ].state as Number
var iColor = gCCT_LED.members.findFirst[ t | t.name == strThing+strSuffixSeparator+strSuffixTemperature ].state as Number
logInfo("CCT_LED", "Setting 'Brightness' to {} and 'White Color' to {}",iBrightness,iColor)
iNewWwState = Math::round ((iColor / 100 * iBrightness).intValue)
iNewCwState = iBrightness - iNewWwState
}
logInfo("CCT_LED", "Changing channel 'Cold White' to {} and 'Warm White' to {}",iNewCwState,iNewWwState)
sendCommand(strThing + "_cw", iNewCwState.toString)
sendCommand(strThing + "_ww", iNewWwState.toString)
end
```
#### Reading colors from Color Picker:
```
import org.openhab.core.library.types.*

110
bundles/org.openhab.binding.shelly/doc/AdvancedUsers.md Normal file
View File

@ -0,0 +1,110 @@
# Advanced Users
This section provides information for advanced use cases.
## Additiona Resources
There are additional resources available providing more information on Shelly devices and how to integrate those into openHAB:
- [Shelly Homepage](https://shelly.cloud)
- [Shelly Support Group (English)](https://www.facebook.com/groups/ShellyIoTCommunitySupport)
- [Firmware Archive](http://archive.shelly-faq.de)
- [API Documentation](https://shelly-api-docs.shelly.cloud/?fbclid=IwAR23ukCi_3aBSTPRHYUIcpr0pLi0vcyL0fF0PnJQdFvkkc8_Zo5LkAcli_A#http-server)
and the [openHAB Community thread specifically for the binding](https://community.openhab.org/t/shelly-binding) - any feedback welcome here.
You could also [report a bug or request a feature](https://github.com/openhab/openhab-addons/issues?q=is%3Aissue+is%3Aopen+%5Bshelly%5D) for the Shelly Binding.
## Firmware Upgrade
The Shelly App usually displays the installed firmware and also provide the function to upgrade the device with new firmware.
However, if this doesn't work (sometimes there are issues) you could use the [Shelly Firmware Archi Link Generator](http://archive.shelly-faq.de), which provides download links to current, but also archived firmware files for all devices.
|Version|Notes |
|-------|--------------------------------------------------------------------------------------------------|
|1.5.7 |Minimum supported version. Older versions work in general, but have impacts to functionality (e.g. no events for battery powered devices). The binding displays a WARNING in the log if the firmware is older.|
|1.6.x |First stable CoIoT implementation. AutoCoIoT is enabled when firmware version >= 1.6 is detected. |
|1.7.x |Add additional status update values, fixes various issues |
|1.8.0 |Brings CoIoT version 2, which fixes a lot issues and gaps of version 1. |
|1.9.2 |Various improvements, roller favorites, CoAP fixes |
There are 3 options available to perform the upgrade
- The Shelly App usually detects when a new version becomes available and offers to do the upgrade within the UI (Web or App)
- Alterco provides the [Shelly Firmware Archive Link Generator](http://archive.shelly-faq.de).
This can be used to generate the upgrade link, which could be easily used to perform the upgrade on the cli-level having an Internet connection on that terminal (Shelly device doesn't require an Internet access).
You specify the device's IP and device model SHSW-25 and the page will generate you the link for the firmware download using the OTA of the device.
Then you run "curl -s [-u user:password] &gt;generated link&gt;" from the terminal.
This should show a JSON result, make sure that it shows "status:updating".
Wait 15sec and access the device's Web UI, go to Settings:Firmware Upgrade and make sure than the new version was installed successful.
- Manual download and installation of the firmware
Manually pick the download link from the [Shelly Firmware Repository](https://api.shelly.cloud/files/firmware) and get the release or beta link.
Once you downloaded the file you need to copy it to an http server.
Open the following url http://&lt;shelly ip&gt;/ota?url=http://&lt;web server&gt;/&lt;path&gt;/&lt;zip-file&gt;
Again, make sure that the file is downloaded and installed properly.
## Trouble Shooting
### Network Settings
Shelly devices do only support IPv4.
This implies that the openHAB host system has IPv4 bound to the network interface.
The binding is only able to discover devices on the local subnet.
Add things manually with the given IP if you have a routed network in between or using a VPN connection.
The binding enables CoIoT protocol by default if the device is running firmware 1.6 or newer.
CoIoT is based on CoAP and uses a UDP based signaling using IP Multicast (224.0.1.187, port 5683).
Again if the device is not on the same local IP subnet you need special router/switch configurations to utilized CoAP via IP Multicast.
Otherwise disable the Auto-CoIoT feature in the binding config (not the thing config), disable CoIoT events in the thing configuration and enable sensors events (http callback).
Nevertheless in this setup the binding can communicate the device, but you are loosing the benefits of CoIoT.
Refer to openHAB's general documentation when running openHAB in a docker container. Enabling mDNS discovery has additional setup requirements.
### Re-discover when IP address has changed
Important: The IP address should not be changed after the device is added to openHAB.
This can be achieved by
- assigning a static IP address (recommended for battery powered devices) or
- using DHCP and setup the router to always assign the same IP address to the device
When the IP address changes for a device you need to delete the Thing and then re-discover the device.
In this case channel linkage gets lost and you need to re-link the channels/items.
## Log optimization
The binding provides channels (e.g. heartBeat, currentWatts), which might cause a lot of log output, especially when having multiple dozen Shellys.
openHAB has an integrated feature to filter the event log.
This mechanism doesn't filter the event, but the output is not written to the log file (items still receive the updates).
The configuration has to be added to the log configuration file, which is different to openHAB 2.5.x and 3.x (see below).
The example filters events for items `heartBeat`, `lastUpdate`, `LetzteAktualisierung`, `Uptime`, `Laufzeit`, `ZuletztGesehen`
Replace those strings with the items you want to filter.
Use a list of items to reduce logging.
`Please note:` Once events are filtered they are not show anymore in the logfile, you can’t find them later.
The configuration format of openHAB 3 is in xml format.
- Open the file `userdata/etc/log4j2.xml`
- Search for tag 'RollingFile'
- and add a tag `<RegexFilter>...</RegExFilter>`
The attribute `regex` of this tag defines the regular expression, `onMatch="DENY"` the the logger to discard those lines
Example:
```
...
<!-- Rolling file appender -->
<RollingFile fileName="${sys:openhab.logdir}/openhab.log" filePattern="${sys:openhab.logdir}/openhab.log.%i" name="LOGFILE">
<PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} [%-5.5p] [%-36.36c] - %m%n"/>
<RegexFilter regex=".*(heartBeat|LastUpdate|lastUpdate|LetzteAktualisierung|Uptime|Laufzeit|ZuletztGesehen).*" onMatch="DENY" onMismatch="ACCEPT"/>
<Policies>
<SizeBasedTriggeringPolicy size="16 MB"/>
</Policies>
</RollingFile>
...
```

227
bundles/org.openhab.binding.shelly/doc/UseCaseSmartRoller.md Normal file
View File

@ -0,0 +1,227 @@
# Smartify Roller Shutters with openHAB and Shelly
![](https://shelly.cloud/wp-content/uploads/2020/03/know_base.png)
**How openHAB and Shelly 2.5 provide an enhance experience when controlling rollers**
## Use Case
![](images/oh_image1.png) ![](https://shelly.cloud/wp-content/uploads/2020/06/shelly25.jpg) ![](images/oh_image2.png)
More and more people have rollers, which are equipped with a motor and button control improving your comfort when operating the shutter.
This use case description covers the following aspects
- Operate the roller manual as usual - don't loose some of those features when bringing in the Shelly
- Use openHAB to control the roller (up/down/stop, positioning)
- Utilize device's position favorites
- Utilize safety features, which you get for free with the Shelly
The first point is important: SmartHome is nice for us techies, but standard users should have to use the "standard mode", but also the "new world".
Therefore a struct requirement: make if "compatible for my wife" and avoid "that sucks, I kill you!". Shutters not opening in the morning don't create fun :-)
One more aspect is some kind of protection to avoid physical damage when something gets wrong. The Shellies provide some interesting features to do.
This use case description might also apply to Venetian Blinds, but I don't have those and can't judge on that.
Feel free to adapt the concept and report ideas and experiences to the [community](https://community.openhab.org/t/shelly-binding/56862/1702?u=markus7017)
## Technical pre-requisites
To implement this use case you need
- Roller motor can be attached to the Shelly
For this how-to a roller with an electrical motor is required and will be controlled using A/C and a momentary switch.
The same solutions works with other switch types (DC/AC, 2 button switch etc.).
In this case you need to look into details and user a different Shelly configuration or adapt technical installation.
Refer to the Alterco Shelly documentation and make sure to use proper technical installation and wiring.
Important: Electrical installation should be performed only be people knowing what they do - failures could harm you!!
- Shelly 2.5 to control the roller with firmware 1.9.2+
The Shelly 2.5 supports relay and roller operation mode.
To prepare this use case you need to upgrade to firmware 1.9.2 (or newer) and perform some setup steps (see below).
- openHAB 3.0 (or 2.5) with latest version of the binding
openHAB is the perfect foundation to combine manual and automated control of the roller.
The Shelly binding is available for openHAB 3.0, but still supports version 2.5 (you should at least have 2.5.9).
Nevertheless you need to switch to the so called DEV build to benefit from bug fixes and improvements.
**This version is currently NOT part of the openHAB 3.0 distribution, a PR has been initiated
and it will not become part of the 2.5.x distribution, because this only receives bug fixes and the use case utilizes new features in the binding.**
## Implementation
### Software pre-requisites
#### openHAB version
It's strongly recommended to get on one of the pretty stable openHAB releases
- The good one: openHAB 2.5.9 or newer
- The new kid on the block: 3.0 will be release by end of 2020
- Older versions might worked, but are not covered here.
Refer to the documentation how to upgrade to the current version and where you should watch for necessary adaptions.
By the way: There is a good README for the binding, RTFM if you know what I mean :-)
Latest version is always available [here](https://github.com/markus7017/myfiles/blob/master/shelly/README.md) as part of the DEV build (see below).
Ideally the upgrade could be performed on a Raspberry with
```
openhab-cli stop
openhab-clu clean-cache
apt-get update
apt-get upgrade
openhab-cli start
```
and wait until openHAB has fully initialized and cache has been re-initialized.
That's it - pretty simple, but again you might need to do adaptions.
#### Device firmware
The binding supports Shelly devices for a long time, also with older firmware releases (beginning with version 1.7).
Nevertheless, a lot of issues has been fixed in between as well as new features became available over time.
It's recommended to upgrade your roller device to 1.9.2 or newer.
1.9 brings roller position favorites, which are used by this use case (older version works, but you can't use that feature).
See binding's [README](../README.md) for more information how to upgrade the firmware.
#### Shelly Binding
The Shelly binding is in general included in the openHAB 2.5.x as well as the new 3.0 distribution.
However, the so called DEV build is always on a newer feature level and fixing bugs.
Due to the fact that we utilize some new features of the binding it also requires the DEV build.
Refer to the information how to install the DEV build (check section Resources to get the info where to find this [READMEbeta](https://github.com/markus7017/myfiles/blob/master/shelly/READMEbeta.md))
Important:
After installing the new binding release you should delete all Shelly things and run the discovery.
No worries, openHAB will restore you channel/item linkings.
## Configuration
### Shelly setup - General
![](images/uiroller_1.png) ![](images/uiroller_2.png) ![](images/uiroller_3.png) ![](images/uiroller_4.png)
There are some settings required to prepare your Shelly for this use case.
- Open the Web UI simply by launching 'http://&lt;shelly ip&gt; in the browser, this opens the device's UI
- Go to Settings:DEVICE TYPE and select Roller-Shutter
- POWER ON PARAMETERS: "STOP" will make sure that the roller doesn't start moving on a power failure recovery
- INPUT BUTTONS MODE: This depend on your installed button, if you only have a single one use "One button", if you have 2 buttons or one with 2 positions select "One button"
- POSITIONING CONTROLS: Enable them to have the controls in the App (UP/STOP/DOWN + relative positions), this helps during installation
For safety reasons you might consider:
- OPEN/CLOSE WORKING TIME
This feature makes sure that the Shelly stops the motor after a certain time even the motor doesn't stop by itself.
Start the roller, measure the number of seconds until the shutter stops.
Maybe add 2-3 seconds for safe and set the values for both directions in the UI
![](images/uiroller_wt.png)
- OBSTACLE DETECTION under Safety in the Web UI
Shelly 2.5 has an integrated detection on roller obstacles based on measuring the motor power.
The detection needs to be enabled, "While Moving" cover open and close.
Action Stop makes most sense, you should manually verify the problem.
![](images/uiroller_obs1.png) ![](images/uiroller_obs2.png) ![](images/uiroller_obs3.png)
and there are some more options:
- MAX POWER PROTECTION
A roller should never consume high power - in this case you could assume an electrical problem.
Therefore you could configure the Shelly to turn off power when exceeding a certain limit (e.g. 250W - value depend on your roller motor).
- SWAP INPUTS and REVERSE DIRECTIONS - you could flip operation mode for open/close, this could help in non-standard operations, but could also indicate a wiring problen
It also makes sense to give the device a name. Go to Settings:DEVICE NAME and select a symbolic name.
This name will also discovered by the binding and added as a suffix to the thing name in the Inbox.
It simplifies to identify the roller when you have a ton of Shelly things (believe me).
### Shelly setup - Positioning Favorites
With version 1.9 Alterco introduced an interesting feature called Favorites.
Those allow to store up to 4 pre-defined positions in the device, e.g. 15%, 50%, 65%, 98%.
Once defined you have kind of a short-cut to bring the roller to that position and those favorites are also supported by the binding (see below).
![](images/uiroller_fav1.png) ![](images/uiroller_fav2.png)
To use this feature open the device's Web UI and click on Favorites(+) button.
You could now specify 4 percentage values between 0% (closed) and 100% (open).
Enter the values and try using the button line above the roller control and main UI buttons.
With this configuration your Shelly is ready to be integrated into openHAB.
### Binding/Thing configuration
Once the Shelly is configured you could start the discovery within openHAB.
Important: If you want to password protect your Shellys (strong recommendation) you could set a default user/password in the binding settings and avoid to specify those per thing:
- Open the Binding Configuration in the openHAB UI
- Set User Id and Password, save
- Remove all Shellys from the Inbox (if any)
- and restart the Discovery
![](images/uiroller_rlogin.png)
Now all Shellys should pop up with the correct device names and types.
The binding also adds some information to the Thing Name making the identification easier.
Once you added the device from the Inbox the binding will initialize the device and dynamically create channels depending on the available device/firmware features.
This takes about 5-10 seconds.
During that time the thing is working, but you might miss channels in the UI - that's normal, try to reload the page after 10sec and boom all there.
Go to the channel overview and links the channels you want to use, refer to the README to get more details on channels, type and values.
The only thing to configure are the positioning favorite ids for the roller UP and DOWN commands.
Edit the thing configuration and select the ids in the corresponding entry fields.
Value 0 means: no favorite, value 1-4 select the position as defined in the Shelly App.
There is also a dedicated channel (roller#rollerFav), which accepts this ids and triggers the roller moving to the position (% value) as defined for the matching favorites id.
### Device events
As you might know the binding supports the Alterco Shelly CoIoT protocol.
The device supports so called I/O URL Actions, which are kind of a callback to an application for certain events.
Whenever possible you should prefer CoIoT events, because they are triggered near realtime and provide way more information compared to the Action URLs.
The binding uses those CoIoT updates as triggers, but also to update the channel data.
Refer to the [README](../README.md) for more information on CoIoT.
### Automation
Beside manual operation the binding provide various options to control the roller from within openHAB rules.
For example
- link channel roller#control and use 'sendCommand(&lt;item&gt;, UP)' to open the shutter or 'sendCommand(&lt;item&gt;, DOWN)' to close it.
- get status updates from roller operations by observing channel 'roller#state' and 'roller#stopReason', those report an updated status once the operation is completed
- select a position by sending a number value of 100..0 to channel 'roller#rollerpos'
- or use the defined favorites by sending favorite id to channel 'roller#rollerFav'
- you might set a auto-timer, e.g. once the roller is opened close it again after xx minutes by sending a value to the 'roller#autoOn' or 'roller#autoOff' channels
- you could also get the position of the roller from 'roller#control' (by linking a Number item) or the last status from 'roller#state'.
Please note that the device only provides updates only after the roller stops, not during movement so it's not possible to get position updates while the roller is moving.
- of course you could use time-triggered rules, trigger the shutter depending on sunrise/sunset within openHAB, but also directly on the device
## Extending the Use Case
There are two valuable options, which even extend and improve the user experience.
- Button-1
Using the described setup you could add a Button-1 to trigger rules, e.g.
- 1xshort: open roller
- 2xshort: go to 25% (because disturbs enjoying your morning coffee with your wife or husband)
- 3xshort: go to 75% (sun is disturbing while watching your TV)
- long : close shutter (if not done by some automation)
- Voice control
And of course you could utilize openHAB's voice integration, e.g. with Alexa, Siri or Google Home.
- Scenes
There are more of less limits when integrating even more advanced roller control based on openHAB rules.
This allows to provide a scene to the user, which does a lot of complex stuff under the hood.
Be welcome to contribute your ideas to the community, this is what creates the difference between openHAB/Shelly setup compared to rollers with button control.
### Resources
There is a bunch of ressources you could browse around openHAB, Shelly or the binding
- [Binding README](../README.md)
- [Bugs/Features](https://github.com/openhab/openhab-addons/issues?q=is%3Aissue+is%3Aopen+%5Bshelly%5D)
- [Firmware Index](https://repo.shelly.cloud/files/firmware/?fbclid=IwAR0Kz6bjMGoq_HYU85QAdl8b-xh7E3IPa4ENKjqsvmMAYQ6QGC8ODvqPzUs)
- [Firmware Archive](http://archive.shelly-faq.de)
- [API Doc](https://shelly-api-docs.shelly.cloud/?fbclid=IwAR23ukCi_3aBSTPRHYUIcpr0pLi0vcyL0fF0PnJQdFvkkc8_Zo5LkAcli_A#http-server)
Note: The binding version included in the final OH 3.0 distro is significantly older than the DEV build. I can't make it in-time to bring in the PR in advance to the feature freeze for 3.0 - sorry for that, but always a matter of (spare time).
- [Shelly 2.5 product page](https://shelly.cloud/knowledge-base/devices/shelly-25/)
- [Shelly Support Group (English)](https://www.facebook.com/groups/ShellyIoTCommunitySupport)
and the [openHAB Community thread specifically for the binding](https://community.openhab.org/t/shelly-binding/56862/1701)

BIN
bundles/org.openhab.binding.shelly/doc/images/oh_image1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
bundles/org.openhab.binding.shelly/doc/images/oh_image2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

BIN
bundles/org.openhab.binding.shelly/doc/images/uiroller_fav1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 144 KiB

BIN
bundles/org.openhab.binding.shelly/doc/images/uiroller_fav2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 143 KiB

BIN
bundles/org.openhab.binding.shelly/doc/images/uiroller_obs1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 144 KiB

BIN
bundles/org.openhab.binding.shelly/doc/images/uiroller_obs2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 218 KiB

BIN
bundles/org.openhab.binding.shelly/doc/images/uiroller_obs3.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 224 KiB

BIN
bundles/org.openhab.binding.shelly/doc/images/uiroller_rlogin.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 222 KiB

BIN
bundles/org.openhab.binding.shelly/doc/images/uiroller_wt.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 228 KiB