MQTT is a great protocol to have in your automation arsenal. This article explains how to quickly get started with MQTT using Docker and Home Assistant.
Note: I now use the Eclipse MQTT container and have written an updated MQTT, Docker, and Home Assistant article. I’m leaving this article as a reference.
Table of Contents
What is MQTT and what can I do with it?
MQTT, which stands for Message Queuing Telemetry Transport, is often described as the protocol of the Internet of Things (IOT). It’s a lightweight publish/subscribe system where clients can both publish and subscribe to messages. It works well for IOT devices because it is low-bandwidth.
MQTT uses a broker to facilitate communication between subscribers and publishers. In the diagram above, Home Assistant subscribes to messages published by sensors and jobs. However, Home Assistant can also be a publisher and the clients can also be subscribers.
Common uses of MQTT include:
- Sharing and reacting to sensor information like temperature, humidity, motion, and light levels
- Integrating alarm panels that don’t normally talk to your smarthome hub
- For relays to communicate with home automation controllers to open gates, garage doors, even to control irrigation, heating and cooling systems
- As a substitute for devices that don’t have an API or a standard way to communicate with other devices in your ecosystem. You can build these devices for pennies on the dollar compared to their commercial counterparts
I am currently using MQTT to provide Home Assistant with the status of my home backups and some cron jobs. I also use MQTT to interface with a homebrew garage door controller, temperature/humidity/motion multisensor, and relays that control light switches.
What is Docker?
Docker is a virtualization technology, similar to virtual machines. Instead of virtualizing an entire operating system, Docker allows you to virtualize an application into a container for maximum portability and flexibility. I previously wrote an article about Docker so I won’t go into too much detail here.
What is Home Assistant?
Setting up MQTT in Docker
Picking a broker is the first part of getting started with MQTT. Home Assistant comes with an embedded broker. Cloud-based brokers are popular as well. I went with Mosquitto because it’s popular and there’s a Docker image.
Set up persistent data and base configuration
I chose to go with the Toke Mosquitto container because I easily found good documentation. You should set up persistent data directories and the base configuration file (mosquitto.conf) before starting your container. I’m basing this tutorial on my Ubuntu 18.04 system, but this should work with most Linux systems:
mkdir -p /storage/mosquitto/config mkdir -p /storage/mosquitto/data mkdir -p /storage/mosquitto/log
Replace the directories with whatever is appropriate to you. You should copy a mosquitto.conf file into the “config” directory. My base mosquitto file:
# Place your local configuration in /mqtt/config/conf.d/ pid_file /var/run/mosquitto.pid persistence true persistence_location /mqtt/data/ user mosquitto # Port to use for the default listener. port 1883 log_dest file /mqtt/log/mosquitto.log log_dest stdout include_dir /mqtt/config/conf.d
Create and run the container
Now the easy part, the Docker run command:
sudo docker run -itd \ --name=mqtt \ --restart=always \ --net=host \ -v /storage/mosquitto/config:/mqtt/config:ro \ -v /storage/mosquitto/data:/mqtt/data \ -v /storage/mosquitto/log:/mqtt/log \ toke/mosquitto
This command tells the container to where to look for config, data, and log files. I’ve pointed these to the local directories I set up earlier. My Mosquitto MQTT broker should be up and running now.
To test, install the mosquitto client package:
sudo apt install mosquitto-clients
This will get you access to publish and subscribe commands. First, start by opening a terminal and subscribing to a topic:
mosquitto_sub -h <brokerhost> -t "test"
Replace <brokerhost> with the IP or hostname of your broker. This starts a subscription to any messages that are published with the topic “test.”
In another terminal send a message to the topic test:
mosquitto_pub -h <brokerhost> -t "test" -m "Hello World"
After entering this command, “Hello World” should show up in the terminal where you ran the mosquitto_sub command. If you see it, your broker is working!
As it is currently set up, any client can connect to your broker to publish and subscribe to any topic. You can add some security by requiring a username and password for clients to connect to the broker.
First, you’ll need to create a password file. The best way is to connect to your container and run mosquitto_passwd. In order to connect to your container’s console you need to find out its ID:
This will give you a list of containers and their IDs. Using that ID you can then run:
docker exec -it <containerID> bash
Replacing <containerID> with the container of your Mosquitto container will give you a command line. Alternatively, you can use Portainer to connect directly to the console.
From the console run something similar to:
mosquitto_passwd -c /mqtt/config/credentials <username>
With appropriate filename and username arguments, this command will ask for a password and then create a hashed password file. Then you need to update your Mosquitto config.
If you used a mosquitto.conf file similar to what I posted above you need to create a default.conf file in the conf.d subdirectory of your config directory with the following contents:
allow_anonymous false password_file /mqtt/config/credentials
Remember to use the appropriate password_file path and filename. After restarting the container your publish and subscribe commands will need to have a username and password to work:
mosquitto_sub -h <brokerhost> -t "test" -u "<username>" -P "<password>" mosquitto_pub -h <brokerhost> -t "test" -m "Hello World" -u "<username>" -P "<password>"
You can make your broker more secure by using web sockets or TLS. Digital Ocean has a great tutorial.
Configuring Home Assistant for MQTT
This is as simple as adding the following code to your configuration.yaml:
mqtt: broker: <brokerip> username: <mqtt_username> password: <mqtt_password>
You don’t need the username and password if you did not configure your broker to use one. Then, you want to configure Home Assistant to subscribe to some topics. I decided to test this by subscribing to a topic that displays the time of my last Home Assistant backup:
sensor: - platform: mqtt name: "Last HA config backup" state_topic: "backup/HA"
I added a mosquitto_pub statement to my backup script. It simply sends the time of the last backup to the topic “backup/HA.” Here is the sensor card in the UI that displays the message:
MQTT is cool, solid, and fast. It provides an easy way to pass information. It also makes it easy to integrate inexpensive hardware. Running it in Docker and configuring Home Assistant to use MQTT is a straightforward process.
I have a few MQTT projects upcoming/completed that I’ll write about over the next few weeks:
- Building a smart garage door opener using a Shelly 1 relay
- Putting together an inexpensive multisensor (light, temperature, motion, humidity) based on the NodeMCU
- Using a Shelly 1 relay to add smart control to a light switch
- Adding control and status monitoring of my irrigation system
- Using a Sonoff RF Bridge to enable 433Mhz RF devices to integrate with Home Assistant
As a reminder, I wrote an updated MQTT article that you should use if you are interested in setting it up in Docker.
Are any of you using MQTT? What do you use it for? Let me know in the comments or connect with me on Twitter!
This page contains affiliate links. If you purchase an item using an affiliate link I will receive a small commission at no cost to you. Affiliates do not influence my recommendations. Read my disclosures for more information.