Getting started with TBMQ

• Introduction
• Installing TBMQ
• Configure client authentication & authorization
• Publishing and Subscribing to Topics
  • Subscribe to topic
  • Publish message
  • Autogenerated subscribe and publish commands
  • Result
• Next Steps

Introduction

The goal of this tutorial is to showcase the fundamental usage of TBMQ. Through this tutorial, you will gain knowledge and proficiency in the following areas:

• Establishing connections between MQTT clients and the broker.
• Publishing MQTT messages.
• Subscribing to topics to receive published messages.
• Configuring authentication and authorization mechanisms for MQTT clients.

For more comprehensive information regarding the architecture of TBMQ, navigate to the following document. This resource will provide you with detailed insights into the underlying structure and design principles of the broker, allowing you to develop a deeper understanding of its inner functionalities.

Installing TBMQ

To obtain detailed instructions on how to install TBMQ on different platforms, we recommend exploring the Installation options documentation. This resource will provide you with step-by-step guidance tailored to various deployment scenarios.

Follow the below instructions depending on your system for quick TBMQ installation.

1
2
wget https://raw.githubusercontent.com/thingsboard/tbmq/release-2.0.0/msa/tbmq/configs/tbmq-install-and-run.sh &&
sudo chmod +x tbmq-install-and-run.sh && ./tbmq-install-and-run.sh

1
Get-ExecutionPolicy

1
Set-ExecutionPolicy Unrestricted

1
2
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/thingsboard/tbmq/release-2.0.0/msa/tbmq/configs/windows/tbmq-install-and-run.ps1" `
-OutFile ".\tbmq-install-and-run.ps1"; .\tbmq-install-and-run.ps1

Once the installation process is complete for local deployment, you can access TBMQ UI by visiting the following URL: http://localhost:8083. Wait patiently until the services are up and running. To log in, utilize the following default credentials.

Username:

1
[email protected]

Password:

1
sysadmin

Configure client authentication & authorization

In order to secure the connection to the broker we should enable Basic or TLS authentication. In this tutorial, we will focus on the Basic authentication type. For this, we have set SECURITY_MQTT_BASIC_ENABLED environment variable to true in the docker-compose.yml downloaded in the previous step.

Once Basic authentication is enabled, it is necessary to create MQTT Client Credentials of type Basic to authenticate and validate the connecting client.

• Navigate to “Credentials” tab, click “+” in the top right corner of the table.
• Input credentials name. For example, “Getting Started Credentials”.
• Input “username” and “password” with chosen values. For example, use username and password values respectively.
• Authorization rules are set to allow publishing/subscribing to any topic by default.
• Click “Add” to save credentials.

A wider range of authentication methods can be found within the security guide, offering enhanced options for ensuring secure access.

Publishing and Subscribing to Topics

Now, let’s proceed with publishing messages and subscribing to topics to observe the flow of messages. In this tutorial, we will utilize Mosquitto clients for this purpose.

Please refer to the following links to learn how to publish messages to a topic and subscribe to topic filters in order to receive messages.

Subscribe to topic

To subscribe to the sensors/temperature topic and start receiving messages from TBMQ, you can utilize the following command:

1
mosquitto_sub -d -h $THINGSBOARD_MQTT_BROKER_HOST_NAME -p 1883 -t sensors/temperature -q 1 -u username -P password -i tbmq_dev

Note, replace the $THINGSBOARD_MQTT_BROKER_HOST_NAME with the correct public IP address or DNS name of the broker, username and password values according to the specified ones in the provisioned credentials. Kindly replicate the aforementioned process for publishing the message below.

Use the following command for local deployment:

1
mosquitto_sub -d -h localhost -p 1883 -t sensors/temperature -q 1 -u username -P password -i tbmq_dev

Upon successful establishment of the connection, we can proceed to examine the session information within the UI.

Publish message

To publish a message to TBMQ for the topic sensors/temperature, you can utilize the following command:

1
mosquitto_pub -d -h $THINGSBOARD_MQTT_BROKER_HOST_NAME -p 1883 -t sensors/temperature -m 32 -q 1 -u username -P password

Use the following command for local deployment:

1
mosquitto_pub -d -h localhost -p 1883 -t sensors/temperature -m 32 -q 1 -u username -P password

Autogenerated subscribe and publish commands

You may also find the TBMQ browser tool “Check Connectivity” useful for automatically generating commands to subscribe to a topic and publish a message. This tool uses your host, port, and client credentials data to construct mosquitto_sub and mosquitto_pub commands. It is available only for the Basic client credentials type.

Please follow these steps to generate commands for “Getting Started Credentials”:

1. Open the ‘Client Credentials’ page from the left-hand menu.
2. Click on row with client credentials “Getting Started Credentials” to open the details.
3. Click on the “Check connectivity” button.
4. In the opened window, select your operating system and install the necessary client tools.
5. You can copy and run the commands, but do not forget to replace “$YOUR_PASSWORD” with the real password.

You can read more about Check Connectivity here.

Result

You should receive and observe the published message for the subscribed client.

Next Steps

• Installation guides - Learn how to set up TBMQ on various available operating systems.

• Security guide - Learn how to enable authentication and authorization of MQTT clients.

• Configuration guide - Learn about TBMQ configuration files and parameters.

• MQTT client type guide - Learn about TBMQ client types.

• Integration with ThingsBoard - Learn about how to integrate TBMQ with ThingsBoard.