When you’re working with MQTT in Home Assistant, you’ll know that it does require some manual configuration.
Often you’re copy/pasting the configs from other devices and adapting them to fit the new devices.

Below I’ve copy/pasted and template-ized the configs I’m using.

If you have an idea for any improvements, hit me up on Twitter!

For an introduction on MQTT for Shelly devices, see my blog post: Getting started with MQTT and Home Assistant (and Shelly).

shellies-discovery

Some time ago I switched from manually adding Shelly devices via MQTT configurations to an automated script: ha-shellies-discovery. It automatically recognizes new Shelly devices talking to the MQTT broker (after the Shelly’s been configured to use MQTT) and creates devices and entities for each of them. So you no longer need to add a new config for each device you added and all entities are nicely grouped per device from the start.

This script can easily be installed in Home Assistant using HACS. I won’t write a tutorial on doing this, as all required information can be found in the ha-shellies-discovery documentation.

Using the configurations examples below to manually add Shelly devices via MQTT is still a valid option. Espcially if you’re wanting to do ’non-default’ integrations (e.g. use some templating to modify values).
But for regular installs, I’d move to the automated option. We’re all using Home Assistant to automate our lives, why not use it to automate device integration?

Shelly Gen 1 and Shelly Gen 2

With the introduction of the Shelly 4Pro PM also came the introduction of a new generation of devices. This new generation also brings in changes in the communication methods, including MQTT.

The content of this blog posts discusses the Gen 1 devices. Once the Gen 2 become more readily available, and I get my hands on one or more of them, I may make a new post about the changes.

Configuration file structure

First of all, an important factor in keeping everyting readable and manageable, working with the directory structure is a must!

The king of configuration splitting (as it’s called) is Frenck.
Check out these videos of him and DrZzs and Frenck’s notes to learn more about the different options.

I generally group configurations for devices by their type/use (e.g. lights).
This does mean that some configs that are more related to the device (e.g. device temp) are grouped with that light.

My current configuration filetree looks as follows.
Note that I skipped files/folders not relevant to this post.

.
+-- automations.yaml
+-- configuration.yaml
+-- groups.yaml
+-- scripts.yaml
+-- binsensors
|   +-- room_x
|   |   +-- lamps.yaml
|   +-- etc.
+-- customisations
|   +-- customize_domain.yaml
|   +-- customize_glob.yaml
|   +-- customize.yaml
+-- lights
|   +-- room_x
|   |   +-- lamps.yaml
|   +-- etc.
+-- sensors
|   +-- room_x
|   |   +-- lamps.yaml
|   |   +-- shelly_ht.yaml
|   +-- room_y
|   |   +-- lamps.yaml
|   |   +-- shelly_dw2.yaml
|   +-- etc.
+-- switches
|   +-- room_x
|   |   +-- floorlamp.yaml

To get this to work, I added the following lines to configuration.yaml.

homeassistant:
  customize_domain: !include customisations/customize_domain.yaml
  customize_glob: !include customisations/customize_glob.yaml
  customize: !include customisations/customize.yaml

automation: !include automations.yaml
group: !include group.yaml
script: !include scripts.yaml
binary_sensor: !include_dir_merge_list binsensors/
light: include_dir_merge_list lights/
sensor: include_dir_merge_list sensors/
switch: include_dir_merge_list switchess/

MQTT Templates

Note that I’m only sharing the configs of devices I already own.
If you want me to check out another device, I can either try to make up the configs based on the Docs or you can send me one and I’ll have a go at it (hit me up on Twitter).

Platform: light, switch, cover, …

While the Shelly devices like 1/1L/1PM/2.5/Plug/Plug_S are in fact “just” relays, the installation posibilities are endless.
Most commonly, they’re used to control lights or wall sockets.

In Home Assistant, devices can be configured as a switch, which gives you simple on/off capabilities.
But you can also configure a device as light, which will also give you control over brightness and colour temp, if the device supports it.
Configuring a device as cover allows you to control things like blinds, curtains, shades, shutters, garage doors, …

All of my Shelly devices are currently configured as lights.
However, it’s just a matter of setting the correct platform and/or adding the config in the right file for your Shelly to be configured as switch, cover, …

Shelly relays (1, 1PM, 1L, 2.5)

The Shelly relays allow you to toggle one or more channels on/off, give you the switch state and may give you info on power consumption and device temperature.

Some devices, like the Shelly2.5 have multiple switch inputs and outputs. These need to be added individually.

Light vs Switch setup

The examples below assume the Shelly relay was connected to a lamp. However, you can use the relay to toggle a wall socket, heater, swimming pool pump, garden watering system, …

Since a Shelly relay (e.g. Shelly 1 or 2.5) only supports on/off toggling, so it doesn’t really matter whether it’s configured as a light or a switch.

If you want Home Assistant to recognise the Shelly purely as an on-off switch, move the config below to switches/room_x/fan.yaml (for example).

## /lights/room_x/lamps.yaml

# Lamp room X - Shelly 1PM
- platform: mqtt
  name: Room X - lamp
  payload_on: "on"
  payload_off: "off"
  qos: 1
  state_topic: shellies/shelly1pm-[SHELLY ID]/relay/0
  command_topic: shellies/shelly1pm-[SHELLY ID]/relay/0/command
  json_attributes_topic: shellies/shelly1pm-[SHELLY ID]/info


## /lights/room_y/lamps.yaml

# Lamp room Ya - Shelly 2.5
- platform: mqtt
  name: Room Y - lamp A
  payload_on: "on"
  payload_off: "off"
  qos: 1
  state_topic: shellies/shellyswitch25-[SHELLY ID]/relay/0
  command_topic: shellies/shellyswitch25-[SHELLY ID]/relay/0/command
  json_attributes_topic: shellies/shellyswitch25-[SHELLY ID]/info

# Lamp room Yb - Shelly 2.5
- platform: mqtt
  name: Room Y - lamp B
  payload_on: "on"
  payload_off: "off"
  qos: 1
  state_topic: shellies/shellyswitch25-[SHELLY ID]/relay/1
  command_topic: shellies/shellyswitch25-[SHELLY ID]/relay/1/command
  json_attributes_topic: shellies/shellyswitch25-[SHELLY ID]/info

Binary sensors

These binary sensors allow you to create automations for a long-push on the connected button, but also give you some insights on the device state.

Again, repeat add extra relays if needed by copying the relevant sections and changing the relay number.

# /binsensors/room_x/lamps.yaml

# Longpush
- platform: mqtt
  name: Room X - lamp - longpush
  expire_after: 86400
  qos: 1
  payload_on: 1
  payload_off: 0
  state_topic: shellies/shelly1pm-[SHELLY ID]/longpush/0
# Switch state
- platform: mqtt
  name: Room X - lamp - switch
  expire_after: 86400
  qos: 1
  payload_on: 1
  payload_off: 0
  state_topic: shellies/shelly1pm-[SHELLY ID]/input/0
# Over temp
- platform: mqtt
  name: Room X - lamp - overtemp
  expire_after: 86400
  qos: 1
  payload_on: 1
  payload_off: 0
  state_topic: shellies/shelly1pm-[SHELLY ID]/overtemperature
# Firmware upgrade
- platform: mqtt
  name: Room X - lamp - firmware
  state_topic: shellies/shelly1pm-[SHELLY ID]/announce
  value_template: "{{ value_json.new_fw }}"
  payload_on: true
  payload_off: false

Sensors

The input_event sensor again allows you to build automations based on the actions of the connected switch. The remaining sensors give you insights on the device status.

## /sensors/room_x/lamp.yaml

# Input type
- platform: mqtt
  name: Room X - lamp - input
  expire_after: 86400
  qos: 1
  state_topic: shellies/shelly1pm-[SHELLY ID]/input_event/0
# Device temperature °C
- platform: mqtt
  name: Room X - lamp - temperature
  expire_after: 86400
  qos: 1
  device_class: temperature
  unit_of_measurement: '°C'
  icon: mdi:temperature-celcius
  state_topic: shellies/shelly1pm-[SHELLY ID]/temperature
# Device temperature °F
- platform: mqtt
  name: Room X - lamp - temperature F
  expire_after: 86400
  qos: 1
  device_class: temperature
  unit_of_measurement: '°F'
  icon: mdi:temperature-fahrenheit
  state_topic: shellies/shelly1pm-[SHELLY ID]/temperature_f
# Power consumption (live)
- platform: mqtt
  name: Room X - lamp - power
  expire_after: 86400
  qos: 1
  device_class: power
  unit_of_measurement: 'W'
  icon: mdi:lightning-bolt-outline
  state_topic: shellies/shelly1pm-[SHELLY ID]/relay/0/power
# Power consumption (since reboot)
- platform: mqtt
  name: Room X - lamp - energy
  expire_after: 86400
  qos: 1
  device_class: energy
  state_class: total_increasing
  unit_of_measurement: 'Wh'
  value_template: "{{ value | float / 60 }}"
  icon: mdi:lightning-bolt
  state_topic: shellies/shelly1pm-[SHELLY ID]/relay/0/energy
# Overpower
- platform: mqtt
  name: Room X - lamp - overpower
  expire_after: 86400
  qos: 1
  device_class: power
  unit_of_measurement: 'W'
  icon: mdi:flash-alert
  state_topic: shellies/shelly1pm-[SHELLY ID]/overpower_value

External sensors

If you have external temperature or humidity sensors connected to the Shelly 1PM, you can also read their values over MQTT.

Temperature

Up to 3 DS1820 sensors can be added to the Shelly 1PM.
You can read their values from the sensor IDs 0, 1, 2.

## /sensors/room_x/lamp.yaml

# Temp sensor 0 °C
- platform: mqtt
  name: Room X - lamp - temperature 0
  expire_after: 86400
  qos: 1
  device_class: temperature
  unit_of_measurement: '°C'
  icon: mdi:home-thermometer-outline
  state_topic: shellies/shelly1pm-[SHELLY ID]/ext_temperature/0
# Temp sensor 0 °F
- platform: mqtt
  name: Room X - lamp - temperature 0 F
  expire_after: 86400
  qos: 1
  device_class: temperature
  unit_of_measurement: '°F'
  icon: mdi:home-thermometer-outline
  state_topic: shellies/shelly1pm-[SHELLY ID]/ext_temperature_f/0

Humidity

If a DHT22 sensor is added, it’ll also report on humdity.

## /sensors/room_x/lamp.yaml

# Humidity sensor 0 %
- platform: mqtt
  name: Room X - lamp - humidity 0
  expire_after: 86400
  qos: 1
  device_class: humidity
  unit_of_measurement: '%'
  icon: mdi:water-percent
  state_topic: shellies/shelly1pm-[SHELLY ID]/ext_humidity/0

Combined sensor output

Returns the output of the attached sensors along with their hardware ID in one JSON payload.

## /sensors/room_x/lamp.yaml

# External tmp sensors °C
- platform: mqtt
  name: Room X - lamp - temperatures
  expire_after: 86400
  qos: 1
  device_class: temperature
  unit_of_measurement: '°C'
  icon: mdi:home-thermometer-outline
  state_topic: shellies/shelly1pm-[SHELLY ID]/ext_temperatures
  json_attributes_topic: shellies/shelly1pm-[SHELLY ID]/ext_temperatures
# External tmp sensors °F
- platform: mqtt
  name: Room X - lamp - temperatures F
  expire_after: 86400
  qos: 1
  device_class: temperature
  unit_of_measurement: '°F'
  icon: mdi:home-thermometer-outline
  state_topic: shellies/shelly1pm-[SHELLY ID]/ext_temperatures_f
  json_attributes_topic: shellies/shelly1pm-[SHELLY ID]/ext_temperatures_f
# External humidity sensors
- platform: mqtt
  name: Room X - lamp - humidities
  expire_after: 86400
  qos: 1
  device_class: humidity
  unit_of_measurement: '%'
  icon: mdi:water-percent
  state_topic: shellies/shelly1pm-[SHELLY ID]/ext_humidities
  json_attributes_topic: shellies/shelly1pm-[SHELLY ID]/ext_humidities

Shelly 2.5

The Shelly 2.5 has 2 switch inputs and 2 relays. These relays can be used to control 2 different loads (e.g. 2 lamps in a room) or to control the up/down motion of rolling shutters.
Make sure to set the device in the correct mode!

Relay Mode

The Shelly 2.5 works similar as the 1PM while in Relay Mode.
Just note that the 2.5 has 2 switch inputs and 2 relay outputs, so you’d need to duplicate configs specific to those, one linked to input/relay 0 and to other to input/relay 1.

Controlling the 2 relays:

## /switches/room_abc/shelly_25.yaml

- platform: mqtt
  name: Shelly 2.5 - relay 1
  payload_on: "on"
  payload_off: "off"
  qos: 1
  state_topic: shellies/shellyswitch25-<deviceid>/relay/0
  command_topic: shellies/shellyswitch25-<deviceid>/relay/0/command
- platform: mqtt
  name: Shelly 2.5 - relay 2
  payload_on: "on"
  payload_off: "off"
  qos: 1
  state_topic: shellies/shellyswitch25-<deviceid>/relay/1
  command_topic: shellies/shellyswitch25-<deviceid>/relay/1/command

Read inputs on the 2 switch inputs:

## /sensors/room_abc/shelly_25.yaml
- platform: mqtt
  name: Shelly 2.5 - input 1
  expire_after: 86400
  qos: 1
  state_topic: shellies/shellyswitch25-<deviceid>/input_event/0
- platform: mqtt
  name: Shelly 2.5 - input 2
  expire_after: 86400
  qos: 1
  state_topic: shellies/shellyswitch25-<deviceid>/input_event/1

Longpush detection on the 2 switch inputs:

## /binsensors/room_abc/shelly_25.yaml
- platform: mqtt
  name: Shelly 2.5 - longpush 1
  expire_after: 86400
  qos: 1
  payload_on: 1
  payload_off: 0
  state_topic: shellies/shellyswitch25-<deviceid>/longpush/0
- platform: mqtt
  name: Shelly 2.5 - longpush 2
  expire_after: 86400
  qos: 1
  payload_on: 1
  payload_off: 0
  state_topic: shellies/shellyswitch25-<deviceid>/longpush/1

Roller Mode

Home Assistant has the cover integration, which we can use to integrate our Shelly 2.5 in Roller Mode.

cover:
  - platform: mqtt
    name: Rolling Shutters
    command_topic: shellies/shellyswitch25-<deviceid>/roller/0/command # rc, open, close and stop
    state_topic: shellies/shellyswitch25-<deviceid>/roller/0 # open, close, stop
    position_topic: shellies/shellyswitch25-<deviceid>/roller/0/pos
    set_position_topic: shellies/shellyswitch25-<deviceid>/roller/0/command/pos
    availability_topic: shellies/shellyswitch25-<deviceid>/online
    json_attributes_topic: shellies/shellyswitch25-<deviceid>/info
    payload_open: open
    payload_close: close
    payload_stop: stop
    state_opening: open
    state_closing: close
    position_open: 100
    position_closed: 0
    payload_available: true
    payload_not_available: false
    qos: 1

switch:
  - platform: mqtt
    name: Rolling Shutters - Calibrate
    command_topic: shellies/shellyswitch25-<deviceid>/roller/0/command
    payload_on: rc
  - platform: mqtt
    name: Rolling Shutters - FW upgrade
    command_topic: shellies/shellyswitch25-<deviceid>/command
    payload_on: update_fw

binary_sensor:
  - platform: mqtt
    name: Rolling Shutters - switch open
    payload_on: 1
    payload_off: 0
    state_topic: shellies/shellyswitch25-<deviceid>/input/0
  - platform: mqtt
    name: Rolling Shutters - switch close
    payload_on: 1
    payload_off: 0
    state_topic: shellies/shellyswitch25-<deviceid>/input/1
  - platform: mqtt
    name: Rolling Shutters - overtemperature
    payload_on: 1
    payload_off: 0
    state_topic: shellies/shellyswitch25-<deviceid>/overtemperature
  - platform: mqtt
    name: Rolling Shutters - firmware available
    payload_on: true
    payload_off: false
    value_template: "{{ value_json.new_fw }}"
    state_topic: shellies/shellyswitch25-<deviceid>/announce

sensor:
  - platform: mqtt
    name: Rolling Shutters - temperature
    device_class: temperature
    unit_of_measurement: '°C'
    state_topic: shellies/shellyswitch25-<deviceid>/temperature
  - platform: mqtt
    name: Rolling Shutters - power consumption
    device_class: power
    unit_of_measurement: 'W'
    state_topic: shellies/shellyswitch25-<deviceid>/roller/0/power
  - platform: mqtt
    name: Rolling Shutters - energy consumption since last reboot
    device_class: energy
    state_class: total_increasing
    unit_of_measurement: 'Wh'
    value_template: "{{ value | float / 60 }}"
    state_topic: shellies/shellyswitch25-<deviceid>/roller/0/energy

Shelly i3

Sensors

## /sensors/room_z/switch.yaml

# Shelly i3 - Input 1
- platform: mqtt
  name: "Room Z - switch - input 1"
  expire_after: 604800
  qos: 1
  state_topic: "shellies/shellyix3-[SHELLY ID]/input_event/0"
# Shelly i3 - Input 2
- platform: mqtt
  name: "Room Z - switch - input 2"
  expire_after: 604800
  qos: 1
  state_topic: "shellies/shellyix3-[SHELLY ID]/input_event/1"
# Shelly i3 - Input 3
- platform: mqtt
  name: "Room Z - switch - input 3"
  expire_after: 604800
  qos: 1
  state_topic: "shellies/shellyix3-[SHELLY ID]/input_event/2"

Binary Sensors

## /binsensors/room_z/switch.yaml

# Online
- platform: mqtt
  name: "Room Z - switch"
  payload_on: true
  payload_off: false
  state_topic: "shellies/shellyix3-[SHELLY ID]/online"
  json_attributes_topic: "shellies/shellyix3-[SHELLY ID]/info"
# Switch 1
- platform: mqtt
  name: "Room Z - switch - switch 1"
  expire_after: 604800
  qos: 1
  payload_on: 1
  payload_off: 0
  state_topic: "shellies/shellyix3-[SHELLY ID]/input/0"
# Switch 2
- platform: mqtt
  name: "Room Z - switch - switch 2"
  expire_after: 604800
  qos: 1
  payload_on: 1
  payload_off: 0
  state_topic: "shellies/shellyix3-[SHELLY ID]/input/1"
# Switch 3
- platform: mqtt
  name: "Room Z - switch - switch 3"
  expire_after: 604800
  qos: 1
  payload_on: 1
  payload_off: 0
  state_topic: "shellies/shellyix3-[SHELLY ID]/input/2"
# Firmware upgrade
- platform: mqtt
  name: "Room Z - switch - firmware"
  state_topic: "shellies/shellyix3-[SHELLY ID]/announce"
  value_template: "{{ value_json.new_fw }}"
  payload_on: true
  payload_off: false

Shelly Plug (S)

The Shelly Plug S added a temperature sensor and overtemperature warning, which the Shelly Plug doesn’t.

Also note the small difference in the model naming when entering the MQTT topic for the Shelly Plug and Shelly Plugs S (shellyplug / shellyplug-s).

Light vs Switch setup

Again, the template below is for configuring the entity to show up as a lamp in HA. E.g. when a floorlamp is connected to the Shelly Plug (S).

If the Plug (S) controls something different, like a fan, you may want to add the config below to a file in the switches folder.

## /lights/room_x/floorlamp.yaml

- platform: mqtt
  name: Room X - floorlamp
  payload_on: "on"
  payload_off: "off"
  qos: 1
  state_topic: "shellies/shellyplug-s-[SHELLY ID]/relay/0"
  command_topic: "shellies/shellyplug-s-[SHELLY ID]/relay/0/command"

Binary Sensors

## /binsensors/room_x/floorlamp.yaml

# Online
- platform: mqtt
  name: "Room X - floorlamp"
  payload_on: true
  payload_off: false
  state_topic: "shellies/shellyplug-s-[SHELLY ID]/online"
  json_attributes_topic: "shellies/shellyplug-s-[SHELLY ID]/info"
# Switch
- platform: mqtt
  name: "Room X - floorlamp - switch"
  expire_after: 604800
  qos: 1
  payload_on: "on"
  payload_off: "off"
  state_topic: "shellies/shellyplug-s-[SHELLY ID]/relay/0"
# Overtemp (Shelly Plug S only)
- platform: mqtt
  name: "Room X - floorlamp - overtemperature"
  state_topic: "shellies/shellyplug-s-[SHELLY ID]/overtemperature"
  payload_on: 1
  payload_off: 0

Sensors

## /sensors/room_x/floorlamp.yaml

# Power consumption
- platform: mqtt
  name: Room X - floorlamp - power
  qos: 1
  expire_after: 86400
  device_class: power
  unit_of_measurement: 'W'
  icon: mdi:lightning-bolt-outline
  state_topic: shellies/shellyplug-s-[SHELLY ID]/relay/0/power
# Energy consumption
- platform: mqtt
  name: Room X - floorlamp - energy
  qos: 1
  expire_after: 86400
  device_class: energy
  state_class: total_increasing
  unit_of_measurement: 'Wh'
  value_template: "{{ value | float / 60 }}"
  icon: mdi:lightning-bolt-outline
  state_topic: shellies/shellyplug-s-[SHELLY ID]/relay/0/energy
# Overpower value
- platform: mqtt
  name: Room X - floorlamp - overpower
  qos: 1
  expire_after: 86400
  device_class: power
  unit_of_measurement: 'W'
  icon: mdi:flash-alert-outline
  state_topic: shellies/shellyplug-s-[SHELLY ID]/overpower_value
# Temperature °C (Shelly Plug S only)
- platform: mqtt
  name: Room X - floorlamp - temperature
  qos: 1
  expire_after: 86400
  device_class: temperature
  unit_of_measurement: '°C'
  icon: mdi:temperature-celsius
  state_topic: shellies/shellyplug-s-[SHELLY ID]/temperature
# Temperature °F (Shelly Plug S only)
- platform: mqtt
  name: Room X - floorlamp - temperature
  qos: 1
  expire_after: 86400
  device_class: temperature
  unit_of_measurement: '°F'
  icon: mdi:temperature-fahrenheit
  state_topic: shellies/shellyplug-s-[SHELLY ID]/temperature_f

Shelly DW2

Shelly’s Door/Window sensor.

Sensors

## /sensors/doors/frontdoor.yaml
- platform: mqtt
  name: "Front door - lux"
  unit_of_measurement: 'lm'
  expire_after: 86400
  device_class: illuminance
  #icon: mdi:theme-light-dark
  qos: 1
  state_topic: "shellies/shellydw2-[SHELLY ID]/sensor/lux"
- platform: mqtt
  name: "Front door - tilt"
  unit_of_measurement: '°'
  expire_after: 86400
  icon: mdi:format-rotate-90
  qos: 1
  state_topic: "shellies/shellydw2-[SHELLY ID]/sensor/tilt"
- platform: mqtt
  name: "Front door - batterij"
  unit_of_measurement: '%'
  expire_after: 86400
  device_class: battery
  #icon: mdi:battery
  qos: 1
  state_topic: "shellies/shellydw2-[SHELLY ID]/sensor/battery"

Binary Sensors

## /binsensors/doors/frontdoor.yaml
- platform: mqtt
  name: "Front door - Status"
  expire_after: 604800
  device_class: door
  payload_on: "open"
  payload_off: "close"
  qos: 1
  state_topic: "shellies/shellydw2-[SHELLY ID]/sensor/state"
- platform: mqtt
  name: "Front door - Vibration"
  expire_after: 604800
  device_class: vibration
  payload_on: 0
  payload_off: 1
  qos: 1
  state_topic: "shellies/shellydw2-[SHELLY ID]/sensor/vibration"
- platform: mqtt
  name: "Front door - Firmware"
  state_topic: "shellies/shellydw2-[SHELLY ID]/announce"
  value_template: "{{ value_json.new_fw }}"
  payload_on: true
  payload_off: false

Shelly EM

Shelly Energy Meter

Sensors

The EM has 2 probes. The config below is for the 1st probe. Copy the all parts in the config for Phase A and replace emeter/0 with emeter/1 for Phase B.

The ‘current’ counters reset on device reboot.
The ’total’ counters are stored in the non-volatile memory.

## /sensors/energy/shelly_em.yaml
- platform: mqtt
  name: "EM - Phase A - Energy"
  value_template: "{{ value|float / 60000 }}" # Wm to kWh
  unit_of_measurement: 'kWh'
  expire_after: 86400
  device_class: energy
  state_class: total_increasing
  qos: 1
  state_topic: "shellies/shellyem-<deviceid>/emeter/0/energy"
- platform: mqtt
  name: "EM - Phase A - Returned Energy"
  value_template: "{{ value|float / 60000 }}"
  unit_of_measurement: 'kWh'
  expire_after: 86400
  device_class: energy
  state_class: total_increasing
  qos: 1
  state_topic: "shellies/shellyem-<deviceid>/emeter/0/returned_energy"
- platform: mqtt
  name: "EM - Phase A - Total Energy"
  value_template: "{{ value|float / 60000 }}"
  unit_of_measurement: 'kWh'
  expire_after: 86400
  device_class: energy
  state_class: total_increasing
  qos: 1
  state_topic: "shellies/shellyem-<deviceid>/emeter/0/total_energy"
- platform: mqtt
  name: "EM - Phase A - Total Returned Energy"
  value_template: "{{ value|float / 60000 }}"
  unit_of_measurement: 'kWh'
  expire_after: 86400
  device_class: energy
  state_class: total_increasing
  qos: 1
  state_topic: "shellies/shellyem-<deviceid>/emeter/0/total_returned"
- platform: mqtt
  name: "EM - Phase A - Power"
  unit_of_measurement: 'W'
  expire_after: 86400
  device_class: power
  qos: 1
  state_topic: "shellies/shellyem-<deviceid>/emeter/0/power"
- platform: mqtt
  name: "EM - Phase A - Reactive Power"
  unit_of_measurement: 'W'
  expire_after: 86400
  device_class: power
  qos: 1
  state_topic: "shellies/shellyem-<deviceid>/emeter/0/reactive_power"
- platform: mqtt
  name: "EM - Phase A - Voltage"
  unit_of_measurement: 'V'
  expire_after: 86400
  device_class: voltage
  qos: 1
  state_topic: "shellies/shellyem-<deviceid>/emeter/0/voltage"

Binary Sensors

Note: this part is untested.
If this doesn’t work, and you know how to fix it, reach out to me on Twitter.

## /binsensors/energy/shelly_em.yaml
- platform: mqtt
  name: "EM - Relay Overpower"
  expire_after: 86400
  qos: 1
  state_topic: "shellies/shellyem-<deviceid>/relay/0" # on, off, or overpower
  value_template: {{ 'on' if value == 'overpower' else 'off' }}

Switches

Note: the value template part is untested.
If this doesn’t work, and you know how to fix it, reach out to me on Twitter.

## /switches/energy/shelly_em.yaml
- platform: mqtt
  name: "EM - Relay"
  expire_after: 604800
  qos: 1
  command_topic: "shellies/shellyem-<deviceid>/relay/0/command"
  state_topic: "shellies/shellyem-<deviceid>/relay/0"
  value_template: {{ 'on' if value == 'on' else 'off' }} # Test for capturing 'overpower' state
- platform: mqtt
  name: "EM - Phase A - Reset Totals"
  expire_after: 604800
  qos: 1
  optimistic: true
  payload_on: "reset_totals"
  payload_off: ""
  command_topic: "shellies/shellyem-<deviceid>/emeter/0/command"
- platform: mqtt
  name: "EM - Reset Device Data"
  expire_after: 604800
  qos: 1
  optimistic: true
  payload_on: "reset_data"
  payload_off: ""
  command_topic: "shellies/shellyem-<deviceid>/command"

Shelly 3EM

Shelly 3-phase Energy Meter

Sensors

The 3EM has 3 probes. The config below is for the 1st probe. Copy the all parts in the config for Phase A and replace emeter/0 with emeter/1 or emeter/2 for Phase B and Phase C respectively.

The ‘current’ counters reset on device reboot.
The ’total’ counters are stored in the non-volatile memory.

## /sensors/energy/shelly_3em.yaml
- platform: mqtt
  name: "3EM - Phase A - Energy"
  value_template: "{{ value|float / 60000 }}" # Wm to kWh
  unit_of_measurement: 'kWh'
  expire_after: 86400
  device_class: energy
  state_class: total_increasing
  qos: 1
  state_topic: "shellies/shellyem3-<deviceid>/emeter/0/energy"
- platform: mqtt
  name: "3EM - Phase A - Returned Energy"
  value_template: "{{ value|float / 60000 }}"
  unit_of_measurement: 'kWh'
  expire_after: 86400
  device_class: energy
  state_class: total_increasing
  qos: 1
  state_topic: "shellies/shellyem3-<deviceid>/emeter/0/returned_energy"
- platform: mqtt
  name: "3EM - Phase A - Total Energy"
  value_template: "{{ value|float / 60000 }}"
  unit_of_measurement: 'kWh'
  expire_after: 86400
  device_class: energy
  state_class: total_increasing
  qos: 1
  state_topic: "shellies/shellyem3-<deviceid>/emeter/0/total_energy"
- platform: mqtt
  name: "3EM - Phase A - Total Returned Energy"
  value_template: "{{ value|float / 60000 }}"
  unit_of_measurement: 'kWh'
  expire_after: 86400
  device_class: energy
  state_class: total_increasing
  qos: 1
  state_topic: "shellies/shellyem3-<deviceid>/emeter/0/total_returned"
- platform: mqtt
  name: "3EM - Phase A - Power"
  unit_of_measurement: 'W'
  expire_after: 86400
  device_class: power
  qos: 1
  state_topic: "shellies/shellyem3-<deviceid>/emeter/0/power"
- platform: mqtt
  name: "3EM - Phase A - Voltage"
  unit_of_measurement: 'V'
  expire_after: 86400
  device_class: voltage
  qos: 1
  state_topic: "shellies/shellyem3-<deviceid>/emeter/0/voltage"
- platform: mqtt
  name: "3EM - Phase A - Current"
  unit_of_measurement: 'A'
  expire_after: 86400
  device_class: current
  qos: 1
  state_topic: "shellies/shellyem3-<deviceid>/emeter/0/current"
- platform: mqtt
  name: "3EM - Phase A - Power Factor"
  # If the PF is returned as a value between 0.0 and 1.0
  # instead of a % value between 0 and 100
  # uncomment the line below
  #value_template: "{{ value|float * 100 }}"
  unit_of_measurement: '%'
  expire_after: 86400
  device_class: power_factor
  qos: 1
  state_topic: "shellies/shellyem3-<deviceid>/emeter/0/pf"

Binary Sensors

Note: this part is untested.
If this doesn’t work, and you know how to fix it, reach out to me on Twitter.

## /binsensors/energy/shelly_3em.yaml
- platform: mqtt
  name: "3EM - Relay Overpower"
  expire_after: 86400
  qos: 1
  state_topic: "shellies/shellyem3-<deviceid>/relay/0" # on, off, or overpower
  value_template: {{ 'on' if value == 'overpower' else 'off' }}

Switches

Note: the value template part is untested.
If this doesn’t work, and you know how to fix it, reach out to me on Twitter.

## /switches/energy/shelly_3em.yaml
- platform: mqtt
  name: "3EM - Relay"
  expire_after: 604800
  qos: 1
  command_topic: "shellies/shellyem3-<deviceid>/relay/0/command"
  state_topic: "shellies/shellyem3-<deviceid>/relay/0"
  # Remove the line below if the value_template doesn't function properly
  value_template: {{ 'on' if value == 'on' else 'off' }} # Test for capturing 'overpower' state
- platform: mqtt
  name: "3EM - Phase A - Reset Totals"
  expire_after: 604800
  qos: 1
  optimistic: true
  payload_on: "reset_totals"
  payload_off: ""
  command_topic: "shellies/shellyem3-<deviceid>/emeter/0/command"
- platform: mqtt
  name: "3EM - Reset Device Data"
  expire_after: 604800
  qos: 1
  optimistic: true
  payload_on: "reset_data"
  payload_off: ""
  command_topic: "shellies/shellyem3-<deviceid>/command"

Shelly 4Pro

Shelly 4-channel DIN mountable relay

Sensors

The 4Pro has 4 channels. The config below is for the 1st channel. Copy the all parts in the config for Channel 1 and replace input/0 and relay/0 with input/1 and relay/1, up to input/3 and relay/3 for channels 2 to 4 respectively.

## /sensors/din/shelly_4pro.yaml
- platform: mqtt
  name: "4Pro - Channel 1 - Power"
  unit_of_measurement: 'W'
  expire_after: 86400
  device_class: power
  qos: 1
  state_topic: "shellies/shelly4pro-<deviceid>/relay/0/power"
- platform: mqtt
  name: "4Pro - Channel 1 - Energy"
  value_template: "{{ value|float / 60000 }}" # Wm to kWh
  unit_of_measurement: 'kWh'
  expire_after: 86400
  device_class: energy
  state_class: total_increasing
  qos: 1
  state_topic: "shellies/shelly4pro-<deviceid>/relay/0/energy"

Binary Sensors

Note: this part is untested.
If this doesn’t work, and you know how to fix it, reach out to me on Twitter.

## /binsensors/din/shelly_4pro.yaml
- platform: mqtt
  name: "4Pro - Channel 1 Overpower"
  expire_after: 86400
  qos: 1
  state_topic: "shellies/shelly4pro-<deviceid>/relay/0" # on, off, or overpower
  value_template: {{ 'on' if value == 'overpower' else 'off' }}
- platform: mqtt
  name: "4Pro - Channel 1 Input"
  expire_after: 86400
  qos: 1
  state_topic: "shellies/shelly4pro-<deviceid>/input/0"
  payload_on: 1
  payload_off: 0

Switches

Note: the value template part is untested.
If this doesn’t work, and you know how to fix it, reach out to me on Twitter.

## /switches/din/shelly_4pro.yaml
- platform: mqtt
  name: "4Pro - Channel 1"
  expire_after: 604800
  qos: 1
  command_topic: "shellies/shelly4pro-<deviceid>/relay/0/command"
  payload_on: "on"
  payload_off: "off"
  state_topic: "shellies/shelly4pro-<deviceid>/relay/0"
  # Remove the line below if the value_template doesn't function properly
  value_template: {{ 'on' if value == 'on' else 'off' }} # Test for capturing 'overpower' state

Groups

I like grouping all entities together for a quick overview

## /groups.yaml

# Room X
## Shelly 1PM
shelly_room_x_lamp:
  name: Shelly Room X lamp
  entities:
  - light.room_x_lamp
  - sensor.room_x_lamp_input
  - sensor.room_x_lamp_temperature
  - sensor.room_x_lamp_temperature_f
  - sensor.room_x_lamp_power
  - sensor.room_x_lamp_energy
  - sensor.room_x_lamp_overpower
  - binary_sensor.room_x_lamp_longpush
  - binary_sensor.room_x_lamp_switch
  - binary_sensor.room_x_lamp_overtemp
  - binary_sensor.room_x_lamp_firmware
  # External sensors
  - sensor.room_x_lamp_temperature_0
  - sensor.room_x_lamp_temperature_0_f
  - sensor.room_x_lamp_humidity_0
  - sensor.room_x_lamp_temperatures
  - sensor.room_x_lamp_temperatures_f
  - sensor.room_x_lamp_humidities

# Room Z
## Shelly i3
shelly_room_z_switch:
  name: Shelly Room Z i3
  entities:
  - sensor.room_z_switch_input_1
  - sensor.room_z_switch_input_2
  - sensor.room_z_switch_input_3
  - binary_sensor.room_z_switch
  - binary_sensor.room_z_switch_switch_1
  - binary_sensor.room_z_switch_switch_2
  - binary_sensor.room_z_switch_switch_3
  - binary_sensor.room_z_switch_firmware

Customisations

Icons

Setting icons for platforms that don’t support it out-of-the-box

# /customisations/customize_glob.yaml

# Longpush
"binary_sensor.*_longpush":
  icon: mdi:gesture-tap-hold

# Switch state
"binary_sensor.*_switch":
  icon: mdi:light-switch

# Over temperature
"binary_sensor.*_overtemperature":
  icon: mdi:thermometer-alert

# Firmware upgrade
"binary_sensor.*_firmware":
  icon: mdi:upload


# /customisations/customize.yaml

# Lights
light.all_lights:
  icon: mdi:lightbulb-group

Changelog

2021-08-30

  • Note on Shelly Gen 2 devices

2021-04-26

2021-03-21

  • Added template for Shelly EM
  • Added template for Shelly 3EM
  • Added template for Shelly 4Pro

2020-11-09

  • Added template for Shelly i3
  • Added template for Shelly Plug S