Setting up MQTT Broker for DIY Home Assistant Sensors

This post may contain affiliate links. Please read my disclaimer for more info.

I’m planning on creating some DIY sensors and switches across my house (more on that in future posts!) and was looking for a good way to communicate over WiFi with them from Home Assistant.

If you’ve never heard of MQTT it is described as a “publish-subscribe-based messaging protocol that works on top of TCP/IP”. It works especially well in small code footprint areas like microcontrollers. It is commonly used for this type of application and I decided to go with it for my home automation projects.

Below is a data flowchart for what I’m wanting to eventually get to. My DIY sensors will publish and subscribe to separate MQTT “topics”. When the value of their state changes they push that data to the topic which Home Assistant subscribes to. Home Assistant reads the data from the topic and displays it in the UI. The data can work the other way too when a user activates a switch in the Home Assistant UI (or via an automation) it publishes to an MQTT topic that an DIY IoT switch subscribes to. Essentially, the MQTT broker enables two way messaging between any connected devices and my Home Assistant installation.

Setting up the Broker

MQTT uses a “broker” for the communication. In practice, this means that all the clients do not need to know about each other, they just pass messages around on the various “topics” listed on the broker.

Let’s go ahead and get the broker up and running, I’ll be running it on a Raspberry Pi 3+ using Docker Compose. I plan on using this on the same Pi I run Home Assistant, my docker-compose.yml file looks like this:

version: "3"
 
services:
  homeassistant:
    image: homeassistant/raspberrypi3-homeassistant:0.68.1
    volumes:
      - /home/pi/home-assistant-config/configuration:/config
      - /etc/localtime:/etc/localtime:ro
    network_mode: "host"
    ports:
      - "8123:8123"
    devices:
      - "/dev/ttyACM0:/dev/zwave:rmw"
    depends_on:
      - mosquitto
  mosquitto:
    image: leojrfs/mosquitto-arm:latest
    volumes:
      - /var/mosquitto/data:/mosquitto/data
      - /var/mosquitto/log:/mosquitto/log
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf
    network_mode: "host"
    ports:
      - "1883:1883"
      - "9001:9001"

version: "3"

services:

homeassistant:

image: homeassistant/raspberrypi3-homeassistant:0.68.1

volumes:

- /home/pi/home-assistant-config/configuration:/config

- /etc/localtime:/etc/localtime:ro

network_mode: "host"

ports:

- "8123:8123"

devices:

- "/dev/ttyACM0:/dev/zwave:rmw"

depends_on:

- mosquitto

mosquitto:

image: leojrfs/mosquitto-arm:latest

volumes:

- /var/mosquitto/data:/mosquitto/data

- /var/mosquitto/log:/mosquitto/log

- ./mosquitto.conf:/mosquitto/config/mosquitto.conf

network_mode: "host"

ports:

- "1883:1883"

- "9001:9001"

Some interesting notes:

We are using the Mosquitto project for our MQTT broker
Two ports need to be exposed from the docker container, 1883 and 9001
Home Assistant now depends on Mosquitto for operation
A configuration file mosquitto.conf should be present in the same directory as the docker-compose.yml file. This file is mounted into the container in the config directory.
The /var/mosquitto/data and /var/mosquitto/log directories need to be created on the docker host for mosquitto to store its data and logs.

My mosquitto.conf file (should be in same directory as docker-compose.yml):

persistence true
persistence_location /mosquitto/data/
 
log_dest file /mosquitto/log/mosquitto.log

persistence true

persistence_location /mosquitto/data/

log_dest file /mosquitto/log/mosquitto.log

Now create the directories needed for Mosquitto. Note that we need to set them to 777 permissions because the user within the docker container will have a different UID but still needs access to writing to these directories.

sudo mkdir -p /var/mosquitto/data
sudo mkdir -p /var/mosquitto/log
sudo chmod -R 777 /var/mosquitto

sudo mkdir -p /var/mosquitto/data

sudo mkdir -p /var/mosquitto/log

sudo chmod -R 777 /var/mosquitto

After writing up the docker-compose.yml file, mosquitto.conf and creating the needed directories you can boot up your MQTT broker with:

docker-compose up -d mosquitto

1	docker-compose up -d mosquitto

Testing the Broker

Now that the broker should be running we can test it out by subscribing and publishing to a topic.

From my development machine, I installed the mosquitto package to get the publish and subscribe clients available. Check the mosquitto docs for more information on how to install it on your platform.

Next, start subscribing to a topic by using the mosquitto_sub command.

mosquitto_sub -h ha.local -v -t "home-assistant/#"

1	mosquitto_sub -h ha.local -v -t "home-assistant/#"

Make sure to change the hostname from ha.local to whatever the host is running your MQTT broker. This starts a process that subscribes to the topic and waits for new data.

Now, open up a second terminal for a new process and run the publisher using the mosquitto_pub command.

mosquitto_pub -h ha.local -t home-assistant/switch/1/on -m "Switch is ON"

1	mosquitto_pub -h ha.local -t home-assistant/switch/1/on -m "Switch is ON"

(Again make sure to change the hostname to match your system). You should see the message pop up in the subscriber terminal. If so, your MQTT broker is up and running!

Integrating with Home Assistant

Adding the MQTT broker to Home Assistant is really easy, especially if you’ve already confirmed that the broker is working correctly. All you need to do is modify your Home Assistant configuration.yaml with the following:

mqtt:
  broker: localhost
  port: 1883

mqtt:

broker: localhost

port: 1883

Make sure to change localhost to the hostname running your MQTT broker if you didn’t run it on the same machine.

Reboot Home Assistant after making that change and if no errors pop up in the Home Assistant UI it should be working correctly.

Coming soon will be some blog posts where I develop some DIY sensors and switches and use MQTT to control them. Stay tuned! Some other interesting things to do now would be:

Secure the broker with a password and SSL
Use a GPS application like OwnTracks or Zanzito to send GPS over MQTT to Home Assistant for presence detection
WiFI sensors that publish and read data over MQTT