Skip to main content

MQTT Protocol

MQTT (Message Queuing Telemetry Transport) is a lightweight publish-subscribe messaging protocol designed for constrained devices and low-bandwidth networks. It's ideal for IoT applications.

Overview​

MQTT provides:

  • Lightweight messaging
  • Publish-subscribe pattern
  • Quality of Service levels
  • Retained messages
  • Last Will and Testament
  • Low bandwidth requirements
  • Efficient for IoT

Architecture​

Components​

MQTT Broker Central message router:

  • Receives all messages
  • Filters messages by topic
  • Distributes to subscribers
  • Manages connections

MQTT Clients Publishers and subscribers:

  • Publish messages to topics
  • Subscribe to topics
  • Maintain connection to broker

Communication Flow​

Publisher → [Topic: sensors/temp] → Broker → Subscribers

Topics​

Topic Structure​

Topics are hierarchical paths:

home/livingroom/temperature
building1/floor2/room201/humidity
factory/line3/machine5/status

Use forward slashes (/) as separators.

Topic Hierarchy​

sensors/
  ├── temperature/
  │   ├── indoor
  │   └── outdoor
  ├── humidity/
  └── pressure/

Topic Naming Best Practices​

Good:

device/001/temperature
site/warehouse/zone-a/motion
alert/critical/overheat

Avoid:

temp (too generic)
/sensor/ (leading/trailing slashes)
sensor temperature (spaces)

Wildcards​

Single-level (+) Matches one level:

sensors/+/temperature
Matches:
- sensors/room1/temperature
- sensors/room2/temperature
Does NOT match:
- sensors/room1/indoor/temperature

Multi-level (#) Matches multiple levels (must be last):

sensors/#
Matches:
- sensors/temperature
- sensors/room1/temperature
- sensors/room1/indoor/temperature

Examples:

home/+/temperature      # All room temperatures
home/+/+               # All metrics in all rooms
home/#                 # Everything under home
+/bedroom/temperature  # Bedroom temp in all homes

Quality of Service (QoS)​

QoS 0: At Most Once​

Fire and forget:

  • No acknowledgment
  • Message may be lost
  • Fastest, lowest overhead
  • Best for frequent, non-critical data

Use for:

  • Sensor readings sent every second
  • Status updates
  • Non-critical telemetry

QoS 1: At Least Once​

Acknowledged delivery:

  • Sender receives PUBACK
  • Guaranteed delivery
  • Possible duplicates
  • Moderate overhead

Use for:

  • Important measurements
  • Commands
  • Alerts
  • State changes

QoS 2: Exactly Once​

Assured delivery:

  • Four-way handshake
  • No duplicates
  • Guaranteed once
  • Highest overhead

Use for:

  • Critical commands
  • Financial transactions
  • Safety-critical data

QoS Negotiation​

Actual QoS is minimum of:

  • Publisher QoS
  • Subscriber QoS

Example:

Publish with QoS 2
Subscribe with QoS 1
→ Messages delivered at QoS 1

Retained Messages​

Purpose​

Last published message saved by broker.

Behavior​

1. Publish with retain flag set
2. Broker stores message
3. New subscribers immediately receive it
4. Only one retained message per topic

Use Cases​

home/livingroom/temperature (retain)
→ New subscribers get current temp immediately

device/001/status (retain)
→ Shows last known device state

Clear Retained Message​

Publish empty message with retain flag.

Last Will and Testament (LWT)​

Purpose​

Message sent when client disconnects unexpectedly.

Configuration​

Set when connecting:

Will Topic: device/001/status
Will Message: "offline"
Will QoS: 1
Will Retain: true

Use Cases​

Device Status:

On Connect:
  Publish: device/001/status = "online"
  
Will Message:
  Topic: device/001/status
  Message: "offline"
  
On Clean Disconnect:
  Publish: device/001/status = "offline"

Heartbeat:

Will topic: alerts/timeout
Will message: "Device 001 connection lost"

Connection​

Connect Packet​

Client ID: device-001 (unique identifier)
Clean Session: true/false
Keep Alive: 60 (seconds)
Username: optional
Password: optional
Will Message: optional (LWT)

Clean Session​

True:

  • No session state persisted
  • Start fresh each connection
  • Subscriptions not remembered

False:

  • Session persists across disconnections
  • Subscriptions maintained
  • Queued messages delivered

Keep Alive​

Heartbeat interval:

Keep Alive: 60 seconds
- Client sends PINGREQ
- Broker responds PINGRESP
- Detects broken connections

Message Structure​

MQTT Packet​

Fixed Header:
- Packet Type (PUBLISH, SUBSCRIBE, etc.)
- Flags (DUP, QoS, RETAIN)
- Remaining Length

Variable Header:
- Topic Name
- Packet Identifier

Payload:
- Message content

Publish Message​

Topic: sensors/temperature
QoS: 1
Retain: false
Payload: {"value": 22.5, "unit": "C"}

MQTT over TCP vs WebSocket​

MQTT over TCP (Port 1883)​

Standard MQTT
Port: 1883 (unencrypted)
Port: 8883 (TLS/SSL)
Binary protocol
Most efficient

MQTT over WebSocket (Port 80/443)​

For browsers
Port: 80 (ws://)
Port: 443 (wss://)
Works through firewalls
Slightly more overhead

Security​

Authentication​

Username/Password:
- Simple authentication
- Sent in CONNECT packet

Certificate-Based:
- TLS client certificates
- Strong authentication
- No password needed

Encryption​

TLS/SSL:
- Encrypted connection
- Port 8883 (MQTT)
- Port 443 (WebSocket)
- Protects data in transit

Authorization​

Topic ACLs:
- Control publish permissions
- Control subscribe permissions
- Per-user or per-client

Example:

User: device001
Can publish: device001/#
Can subscribe: device001/commands/#

Mosquitto​

  • Open source
  • Lightweight
  • Easy to deploy
  • Good for development

HiveMQ​

  • Enterprise-grade
  • Highly scalable
  • Commercial support
  • Advanced features

EMQX​

  • Massively scalable
  • IoT-focused
  • Open source and commercial
  • High performance

Cloud Brokers​

  • AWS IoT Core
  • Azure IoT Hub
  • Google Cloud IoT
  • HiveMQ Cloud

Best Practices​

Topic Design​

  1. Use hierarchical structure
  2. Include device ID in topics
  3. Separate commands and status
  4. Use consistent naming

Example Structure:

devices/{device-id}/telemetry/{metric}
devices/{device-id}/status
devices/{device-id}/commands/{action}
alerts/{severity}/{type}

Message Design​

  1. Use JSON for structured data
  2. Keep messages small
  3. Include timestamps
  4. Version your message formats

Connection Management​

  1. Implement reconnection logic
  2. Use exponential backoff
  3. Handle CONNACK errors
  4. Monitor connection state

QoS Selection​

  1. Use QoS 0 for frequent data
  2. Use QoS 1 for important messages
  3. Avoid QoS 2 unless necessary
  4. Match QoS to importance

Retained Messages​

  1. Use for status and state
  2. Clear when no longer needed
  3. Don't retain large messages
  4. Consider TTL requirements

Common Patterns​

Command/Response​

Publisher:
  devices/001/commands/restart

Device subscribes and executes:
  On message received:
    Execute command
    Publish response to:
      devices/001/responses/restart
      Payload: {"status": "success"}

Request/Reply​

Request:
  Topic: devices/001/requests
  Payload: {"action": "get_status", "reply_to": "client/123/reply"}

Response:
  Topic: client/123/reply
  Payload: {"status": "online", "temp": 22.5}

Heartbeat​

Every 30 seconds:
  Publish: devices/001/heartbeat
  Payload: {"timestamp": "2023-10-09T12:00:00Z"}

Monitor:
  Subscribe: devices/+/heartbeat
  Alert if not received in 60 seconds

AppBlocks Implementation​

MQTT Feature​

Configure in MQTT feature:

  • Broker address
  • Port and security
  • Authentication
  • Keep alive
  • Clean session

Publish​

Use MQTT Publish block:

  • Set topic
  • Choose QoS
  • Set retain flag
  • Provide payload

Subscribe​

Use MQTT Subscribe block:

  • Subscribe to topic(s)
  • Use wildcards
  • Handle received messages

Connection Status​

Use On MQTT Connected block:

  • Detect connection
  • Detect disconnection
  • Handle reconnection

Troubleshooting​

Common MQTT issues:

Cannot connect:

  • Check broker address and port
  • Verify network connectivity
  • Check firewall rules
  • Validate credentials

Messages not received:

  • Verify subscription topic
  • Check QoS levels
  • Confirm broker connection
  • Test with MQTT client tool

Frequent disconnections:

  • Increase keep alive
  • Check network stability
  • Verify broker capacity
  • Monitor client errors

High latency:

  • Use QoS 0 for non-critical data
  • Check broker load
  • Verify network speed
  • Consider local broker

Testing Tools​

Mosquitto Clients​

# Subscribe
mosquitto_sub -h broker.example.com -t "sensors/#"

# Publish
mosquitto_pub -h broker.example.com -t "sensors/temp" -m "22.5"

MQTT.fx​

  • GUI client
  • Topic monitoring
  • Message publishing
  • Connection testing

MQTT Explorer​

  • Visual topic browser
  • Message history
  • Statistics
  • Easy to use

See Also​