Home Assistant MQTT Integration: Complete Setup Guide

Home Assistant MQTT support lets you bring any device that speaks MQTT into your smart home: DIY ESP32 sensors, Tasmota plugs, Zigbee2MQTT networks and industrial gateways alike. In this guide you will configure the Home Assistant MQTT integration, create sensors and switches in YAML, test everything against the public broker at broker.connectmq.com, and then move to a private ConnectMQ broker with TLS.

How Home Assistant Uses MQTT

Home Assistant is not an MQTT broker. Its MQTT integration is a client that connects to a broker, subscribes to state topics and publishes to command topics. Devices are clients of the same broker. The broker sits in the middle and routes messages, which is explained in detail in what an MQTT broker does.

That gives you two hosting choices:

Option	Where the broker runs	Good for	Trade-offs
Mosquitto add-on	On the Home Assistant host	Single home, all devices on the LAN	Remote devices need port forwarding or VPN; you maintain backups
Cloud broker	Hosted, reached over TLS	Devices at several locations, remote sensors, sharing data with other apps	Needs internet; choose a provider you trust
Both, bridged	Local Mosquitto bridged to a cloud broker	Local resilience plus remote access	More configuration

This tutorial uses a cloud broker because it works the same whether Home Assistant runs on a Raspberry Pi, a NUC or a virtual machine. If you want the detailed reasoning and the bridged option, read using an external MQTT broker with Home Assistant.

Step 1: Add the MQTT Integration

Open Settings > Devices & services.
Click Add integration and search for MQTT.
Choose MQTT (not an add-on), and enter the broker details:
- Broker: broker.connectmq.com
- Port: 1883
- Username and password: leave empty for the public test broker
Submit. Home Assistant connects and creates the MQTT integration entry.

To set the client ID, TLS or protocol version, enable Advanced mode in your user profile first. The integration's configuration dialog then shows extra fields such as client ID, keep alive, broker certificate validation, transport (TCP or WebSockets) and MQTT protocol version. You will need these in Step 6.

The public broker needs a non-empty client ID. Home Assistant generates a random one automatically when the field is left empty, which is fine for testing.

Step 2: Check the Connection

Open Settings > Devices & services > MQTT > Configure. This page has a Publish a packet form and a Listen to a topic form.

In Listen to a topic, enter connectmq/demo/ha-x7m2/# and click Start listening. Then, from any computer, publish a test message:

mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-test-x7m2 \
  -t "connectmq/demo/ha-x7m2/test" -m "hello from the terminal"

The message appears in Home Assistant within a second. If it does not, check that Home Assistant's host can reach port 1883 outbound; some networks block it, in which case use 8883 with TLS.

Step 3: Create an MQTT Sensor in YAML

Suppose an ESP32 publishes temperature and humidity as JSON to connectmq/demo/ha-x7m2/livingroom/climate:

{"temperature": 22.7, "humidity": 48.1, "battery": 87}

Add this to configuration.yaml (or a file included from it):

mqtt:
  sensor:
    - name: "Living Room Temperature"
      unique_id: livingroom_temperature_x7m2
      state_topic: "connectmq/demo/ha-x7m2/livingroom/climate"
      value_template: "{{ value_json.temperature }}"
      unit_of_measurement: "°C"
      device_class: temperature
      state_class: measurement
      expire_after: 600

    - name: "Living Room Humidity"
      unique_id: livingroom_humidity_x7m2
      state_topic: "connectmq/demo/ha-x7m2/livingroom/climate"
      value_template: "{{ value_json.humidity }}"
      unit_of_measurement: "%"
      device_class: humidity
      state_class: measurement
      expire_after: 600

unique_id lets you rename the entity and assign it to an area in the UI. expire_after marks the sensor unavailable if no message arrives for ten minutes, which is how you notice a dead battery. state_class: measurement makes long-term statistics work.

Reload with Developer tools > YAML > Manually configured MQTT entities, then simulate the device:

mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-test-x7m2 \
  -t "connectmq/demo/ha-x7m2/livingroom/climate" \
  -m '{"temperature": 22.7, "humidity": 48.1, "battery": 87}'

Step 4: Create an MQTT Switch

A switch needs a command topic that Home Assistant publishes to and a state topic the device reports on:

mqtt:
  switch:
    - name: "Desk Lamp"
      unique_id: desk_lamp_x7m2
      command_topic: "connectmq/demo/ha-x7m2/desk-lamp/set"
      state_topic: "connectmq/demo/ha-x7m2/desk-lamp/state"
      availability_topic: "connectmq/demo/ha-x7m2/desk-lamp/availability"
      payload_on: "ON"
      payload_off: "OFF"
      state_on: "ON"
      state_off: "OFF"
      qos: 1
      retain: false

Put sensors and switches under the same single mqtt: key in your configuration; YAML does not allow the key twice. If you have no hardware yet, play the device yourself:

# act as the device: announce availability and report state
mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-dev-x7m2 -r \
  -t "connectmq/demo/ha-x7m2/desk-lamp/availability" -m "online"
mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-dev-x7m2 -r \
  -t "connectmq/demo/ha-x7m2/desk-lamp/state" -m "OFF"

# watch the commands Home Assistant sends when you flip the switch
mosquitto_sub -h broker.connectmq.com -p 1883 -i ha-dev2-x7m2 \
  -t "connectmq/demo/ha-x7m2/desk-lamp/set" -v

When you toggle the switch in the dashboard, ON appears in the terminal. Publish ON to the state topic to confirm, and the switch stays on. Without a state topic, Home Assistant runs the switch in optimistic mode and simply assumes the command worked.

For lights with brightness, use the light platform with schema: json; the payload format matches the dimmer in our smart lighting MQTT tutorial.

Step 5: A Real Device

The fastest real device is an ESP32 running a short sketch, as in the ESP32 MQTT tutorial, publishing to the same climate topic. ESPHome and Tasmota devices can also publish over MQTT; see ESPHome MQTT. Instead of writing YAML for every entity, those devices can announce themselves automatically through Home Assistant MQTT discovery.

Step 6: Move to a Private Broker with TLS

The free public MQTT broker is perfect for the first hour, but everything on it is readable by everyone, and anyone can publish to your switch's command topic. Your home data belongs on a private broker. There is also a practical reason: the public broker allows 10 subscriptions per client, and Home Assistant subscribes to one topic per entity plus discovery topics, so you reach the limit quickly.

Sign up at the ConnectMQ portal, create a broker and copy the generated username, password and client ID.
In Home Assistant open Settings > Devices & services > MQTT, open the entry's menu and choose Reconfigure (or Configure and then Re-configure MQTT, depending on your version).
Set port 8883, enter the username and password, set the client ID to the issued value, and set broker certificate validation to Auto so the system CA store validates the Let's Encrypt certificate.
Change your topics from connectmq/demo/ha-x7m2/... to your own root, for example home/livingroom/climate, in both the devices and the YAML.

The client ID must match the issued one exactly, because ConnectMQ binds client IDs to credentials. A mismatch shows up as repeated "connection refused, not authorized" lines in the Home Assistant log.

Troubleshooting Checklist

Integration will not connect. Test the same host, port and credentials with mosquitto_sub from another machine.
Entity shows unknown. The device has not published since Home Assistant started. Publish state with the retain flag.
Entity shows unavailable. Either expire_after elapsed or the availability topic says offline.
Template errors in the log. The payload is not the JSON you expect; listen to the topic and compare.
Two brokers fight over one device. A device can connect to only one broker at a time; pick one, or bridge them.
Disconnects every few seconds. Two clients use the same client ID and kick each other off.

Run Home Assistant on ConnectMQ

Create a free Serverless broker at app.connectmq.com, no credit card required. Up to 25 connections cover a typical home, and the live topic explorer in ConnectMQ helps you debug payloads without leaving the browser. If you are wondering how a hosted MQTT broker compares with running Mosquitto yourself, the comparison above and the IoT automation guide will help you decide.

Frequently Asked Questions

Does Home Assistant include an MQTT broker?

No. The MQTT integration is a client. You either install the Mosquitto add-on or connect to an external broker such as ConnectMQ.

Can I use YAML and discovery together?

Yes. YAML-defined entities and discovered entities coexist in the same integration, as long as their unique IDs differ.

Which port should Home Assistant use for a cloud broker?

Use 8883 with TLS. Port 1883 sends credentials and data unencrypted and should only be used for public test data.

Why does my switch turn back off by itself?

The device publishes OFF on the state topic, or a retained OFF message is replayed. Check the state topic with a subscriber and clear stale retained messages.