Advanced Setup
WELL Project Annual Calibration / Replacement
Advanced Wi-Fi Setup via USB
Setting up 10+ Atmocubes
Modbus Setup Guide
BACnet Setup Guide
Setting Up a Local MQTT Environment
Modifying On-Device Indicator Ranges
Bluetooth API Specification
Integrating with Home Assistant via MQTT and Setting Up Automations
Using a WiFi router with built-in LTE as a hub
Integrating with AWS IoT Core via MQTT

Setting Up a Local MQTT Environment

What is MQTT?

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.

What is an MQTT broker?

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.

1. Installing and configuring the Mosquitto MQTT broker in Docker

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:

docker run -it -d --name atmo1 -p 1883:1883 -p 9001:9001 -v /mosquitto/mosquitto.conf:/mosquitto/config/mosquitto.conf eclipse-mosquitto

Let’s break down the command here:

  • -it is used to be able to attach a console to the container.
  • –name is used to assign a name to the Docker container. You can use a specified name (in our case, atmo1) to access the container.
  • -p 1883:1883 maps a port on your local machine (Docker host) to a container port. If port 1883 on the Docker host is busy, you can use another port, for example, -p 18883:1883. Port 1883 is used for MQTT, and port 9001 is for Websocket.
  • -v is used to mount volumes. It links (maps) local files/folders to the container’s files/folders. You can also chain multiple -v flags to create multiple volumes.
  • -d is used to run the container as a daemon (in the background).
  • eclipse-mosquito is the name of the image that will be used as the container’s blueprint.
  • -v /mosquitto/mosquitto.conf:/mosquitto/config/mosquitto.conf maps a mosquitto.conf configuration file from your local machine to the container. Your local machine and the docker container will share this file, which means that any changes you perform on this file locally will also be made to that same file inside of the container. This will be important later for configuring authentication settings.

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.

Note: 

  • For Windows, change the path to the Windows format, like: “C:\mosquitto\mosquitto.conf”
  • For macOS and Linux, no changes are needed.

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:

allow_anonymous true
listener 1883 0.0.0.0

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:

docker logs atmo1

You should see an output similar to the following:

1611983321: mosquitto version 2.0.15 starting
1611983321: Config loaded from /mosquitto/config/mosquitto.conf.
1611983321: Opening ipv4 listen socket on port 1883.
1611983321: Opening ipv6 listen socket on port 1883.

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.

Adding Authentication

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:

mosquitto_passwd -c /mosquitto/passwd_file user_name

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:

password_file /mosquitto/passwd_file
allow_anonymous false

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.

2. Setting up Atmocube as an MQTT client

Follow the steps below to configure Atmocube using the Atmocube Configuration Tool:

  1. Go to https://config.atmocube.app/
  1. Choose the correct SKU for the Atmocube from the drop-down menu on the configuration page. The model number can be found on the back of the device.
  1. In the Wi-Fi tab, enter the Wi-Fi network details.
  1. To enable MQTT, open the configuration menu by clicking on the MQTT tab. 
  1. Unchecking the “Production” option will reveal the following input fields:
  • MQTT host - Enter the IP address of your MQTT server.
  • MQTT port - Enter the port number exposed by the MQTT server.
  • MQTT security - depending on the type of authentication the MQTT server is using, select either MQTT TCP or MQTT TLS. For the purpose of this guide, we are using MQTT TCP. 
  1. a. For MQTT TCP, enter a username and password (even if the broker is unsecured).

         b. For MQTT TLS, enter the file names of the client certificates.

  1. After all details have been entered, click on the “Generate config” button to generate the configuration file. 
  1. Save the generated config.json file to the root of a USB flash drive formatted with the FAT file system.
  1. Disconnect Atmocube from the power source (if powered on).
  1. Insert the USB flash drive into the USB-A slot in Atmocube.
  1. Re-connect Atmocube to the power source.
  1. Once the Atmocube is turned on, it will access the config.json file from the USB flash drive. The power status LED will turn a solid purple color to indicate that the USB flash drive has been detected.
  1. After the configuration is successful, remove the USB flash drive from Atmocube.

3. Connect and receive data from Atmocube

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. 

Troubleshoot

Error: Address not available.

This error may mean that the specified port is already taken or that Mosquitto is already running.

Possible solutions:

  1. Try uninstalling all previously running versions of Mosquitto.
  2. Use a different port for the broker.

The MQTT client does not receive the expected messages from Atmocube.

This error may indicate an error with the Atmocube configuration.

Possible solutions:

  1. Ensure all steps while generating the config.json file were followed carefully. 
  2. Try using an alternate FAT-formatted USB flash drive. 
  3. Ensure that the correct SKU is selected.
  4. Double-check the information entered.