Shelly

Integrate Shelly devices into Home Assistant.

Configuration

Adding Shelly to your Home Assistant instance can be done via the user interface, by using this My button:

Shelly can be auto-discovered by Home Assistant. If an instance was found, it will be shown as “Discovered”, which you can select to set it up right away.

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.

We recommend using unicast for communication. To enable this, enter the local IP address of the Home Assistant server and port 5683 into the CoIoT peer field and push SAVE button. This is mandatory for Shelly Motion with firmware 1.1.0 or newer. After changing the CoIoT peer, the Shelly device needs to be manually restarted.

Entity naming (generation 1)

The integration uses Device Name to name its entities if the device has only one relay or no relays at all.

The integration uses the following strategy to name its entities if the device has more than one relay:

• If Device Name or Channel Name is set in the device, the integration will use them to generate the entities’ name.
• If channel names are set, they will be used in the entity names. The device name will not be used.
• If only the device name is set, and the device has multiple channels, the channel number will be appended to the entity name (e.g., Channel 2).
• In case device name and channel names are not set, the entity name will be generated by the Device Type, Device ID and Channel Number.

Examples:

Names are set from the device web page:

• Device name can be set in Settings >> DEVICE NAME
• 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.

Entity naming (generation 2)

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

If the BUTTON TYPE of the switch connected to the device is set to momentary or detached switch, integration fires events under the type shelly.click when the switch is used. You can use these events in your automations.

Also, some devices do not add an entity for the button/switch. For example, the Shelly Button1 has only one entity for the battery level. It does not have an entity for the button itself. To trigger automations based on button presses, use the shelly.click event.

Listening for events

You can subscribe to the shelly.click event type in Developer Tools/Events in order to examine the event data JSON for the correct parameters to use in your automations. For example, shelly.click returns event data JSON similar to the following when you press the Shelly Button1.

Event 0 fired 9:53 AM:
{
    "event_type": "shelly.click",
    "data": {
        "device_id": "e09c64a22553484d804353ef97f6fcd6",
        "device": "shellybutton1-A4C12A45174",
        "channel": 1,
        "click_type": "single",
        "generation": 1
    },
    "origin": "LOCAL",
    "time_fired": "2021-04-28T08:53:12.755729+00:00",
    "context": {
        "id": "e0f379706563aaa0c2c1fda5174b5a0e",
        "parent_id": null,
        "user_id": null
    }
}

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:

1. In the Triggers section of the automation, set Trigger Type to Device.
2. In the Device dropdown menu. find the Shelly Button1.
3. In the Trigger dropdown menu, select Button double clicked.
4. Set any conditions and actions to complete your automation.

You can also create automations using YAML, for example:

- alias: "Toggle living room light"
  trigger:
    platform: event
    event_type: shelly.click
    event_data:
      device: shellyswitch25-AABBCC
      channel: 1
      click_type: single
  action:
    service: light.toggle
    target:
      entity_id: light.living_room

- alias: "Toggle living room lamp"
  trigger:
    platform: event
    event_type: shelly.click
    event_data:
      device: shellyswitch25-AABBCC
      channel: 2
      click_type: long
  action:
    service: light.toggle
    target:
      entity_id: light.lamp_living_room

Possible values for click_type

Generation 2 devices use the values btn_down, btn_up, single_push, double_push and long_push as click_type.

Appliance type (generation 1)

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.

Consumption type (generation 2)

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

Shelly lights supporting light transition:

• Shelly Bulb RGBW
• Shelly DUO
• Shelly Dimmer
• Shelly Dimmer 2
• Shelly RGBW2
• Shelly Vintage

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:

# Example configuration.yaml entry
shelly:
  coap_port: 12345

Additional info

Shelly devices rely on SNTP for features like power measurement. Please check from the device Web UI that the configured server is reachable.

Known issues and limitations

• 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)
• Device authentication for generation 2 devices is not supported
• Before set up, battery-powered devices must be woken up by pressing the button on the device.