MQTT on Home Assistant is one of the most annoying things to figure out. The documentation is extremely minimal, their forum is filled with links to the documentation when people ask about not being able to understand the documentation. I’m keeping notes & warnings here.
There are a few elements of MQTT that are important for this. You might already have some of this set up, if you followed some general Home Assistant getting started guides.
MQTT Broker - We use Mosquitto for this. There are others. This is a service that runs as a messaging hub for the MQTT messages. You can run this on the same device, you can run it on an external server, you can run it in the cloud. This guide is for a local setup, it’s easier to debug.
MQTT Integration in Home Assistant. This is the Home Assistant side that interacts with your MQTT broker. It picks up sensor data & forwards signals to the MQTT broker.
For debugging, here’s what you need:
1. Configuration file editing
You’re going to need to make changes in the main configuration file, /config/configuration.yaml. Go to Supervisor -> Add-on Store & install “File Editor”.
You’ll now see “File Editor” in the sidebar. Click there, click on the “folder” icon top-left, and select the configuration.yaml file. You only have access to this folder.
BTW, after making changes: Click the red save-icon top-right, and reload the configuration into Home Assistant.
a. Configuration -> Server Controls -> Check Configuration. If the configuration file is OK, then proceed. Otherwise fix the file first.
b. Reload either by using Server Management / Restart (on the same page) or by selecting the item in the “YAML configuration reloading” list. If you’re new, just click Restart and wait.
2. Create a user for Mosquitto
You’ll need a Home Assistant user to run for Mosquitto. Let’s add it
first. Configuration -> Users -> Add users (bottom right). You can
use anything. For debugging, let’s keep it simple: Display name:
mqttusername , Username: mqttusername , Password: mqttpassword ; don’t make it
administrator.
3. Install Mosquitto MQTT locally
You can move this to an external device if you want later on. Keep things simple for debugging. Supervisor -> Add-on Store -> “Mosquitto Broker” in the official list on top.
Click on the “Configuration” tab to change the settings for Mosquitto. In particular, use the username & password you created, eg:
{
"logins": [
{
"username": "mqttusername",
"password": "mqttpassword"
}
],
"anonymous": false,
"customize": {
"active": false,
"folder": "mosquitto"
},
"certfile": "fullchain.pem",
"keyfile": "privkey.pem",
"quiet_logs": true
}
Things to watch out for here, as you get started:
- Don’t allow anonymous. There are weird restrictions & username/password is just as easy.
Go back to the Info tab, select “Watchdog” and “Auto-Update”, then click “Start”.
Links:
MQTT Broker settings in HA (didn’t need any of these)
4. Install the MQTT integration
The MQTT integration will take messages sent to the MQTT broker and use them for the sensors you have set up (or will automatically create sensor entries for you, if you use auto-discovery like we want to). Go to Configuration -> Integrations -> Add Integrations -> MQTT. In the options, use:
Broker: 127.0.0.1 (this is the local server IP address)
Port: 1883 (this is the default MQTT port)
Username / Password: the one you set up (mqttusername / mqttpassword in this case)
Done :)
5. Install other useful stuff
Some other tools will make debugging a bit easier. In particular:
Log Viewer - Supervisor -> Add-on Store -> Log Viewer. Enable Auto-update & Show in Sidebar, click Start. This adds “Log Viewer” to the sidebar, which shows your logs & auto-refreshes as new entries are added. It makes recognizing what’s happening a bit easier. (info)
Terminal & SSH - Supervisor -> Add-on Store -> Terminal & SSH. Enable Auto-update & Show in Sidebar, click Start. This gives you a SSH terminal to the Linux command line on your device, where you can issue some commands. This is useful if you want to double-check the local Mosquitto installation, want to monitor the MQTT queue, or try sending MQTT messages for testing. You only have one terminal window to use, so it’s a bit limited, but good enough for the few things we need. (info)
6. Confirm it’s set up properly
Just kidding, you can’t.
Comments / questions
There's currently no commenting functionality here. If you'd like to comment, please use Mastodon and mention me ( @hi@johnmu.com ) there. Thanks!