mosquitto_pub and mosquitto_sub commands in IOT Protocols - Deep Dive

Overview - mosquitto_pub and mosquitto_sub commands

What is it?

mosquitto_pub and mosquitto_sub are command-line tools used to send and receive messages using the MQTT protocol. mosquitto_pub publishes messages to a topic on an MQTT broker, while mosquitto_sub subscribes to topics to receive messages. These tools help devices and applications communicate in real-time by exchanging small messages efficiently.

Why it matters

Without these commands, testing and interacting with MQTT brokers would be difficult and slow, making it hard to develop or debug IoT systems. They provide a simple way to simulate devices sending and receiving data, which is essential for building connected applications that rely on instant messaging.

Where it fits

Learners should first understand basic networking and the MQTT protocol before using these commands. After mastering them, learners can explore advanced MQTT features, broker configurations, and integrate MQTT with IoT platforms or automation systems.

Mental Model

Core Idea

mosquitto_pub sends messages to a channel, and mosquitto_sub listens to that channel to receive messages instantly.

Think of it like...

It's like a walkie-talkie: mosquitto_pub is the person speaking into the device, and mosquitto_sub is the person listening on the same frequency to hear the message.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ mosquitto_pub │──────▶│ MQTT Broker   │──────▶│ mosquitto_sub │
│ (publisher)   │       │ (message hub) │       │ (subscriber)  │
└───────────────┘       └───────────────┘       └───────────────┘

Build-Up - 8 Steps

1

Foundation

Understanding MQTT Basics

Concept: Learn what MQTT is and how it uses topics to organize messages.

MQTT is a lightweight messaging protocol designed for devices to send and receive small messages quickly. It uses a broker to manage message delivery. Messages are sent to 'topics' which act like channels or labels. Devices subscribe to topics to get messages sent there.

Result

You understand that MQTT uses a broker and topics to send messages between devices.

Knowing MQTT's basic structure is essential before using mosquitto_pub and mosquitto_sub because these commands interact directly with topics on the broker.

2

Foundation

Installing Mosquitto Client Tools

Concept: Set up mosquitto_pub and mosquitto_sub on your computer.

Install the Mosquitto client tools using your system's package manager. For example, on Ubuntu: sudo apt-get install mosquitto-clients. This gives you access to mosquitto_pub and mosquitto_sub commands to publish and subscribe to MQTT topics.

Result

You have mosquitto_pub and mosquitto_sub ready to use on your system.

Having the tools installed is the first practical step to experimenting with MQTT messaging.

3

Intermediate

Publishing Messages with mosquitto_pub

🤔Before reading on: do you think mosquitto_pub requires a running broker to send messages? Commit to your answer.

Concept: Learn how to send messages to a topic using mosquitto_pub.

Use mosquitto_pub with the -t option to specify the topic and -m to provide the message. For example: mosquitto_pub -t 'home/livingroom/temperature' -m '22.5'. This sends the message '22.5' to the topic 'home/livingroom/temperature' on the default broker (localhost).

Result

The message is sent to the MQTT broker under the specified topic.

Understanding that mosquitto_pub sends messages to a broker topic helps you simulate device data publishing.

4

Intermediate

Subscribing to Topics with mosquitto_sub

🤔Before reading on: do you think mosquitto_sub can receive messages sent before it starts? Commit to your answer.

Concept: Learn how to listen for messages on a topic using mosquitto_sub.

Use mosquitto_sub with the -t option to specify the topic to listen to. For example: mosquitto_sub -t 'home/livingroom/temperature'. This command waits and prints any messages published to that topic in real-time.

Result

You receive and see messages published to the subscribed topic as they arrive.

Knowing mosquitto_sub listens continuously for messages helps you monitor live data streams.

5

Intermediate

Connecting to Remote Brokers

🤔Before reading on: do you think mosquitto_pub and mosquitto_sub only work with local brokers? Commit to your answer.

Concept: Learn how to specify a remote MQTT broker to publish or subscribe messages.

Use the -h option to specify the broker's hostname or IP address. For example: mosquitto_pub -h broker.example.com -t 'sensor/data' -m 'value'. Similarly, mosquitto_sub -h broker.example.com -t 'sensor/data'. This connects your commands to a broker running anywhere on the network or internet.

Result

You can send and receive MQTT messages through brokers not running on your local machine.

Understanding how to connect to remote brokers expands your ability to work with real IoT deployments.

6

Advanced

Using Quality of Service Levels

🤔Before reading on: do you think MQTT messages are always delivered exactly once? Commit to your answer.

Concept: Learn how to control message delivery guarantees using QoS options in mosquitto_pub and mosquitto_sub.

MQTT supports three QoS levels: 0 (at most once), 1 (at least once), and 2 (exactly once). Use -q option to set QoS. For example: mosquitto_pub -t 'topic' -m 'msg' -q 1. This ensures the broker tries to deliver the message at least once, which is important for reliable communication.

Result

Messages are delivered with the specified reliability level, balancing speed and guarantee.

Knowing QoS levels helps you choose the right balance between speed and message delivery assurance in your applications.

7

Advanced

Handling Authentication and Encryption

🤔Before reading on: do you think mosquitto_pub and mosquitto_sub can connect securely by default? Commit to your answer.

Concept: Learn how to use username/password and TLS options to secure MQTT connections.

Use -u and -P options to provide username and password. For example: mosquitto_pub -h broker.example.com -u user -P pass -t 'secure/topic' -m 'secret'. For encryption, use --cafile to specify the CA certificate and --tls-version to enforce TLS. This protects data from eavesdropping and unauthorized access.

Result

Your MQTT messages are sent and received securely with authentication and encryption.

Understanding security options is critical for protecting sensitive IoT data in real-world deployments.

8

Expert

Advanced Subscription Filters and Retained Messages

🤔Before reading on: do you think mosquitto_sub can subscribe to multiple topics with wildcards? Commit to your answer.

Concept: Learn how to use topic wildcards and retained messages to manage complex subscriptions and message history.

Use + and # wildcards to subscribe to multiple topics. For example: mosquitto_sub -t 'home/+/temperature' listens to temperature in all rooms. Retained messages are stored by the broker and sent immediately to new subscribers. Use -r with mosquitto_pub to set retained messages. This helps new subscribers get the last known value instantly.

Result

You can listen to groups of topics and receive the latest message immediately upon subscription.

Mastering wildcards and retained messages allows efficient monitoring and state management in large MQTT systems.

Under the Hood

mosquitto_pub and mosquitto_sub communicate with an MQTT broker using the MQTT protocol over TCP/IP. mosquitto_pub sends a PUBLISH packet with a topic and message payload to the broker. mosquitto_sub sends a SUBSCRIBE packet to register interest in topics. The broker manages message routing, delivering published messages to all subscribers of matching topics. The commands handle connection setup, packet formatting, and keep-alive pings automatically.

Why designed this way?

These tools were designed to be simple, lightweight clients for testing and interacting with MQTT brokers. The MQTT protocol itself was created for low-bandwidth, low-power devices, so the commands follow this minimalism. They avoid complex GUIs or heavy dependencies to remain accessible and scriptable for automation and debugging.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ mosquitto_pub │──────▶│ MQTT Broker   │──────▶│ mosquitto_sub │
│ (PUBLISH)     │       │ (ROUTER)      │       │ (SUBSCRIBE)   │
└───────┬───────┘       └───────┬───────┘       └───────┬───────┘
        │                       │                       │       
        │ PUBLISH packet        │                       │       
        │──────────────────────▶│                       │       
        │                       │                       │       
        │                       │ SUBSCRIBE packet      │       
        │                       │◀──────────────────────│       
        │                       │                       │       
        │                       │ PUBLISH message        │       
        │                       │──────────────────────▶│       
        ▼                       ▼                       ▼       

Myth Busters - 4 Common Misconceptions

Quick: Does mosquitto_sub receive messages sent before it starts? Commit to yes or no.

Common Belief: mosquitto_sub will receive all past messages sent to a topic, even before it started listening.

Reality: mosquitto_sub only receives messages published after it subscribes, unless the message was retained by the broker.

Why it matters: Assuming mosquitto_sub gets all past messages can cause missed data and confusion during testing or monitoring.

Quick: Do you think mosquitto_pub can send messages without a running broker? Commit to yes or no.

Common Belief: mosquitto_pub can send messages directly to other clients without a broker.

Reality: mosquitto_pub requires a running MQTT broker to accept and route messages; it cannot send messages peer-to-peer.

Why it matters: Trying to use mosquitto_pub without a broker leads to connection errors and failed message delivery.

Quick: Does setting QoS 2 guarantee no duplicate messages? Commit to yes or no.

Common Belief: Using QoS 2 in mosquitto_pub and mosquitto_sub means messages are never duplicated.

Reality: QoS 2 aims for exactly once delivery but duplicates can still occur in rare network failure cases; clients must handle duplicates gracefully.

Why it matters: Believing QoS 2 is perfect can cause overlooked bugs if duplicate messages are not accounted for.

Quick: Can mosquitto_pub and mosquitto_sub encrypt messages by default? Commit to yes or no.

Common Belief: Messages sent with mosquitto_pub and received with mosquitto_sub are encrypted automatically.

Reality: Encryption requires explicit TLS configuration; by default, messages are sent in plain text.

Why it matters: Assuming default encryption risks exposing sensitive data on insecure networks.

Expert Zone

1

mosquitto_sub can handle multiple topic subscriptions simultaneously by repeating the -t option, allowing complex monitoring setups.

2

Retained messages can cause confusion if not cleared properly; publishing a zero-length retained message removes the retained message from the broker.

3

Using clean session flags affects whether subscriptions persist across client reconnects, impacting message delivery guarantees.

When NOT to use

Avoid mosquitto_pub and mosquitto_sub for high-throughput or complex MQTT client needs; use full MQTT client libraries like Paho or MQTT.js for advanced features, persistent sessions, and better error handling.

Production Patterns

In production, mosquitto_pub and mosquitto_sub are mainly used for testing, debugging, and simple automation scripts. Real devices use embedded MQTT clients with persistent connections and advanced session management.

Connections

Publish-Subscribe Messaging Pattern

mosquitto_pub and mosquitto_sub implement this pattern using MQTT topics as channels.

Understanding the publish-subscribe pattern clarifies how decoupled communication works, enabling scalable and flexible message exchange.

TCP/IP Networking

MQTT runs over TCP/IP, so mosquitto_pub and mosquitto_sub rely on stable network connections to communicate with brokers.

Knowing TCP/IP basics helps troubleshoot connection issues and understand message delivery reliability.

Radio Communication (Walkie-Talkies)

Both use channels/frequencies to send and receive messages asynchronously.

Recognizing this similarity helps grasp how MQTT topics act like radio channels for message exchange.

Common Pitfalls

#1 Trying to publish messages without a running MQTT broker.

Wrong approach:

mosquitto_pub -t 'test/topic' -m 'hello'

Correct approach:

Start the broker first (e.g., mosquitto) then run: mosquitto_pub -t 'test/topic' -m 'hello'

Root cause:

Not understanding that mosquitto_pub needs a broker to accept and route messages.

#2 Expecting mosquitto_sub to receive messages sent before subscription without retained messages.

Wrong approach:

mosquitto_sub -t 'sensor/data' (after messages were published)

Correct approach:

Publish messages with -r to retain them: mosquitto_pub -t 'sensor/data' -m 'value' -r, then subscribe: mosquitto_sub -t 'sensor/data'

Root cause:

Misunderstanding how MQTT message retention works.

#3 Using plain text connections for sensitive data.

Wrong approach:

mosquitto_pub -h broker.example.com -t 'secure' -m 'secret'

Correct approach:

Use TLS and authentication: mosquitto_pub -h broker.example.com --cafile ca.crt -u user -P pass -t 'secure' -m 'secret'

Root cause:

Ignoring security best practices for MQTT communication.

Key Takeaways

mosquitto_pub and mosquitto_sub are simple command-line tools to send and receive MQTT messages via a broker.

They require a running MQTT broker to function and communicate using topics as message channels.

Understanding MQTT topics, QoS levels, and retained messages is essential to use these commands effectively.

Security features like authentication and TLS must be explicitly configured to protect MQTT data.

These tools are ideal for testing and debugging but not for complex or high-performance MQTT client needs.