MQTT in a nutshell

First of all: I’m definitely no expert in MQTT (Message Queue Telemetry Transport).
If you want to learn more about how MQTT works, I suggest you watch this video by The Hook Up.

MQTT is a communication protocol clients and servers/brokers can use to send commands and data back and forth.
The MQTT Client publishes MQTT messages to the MQTT Broker. The MQTT Client also subscribes to MQTT topics at the MQTT Broker.
The MQTT Broker receives the published messages, filters them and sends them out to the subscribed MQTT Clients.

A MQTT message could be the current temperature/humidity, the state of a light (on/off, open/closed), and much more.
Subscribed clients can use this data for further processing, to trigger actions, to display in visualisations, etc.

Managing Shelly H&T in Home Assistant using MQTT

I’ll describe how I setup my installation of Home Assistant to make use of MQTT to collect data from my Shelly H&T sensors.

1. Installing the MQTT broker

First of all, we’ll need to install a MQTT broker.

In the Add-on Store, look for and install the Mosquitto broker add-on.

Mosquitto broker in add-on store
Mosquitto broker in add-on store

You’ll need to create one or more MQTT users which will be used by clients to authenticate against the broker. There’re 2 options to do so:

  1. Create a new user for MQTT via Configuration -> Users.
    Note: This name cannot be homeassistant or addon, those are reserved by the Mosquitto addon.

  2. Add a logins section to the add-on configuration:

    logins:
  - username: user
    password: passwd
anonymous: false
customize:
  active: false
  folder: mosquitto
certfile: fullchain.pem
keyfile: privkey.pem
require_certificate: false

Start the add-on and check the logs for errors.

Add the Mosquitto broker as integration via Configuration -> Integrations and configure it by entering the login credentials of the previously created user.

2. Configuring Shelly to communicate over MQTT

Note: Once configured to use MQTT, Shelly devices won’t be able to use Cloud Actions anymore.
This means you won’t be able to trigger an action on a Shelly using a webhook like you would with IFTTT.
However, you can setup a webhook in Home Assistant and point IFTTT there to trigger an action on the Shelly, should you for some reason would still use IFTTT when you already have HA.

You can’t configure Shelly’s to use MQTT using the mobile app. You’ll have to use their web interface.

  1. Locate your device’s IP in your router or open the Shelly app and go to Settings > Device Information.
  2. Open a web browser and browse to http://[Shelly IP] e.g., http://192.168.1.201
  3. Go to Internet & Security > Advanced - Developer Settings
    Developer Settings
    Enabling MQTT via Web UI
  4. Tick the checkbox next to Enable action execution via MQTT
  5. Enter the credentials for the MQTT user account you previously created.
  6. As server, enter your Home Assistant installation’s internal IP and port 1883. E.g., 192.168.1.200:1883.
  7. Do NOT check the Use custom MQTT prefix checkbox.
  8. If you check the checkbox next to Retain each broker that connects with this devices will automatically receive the latest command or status update sent from the Shelly.
    If you don’t want to have automations executing multiple times because the broker reconnected, do not check this box.
  9. If you’re experiencing network issues, set Max QoS to 1 or 2.
    The default of QoS 0 sends out a status update and doesn’t perform any validation of correct receival by the broker.
    QoS 1 and 2 implement a basic or more advanced validation so that the device (and the broker) are sure they’ve received the MQTT message.
  10. Hit Save

While we’re here, I’d suggest to also disable the Cloud connection. We’ll be managing this devices over MQTT from Home Assistant from now on so don’t need this extra network traffic anymore.

3. Testing MQTT connectivity

We’ll want to test whether our devices is talkings to our broker.
This ensures that we’re at least all good up until here.

For this, we’ll listen to all MQTT messages sent by Shelly devices and send out a command to all listening Shelly devices telling them to announce their presence to us.

  1. In Home Assistant, go to Configuration > Integrations
  2. Go to the MQTT broker “Mosquitto” and click Configure
  3. Under Listen to a topic enter shellies/# and click Start listening
  4. Under Publish a packet enter shellies/command as topic and announce as payload and click Publish

Note: If you’re adding/testing battery powered devices, like the Shelly H&T or Shelly DW2, you’ll need to wake them up before pressing the Publish button.

Mosquitto config
Testing MQTT connectivity

You should now see one or more messages appearing in the log below.
For example, you’ll see messages arriving on shellies/[device type]-[device ID/MAC]/announce containing general info on the device.

MQTT message on announce
Announce message from a Shelly 2.5

Note the id somewhere, we’ll need this to add the Shelly to HA.

4. Adding the Shelly to Home Assistant

Home Assistant has the concept of entity types. We’ll mainly be working with light, sensor and binary_sensor.
Each type has some specific configurations. Make sure you configure your device within the correct entity type and use the correct configuration options.

You’ll also see me use the device_class parameter to tell HA which type of entity this is (e.g. door, temperature, battery, …). Check the HA docs for more info on this, since this cannot be used with every entity type.
I’m using this with sensors and binary sensors.

Note: To avoid adding to much clutter to my configuration.yaml file, I’ve setup a tree structure of config files.
If you keep everything within one file, make sure all enitities of the same device type (e.g. lights) are collected under their header (e.g. light:). I’ll add the filename to the configs below so that you know which header we’re working under.

For a set of MQTT templates for Shelly devices, see my blog post: MQTT templates for Shelly devices.

# configuration.yaml
binary_sensor: !include_dir_merge_list binsensors/
sensor: !include_dir_merge_list sensors/
light: !include_dir_merge_list lights/
switch: !include_dir_merge_list switches/

# configuration.yaml
# v binsensors/
#   > mqtt-shelly.yaml
#   > ...
# v sensors/
#   > mqtt-shelly.yaml
#   > ...
# v lights/
#   > mqtt-shelly.yaml
#   > lightgroups.yaml
#   > ...
# v switches/
#   > mqtt-shelly.yaml

Below are a few example of Shelly devices being added over MQTT.
Be sure to use the correct Shelly device ID (e.g. shelly1pm-xxxxxxx).
The unique_id must be _well_ unique! This is used internally by the MQTT platform.
The name will be used for naming the entity. I.e. a light named Hello World will result in an entity_id of light.hello_world.
Finally, the QoS value needs to match what you’ve configured in the Shelly.

You can find more info on the MQTT topics for each device in the Shelly docs.
Be sure to also check the Home Assistant docs on MQTT Light, MQTT Switch, MQTT Sensor, and MQTT Binary Sensor.

a. Shelly 1PM

Adding a Shelly 1PM installed behind a light switch as a light entity in Home Assistant.

Note: If the Shelly is used as a switch (e.g. to switch a fan), configure this under switch instead.
In my setup, that would in in /switches/mqtt-shelly.yaml

# /lights/mqtt-shelly.yaml
- platform: mqtt
  name: "Shelly1PM-example"
  unique_id: "shelly_1pm_example"
  payload_on: "on"
  payload_off: "off"
  qos: 1
  state_topic: "shellies/shelly1pm-xxxxxxx/relay/0"
  command_topic: "shellies/shelly1pm-xxxxxxx/relay/0/command"
  json_attributes_topic: "shellies/shelly1pm-xxxxxxx/info"

b. Shelly 2.5

Note that you’ll need to add an entity for each channel.

It’s also possible to configure one relay as a light and another as a switch.
You’ll have to move the configuration for the specific relay channel to the correct file for this.

# /lights/mqtt-shelly.yaml
- platform: mqtt
  name: "Shelly2.5-example-ch0"
  unique_id: "shelly_25_example_0"
  payload_on: "on"
  payload_off: "off"
  qos: 1
  state_topic: "shellies/shellyswitch25-xxxxxxx/relay/0"
  command_topic: "shellies/shellyswitch25-xxxxxxx/relay/0/command"
  json_attributes_topic: "shellies/shellyswitch25-xxxxxxx/info"
- platform: mqtt
  name: "Shelly2.5-example-ch1"
  unique_id: "shelly_25_example_1"
  payload_on: "on"
  payload_off: "off"
  qos: 1
  state_topic: "shellies/shellyswitch25-xxxxxxx/relay/1"
  command_topic: "shellies/shellyswitch25-xxxxxxx/relay/1/command"
  json_attributes_topic: "shellies/shellyswitch25-xxxxxxx/info"

c. Shelly H&T

Note: This is a sensor, not a light.

The Shelly H&T reports on the room temperature, room humdity and it’s own battery state.
I’m adding the general device attributes (json_attributes_topic) only to the temperature sensor entity.

# /sensors/mqtt-shelly.yaml
- platform: mqtt
  name: "ShellyHT-example-temperature"
  unique_id: "shelly_ht_example_temperature"
  unit_of_measurement: '°C'
  expire_after: 86400
  device_class: temperature
  icon: mdi:home-thermometer-outline
  qos: 1
  state_topic: "shellies/shellyht-xxxxxxx/sensor/temperature"
  json_attributes_topic: "shellies/shellyht-xxxxxxx/announce"
- platform: mqtt
  name: "ShellyHT-example-humidity"
  unique_id: "shelly_ht_example_humidity"
  unit_of_measurement: '%'
  expire_after: 86400
  device_class: humidity
  icon: mdi:water-percent
  qos: 1
  state_topic: "shellies/shellyht-xxxxxxx/sensor/humidity"
- platform: mqtt
  name: "ShellyHT-example-battery"
  unique_id: "shelly_ht_example_battery"
  unit_of_measurement: '%'
  expire_after: 86400
  device_class: battery
  icon: mdi:battery
  qos: 1
  state_topic: "shellies/shellyht-xxxxxxx/sensor/battery"

d. Shelly DW2

Note: Here we’re using 2 different device classes. binary_sensor and sensor. That’s because the state is a binary 0/1 (closed/open) while the lux and battery values have a range of values.

There are more sensors you can collect data on, like vibration or title.
Check the docs. Make sure to use dw2 instead of dw in the topic names!

# /binsensors/mqtt-shelly.yaml
- platform: mqtt
  name: "ShellyDW2-example-Status"
  unique_id: "shelly_dw2_example_state"
  expire_after: 604800
  device_class: door
  payload_on: "open"
  payload_off: "close"
  qos: 1
  state_topic: "shellies/shellydw2-xxxxxxx/sensor/state"
  json_attributes_topic: "shellies/shellydw2-xxxxxxx/announce"

# /sensors/mqtt-shelly.yaml
- platform: mqtt
  name: "ShellyDW2-example-lux"
  unique_id: "shelly_dw2_example_lux"
  unit_of_measurement: 'lm'
  expire_after: 86400
  device_class: illuminance
  icon: mdi:theme-light-dark
  qos: 1
  state_topic: "shellies/shellydw2-xxxxxxx/sensor/lux"
- platform: mqtt
  name: "ShellyDW2-example-battery"
  unique_id: "shelly_dw2_example_battery"
  unit_of_measurement: '%'
  expire_after: 86400
  device_class: battery
  icon: mdi:battery
  qos: 1
  state_topic: "shellies/shellydw2-xxxxxxx/sensor/battery"

e. Shelly 1/1PM/2.5 sensors

The Shelly relays return more than just an on/off state. Depending on the device’s features, it can also report the longpush input, power usage, internal temperature, whether it’s going in safety mode because of an overtemp situation, and more.

# /binsensors/mqtt-shelly.yaml
- platform: mqtt
  name: "Shelly1PM-example-longpush"
  unique_id: "shelly_1pm_example_longpush"
  expire_after: 604800
  payload_on: 1
  payload_off: 0
  qos: 1
  state_topic: "shellies/shelly1pm-xxxxxxx/longpush/0"

# /sensors/mqtt-shelly.yaml
- platform: mqtt
  name: "Shelly1PM-example-input"
  unique_id: "shelly_1pm_example_input"
  qos: 1
  expire_after: 86400
  state_topic: "shellies/shelly1pm-xxxxxxx/input_event/0"
- platform: mqtt
  name: "Shelly1PM-example-temperature"
  unique_id: "shelly_1pm_example_temperature"
  qos: 1
  expire_after: 86400
  device_class: temperature
  unit_of_measurement: '°C'
  icon: mdi:temperature-celsius
  state_topic: "shellies/shelly1pm-xxxxxxx/temperature"
- platform: mqtt
  name: "Shelly1PM-example-power"
  unique_id: "shelly_1pm_example_power"
  qos: 1
  expire_after: 86400
  device_class: power
  unit_of_measurement: 'W'
  icon: mdi:lightning-bolt-outline
  state_topic: "shellies/shelly1pm-xxxxxxx/relay/0/power"

5. Grouping entities

I prefer to group the seperate entities belonging to the same devices together.
This way, I can add the group to my Lovelace dashboard and get a quick glance upon the different entity states.

Note that you need to reference the entitiy_id’s as you find them in the Developer Tools.
The entity_id is based on the name in lowercase, replacing spaces with underscore.

# configuration.yaml
group: !include groups.yaml

# groups.yaml
shelly_shelly1pm-example:
  name: Shelly 1PM example
  entities:
  - light.shelly1pm-example
  - sensor.shelly1pm-example-input
  - sensor.shelly1pm-example-power
  - sensor.shelly1pm-example-temperature
  - binary_sensor.shelly1pm-example-longpush

You can also group lights into a light group.

# configuration.yaml
light: !include_dir_merge_list lights/

# /lights/lightgroups.yaml
- platform: group
  name: All lights
  entities:
  - light.shelly1pm-example
  - light.shelly25-example-ch0
  - light.shelly25-example-ch1

6. Customising entities

If you want to change the icon for a specific light (group), you can do so using customisations.

Check the Material Design Icons cheatsheet for a list of available icons.
Note that recently added icons may not (yet) be availabe in HA.

# configuration.yaml
homeassistant:
  customize: !include customize.yaml

# customize.yaml
lights.all_lights
  icon: mdi:lightbulb-group

light.shelly1pm-example
  icon: mdi:vanity-light

light.shelly25-example-ch0
  icon: mdi:ceiling-light
light.shelly25-example-ch1
  icon: mdi:coach-lamp

Done for now

If everything went well, after a reboot, you should be able to find your lights/sensors/… in the Developer Tools.

You can now add them to your Lovelace dashboard, use them in automations & scripts or even program Node-RED flows with them.

This post is already long enough and I was meaning to only discuss the basics of adding Shelly devices to Home Assistant over MQTT.
In the future, I may write another blog post with more info on fancy automations.

I currently only have Shelly 1PM, Shelly 2.5, Shelly H&T, and Shelly DW2 in my house.
Once I integrate some other devices, like a Dimmer2, RGBW2, 1L, … I’ll either write another post or add more configurations to this post.

That’s all for now.

Hit me up on Twitter if you have any more questions.

Changelogs

2020-10-13

  • Updated configurations using light instead of switch for Shelly relays being used behind a light switch.
  • Added light groups
  • Added section on customising entities
  • Added links to Home Assistant documentation

2020-10-22

  • Fixed incorrect statement stating that enabling MQTT would mean you lose all Cloud connectivity.