MQTT integration

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.

1. Device (client) publishes an MQTT message to a topic matching the integration’s topic filters.
2. TBMQ broker receives the message and forwards it to the TBMQ Integration Executor.
3. Integration Executor processes the message and forwards it to the external MQTT broker or system.
4. External system receives the message and processes the data.

• 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).

1. Go to the Integrations page and click the ”+” button.
2. Select MQTT as the integration type and click Next.
3. On the Topic Filters step, subscribe to tbmq/mqtt-integration and click Next.
4. In the Configuration step:
   • Enter the Host (e.g., localhost).
   • Enter the Port (e.g., 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.

Navigate to Integrations page and click the plus icon Select MQTT as the integration type and click Next Change default topic filter to tbmq/mqtt-integration and click Next Specify Host, Port, Credentials and Topic name, then click Add

Topic filters define MQTT-based subscriptions that trigger the integration. When TBMQ receives a message matching a configured topic filter, the integration processes it and forwards the data to the external system.

For example, with the topic filter tbmq/devices/+/status, any of the following messages will trigger the integration:

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

TBMQ logs integration-related events for debugging and troubleshooting:

• Lifecycle Events — logs events such as Started, Created, Updated, Stopped.
• Statistics — insights into integration performance, including processed message counts and error rates.
• Errors — captures failures related to authentication, timeouts, payload formatting, or connectivity issues.

Lifecycle events for the MQTT integration Statistics events showing processed message counts Error events capturing integration failures

1. Navigate to the WebSocket Client page.
2. Select WebSocket Default Connection (or any working connection) and click Connect. Verify the connection status shows 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.

Select a working connection and click Connect Set topic to tbmq/mqtt-integration and click Send

If successful, two new messages should appear in the Messages table:

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

{
   "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 field descriptions: