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) .

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
  unique_id: shelly_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
  unique_id: shelly_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
  unique_id: shelly_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
  unique_id: shelly_room_x_lamp_longpush
  expire_after: 86400
  qos: 1
  paylond_on: 1
  payload_off: 0
  state_topic: shellies/shelly1pm-[SHELLY ID]/longpush/0
# Switch state
- platform: mqtt
  name: Room X - lamp - switch
  unique_id: shelly_room_x_lamp_switch
  expire_after: 86400
  qos: 1
  paylond_on: 1
  payload_off: 0
  state_topic: shellies/shelly1pm-[SHELLY ID]/input/0
# Over temp
- platform: mqtt
  name: Room X - lamp - overtemp
  unique_id: shelly_room_x_lamp_overtemp
  expire_after: 86400
  qos: 1
  paylond_on: 1
  payload_off: 0
  state_topic: shellies/shelly1pm-[SHELLY ID]/overtemperature
# Firmware upgrade
- platform: mqtt
  name: Room X - lamp - firmware
  unique_id: shelly_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
  unique_id: shelly_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
  unique_id: shelly_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
  unique_id: shelly_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
  unique_id: shelly_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
  unique_id: shelly_room_x_lamp_energy
  expire_after: 86400
  qos: 1
  device_class: power
  unit_of_measurement: 'Wm'
  icon: mdi:lightning-bolt
  state_topic: shellies/shelly1pm-[SHELLY ID]/relay/0/energy
# Overpower
- platform: mqtt
  name: Room X - lamp - overpower
  unique_id: shelly_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
  unique_id: shelly_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
  unique_id: shelly_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
  unique_id: shelly_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
  unique_id: shelly_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
  unique_id: shelly_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
  unique_id: shelly_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 i3

Sensors

## /sensors/room_z/switch.yaml

# Shelly i3 - Input 1
- platform: mqtt
  name: "Room Z - switch - input 1"
  unique_id: "shelly_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"
  unique_id: "shelly_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"
  unique_id: "shelly_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"
  unique_id: "shelly_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"
  unique_id: "shelly_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"
  unique_id: "shelly_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"
  unique_id: "shelly_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"
  unique_id: "shelly_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
  unique_id: shelly_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"
  unique_id: "shelly_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"
  unique_id: "shelly_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"
  unique_id: "shelly_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
  unique_id: shelly_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
  unique_id: shelly_room_x_floorlamp_energy
  qos: 1
  expire_after: 86400
  device_class: power
  unit_of_measurement: 'Wm'
  icon: mdi:lightning-bolt-outline
  state_topic: shellies/shellyplug-s-[SHELLY ID]/relay/0/energy
# Overpower value
- platform: mqtt
  name: Room X - floorlamp - overpower
  unique_id: shelly_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
  unique_id: shelly_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
  unique_id: shelly_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

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

2020-11-09

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