MQTT Guide

What is MQTT?

MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol designed for IoT devices. Think of it as a bulletin board where devices post messages (publish) and read messages (subscribe).

The MQTT configured card let's your control parameters explained below

Real-World Analogy

Imagine a post office with mailboxes:

• Topics = Mailbox addresses (e.g., home/kitchen/temperature)
• Publish = Putting a letter in a mailbox
• Subscribe = Checking a mailbox for new mail
• Broker = The post office that manages all mailboxes
• Payload = The message content
• QoS = Delivery guarantee (regular mail vs. certified mail)
• Retain = Leaving a copy on the bulletin board for newcomers

Core MQTT Concepts

1. Topics (The Address)

Topics are hierarchical paths separated by forward slashes (/), like file system paths:

home/livingroom/temperature
home/livingroom/humidity
home/bedroom/light/state
home/bedroom/light/brightness
zigbee2mqtt/motion_sensor/occupancy
tasmota/relay/power

Topic Structure Best Practices:

• Start with your system/domain: home/, zigbee2mqtt/, tasmota/
• Add location: livingroom/, bedroom/, outdoor/
• Add device/function: temperature, humidity, light/state
• Keep it readable and consistent

Topic Wildcards (for subscribing only):

• + = Single level wildcard
  • home/+/temperature matches home/livingroom/temperature and home/bedroom/temperature
• # = Multi-level wildcard (must be at the end)
  • home/# matches everything under home/
  • # matches ALL topics (use with caution!)

2. Publish vs Subscribe

Operation	What It Does	Example
Subscribe	Listen for messages on a topic	Read temperature from sensor
Publish	Send a message to a topic	Turn on a light

JSON Path Extraction

For complex JSON payloads:

{
  "sensor": {
    "temperature": {
      "value": 22.5,
      "unit": "C"
    }
  }
}

You might need to access sensor.temperature.value.

Protocol Wizard tip: Create a string entity first, examine the JSON, then create targeted entities.

Additional Resources

Official Documentation

• MQTT.org - Official MQTT specification
• Mosquitto - Popular open-source broker
• HiveMQ - Excellent MQTT tutorials

Tools

• MQTT Explorer - Best desktop MQTT client
• MQTT.fx - Alternative GUI client
• mosquitto_pub / mosquitto_sub - Command-line tools

Common Integrations

• Zigbee2MQTT - Zigbee devices
• Tasmota - ESP8266/ESP32 firmware
• ESPHome - ESP device framework
• Node-RED - Visual MQTT programming

Quick Reference Card

┌─────────────────────────────────────────────┐
│ MQTT Quick Reference                        │
├─────────────────────────────────────────────────┤
│ Topic:      home/livingroom/temperature         │
│ Payload:    22.5                                │
│ QoS:        0 = fast, 1 = reliable, 2 = sure    │
│ Retain:     Save last message on broker         │
│ Wildcards:  + (one level), # (all levels)       │
│                                                 │
│ Common Commands:                                │
│ • Explore: Topic = #                            │
│ • Publish: Set value → Write                    │
│ • Subscribe: Set topic → Read                   │
│ • Entity: Read → Create Entity                  │
└─────────────────────────────────────────────────┘

Next Steps

1. Explore your network: Topic = #, click Read
2. Find interesting topics: Look for sensors, switches
3. Create entities: Make permanent sensors from topics
4. Test commands: Publish to /set topics to control devices
5. Build automations: Use your new entities in HA automations!

---

Need help? Open an issue on GitHub or check existing wiki pages!

# MQTT Protocol Guide

What is MQTT?

MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol designed for IoT devices. Think of it as a bulletin board where devices post messages (publish) and read messages (subscribe).

Real-World Analogy

Imagine a post office with mailboxes:

• Topics = Mailbox addresses (e.g., home/kitchen/temperature)
• Publish = Putting a letter in a mailbox
• Subscribe = Checking a mailbox for new mail
• Broker = The post office that manages all mailboxes
• Payload = The message content
• QoS = Delivery guarantee (regular mail vs. certified mail)
• Retain = Leaving a copy on the bulletin board for newcomers

Core MQTT Concepts

1. Topics (The Address)

Topics are hierarchical paths separated by forward slashes (/), like file system paths:

home/livingroom/temperature
home/livingroom/humidity
home/bedroom/light/state
home/bedroom/light/brightness
zigbee2mqtt/motion_sensor/occupancy
tasmota/relay/power

Topic Structure Best Practices:

• Start with your system/domain: home/, zigbee2mqtt/, tasmota/
• Add location: livingroom/, bedroom/, outdoor/
• Add device/function: temperature, humidity, light/state
• Keep it readable and consistent

Topic Wildcards (for subscribing only):

• + = Single level wildcard
  • home/+/temperature matches home/livingroom/temperature and home/bedroom/temperature
• # = Multi-level wildcard (must be at the end)
  • home/# matches everything under home/
  • # matches ALL topics (use with caution!)

2. Publish vs Subscribe

Operation	What It Does	Example
Subscribe	Listen for messages on a topic	Read temperature from sensor
Publish	Send a message to a topic	Turn on a light

Common Pattern:

Device publishes → Topic: home/sensor/temperature → Payload: "22.5"
Home Assistant subscribes → Topic: home/sensor/temperature → Receives: "22.5"

3. Payload (The Message)

The actual data being sent. Can be:

• Plain text: 22.5, ON, connected
• JSON: {"temperature": 22.5, "humidity": 65}
• Binary: Raw bytes (less common)

Examples:

Topic: home/light/state      Payload: ON
Topic: home/sensor/temp      Payload: 22.5
Topic: zigbee2mqtt/sensor    Payload: {"temperature":22.5,"humidity":65,"battery":100}

4. QoS (Quality of Service)

How reliably the message is delivered:

QoS	Name	Guarantee	When to Use
0	At most once	Fire and forget, no guarantee	Frequent sensor data (temperature every second)
1	At least once	Acknowledged, may duplicate	Important commands (turn light on)
2	Exactly once	Guaranteed once, no duplicates	Critical data (payment, alarm)

Visual Example:

QoS 0: 📨 → [might arrive, might not]
QoS 1: 📨 → ✓ [arrived, might arrive again]
QoS 2: 📨 → ✓✓ [arrived exactly once]

99% of the time, use QoS 0 or 1.

5. Retain Flag

When retain = true, the broker saves the last message and immediately sends it to new subscribers.

Without Retain:

1. Light publishes: "ON"
2. You restart Home Assistant
3. You have no idea if light is ON or OFF until next message

With Retain:

1. Light publishes: "ON" (retained)
2. You restart Home Assistant
3. Broker immediately sends "ON" to you
4. You know current state immediately!

When to use retain:

• ✅ Device state: ON/OFF
• ✅ Configuration: {"mode": "auto"}
• ✅ Status: online/offline
• ❌ Sensor readings: 22.5 (changes frequently)
• ❌ Commands: TOGGLE (one-time action)

Using MQTT in Protocol Wizard

Step 1: Set Up MQTT Broker

If you don't have a broker yet:

1. Install Mosquitto Add-on (easiest):

   • Settings → Add-ons → Add-on Store
   • Search "Mosquitto broker"
   • Install and Start
   • Configuration → Set anonymous: true for testing

2. Or use external broker:

   • Mosquitto on Raspberry Pi
   • CloudMQTT
   • HiveMQ

Step 2: Add MQTT Device in Protocol Wizard

1. Settings → Devices & Services → Protocol Wizard
2. Click "Add Integration"
3. Select MQTT protocol
4. Enter broker details:
   • Broker: localhost (or IP address)
   • Port: 1883 (default unencrypted)
   • Username: (leave empty if anonymous)
   • Password: (leave empty if anonymous)
   • Update Interval: 30 seconds (for polling entities)

Step 3: Explore with the Card

A. Discover What's on Your Network

Topic: #
Wait Time: 5
Click: Read

This subscribes to ALL topics and shows you everything flowing through your broker! 🎉

You might see:

• zigbee2mqtt/bridge/state → online
• homeassistant/sensor/temp/state → 22.5
• tasmota/device/POWER → ON

B. Subscribe to Specific Topics

Topic: zigbee2mqtt/#
Wait Time: 5
Click: Read

See all Zigbee2MQTT messages.

C. Publish Test Messages

Topic: test/hello
Value: Hello World
QoS: 0
Retain: false
Click: Write

Then read it back:

Topic: test/hello
Click: Read

D. Create Entities from Topics

1. Find an interesting topic (e.g., temperature sensor)
2. Click Read to get the value
3. Click "+ Create Entity from this Read"
4. Configure:
   • Name: Living Room Temperature
   • Data Type: float (if numeric)
   • Read/Write: Read (for sensors)
   • QoS: 0 (for frequent data)
5. Click Create Entity

Now you have a Home Assistant sensor! 📊

Common MQTT Patterns

Pattern 1: Zigbee2MQTT Devices

Topics:

zigbee2mqtt/bridge/state              → Coordinator status
zigbee2mqtt/[device_friendly_name]    → Device state (JSON)
zigbee2mqtt/[device_friendly_name]/set → Send commands

Example - Temperature Sensor:

Subscribe to: zigbee2mqtt/living_room_sensor
Payload: {"temperature":22.5,"humidity":65,"battery":100}

Create 3 entities:
1. Temperature → Extract "temperature" → 22.5
2. Humidity → Extract "humidity" → 65
3. Battery → Extract "battery" → 100

Example - Smart Light:

Read state:   zigbee2mqtt/bedroom_light
Set state:    zigbee2mqtt/bedroom_light/set → {"state": "ON"}
Set bright:   zigbee2mqtt/bedroom_light/set → {"brightness": 200}

Pattern 2: Tasmota Devices

Topics:

stat/[device]/POWER    → Current state
cmnd/[device]/POWER    → Send commands
tele/[device]/SENSOR   → Telemetry data

Example - Smart Plug:

Subscribe to: stat/living_room_plug/POWER
Payload: ON

Publish to: cmnd/living_room_plug/POWER
Payload: TOGGLE

Pattern 3: ESPHome Devices

Topics:

[device_name]/sensor/[sensor_name]/state
[device_name]/switch/[switch_name]/command

Example:

Subscribe to: esp_kitchen/sensor/temperature/state
Payload: 22.5

Pattern 4: Custom Devices

Your own ESP32/Arduino/Python script:

# Python example
import paho.mqtt.client as mqtt

client = mqtt.Client()
client.connect("localhost", 1883)

# Publish sensor data
client.publish("home/custom/temperature", "22.5")

# Subscribe to commands
def on_message(client, userdata, msg):
    if msg.topic == "home/custom/command":
        print(f"Received: {msg.payload}")

client.subscribe("home/custom/command")
client.on_message = on_message
client.loop_forever()

MQTT Explorer Card Features

Read Operations

Feature	Description
Single Topic	Subscribe to one specific topic
Wildcards	Use + or # to see multiple topics
Wait Time	How long to wait for messages
JSON Display	Automatically formats JSON payloads
Copy to Clipboard	Quick copy of values

Write Operations

Feature	Description
Publish	Send messages to any topic
QoS Selection	Choose delivery guarantee
Retain Flag	Make messages persistent
JSON Support	Send structured data

Entity Creation

After a successful read:

1. Click "+ Create Entity"
2. Fill in:
   • Name: Human-readable name
   • Data Type: string/integer/float/boolean/json
   • Read/Write Mode:
     • Read (subscribe only)
     • Write (publish only)
     • Read/Write (both)
   • QoS: 0/1/2
   • Retain: true/false
3. Entity appears in Home Assistant!

Real-World Examples

Example 1: Monitor Temperature

Setup:

Topic: zigbee2mqtt/temp_sensor
Data Type: json
Read Mode: Read
QoS: 0

What you see:

{
  "temperature": 22.5,
  "humidity": 65,
  "battery": 98
}

Create entity to extract temperature field.

Example 2: Control Smart Light

Read current state:

Topic: zigbee2mqtt/bedroom_light
Click: Read
Result: {"state": "ON", "brightness": 200}

Turn it off:

Topic: zigbee2mqtt/bedroom_light/set
Value: {"state": "OFF"}
QoS: 1
Retain: true
Click: Write

Example 3: Debug Device Communication

See all messages from a device:

Topic: zigbee2mqtt/problematic_device/#
Wait Time: 10
Click: Read

Watch the value area for incoming messages!

Example 4: Integration Testing

Test automation trigger:

Topic: test/motion
Value: detected
Click: Write

Then check if your automation fired!

Troubleshooting

"Timeout or no data"

Causes:

• Topic doesn't exist
• No device is publishing to that topic
• Wait time too short
• Not connected to broker

Solutions:

1. Use wildcard to see what topics exist: #
2. Increase wait time
3. Check broker is running
4. Verify device is connected

"Failed to connect to MQTT broker"

Causes:

• Broker not running
• Wrong address/port
• Authentication required but not provided
• Firewall blocking connection

Solutions:

1. Check Mosquitto add-on is started
2. Try localhost instead of IP
3. Enable anonymous access in broker config
4. Check firewall rules (port 1883)

"Permission denied"

Cause: Broker requires authentication

Solution:

1. Mosquitto config → Add username/password
2. Or set anonymous: true for testing

"Messages not retained"

Cause: Retain flag not set

Solution: Check "Retain message on broker" when publishing

MQTT Best Practices

Topic Design

✅ Good:

home/livingroom/temperature
home/livingroom/humidity
home/bedroom/light/state
home/bedroom/light/brightness

❌ Bad:

temp (too vague)
home-livingroom-temperature (use / not -)
home/livingroom (what data is this?)

Performance

• QoS 0 for high-frequency data (every second)
• QoS 1 for commands and important state
• QoS 2 only when absolutely necessary (slow)
• Retain for state, not for frequent sensor readings
• Short payloads = faster (prefer JSON over XML)

Security

• ✅ Use username/password in production
• ✅ Use TLS/SSL on port 8883 for external access
• ✅ Limit topic permissions (ACLs)
• ❌ Never use anonymous in production
• ❌ Never expose broker directly to internet

Debugging

1. MQTT Explorer (desktop app) - Visual topic browser
2. mosquitto_sub (command line) - See all messages

   mosquitto_sub -h localhost -t '#' -v

3. Protocol Wizard Card - In-dashboard exploration
4. Home Assistant MQTT integration - Developer tools

Advanced Topics

Message Retention

Publish with retain=true:
Topic: home/light/state
Payload: ON
Retain: true

→ Broker saves this message
→ New subscribers immediately get "ON"
→ Until next publish overwrites it

Last Will and Testament (LWT)

Devices can set a "last will" message that broker sends if device disconnects unexpectedly:

Topic: home/device/status
LWT Payload: offline
Normal Payload: online

When device crashes, broker auto-sends offline.

Topic Patterns

Pattern	Matches	Use Case
home/+/temp	All room temps	Monitor all temperature sensors
home/bedroom/#	Everything in bedroom	Debug bedroom devices
zigbee2mqtt/+/availability	All device online status	Monitor network health
#	Everything	Full network exploration

JSON Path Extraction

For complex JSON payloads:

{
  "sensor": {
    "temperature": {
      "value": 22.5,
      "unit": "C"
    }
  }
}

You might need to access sensor.temperature.value.

Protocol Wizard tip: Create a string entity first, examine the JSON, then create targeted entities.

Additional Resources

Official Documentation

• [MQTT.org](https://mqtt.org/) - Official MQTT specification
• [Mosquitto](https://mosquitto.org/) - Popular open-source broker
• [HiveMQ](https://www.hivemq.com/mqtt-essentials/) - Excellent MQTT tutorials

Tools

• [MQTT Explorer](https://mqtt-explorer.com/) - Best desktop MQTT client
• [MQTT.fx](https://mqttfx.jensd.de/) - Alternative GUI client
• mosquitto_pub / mosquitto_sub - Command-line tools

Common Integrations

• [Zigbee2MQTT](https://www.zigbee2mqtt.io/) - Zigbee devices
• [Tasmota](https://tasmota.github.io/docs/) - ESP8266/ESP32 firmware
• [ESPHome](https://esphome.io/) - ESP device framework
• [Node-RED](https://nodered.org/) - Visual MQTT programming

Quick Reference Card

┌─────────────────────────────────────────────────┐
│ MQTT Quick Reference                            │
├─────────────────────────────────────────────────┤
│ Topic:      home/livingroom/temperature         │
│ Payload:    22.5                                │
│ QoS:        0 = fast, 1 = reliable, 2 = sure    │
│ Retain:     Save last message on broker         │
│ Wildcards:  + (one level), # (all levels)       │
│                                                 │
│ Common Commands:                                │
│ • Explore: Topic = #                            │
│ • Publish: Set value → Write                    │
│ • Subscribe: Set topic → Read                   │
│ • Entity: Read → Create Entity                  │
└─────────────────────────────────────────────────┘

Next Steps

1. Explore your network: Topic = #, click Read
2. Find interesting topics: Look for sensors, switches
3. Create entities: Make permanent sensors from topics
4. Test commands: Publish to /set topics to control devices
5. Build automations: Use your new entities in HA automations!

---

Need help? Open an issue on [GitHub](https://github.com/partach/protocol_wizard/issues) or check existing [wiki pages](https://github.com/partach/protocol_wizard/wiki)!