10 minutes
Getting started with MQTT and Home Assistant (and Shelly)
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
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.
- 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
http://[Shelly IP]
e.g.,http://192.168.1.201
- Go to Internet & Security > Advanced - Developer Settings
Enabling MQTT via Web UI - 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.,
192.168.1.200:1883
. - 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/command
as topic andannounce
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.

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.

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 ofswitch
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.
Home Automation Home Assistant MQTT Shelly Message Queue Telemetry Transport
1998 Words
2020-10-12 (Last updated: 2020-10-22)