LuisLlamas Logo
instalar-usar-broker-mqtt-mosquitto-home-assistant

How to Install and Use MQTT with Mosquitto in Home Assistant

  • 7 min
  • Beginner

MQTT is a lightweight publish-subscribe protocol for exchanging messages between devices and applications.

What happens if we want to integrate data from an industrial programmable logic controller (PLC), a Python script we’ve written to scrape data from a financial website, or the Zigbee2MQTT software we saw in previous categories into Home Assistant?

In home automation, it is used to connect systems that do not share a manufacturer or language. Although historically the name was associated with MQ Telemetry Transport, MQTT is now the official name, not an acronym we need to expand.

What is MQTT and why is it essential?

Historically, on the web, we have used the HTTP protocol based on the Client-Server model. In HTTP, if we want to know the temperature of a sensor, the client has to constantly ask the server: “What’s the temperature? And now? And now?” (known as Polling). This consumes a lot of bandwidth and energy.

MQTT solves this problem using a completely different paradigm: the Publish/Subscribe (Pub/Sub) model.

In an MQTT architecture, there are three fundamental pieces:

  1. The Broker (The central server): It is the conductor. It receives all messages from sending devices and is responsible for instantly distributing them to devices interested in that information.
  2. Publishers: Devices or scripts that generate data and send it to the Broker.
  3. Subscribers: Devices or programs that connect to the Broker and say: “Notify me immediately if information about this specific topic arrives”.

The great architectural advantage of MQTT is decoupling. The living room thermometer (Publisher) doesn’t need to know the IP address or the language Home Assistant (Subscriber) is programmed in. Both only need to know the Broker’s IP. The Broker acts as an absolute intermediary.

Information structure: topics and payloads

So the Broker knows who to send each message to, MQTT does not use destination IP addresses, but instead uses Topics.

Topics

A Topic is simply a text string that acts as a routing channel. It is structured hierarchically using forward slashes (/), very similar to folders on a hard drive.

Examples of well-structured Topics:

  • house/ground_floor/living_room/temperature
  • house/garage/door/status
  • zigbee2mqtt/hallway_motion_sensor

Subscribers can subscribe to an exact topic, or use Wildcards to listen to multiple channels at once.

  • The + wildcard replaces a single level: Subscribing to house/+/temperature will give us the temperature of all rooms.
  • The # wildcard replaces all remaining levels: Subscribing to zigbee2mqtt/# will deliver absolutely all messages generated by our Zigbee network.

The payload

The Payload is the actual content of the message. For the MQTT Broker, the payload is simply a block of raw bytes; it doesn’t care what it contains.

In home automation, the payload is often a simple number (22.5), a text string (on), or, in advanced integrations like Zigbee2MQTT, a JSON object that groups multiple pieces of data into a single message:

{
  "temperature": 22.5,
  "humidity": 45,
  "battery": 98,
  "link_lqi": 255
}
Copied!

QoS and retained messages

MQTT has two concepts worth knowing from the start: QoS (Quality of Service) and Retain.

QoS indicates the delivery guarantee level of the message. For most household sensors, QoS 0 is usually sufficient. For important commands or states, some systems use QoS 1, which guarantees the message is delivered at least once. As almost always, more guarantee implies a bit more complexity.

The Retain flag tells the Broker to save the last message of a Topic and automatically deliver it to any client that subscribes later. This is very useful for states: if Home Assistant restarts, it can retrieve the last known value of house/living_room/temperature without waiting for the sensor to publish again.

Do not use retain without thinking about all messages. It makes sense for states. It can be dangerous for commands. If you retain a command like open_garage, a client connecting later might receive it and execute it out of context. And that’s not so fun anymore.

Installing Mosquitto on Home Assistant OS

There are many MQTT brokers, such as EMQX or HiveMQ. For a home installation, one of the most widespread and lightweight options is Eclipse Mosquitto.

Mosquitto is written in C and consumes few resources for a normal home installation.

Step 1: Install and start Mosquitto

The simplest way is to install the official Mosquitto broker add-on from Home Assistant. When configuring the MQTT integration with this add-on, Home Assistant can automatically generate and manage its internal credentials.

  1. Go to Settings > Add-ons.
  2. Open the add-on store and search for Mosquitto broker.
  3. Install it and make sure to check the “Start on boot” and “Watchdog” options.
  4. Start the add-on.

At the network level, Mosquitto will open the standard port 1883 (TCP) on your Home Assistant server’s IP address (e.g., 192.168.1.50). All your physical devices on the local network should point to that IP and that port.

That port 1883 should stay inside your local network. Do not expose MQTT directly to the Internet unless you know very well what you are doing and have TLS, strong authentication, and a real need. For a normal home, there is no need.

Step 2: Create credentials for other clients

For Zigbee2MQTT, microcontrollers, or other external clients, we will add specific users in the Mosquitto add-on configuration. It is not advisable to share a single password among all devices if we can avoid it.

Step 3: Configure the MQTT integration

The add-on is the server, while the MQTT integration turns Home Assistant into a client. They are two different pieces, although the current wizard can configure them together.

  1. Go to Settings > Devices & Services > Integrations.
  2. Home Assistant should detect Mosquitto and show an “MQTT” card with the “Configure” button.
  3. If it doesn’t appear, add the MQTT integration and follow the wizard. Do not enter 127.0.0.1 out of habit: the address depends on where the broker is running.

MQTT Discovery: automatic entities

If you have set everything up correctly, you now have a two-way data highway ready for use.

You could create entities manually in your configuration.yaml file by telling Home Assistant: “Create a temperature sensor and read its value from the house/living_room/temp topic”. However, this is tedious work.

To solve this, Home Assistant introduced the MQTT Discovery protocol. If a device (like Zigbee2MQTT or an advanced script) supports this standard, it will publish a special JSON message on the configuration topic (typically under the homeassistant/sensor/... hierarchy).

This message contains the name, icon, unit, and data topics. Home Assistant reads it and creates the entities automatically, without us having to declare them one by one in YAML.

The essential tool: MQTT Explorer

When working with MQTT in maker integrations or when writing our own Python scripts, the biggest problem is that messages travel invisibly over the network. If Home Assistant doesn’t show the data, we don’t know if the fault lies with the publisher, the entity configuration, or the network.

To debug these issues, it’s very useful to use a client that allows inspecting topics and payloads.

The standard tool in the industry is MQTT Explorer (free and available for Windows, Mac, and Linux). By connecting it to your server (using the Home Assistant IP, port 1883, and your mqtt_user), this tool will graphically and immediately show you the complete hierarchical tree of all Topics currently circulating on your Broker, the content of their payloads, and a historical log of values.

It is the equivalent of a simplified WireShark focused exclusively on your IoT layer.

Mosquitto allows us to connect Zigbee2MQTT, scripts, and third-party equipment without coupling them directly to Home Assistant.

On this page