How to setup Home Assistant, Raspberry Pi and MQTT

There are many ways to get Raspberry Pi to communicate with Home Assistant:

  • Install Home Assistant on the Raspberry Pi and set up native integration (if I have multiple Raspberry Pi?)
  • Let Home Assistant communicates via pigio(daemon) (there are some open issue)
  • Communicate via MQTT message broker

In this post I’m going to describe the third option: integration via MQTT, the best one in my opinion, let me explain why.

Let start with requirements:

  • MQTT broker installed and running (it is suggested to use mosquitto)
  • Home Assistant installed and running
  • A Raspberry Pi

Our goal is the following architecture (arrows mean “dependency”, not the data direction):

┌────────────────┐      ┌────────────────┐      ┌────────────────┐
│                │      │                │      │                │
│ Home Assistant ├──────►      MQTT      ◄──────┤  Raspberry Pi  │
│                │      │                │      │                │
└────────────────┘      └────────────────┘      └────────────────┘

Connect Home Assistant to MQTT broker

The first step is just to connect Home Assistant to MQTT broker, tipically you have to create a “user” in the broker for Home Assistant then setup Home Assistant via integration as well explained in the documentation.

I suggest to read all the Home Assistant documentation about MQTT integration: it is short, simple and really helpful. Have at least a first read, also if you don’t understand everything in the first place, it will be clearer later.

The really interesting part of MQTT integration is the auto-discovery feature. It let you to setup a new device just with a remote message: you don’t need to manually change the Home Assistant configuration and restart it.

Think about it: you can create as many real or virtual device just with a message. Really powerful.

Publish and receive MQTT messages from Raspberry Pi

After reading the Home Assistant documentation and after practise a little with mosquitto_pub/mosquitto_sub it’s easy to write a little bash script for publishing the GPIO of the Raspberry Pi, but we don’t want to write a single line of code 🙂

The solution is mqtt-io, a Python program that publishes the state of Raspberry Pi pins and executes commands received via MQTT. It supports simple binary sensors, but also others more complicated sensors.

To use mqtt-io just write a configuration file (e.g. config.yml) where you setup MQTT credentials, list and describe all your sensors, buttons, switches and so on, then run:

python3 -m mqtt_io /path/to/config.yaml

Entities should automatically appear in Home Assistant MQTT integration. To debug you can listen for all messages from MQTT:

mosquitto_sub --url mqtts://<user>:<pass>@<mqtt.host>:<mqtt.port>/# -v

I recommend to set a static mqtt client id to avoid duplicated entities in Home Assistant.

Automatically start mqtt-io at start-up

To ensure that everything will works after a restart, you can setup a service like the following:

[Unit]
Description=mqtt-io
After=network.target

[Service]
Type=simple
Restart=always
RestartSec=3
ExecStart=python3 -m mqtt_io /path/to/config.yaml

[Install]
WantedBy=multi-user.target

Just copy the file above (remember to replace config file path) at /etc/systemd/system/mqtt-io.service and enable the service with sudo systemctl enable mqtt-io.

Why message broker is the best choice?

I’m a big fan of message broker and pub/sub pattern in general, I think it is simple to use, helps in decoupling and makes the system extendable.
An example? With the architecture just created it easy to extend and add feature with a really cool tool called node-RED: it is out of scope of this post, but have a look at it, is worth.