Stop the war

Stand with Ukraine flag

Support Ukraine

Try it now Pricing
MQTT Broker
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Documentation Installation Architecture API FAQ
On this page

Getting started with TBMQ

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.

For Linux or macOS users who have Docker installed, the execution of the following commands is recommended:

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

For Windows users who have Docker Desktop installed, the execution of the following instructions is recommended.

Note: make sure the downloaded PowerShell scripts are allowed to run on your system.

  • Open PowerShell (Run as Administrator).
  • (Optional) Get the current execution policy. It determines the level of security for running scripts on a system. For example, if Restricted is returned, it means PowerShell doesn’t execute any scripts.
1
Get-ExecutionPolicy
  • (Optional) Change the current execution policy if required. Set it to the one that will allow you to run PowerShell scripts and the one that suits your security requirements. For example, Unrestricted is the least restrictive setting that allows all scripts to be executed.
1
Set-ExecutionPolicy Unrestricted
  • Install TBMQ
1
2
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/thingsboard/tbmq/release-1.2.1/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:

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

Result

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

image

Next Steps