Skip to content

Commit

Permalink
[shelly] New Shelly Manager (more detailed information, status, integ…
Browse files Browse the repository at this point in the history 
…rated firmware upgrade) (#10276)

* This PR brings in the Shelly Manager, check doc/ShellyManager.md for
additional information.
* Restart Device in Manager when CoIoT Mode has changed
* Updated pattern to extract version info (thanks @fwolter), CoIoT warning
for non-Motion devices fixed; AdvancedUsers.md now refers to Shelly
Manager
* Modified message when beta is detected (reference to 1.5.7 release build
confuses users running 1.10 beta)
* Fix for Enable/Disable AP roaming
* Handle button events also in detached mode, README updated
* Ignore inconsistent version string for initial 1.10 releases
* removed display of firmware id (there are various formats and it has
no value)

Signed-off-by: Markus Michels <markus7017@gmail.com>
  • Loading branch information
@markus7017
markus7017 authored Mar 31, 2021
1 parent b9d3c35 commit 1783017
Show file tree
Hide file tree
Showing 55 changed files with 2,790 additions and 38 deletions.
27 changes: 20 additions & 7 deletions bundles/org.openhab.binding.shelly/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,14 @@ 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.

Also check out the [Shelly Manager](doc/ShellyManager.md), which
- provides detailed information on your Shellys
- helps to diagnose WiFi issues or device instabilities
- includes some common actions and
- simplifies firmware updates.

[Shelly Manager](doc/ShellyManager.md) could also act as a firmware upgrade proxy - the device doesn't need to connect directly to the Internet, instead openHAB services as a download proxy, which improves device security.

## Supported Devices

| thing-type | Model | Vendor ID |
Expand Down Expand Up @@ -257,16 +265,20 @@ The following trigger types are sent:

|Event Type |Description |
|-------------------|---------------------------------------------------------------------------------------------------------------|
|SHORT_PRESSED |The button was pressed once for a short time |
|DOUBLE_PRESSED |The button was pressed twice with short delay |
|TRIPLE_PRESSED |The button was pressed three times with short delay |
|LONG_PRESSED |The button was pressed for a longer time |
|SHORT_LONG_PRESSED |A short followed by a long button push |
|LONG_SHORT_PRESSED |A long followed by a short button push |
|SHORT_PRESSED |The button was pressed once for a short time (lastEvent=S) |
|DOUBLE_PRESSED |The button was pressed twice with short delay (lastEvent=SS) |
|TRIPLE_PRESSED |The button was pressed three times with short delay (lastEvent=SSS) |
|LONG_PRESSED |The button was pressed for a longer time (lastEvent=L) |
|SHORT_LONG_PRESSED |A short followed by a long button push (lastEvent=SL) |
|LONG_SHORT_PRESSED |A long followed by a short button push (lastEvent=LS) |

Check the channel definitions for the various devices to see if the device supports those events.
You could use the Shelly App to set the timing for those events.

If you want to use those events triggering a rule:
- If a physical switch is connected to the Shelly use the input channel(`input` or `input1`/`input2`) to trigger a rule
- For a momentary button use the `button` trigger channel as trigger, channels `lastEvent` and `eventCount` will provide details on the event

### Alarms

The binding provides health monitoring functions for the device.
Expand Down Expand Up @@ -796,7 +808,8 @@ You can define 2 items (1 Switch, 1 Number) mapping to the same channel, see exa

Important: The Shelly Motion does only support CoIoT Unicast, which means you need to set the CoIoT peer address.

Use device WebUI, open COIOT settings, make sure CoIoT is enabled and enter the openHAB IP address or
- Use device WebUI, open COIOT settings, make sure CoIoT is enabled and enter the openHAB IP address or
- Use [Shelly Manager](doc/ShellyManager.md, select Action 'Set CoIoT peer' and the Manager will sets the openHAB IP address as peer address

|Group |Channel |Type |read-only|Description |
|----------|---------------|---------|---------|---------------------------------------------------------------------|
Expand Down
186 changes: 186 additions & 0 deletions bundles/org.openhab.binding.shelly/doc/ShellyManager.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,186 @@
# Shelly Manager

The Shelly Manager is a small extension to the binding, which provides some low level information on the Shelly Devices, but also provides some functions to manage the devices.

To open the Shelly Manage launch the following URL in your browser
- http://&lt;openHAB IP address&gt;:8080/shelly/manager or
- http://&lt;openHAB IP address&gt;:8443/shelly/manager

Maybe you need to change the port matching your setup.

Shelly Manager makes you various device insights available to get an overview of your Shellys
- Get a quick overview that all Shellys operate like expected, statistical data will help to identify issues
- Have some basic setting actions integrated, which help to do an easy setup of new Shellys added to openHAB
- Make firmware updates way easier - filter 'Update available' + integrated 2-click update
- Provide a firmware download proxy, which allows to separate your Shellys from the Internet (improved device security)

## Overview

Once the Shelly Manager is opened an overview of all Shelly devices added as a Thing are displayed.
Things which are not discovered or still site in the Inbox will not be displayed.

![](images/manager/overview.png)

You'll see a bunch of technical details, which are not available as channels or in the Thing properties.
This includes information on the device communication stability.
The statistic gives you a good overview if device communication is stable or a relevant number of timeouts need to be recovered.
In this case you should verify the WiFi coverage or other options to improve stability.

The following information is available
|Column |Description |
|--------------------|---------------------------------------------------------------------------------|
|S |Thing Status - hover over the icon to see more details |
|Name |Device name - hover over the name to get more details |
|Cloud Status Icon |Indicates the status of the Shelly Cloud feature: disabled/enabled/connected |
|MQQT Status Icon |Indicates the staus of the MQTT featured disabled/enabled/connected |
|Refresh button |Trigger a status refresh in background, maybe you need to click more than once |
|Device IP |Assigned IP address, click to open the device’s Web UI in a separate browser tab |
|WiFi Network |SSID of the connected WiFi network |
|WiFi Signal |WiFi signal strength, 0=none, 4=very good |
|Battery Level |Remaining capacity of the battery |
|Heartbeat |Last time a response or an event was received from the device |
|Actions |Drop down with some actions, see below |
|Firmware |Current firmware release |
|Update avail |yes indicates that a firmware update is available |
|Versions |List available firmware versions: prod, beta or archived |
|Uptime |Number of seconds since last device restart |
|Internal Temp |Device internal temperature. Max is depending on device type. |
|Update Period |Timeout for device refresh |
|Remaining Watchdog |Shows number of seconds until device will go offline if no update is received |
|Events |Increases on every event triggered by the device or the binding |
|Last Event |Type of last event or alarm (refer README.md for details) |
|Event Time |When was last event received |
|Device Restarts |Number of detected restarts. This is ok on firmware updates, otherwise indicates a crash |
|Timeout Errors |Number of API timeouts, could be an indication for an unstable connection |
|Timeouts recovered |The binding does retries and timeouts and counts successful recoveries |
|CoIoT Messages |Number of received CoIoT messages, must be >= 2 to indicate CoIoT working |
|CoIoT Errors |Number of CoIoT messages, which can't be processed. >0 indicates firmware issues |

The column S and Name display more information when hovering with the mouse over the entries.

![](images/manager/overview_devstatus.png)
![](images/manager/overview_devsettings.png)

### Device Filters
|Filter |Description |
|--------------------|---------------------------------------------------------------------------------|
|All |Clear filter / display all devices |
|Online only |Filter on devices with Thing Status = ONLINE |
|Inactive only |Filter on devices, which are not initialized for in Thing Status = OFFLINE |
|Needs Attention |Filter on devices, which need attention (setup/connectivity issues), see below |
|Update available |Filter on devices having a new firmware version available |
|Unprotected |Filter on devices, which are currently not password protected |

Beside the Device Filter box you see a refresh button.
At the bottom right you see number of displayed devices vs. number of total devices.
A click triggers a background status update for all devices rather only the selected one when clicking of the refresh button in the device lines.

Filter 'Needs Attention':
This is a dynamic filter, which helps to identify devices having some kind of setup / connectivity or operation issues.
The binding checks the following conditions
- Thing status != ONLINE: Use the 'Inactive Only' filter to find those devices, check openhab.log
- WIFISIGNAL: WiFi signal strength < 2 - this usually leads into connectivity problems, check positioning of portable devices or antenna direction.
- LOWBATTERY: The remaining battery is < 20% (configuration in Thing Configuration), consider to replace the battery
Watch out for bigger number of timeout errors.
- Device RESTARTED: Indicates a firmware problem / crash if this happens without a device reboot or firmware update (timestamp is included)
- OVERTEMP / OVERLOAD / LOADERROR: There are problems with the physical installation of the device, check specifications, wiring, housing!
- SENSORERROR: A sensor error / malfunction was detected, check product documentation
- NO_COIOT_DISCOVERY: The CoIoT discovery has not been completed, check IP network configuration, re-discover the device
- NO_COIOT_MULTICAST: The CoIoT discovery could be completed, but the device is not receiving CoIoT status updates.
You might try to switch to CoIoT Peer mode, in this case the device doesn't use IP Multicast and sends updates directly to the openHAB host.

The result is shown in the Device Status tooltip.

### Device settings & status

When hovering with the mouse over the status icon or the device name you'll get additional information settings and status.

### Device Status

|Status |Description |
|--------------------|---------------------------------------------------------------------------------|
|Status |Thing status, sub-status and description as you know it from openHAB |
|CoIoT Status |CoIoT status: enabled or disabled |
|CoIoT Destination |CoIoT Peer address (ip address:port) or Multicast |
|Cloud Status |Status of the Shelly Cloud connection: disabled, enabled, connected |
|MQTT Status |MQTT Status: disabled, enabled, connected |
|Actions skipped |Number of actions skipped by the device, usually 0 |
|Max Internal Temp |Maximum internal temperature, check device specification for valid range |

### Device Settings

|Setting |Description |
|--------------------|---------------------------------------------------------------------------------|
|Shelly Device Name |Device name according to device settings |
|Device Hardware Rev |Hardware revision of the device |
|Device Type |Device Type ID |
|Device Mode |Selected mode for dual mode devices (relay/roller or white/color) |
|Firmware Version |Current firmware version |
|Network Name |Network name of the device used for mDNS |
|MAC Address |Unique hardware/network address of the device |
|Discoverable |true: the device can be discovered using mDNS, false: device is hidden |
|WiFi Auto Recovery |enabled: the device will automatically reboot when WiFi connect fails |
|Timezone |Configured device zone (see device settings) |
|Time server |Configured time server (use device UI to change) |

### Actions

The Shelly Manager provides the following actions when the Thing is ONLINE.
They are available in the dropdown list in column Actions.

|Action |Description |
|---------------------|---------------------------------------------------------------------------------|
|Reset Statistics |Resets device statistic and clear the last alarm |
|Restart |Restart the device and reconnect to WiFi |
|Protect |Use binding's default credentials to protect device access with user and password|
|Set CoIoT Peer |Disable CoIoT Multicast and set openHAB system as receiver for CoIoT updates |
|Set CoIoT Multicast |Disable CoIoT Multicast and set openHAB system as receiver for CoIoT updates |
|Enable Cloud |Enable the Shelly Cloud connectivity |
|Disable Cloud |Disable the Shelly Cloud connectivity (takes about 15sec to become active) |
|Reconnect WiFi |Sensor devices only: Clears the STA/AP list and reconnects to strongest AP |
|Enable WiFi Roaming |The device will connect to the strongest AP when roadming is enabled |
|Disable WiFi Roaming |Disable Access Point Roaming, device will periodically search for better APs |
|Enable WiFi Recovery |Enables auto-restart if device detects persistent WiFi connectivity issues |
|Disable WiFi Recovery|Disables device auto-restart ion persistent WiFi connectivity issues |
|Factory Reset |Performs a **factory reset**; Attention: The device will lose its configuration |
|Enable Device Debug |Enables on-device debug log - activate only when requested by Allterco support |
|Get Debug Log |Retrieve and display device debug output |
|Get Debug Log1 |Retrieve and display 2nd device debug output |
|Factory Reset |Performs **firmware reset**; Attention: The device will lose its configuration |

Note: Various actions available only for certain devices or when using a minimum firmware version.

![](images/manager/overview_actions.png)

## Firmware Update

The Shelly Manager simplifies the firmware update.
You could select between different versions using the drop down list on the overview page.

Shelly Manager integrates different sources
- Allterco official releases: production and beta release (like in the device UI)
- Older firmware release from the firmware archive - this is a community service
- You could specify any custom URL providing the firmware image (e.g. a local web server), which is accessible for the device using http

| | |
|-|-|
|![](images/manager/overview_versions.png)|All firmware releases are combined to the selection list.<br/>Click on the version you want to install and Shelly Manager will generate the requested URL to trigger the firmware upgrade.|

The upgrade starts if you click "Perform Update".

![](images/manager/fwupgrade.png)

The device will download the firmware file, installs the update and restarts the device.
Depending on the device type this takes between 10 and 60 seconds.
The binding will automatically recover the device with the next status check (as usual).

### Connection types

You could choose between 3 different update types
* Internet: This triggers the regular update; the device needs to be connected to the Internet
* Use openHAB as a proxy: In this case the binding directs the device to request the firmware from the openHAB system.
The binding will then download the firmware from the selected sources and passes this transparently to the device.
This provides a security benefit: The device doesn't require Internet access, only the openHAB host, which could be filtered centrally.
* Custom URL: In this case you could specify

The binding manages the download request with the proper download URL.
2 changes: 1 addition & 1 deletion ...ding.shelly/src/main/java/org/openhab/binding/shelly/internal/ShellyBindingConstants.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,6 @@ public class ShellyBindingConstants {
public static final String PROPERTY_STATS_TIMEOUTS = "statsTimeoutErrors";
public static final String PROPERTY_STATS_TRECOVERED = "statsTimeoutsRecovered";
public static final String PROPERTY_COIOTAUTO = "coiotAutoEnable";
public static final String PROPERTY_COIOTREFRESH = "coiotAutoRefresh";

// Relay
public static final String CHANNEL_GROUP_RELAY_CONTROL = "relay";
Expand Down Expand Up @@ -327,6 +326,7 @@ public class ShellyBindingConstants {
public static final String SHELLY_API_MIN_FWVERSION = "v1.5.7";// v1.5.7+
public static final String SHELLY_API_MIN_FWCOIOT = "v1.6";// v1.6.0+
public static final String SHELLY_API_FWCOIOT2 = "v1.8";// CoAP 2 with FW 1.8+
public static final String SHELLY_API_FW_110 = "v1.10"; // FW 1.10 or newer detected, activates some add feature

// Alarm types/messages
public static final String ALARM_TYPE_NONE = "NONE";
Expand Down
Loading

0 comments on commit 1783017

Please sign in to comment.