Add information about Shelly generation 2 devices (#19400)

Co-authored-by: Simone Chemelli <simone.chemelli@gmail.com>
This commit is contained in:
Maciej Bieniek 2021-09-21 23:01:33 +02:00 committed by GitHub
parent a30006da52
commit 0c0062b4cf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -28,7 +28,13 @@ ha_platforms:
Integrate [Shelly devices](https://shelly.cloud) into Home Assistant.
## Shelly device configuration
{% include integrations/config_flow.md %}
## Shelly device generations
There are two generations of devices. Both generations are supported by this integration. There are some differences in how devices should be configured and in the naming of entities and devices between generations.
## Shelly device configuration (generation 1)
Shelly devices use the `CoIoT` protocol to communicate with integration. For Shelly firmware 1.10.0 or newer, `CoIoT` must be enabled in the device settings. Navigate to the local IP address of your Shelly device, **Internet & Security** >> **ADVANCED - DEVELOPER SETTINGS** and check the box **Enable CoIoT**.
@ -38,9 +44,7 @@ We recommend using `unicast` for communication. To enable this, enter the local
Integration is communicating directly with the device; cloud connection is not needed.
</div>
{% include integrations/config_flow.md %}
## Entity naming
## Entity naming (generation 1)
The integration uses the following strategy to name its entities:
@ -64,9 +68,12 @@ Names are set from the device web page:
- Channel name for single-channel devices can be set in **Settings** >> **CHANNEL NAME**
- Channel name for multi-channel devices can be set in **Settings** >> **CHANNEL NAME** after selecting the channel, by clicking on the channel name.
## Appliance type
## Entity naming (generation 2)
Shelly device relays are added to the Home Assistant by default as `switch` entities. A relay can be added as a `light` entity if the device uses firmware version 1.9.0 or newer and the **Settings** >> **APPLIANCE TYPE** value is set to `light`.
The integration uses the following strategy to name its entities:
- If `Channel Name` is set in the device, the integration will use it to generate the entities' name, e.g. `Kitchen Light`
- If `Channel Name` is set to the default value, the integration will use the `Device ID` and default channel name to generate the entities' name, e.g. `ShellyPro4PM-9808D1D8B912 switch_0`.
## Events
@ -86,7 +93,8 @@ Event 0 fired 9:53 AM:
"device_id": "e09c64a22553484d804353ef97f6fcd6",
"device": "shellybutton1-A4C12A45174",
"channel": 1,
"click_type": "single"
"click_type": "single",
"generation": 1
},
"origin": "LOCAL",
"time_fired": "2021-04-28T08:53:12.755729+00:00",
@ -98,6 +106,8 @@ Event 0 fired 9:53 AM:
}
```
The `generation` value indicates the generation of the device that is the source of the event.
### Automations
The simplest way to create automations is to use the Home Assistant automation editor. For example, to set an automation triggered by a double press of a particular Shelly Button1:
@ -148,23 +158,21 @@ You can also create automations using YAML, for example:
| `SL` | `single_long` |
| `LS` | `long_single` |
Generation 2 devices use the values `btn_down`, `btn_up`, `single_push`, `double_push` and `long_push` as `click_type`.
<div class="note">
Not all devices support all input events. You can check on [Shelly API Reference](https://shelly-api-docs.shelly.cloud/) website what types of Shelly input events your device supports.
</div>
## CoAP port
## Appliance type (generation 1)
In some cases, it may be needed to customize the CoAP port (default: `5683`) your Home Assistant instance is listening to.
Shelly device relays are added to Home Assistant by default as `switch` entities. A relay can be added as a `light` entity if the device uses firmware version 1.9.0 or newer and the **Settings** >> **APPLIANCE TYPE** value is set to `light`.
In order to change it, add the following key to your configuration.yaml:
## Consumption type (generation 2)
```yaml
# Example configuration.yaml entry
shelly:
coap_port: 12345
```
Shelly device relays are added to Home Assistant by default as `switch` entities. A relay can be added as a `light` entity if **CONSUMPTION TYPE** value is set to `Lights`.
## Light transition
@ -189,8 +197,21 @@ The firmware limits the transition time to 5 seconds.
</div>
## CoAP port (generation 1)
In some cases, it may be needed to customize the CoAP port (default: `5683`) your Home Assistant instance is listening to.
In order to change it, add the following key to your `configuration.yaml`:
```yaml
# Example configuration.yaml entry
shelly:
coap_port: 12345
```
## Known issues and limitations
- Only supports firmware 1.8 and later
- Shelly 4Pro and Shelly Sense are not supported (devices based on old CoAP v1 protocol)
- Only supports firmware 1.8 and later for generation 1 devices
- Only supports firmware 0.8 and later for generation 2 devices
- Generation 1 "Shelly 4Pro" and "Shelly Sense" are not supported (devices based on old CoAP v1 protocol)
- Before set up, battery-powered devices must be woken up by pressing the button on the device.