Quick Answer

MQTT topics are like email addresses for messages. Devices publish to topics, other devices subscribe. Install Mosquitto in HA, use mosquitto_pub to send a test message, mosquitto_sub to receive it, then create an HA sensor that reads from any MQTT topic. The whole thing takes 15 minutes.

Table of Contents

  1. Topics and Payloads Explained
  2. Installing Mosquitto in HA
  3. mosquitto_pub — Send a Message
  4. mosquitto_sub — Receive Messages
  5. HA MQTT Sensor (YAML)
  6. Automation from MQTT Message (YAML)
  7. Troubleshooting
  8. FAQ

What You Need

Topics and Payloads Explained

An MQTT topic is a hierarchical string that identifies where a message goes. Think of it like a folder path: home/bedroom/temperature. Topics use forward slashes to create hierarchy.

The payload is the content of the message — it can be plain text, a number, JSON, or even binary data.

Examples of how smart home devices use topics:

MQTT also supports wildcards:

Installing Mosquitto in HA

  1. Go to Settings → Add-ons → Add-on Store
  2. Search Mosquitto broker → click Install
  3. Enable Start on boot and Watchdog
  4. Click Start — it starts immediately
  5. Go to Settings → Integrations — HA auto-discovers Mosquitto and shows a configure prompt
  6. Click Configure → Submit — the MQTT integration is now active

Mosquitto uses your HA user credentials for authentication. Port 1883 (plain), 8883 (TLS).

mosquitto_pub — Send Your First Message

Install the client tools on your Linux/Mac computer:

Bash — Install
# Ubuntu/Debian:
sudo apt install mosquitto-clients

# macOS:
brew install mosquitto

Now publish a test message. Replace values with your HA IP and credentials:

Bash — Publish a test message
mosquitto_pub \
  -h 192.168.1.100 \
  -p 1883 \
  -u "your_ha_username" \
  -P "your_ha_password" \
  -t "home/test/hello" \
  -m "world"

If no error appears, the message was delivered. Send a JSON payload:

Bash — Publish JSON payload
mosquitto_pub \
  -h 192.168.1.100 \
  -p 1883 \
  -u "your_ha_username" \
  -P "your_ha_password" \
  -t "home/bedroom/sensor" \
  -m '{"temperature": 22.5, "humidity": 60}'

mosquitto_sub — Receive Messages

Bash — Subscribe to all messages (debugging)
mosquitto_sub \
  -h 192.168.1.100 \
  -p 1883 \
  -u "your_ha_username" \
  -P "your_ha_password" \
  -t "#" \
  -v

The -t "#" subscribes to every single topic. The -v flag prints the topic name before each payload. Run this in one terminal window, then publish from another — you'll see messages appear in real time. This is incredibly useful for debugging what your Zigbee2MQTT, Shelly, or other devices are publishing.

To subscribe to a specific path:

Bash — Subscribe to a specific topic
mosquitto_sub \
  -h 192.168.1.100 \
  -p 1883 \
  -u "your_ha_username" \
  -P "your_ha_password" \
  -t "zigbee2mqtt/bedroom-sensor" \
  -v

HA MQTT Sensor (YAML)

Create an HA sensor that reads from an MQTT topic. This is how ESPHome and custom devices get their data into HA:

configuration.yaml — MQTT sensor with JSON payload
mqtt:
  sensor:
    - name: "Bedroom Temperature"
      unique_id: bedroom_temperature_mqtt_v1
      state_topic: "home/bedroom/sensor"
      value_template: "{{ value_json.temperature }}"
      unit_of_measurement: "°C"
      device_class: temperature
      state_class: measurement

    - name: "Bedroom Humidity"
      unique_id: bedroom_humidity_mqtt_v1
      state_topic: "home/bedroom/sensor"
      value_template: "{{ value_json.humidity }}"
      unit_of_measurement: "%"
      device_class: humidity
      state_class: measurement

The value_template uses Jinja2 templating to extract values from JSON payloads. After restarting HA, these sensors appear in your entity list and update whenever a message is published to that topic.

Automation from MQTT Message (YAML)

Trigger an automation when a specific MQTT message arrives:

automations.yaml — React to MQTT payload
automation:
  - alias: "Alert on high temperature (MQTT)"
    trigger:
      - platform: mqtt
        topic: "home/bedroom/sensor"
        value_template: "{{ value_json.temperature | float }}"
        above: 28
    action:
      - service: notify.mobile_app_your_phone
        data:
          title: "Hot bedroom!"
          message: >
            Temperature is {{ trigger.payload_json.temperature }}°C.

  - alias: "Custom device button press"
    trigger:
      - platform: mqtt
        topic: "home/custom-button/action"
        payload: "pressed"
    action:
      - service: light.toggle
        target:
          entity_id: light.bedroom

Troubleshooting

FAQ

How do I find what MQTT topics my devices are using?

Run mosquitto_sub -h YOUR_HA_IP -u USER -P PASS -t "#" -v and watch for messages. Every Zigbee2MQTT device, every Shelly, every MQTT-capable device will show up here. It's the single best debugging tool for MQTT.

What's a "retained" MQTT message?

When you publish with the -r flag (mosquitto_pub ... -r), the broker stores the last message for that topic and immediately delivers it to any new subscriber. This is useful for device state — when HA restarts, it immediately gets the current state of all retained topics.

Can two devices share the same MQTT topic?

Yes, but it causes conflicts unless that's intentional. Best practice: give each device its own unique topic path. Two publishers to the same topic will overwrite each other's state in HA.

Related Articles

SmartWired uses affiliate links. If you buy through our links, we may earn a commission at no extra cost to you. See our Affiliate Disclosure.