Getting Started

This guide covers the basics of TBMQ:

• Connecting MQTT clients to the broker.
• Publishing and subscribing to messages.
• Configuring client authentication and authorization.

For details on the TBMQ architecture, see Architecture.

The fastest way to get started with TBMQ is to use the free public MQTT broker at demo.tbmq.io. This sandbox environment allows you to explore TBMQ features without any installation.

MQTT connection details:

You can start publishing and subscribing to topics immediately using these credentials. Sign up for a free account to access the TBMQ UI and explore sessions, subscriptions, and other features.

For full control over your TBMQ instance, you can install it locally. For detailed instructions on different platforms, see Installation options.

Follow the instructions below for a quick local installation.

wget https://raw.githubusercontent.com/thingsboard/tbmq-pe-docker-compose/release-2.3.0/basic/tbmq-install-and-run.sh &&
sudo chmod +x tbmq-install-and-run.sh && ./tbmq-install-and-run.sh

Get-ExecutionPolicy

Set-ExecutionPolicy Unrestricted

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/thingsboard/tbmq-pe-docker-compose/release-2.3.0/basic/windows/tbmq-install-and-run.ps1" `
-OutFile ".\tbmq-install-and-run.ps1"; .\tbmq-install-and-run.ps1

Get the license key

Before proceeding, make sure you have selected a subscription plan or purchased a perpetual license. If you haven't done this yet, visit the Pricing page to compare available options and obtain your license key.

Configure the license key

Open the docker-compose.yml file downloaded by the install script, find the TBMQ_LICENSE_SECRET environment variable, and replace YOUR_LICENSE_KEY_HERE with your actual license key.

After updating the file, apply the changes by running:

./tbmq-install-and-run.sh

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

Username:

[email protected]

Password:

sysadmin

To secure the connection to the broker, enable Basic authentication.

After you enable Basic authentication, create MQTT Client Credentials of type Basic to authenticate connecting clients:

• Go to Authentication → Credentials and click Add (+).
• Enter a credentials name, for example, “Getting Started Credentials”.
• Enter “username” and “password” values of your choice, for example, username and password.
• Click Add.

By default, authorization rules allow publishing and subscribing to any topic.

Go to Authentication → Credentials and click Add (+) Enter a credentials name, for example, "Getting Started Credentials" Enter username and password values of your choice. Click Add to save After adding the credentials, the Check Connectivity window opens with autogenerated commands for subscribing and publishing

For additional authentication methods, see Security overview.

Publish messages and subscribe to topics to observe the flow of messages. This tutorial uses Mosquitto clients. For details, see the mosquitto_pub and mosquitto_sub documentation.

• Demo Instance
• Local Deployment

Subscribe to a topic

Section titled “Subscribe to a topic”

To subscribe to the sensors/temperature topic and start receiving messages, use the following command:

mosquitto_sub -d -h demo.tbmq.io -p 1883 -t sensors/temperature -q 1 -u demo

After connecting, go to the Sessions page to view the session details.

If you signed up for a demo account, log in to demo.tbmq.io and go to the Sessions page to see all active sessions, including your new session.

Publish a message

Section titled “Publish a message”

To publish a message to the sensors/temperature topic, use the following command:

mosquitto_pub -d -h demo.tbmq.io -p 1883 -t sensors/temperature -m 32 -q 1 -u demo

You should see the published message received by the subscribed client: