Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 6

Testing MQTT with Command-Line Tools

Recommended resources

Welcome to the final lesson of our first module. In our previous session, we successfully installed the Mosquitto MQTT broker, set it up to run automatically as a system service, and configured the firewall to permit network connections. With the infrastructure in place, our task today is to verify that it works as expected.

This lesson focuses on performing a fundamental end-to-end test of your MQTT broker. We will use the command-line tools that were installed along with Mosquitto to simulate the core publish-subscribe loop. By having one terminal act as a subscriber and another as a publisher, you will confirm that messages can be sent and received through the broker, both locally and across your network. This validation is the final checkpoint before we begin developing the gesture recognition client in the next module.

A Note on Modern Mosquitto Defaults

Before we begin testing, there is an important configuration detail to address. For security reasons, recent versions of Mosquitto (v2.0 and newer) default to disallowing anonymous connections. This means that if a client tries to connect without providing a username and password, the broker will refuse the connection.

For our initial test, we will use anonymous connections for simplicity. Therefore, we need to create a simple configuration file to explicitly allow them.

The Stack Overflow discussion below highlights this exact issue and provides the necessary configuration.

linux - mosquitto-client obtain refused connection - Stack Overflow

This thread on Stack Overflow is a practical example of a common issue with modern Mosquitto setups. The top-voted answer provides the solution we need.

Focus on the first part of the accepted answer. It provides two essential configuration lines. We will place these in a new configuration file.

Let's apply this fix.

  1. Open a terminal and create a new configuration file using a text editor like nano: 
    sudo nano /etc/mosquitto/conf.d/local.conf
  2. Add the following two lines to the file. The listener directive ensures Mosquitto listens for connections on all network interfaces (not just localhost), and allow_anonymous permits our test clients to connect without credentials. 
    listener 1883
allow_anonymous true
  3. Save the file and exit nano (press Ctrl+X, then Y, then Enter).
  4. For the changes to take effect, you must restart the Mosquitto service: 
    sudo systemctl restart mosquitto

Your broker is now ready for testing.

Testing with mosquitto_pub and mosquitto_sub

The mosquitto-clients package we installed previously includes two essential command-line utilities for interacting with a broker:

  • mosquitto_sub: A client that subscribes to one or more topics and prints any messages it receives.
  • mosquitto_pub: A client that publishes a single message to a topic and then exits.

To perform the test, you will need two separate terminal windows open on your Rocky Linux machine.

The process is clearly demonstrated in the "MQTT Example" guide we referenced in the last lesson.

MQTT Example

This guide provides the exact commands for setting up a subscription and publishing a message.

Follow the instructions in the section Test the Mosquitto installation. You will execute one command in each of your terminal windows.

Let's walk through it with more descriptive topics, which will be useful for your home automation project.

1. The Subscriber

In your first terminal window, run the following command. This will subscribe to the topic home/test and wait for messages. The -v flag (verbose) will print the topic along with the message.

mosquitto_sub -h localhost -t "home/test" -v

The terminal will appear to hang, but it's actively listening for messages on that topic.

2. The Publisher

In your second terminal window, run this command to publish a message:

mosquitto_pub -h localhost -t "home/test" -m "Hello, Broker!"

Let's break down this command:

  • -h localhost: Specifies the host where the broker is running (our local machine).
  • -t "home/test": The topic to which the message is published. This must exactly match the subscriber's topic.
  • -m "Hello, Broker!": The message payload itself.

As soon as you press Enter in the publisher terminal, you should instantly see the following output appear in your subscriber terminal:

home/test Hello, Broker!

This confirms that the broker is correctly routing messages locally. The image below shows what this successful two-terminal test looks like.

Two terminal windows demonstrating a successful MQTT test. The left window runs `mosquitto_sub` to listen on a topic, and the right window uses `mosquitto_pub` to send a message to that same topic. The message appears in the subscriber's window, confirming the broker is working.

Verifying Network Accessibility

The test above used localhost, which means the communication never left your machine. To confirm that your firewall rules are correct and your broker is accessible to other devices on your network (like your future IoT devices), we must perform one more test using your machine's IP address.

  1. Find your IP Address: In a terminal, run the hostname -I command. This will print your local IP address (e.g., 192.168.1.123).

    hostname -I

  2. Run the Test Again: Repeat the steps from before, but replace localhost with your actual IP address in both commands.

    • Subscriber Terminal: (You may need to stop the previous subscriber with Ctrl+C first) 
      


# Replace 192.168.1.123 with your actual IP address
mosquitto_sub -h 192.168.1.123 -t "home/test" -v
    • Publisher Terminal: 
      


# Replace 192.168.1.123 with your actual IP address
mosquitto_pub -h 192.168.1.123 -t "home/test" -m "Network test successful!"

If the message appears in the subscriber window again, you have successfully verified that your broker is installed, running, and fully accessible on your local network.

Conclusion

You have now successfully validated the entire communication backbone of your IoT system. This completes the first major phase of our project: setting up the server environment. With a working operating system, development tools, and a tested messaging broker, your dedicated machine is ready to host both the gesture recognition client and the simulated IoT devices.

Key Takeaways:

  • Modern Mosquitto installations require explicit configuration to allow_anonymous connections.
  • The mosquitto_sub and mosquitto_pub command-line tools are invaluable for testing and debugging an MQTT broker.
  • Testing communication using localhost verifies that the broker service is running correctly.
  • Testing communication using the machine's IP address is a necessary step to confirm that firewall rules and listener configurations are correct for network access.

In our next lesson, we will pivot from system setup to application development. You will write your first Python script for this project, using OpenCV to capture a live video feed from your webcam. This script will form the foundation of the gesture recognition client.

End of Module,Exit lesson