MQTT is a lightweight, publish-subscribe-based messaging protocol designed for use on top of the TCP/IP protocol, primarily in resource-constrained environments and IoT (Internet of Things) applications.
An MQTT broker is a central server or component in the MQTT (Message Queuing Telemetry Transport) protocol that is responsible for receiving, processing, and distributing messages between clients.
The MQTT broker acts as an intermediary between MQTT clients, which are devices that publish messages to "topics" and subscribe to topics to receive messages. The broker is responsible for managing these topics and ensuring that messages are delivered to the correct subscribers.
In this article, we will outline how to set up a local MQTT environment using the Eclipse Mosquitto MQTT broker Docker container, MQTT Explorer, and Atmocube.
Eclipse Mosquitto is a popular open-source MQTT broker that can be easily set up in a Docker container. Atmocube supports MQTT version 3.1.1.
For the installation process, the official eclipse-mosquitto image is used.
Prerequisites: Docker installed on your machine (refer to the official documentation for installation instructions: https://docs.docker.com/get-docker/)
To install the broker, run the following command:
Let’s break down the command here:
The path /mosquitto/mosquitto.conf is used as an example. You can change it, but make sure it exists (together with the mosquitto.conf file). The path in the container (i.e., the /mosquitto/config/mosquitto.conf path) should stay the same.
After the Mosquitto Docker container is installed and started, the broker will be listening at the following address: mqtt://localhost:1883. By default, Mosquitto is configured not to accept any external connections, so it will only be available inside the container. To accept external connections, we need to add some configurations to the mapped mosquitto.conf file.
The simplest and least secure configuration is just adding "allow_anonymous true" to the config file.
To allow external anonymous connections, you can add the following to the mapped configuration file:
This is the least secure setting, allowing any external connection.
For the config file changes to take effect, the container with the broker must be restarted. This can be done by issuing the "docker restart atmo1" command.
To ensure that the Mosquitto container is running successfully, execute the following command:
You should see an output similar to the following:
You can now start connecting MQTT clients to the broker using the IP address of your Docker host machine and port 1883.
Alternatively, on Windows, you may install Docker and use the Docker application UI.
The MQTT TCP broker can be secured by adding authentication. To set up authentication, first, attach to the container with the ‘docker exec -it atmo1 sh’ command and create a password file.
Run the following command to create and add a user to this file:
After that, you will be asked to enter the password for the newly created user and confirm it. Add the following settings to the mosquitto.conf configuration file:
The parameter "allow_anonymous false" will prevent unauthenticated clients from connecting to the broker.
To set up an MQTT broker secured by TLS, client certificates need to be generated. Follow the guide here: How to configure MQTT TLS and certificate-based authorization for the Mosquitto MQTT Broker.
Follow the steps below to configure Atmocube using the Atmocube Configuration Tool:
b. For MQTT TLS, enter the file names of the client certificates.
Prerequisites: MQTT Explorer (http://mqtt-explorer.com/)
For the purpose of demonstration, MQTT Explorer will be used to connect to and subscribe to the MQTT broker.
3.1 Connect to the broker by entering the local IP address of the host machine and the port number exposed by the MQTT broker.
3.2 Depending on how the broker is configured, enter additional details such as the username and password needed to access the server. For MQTT TLS, go to Advanced>Certificates and upload the generated certificates.
3.3 After entering all the data, click Connect, and you should be able to see the data start flowing in. The topic name will be the device ID of your Atmocube.
This error may mean that the specified port is already taken or that Mosquitto is already running.
This error may indicate an error with the Atmocube configuration.