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.
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:
- Create a new user for MQTT via Configuration -> Users.
Note: This name cannot be homeassistant or addon, those are reserved by the Mosquitto addon.
- Add a
loginssection to the add-on configuration:
# logins:  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 connect to the Cloud anymore.
This means that you’ll lose access to the devices through the Shelly app once you’re no longer connected to your home WiFi. You’ll have to use Home Assistant to manage these devices remotely.
sidenote: My devices did appear to work both with the Cloud and MQTT, at least some of them did, but it’s not a supported configuration.
You can’t configure Shelly’s to use MQTT using the mobile app. You’ll have to use their web interface.
- Locate your device’s IP in your router or open the Shelly app and go to Settings > Device Information.
- Open a web browser and browse to
- Go to Internet & Security > Advanced - Developer Settings
- Tick the checkbox next to Enable action execution via MQTT
- Enter the credentials for the MQTT user account you previously created.
- As server, enter your Home Assistant installation’s internal IP and port 1883. E.g.,
- Do NOT check the Use custom MQTT prefix checkbox.
- 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.
- 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.
- 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.
- In Home Assistant, go to Configuration > Integrations
- Go to the MQTT broker “Mosquitto” and click Configure
- Under Listen to a topic enter
shellies/#and click Start listening
- Under Publish a packet enter
shellies/commandas topic and
announceas 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.
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.
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
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.
I’ll add the filename to the configs below so that you know which header we’re working under.
# 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.
unique_id must be _well_ unique! This is used internally by the MQTT platform.
name will be used for naming the entity. I.e. a light named
Hello World will result in an entity_id of
QoS value needs to match what you’ve configured in the Shelly.
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
In my setup, that would in in
# /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
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.
That’s because the
state is a binary 0/1 (closed/open) while the
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
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.
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.
# 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.
- Updated configurations using
switchfor Shelly relays being used behind a light switch.
- Added light groups
- Added section on customising entities
- Added links to Home Assistant documentation
2020-10-12 (Last updated: 2020-10-13)