Setting Up MQTT & Mosquitto in Home Assistant
MQTT is a useful protocol for smart home technology, being designed for the Internet of Things (IoT). It’s a lightweight messaging transport layer that is ideal for connecting remote devices with a minimal network bandwidth — this last part is helpful, as our smart homes are likely to have many devices. With this guide, we’ll set up a MQTT broker in Home Assistant and then configure a device to send messages over MQTT.
Getting Started
To communicate over MQTT, we need an MQTT broker to manage, store and action the messages. Thankfully, Home Assistant has an OOTB integration, called Mosquitto (by Eclipse), which is a well-performing broker.
To locate and install Mosquitto, follow these steps:
- Within your Home Assistant frontend/home navigate to the Supervisor menu
- Select the Add-on Store, and search for Mosquitto
- Click the INSTALL command
For the remainder of the steps, I will share the official instructions (from the Add-On itself). To get the add-on running:
- Start the add-on, by clicking
START - Have some patience and wait a couple of minutes
- Check the add-on Log output to see the result
- Create a new user for MQTT via the
Configuration→Users. Remember this username and password, as we’ll need it later. For this guide, I’ve created a user namedmosquitto, but this could be anything.
Note: This name cannot be homeassistant or addon, those are reserved usernames
Then some final steps and validation:
- Navigate in your Home Assistant frontend to Configuration -> Integrations.
- MQTT should appear as a discovered integration at the top of the page
- Select it and check the box to
Enable MQTT Discoveryif desired, and hitSUBMIT.
Finally, you should see Mosquitto fully set up, like this:
Making It Work
Now with the MQTT broker set up, let’s configure a device to use it. I will use a Shelly 1, but you can use any MQTT device to do this. The steps will differ per device, so refer to that device’s manual. It’s important to know your HA/Mosquitto Broker’s IP address, as well as the username & password you created when we set up Mosquitto, above.
For the Shelly, I head to Internet & Security, and under the ADVANCED — DEVELOPER SETTINGS menu, click the checkbox to select Enable Action Execution via MQTT.
Note: with Shelly, If you enable MQTT, actions via Cloud connection will be disabled
Now, enter the username and password you created when setting up Mosquitto, then enter the Server details; being the IP address of your Home Assistant installation. Remember that the port suffix needs to be :1883. There’s no need to Use Customer MQTT Prefix, but this option is there is you need it.
Leave the Reconnect configurations as default, then ensure Clean Session is selected whilst Retain is unchecked for switches and lights. Lastly, Max QoS being equal to 2 is highly recommended for smart home automation.
Now save settings, and your device is all set up to use MQTT! Remember to check out Defining & Customizing a Shelly Switch via MQTT in Home Assistant, for making the best use of your Mosquitto set up.
