MQTT for Smart Homes: Beginner's Guide with Real Examples

Quick Answer

MQTT is a lightweight messaging protocol that smart home devices use to talk to each other. Devices publish messages to topics on a central broker (like Mosquitto), and other devices or services subscribe to those topics. In Home Assistant, install the Mosquitto add-on, configure the MQTT integration, and your devices can send and receive real-time state updates locally — no cloud required.

What MQTT Is
Broker vs Client
Installing Mosquitto in HA
Your First Publish (bash)
Your First Subscribe (bash)
HA MQTT Sensor (YAML)
Automation from MQTT
Troubleshooting
FAQ

What You Need

A running Home Assistant instance
Mosquitto MQTT Broker add-on (free, from HA add-on store)
mosquitto-clients installed on your computer (for testing)

What MQTT Is

MQTT stands for Message Queuing Telemetry Transport. It was designed in the late 1990s for satellite telemetry — environments where bandwidth is limited and connections are unreliable. That makes it perfect for IoT and smart home devices.

The core idea is simple: devices don't talk directly to each other. Instead, they all talk to a central server called a broker. A device publishes a message to a topic, and any device that's subscribed to that topic receives it instantly.

Example: Your temperature sensor publishes 22.5 to the topic home/bedroom/temperature. Home Assistant is subscribed to that topic and immediately reads the new value.

Broker vs Client

Broker: The central server that receives all messages and routes them to subscribers. You run one broker for your whole home. Mosquitto is the most popular open-source MQTT broker and runs as a Home Assistant add-on.

Client: Any device or software that connects to the broker. Clients can publish (send) messages, subscribe (receive) messages, or both. Your Shelly switch, your ESPHome sensor, Zigbee2MQTT, Node-RED — all of these are clients.

Topic: A string that acts like an address for messages. Topics are hierarchical, separated by slashes: home/living-room/light/state. You can subscribe to wildcards: home/living-room/# gets all messages under that path.

Payload: The content of a message. Can be plain text (ON, 22.5), JSON ({"temperature": 22.5, "humidity": 65}), or binary data.

Installing Mosquitto in Home Assistant

Go to Settings → Add-ons → Add-on Store
Search for Mosquitto broker and click Install
Enable Start on boot and Watchdog
Click Start
Go to Settings → Integrations → MQTT — HA auto-discovers the local Mosquitto broker
Click Configure and accept the auto-detected settings

Mosquitto creates credentials automatically using your HA user accounts. The broker listens on port 1883 (unencrypted, local network only) by default.

Your First Publish

Install the Mosquitto client tools on your computer:

Bash — Install mosquitto clients

# On Ubuntu/Debian:
sudo apt install mosquitto-clients

# On macOS with Homebrew:
brew install mosquitto

Now publish a message to your broker. Replace 192.168.1.100 with your HA IP address, and use your HA username/password:

Bash — Publish a message

mosquitto_pub \
  -h 192.168.1.100 \
  -p 1883 \
  -u "your_ha_username" \
  -P "your_ha_password" \
  -t "home/test/message" \
  -m "Hello from terminal"

If it works with no errors, the message was delivered to the broker. Now subscribe to see it.

Bash — Subscribe to a topic

mosquitto_sub \
  -h 192.168.1.100 \
  -p 1883 \
  -u "your_ha_username" \
  -P "your_ha_password" \
  -t "home/test/#" \
  -v

The -t "home/test/#" subscribes to all topics under home/test/. The -v flag prints the topic name alongside the message. Leave this running in one terminal, then publish from another — you'll see messages arrive in real time.

Tip: Subscribe to # (all topics) to see everything flowing through your broker while debugging: -t "#". You'll immediately see Zigbee2MQTT, your devices, and HA all chatting.

HA MQTT Sensor in YAML

Add this to your configuration.yaml to create a sensor that reads from an MQTT topic:

configuration.yaml — MQTT sensor

mqtt:
  sensor:
    - name: "Bedroom Temperature"
      unique_id: bedroom_temperature_mqtt
      state_topic: "home/bedroom/temperature"
      unit_of_measurement: "°C"
      device_class: temperature
      value_template: "{{ value_json.temperature }}"
      availability_topic: "home/bedroom/status"
      payload_available: "online"
      payload_not_available: "offline"

This sensor listens on home/bedroom/temperature and expects a JSON payload like {"temperature": 22.5, "humidity": 65}. The value_template extracts just the temperature value.

Restart HA after adding this. The new sensor appears under Settings → Devices & Services → Entities.

Tip: From HA 2023.6+, you can also configure MQTT sensors entirely via the UI under the MQTT integration. The YAML approach still works and is preferred for version-controlled setups.

Automation from an MQTT Message

Trigger an HA automation when an MQTT message arrives:

automations.yaml — MQTT trigger

automation:
  - alias: "Alert when temperature too high"
    trigger:
      - platform: mqtt
        topic: "home/bedroom/temperature"
        value_template: "{{ value_json.temperature | float }}"
        above: 28
    action:
      - service: notify.mobile_app_your_phone
        data:
          title: "Temperature Alert"
          message: "Bedroom is {{ trigger.payload_json.temperature }}°C — open a window!"

Troubleshooting

Entities don’t appear in Home Assistant: Confirm the integration is loaded correctly and double-check that the device is supported by the platform you chose.
Commands feel delayed: This is usually caused by cloud polling, weak Wi-Fi, or a slow Zigbee mesh rather than Home Assistant itself.
Things work in the vendor app but not in HA: Re-check credentials, local API permissions, and whether the device is using the correct network path.
Automations misfire: Open the automation trace in Home Assistant and verify the exact entity IDs and state changes being used.

FAQ

Is MQTT secure on my local network?

MQTT on port 1883 is unencrypted — fine for a trusted local network behind a router. For internet-facing brokers, use TLS on port 8883 and require authentication. Never expose port 1883 to the internet.

Do I need MQTT if I use ZHA?

No — ZHA doesn't use MQTT. You only need MQTT if you're using Zigbee2MQTT, Shelly devices, ESPHome (optionally), or custom sensors that publish to MQTT topics.

What's the difference between QoS 0, 1, and 2?

QoS (Quality of Service) controls delivery guarantees. QoS 0 = fire and forget (fastest, may lose messages). QoS 1 = at least once delivery. QoS 2 = exactly once. For smart home use, QoS 1 is usually the right balance.

Can multiple devices publish to the same topic?

Yes, but it causes conflicts unless that's intentional. Best practice: each device has a unique topic path (home/room/device-name/state), and a controller (like HA) subscribes to all of them.

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.