MQTT Integration

• Data Flow Overview
• Prerequisites
• Create TBMQ MQTT Integration
  • Topic Filters
  • Configuration
  • Events
• Sending an Uplink Message

TBMQ MQTT Integration enables forwarding messages to external MQTT brokers, allowing real-time data delivery to third-party platforms. This is useful in scenarios such as:

• Data from TBMQ needs to be forwarded to an external MQTT broker or IoT platform.
• TBMQ is used as an intermediary to route data between internal sources and external MQTT-based systems.

Data Flow Overview

MQTT Integration processes messages and forwards them to an external MQTT broker or system in the following steps:

1. Device (client) publishes an MQTT message to a topic that matches the Integration’s Topic Filters.
2. TBMQ broker receives the message and forwards to TBMQ Integration Executor.
3. TBMQ Integration Executor processes the message, formats it accordingly, and forwards it to the external MQTT broker or system.
4. External system receives the message and processes the data as needed.

Prerequisites

Before setting up the integration, ensure the following:

• A running TBMQ instance.
• A client capable of publishing MQTT messages (e.g., TBMQ WebSocket Client).
• A client capable of receiving MQTT messages (e.g., TBMQ WebSocket Client).

Create TBMQ MQTT Integration

1. Navigate to the Integrations page and click the ”+” button to create a new integration.
2. Select MQTT as the integration type and click Next.
3. On the Topic Filters subscribe to the topic tbmq/mqtt-integration and click Next.
4. In the Configuration step:
   • Enter the Host (localhost);
   • Enter the Port (1883);
   • Set ‘Dynamic topic name’ to false and ‘Topic name’ to sensors/mqtt-integration;
   • Set ‘Credentials’ type to Basic and ‘Username’ to tbmq_websockets_username;
5. Click Add to save the integration.

Important: When configuring an integration to publish messages back to TBMQ, make sure to disable “Dynamic topic name” and ensure that the publish topic does not overlap with the integration’s topic filter, to prevent creating an infinite message loop.

You can test the connectivity to the configured MQTT broker by using the ‘Check connection’ button. This will create an MQTT client that attempts to connect to the broker and then immediately disconnects.

Topic Filters

Topic filters define MQTT-based subscriptions and act as triggers for TBMQ HTTP Integration. When the broker receives a message matching configured topic filters, the integration processes it and forwards the data to the specified external system.

If the integration is configured with the topic filter:

1
tbmq/devices/+/status

Then, any message matching this pattern will trigger the integration, including:

1
2
tbmq/devices/device-01/status
tbmq/devices/gateway-01/status

Configuration

Events

TBMQ provides logging for integration-related events, allowing users to debug and troubleshoot integration behavior. Below are three ‘Event’ types:

• Lifecycle Events – Logs events such as Started, Created, Updated, Stopped, etc.

• Statistics – Provides insights into integration performance, including the number of processed messages and occured errors.

• Errors – Captures failures related to authentication, timeouts, payload formatting, or connectivity issues with the external service.

Sending an Uplink Message

To send a message, follow these steps:

1. Navigate to the WebSocket Client page.
2. Select ‘WebSocket Default Connection’ or any other available working connection, then click Connect. Make sure the ‘Connection status’ is shown as Connected.
3. Set the ‘Topic’ field to tbmq/mqtt-integration to match the Integration’s ‘Topic Filter’.
4. Click the Send icon to publish the message.
5. If successful, two new messages should appear in the ‘Messages’ table:

• One sent by the WebSocket Client.
• One received from the MQTT Integration with message payload similar to:

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  {
   "payload": "eyJ0ZW1wZXJhdHVyZSI6MjV9",
   "topicName": "tbmq/mqtt-integration",
   "clientId": "tbmq_7QUvZzow",
   "eventType": "PUBLISH_MSG",
   "qos": 1,
   "retain": false,
   "tbmqIeNode": "tbmq_ie_node",
   "tbmqNode": "tbmq_node",
   "ts": 1742554969254,
   "props": {},
   "metadata": {
      "integrationName": "MQTT integration"
   }
  }
  

Message description:

• payload: Base64-encoded content of the MQTT message (e.g., "eyJ0ZW1wZXJhdHVyZSI6MjV9" is a JSON object {"temperature": 25}).
• topicName: The MQTT topic to which the message was published.
• clientId: The ID of the MQTT client that published the message.
• eventType: Type of MQTT event, here it’s a published message (the only supported type for now).
• qos: Quality of Service level used for the incoming message.
• retain: Indicates if the message is a retained MQTT message.
• tbmqIeNode: Node ID of the Integration Executor service that handled the message.
• tbmqNode: Node ID of the TBMQ broker that received the message.
• ts: Timestamp (in milliseconds) when the message was received.
• props: MQTT 5.0 user properties or other MQTT properties.
• metadata: Additional metadata added from integration configuration, e.g., the name of the integration that handled the message, added by default.