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

[shelly] Add support for Shelly BLU series of devices (#15031)

Browse Source 
* support for Pro 3EM (WIP)
* Support for Plug-S and Smoke added
* new channel resetTotals for emeters, new channel sensor#mute for Smoke
* Validate Temp reported by CoAP before updating channel, ignore 999
* Add support for Shelly BLU Button and Door/Window

Signed-off-by: Markus Michels <markus7017@gmail.com>
This commit is contained in:
Markus Michels
2023-06-26 16:37:50 +02:00
committed by GitHub
parent 46039efd0a
commit 631148320f
42 changed files with 1459 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -76,20 +76,20 @@ The binding provides the same feature set across all devices as good as possible
### Generation 2 Plus series
| thing-type | Model | Vendor ID |
| -------------------- | -------------------------------------------------------- | --------------------------------------------- |
| shellyplus1 | Shelly Plus 1 with 1x relay | SNSW-001X16EU |
| shellyplus1pm | Shelly Plus 1PM with 1x relay + power meter | SNSW-001P16EU |
| shellyplus2pm-relay | Shelly Plus 2PM with 2x relay + power meter, relay mode | SNSW-002P16EU, SNSW-102P16EU |
| shellyplus2pm-roller | Shelly Plus 2PM with 2x relay + power meter, roller mode | SNSW-002P16EU, SNSW-102P16EU |
| shellyplusplug | Shelly Plug-S | SNPL-00112EU |
| shellyplusplug | Shelly Plug-IT | SNPL-00110IT |
| shellyplusplug | Shelly Plug-UK | SNPL-00112UK |
| shellyplusplug | Shelly Plug-US | SNPL-00116US |
| shellyplusi4 | Shelly Plus i4 with 4x AC input | SNSN-0024X |
| shellyplusi4dc | Shelly Plus i4 with 4x DC input | SNSN-0D24X |
| shellyplusht | Shelly Plus HT with temperature + humidity sensor | SNSN-0013A |
| shellyplussmoke | Shelly Plus Smoke sensor | SNSN-0031Z |
| thing-type | Model | Vendor ID |
| -------------------- | -------------------------------------------------------- | ---------------------------- |
| shellyplus1 | Shelly Plus 1 with 1x relay | SNSW-001X16EU |
| shellyplus1pm | Shelly Plus 1PM with 1x relay + power meter | SNSW-001P16EU |
| shellyplus2pm-relay | Shelly Plus 2PM with 2x relay + power meter, relay mode | SNSW-002P16EU, SNSW-102P16EU |
| shellyplus2pm-roller | Shelly Plus 2PM with 2x relay + power meter, roller mode | SNSW-002P16EU, SNSW-102P16EU |
| shellyplusplug | Shelly Plug-S | SNPL-00112EU |
| shellyplusplug | Shelly Plug-IT | SNPL-00110IT |
| shellyplusplug | Shelly Plug-UK | SNPL-00112UK |
| shellyplusplug | Shelly Plug-US | SNPL-00116US |
| shellyplusi4 | Shelly Plus i4 with 4x AC input | SNSN-0024X |
| shellyplusi4dc | Shelly Plus i4 with 4x DC input | SNSN-0D24X |
| shellyplusht | Shelly Plus HT with temperature + humidity sensor | SNSN-0013A |
| shellyplussmoke | Shelly Plus Smoke sensor | SNSN-0031Z |
### Generation 2 Pro series
@@ -104,6 +104,14 @@ The binding provides the same feature set across all devices as good as possible
| shellypro3em | Shelly Pro 3 with 3 integrated power meters | SPEM-003CEBEU |
| shellypro4pm | Shelly Pro 4 PM with 4x relay + power meter | SPSW-004PE16EU, SPSW-104PE16EU |
### Shelly BLU
| thing-type | Model | Vendor ID |
| ----------------- | ------------------------------------------------------ | --------- |
| shellyblubutton | Shelly BLU Button 1 | SBBT |
| shellybludw | Shelly BLU Door/Windows | SBDW |
## Binding Configuration
The binding has the following configuration options:
@@ -160,6 +168,29 @@ This allows routing the CoIoT/CoAP messages across multiple IP subnets without s
You could use Shelly Manager (doc/ShellyManager.md) to easily do the setup (configuring the openHAB host as CoAP peer address).
Keep Multicast mode if you have multiple hosts, which should receive the CoAP updates.
### Discovery of BLU Devices
The BLU devices use Bluetooth Low Energy (BLE).
The binding can't communicate directly with the device, but the Plus/Pro series with firmware 0.14.1 or newer could be used as a gateway.
The binding automatically installs a script on the Shelly Device (oh-blu-scanner), which forwards the BLU events to the binding using the WebSocket channel.
Follow these steps to add the Shelly BLU Device to openHAB
- Make sure a Shelly is near by the BLU device, enable Bluetooh on this device (the Bluetooth Gateway mode is not required)
- Add this thing to openHAB, make sure thing gets online
- Enable "BLU Gateway Support" in the thing configuration of the Shelly device acting as gateway.
- Now press the button on your BLU device, this wakes up the device and the script forwards this event to the binding
- As a result the corresponding thing should show up in the Inbox
- Add the thing (at this point no channels are created), the new thing will show status CONFIG_PENDING
- Click the device button again, the binding gets another event and creates the channels and thing changes status to ONLINE
- Finally link the channels to the equipment in the model
Note: During initialization the script 'oh-blu-scanner.js' gets installed and activated on the Shelly Gateway device.
Every time an event is received sensors#lastUpdate and channels are updated with the reported values.
device#wifiSignal indicates the Bluetooth signal strength and gets updated when the device sends an event.
The binding supports multiple Shelly Plus/Pro as gateway devices unless they are added as thing and are ONLINE.
### Password Protected Devices
The Shelly devices can be configured to require authorization through a user id and password.
@@ -251,6 +282,7 @@ You could also create a rule to catch those status changes or device alarms (see
| eventsRoller | true: register event "trigger" when the roller updates status | no | true for roller devices |
| favoriteUP | 0-4: Favorite id for UP (see Roller Favorites) | no | 0 = no favorite id |
| favoriteDOWN | 0-4: Favorite id for DOWN (see Roller Favorites) | no | 0 = no favorite id |
| enableBluGateway | true: Active BLU gateway support (install script) | no | false ]
### General Notes
@@ -380,7 +412,7 @@ A new alarm will be triggered on a new condition or every 5 minutes if the condi
| TEMP_OVER | Above "temperature over" threshold |
| VIBRATION | A vibration/tamper was detected (DW2 only) |
Refer to section [Full Example](#full-example) for examples how to catch alarm triggers in openHAB rules
Refer to section [Full Example](#full-example) for examples how to catch alarm triggers in openHAB rules.
## Channels
@@ -1341,6 +1373,38 @@ Channels lastEvent and eventCount are only available if input type is set to mom
| | timerActive | Switch | yes | Relay #1: ON: An auto-on/off timer is active |
| | button | Trigger | yes | Event trigger, see section Button Events |
## Shelly BLU Devices
### Shelly BLU Button 1 (thing-type: shellyblubutton)
See notes on discovery of Shelly BLU devices above.
| Group | Channel | Type | read-only | Description |
| ------- | ------------- | -------- | --------- | ----------------------------------------------------------------------------------- |
| status | lastEvent | String | yes | Last event type (S/SS/SSS/L) |
| | eventCount | Number | yes | Counter gets incremented every time the device issues a button event. |
| | button | Trigger | yes | Event trigger with payload, see SHORT_PRESSED or LONG_PRESSED |
| | lastUpdate | DateTime | yes | Timestamp of the last measurement |
| battery | batteryLevel | Number | yes | Battery Level in % |
| | lowBattery | Switch | yes | Low battery alert (< 20%) |
| device | gatewayDevice | String | yes | Shelly forwarded last status update (BLU gateway), could vary from packet to packet |
### Shelly BLU Door/Window Sensor (thing-type: shellybludw)
See notes on discovery of Shelly BLU devices above.
| Group | Channel | Type | read-only | Description |
| ------- | ------------- | -------- | --------- | ----------------------------------------------------------------------------------- |
| sensors | state | Contact | yes | OPEN: Contact is open, CLOSED: Contact is closed |
| | lux | Number | yes | Brightness in Lux |
| | tilt | Number | yes | Tilt in ° (angle), -1 indicates that the sensor is not calibrated |
| | lastUpdate | DateTime | yes | Timestamp of the last update (any sensor value changed) |
| battery | batteryLevel | Number | yes | Battery Level in % |
| | lowBattery | Switch | yes | Low battery alert (< 20%) |
| device | gatewayDevice | String | yes | Shelly forwarded last status update (BLU gateway), could vary from packet to packet |
## Full Example
### shelly.things
@@ -1582,4 +1646,3 @@ sitemap demo label="Home"
Number item=Shelly_Power
}
}
```