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, version 2.1 or later, with the TBMQ Integration Executor service running. Without a reachable executor, saving an integration fails with a validation timeout.
• A client capable of publishing MQTT messages (e.g., TBMQ WebSocket Client).
• A client capable of receiving MQTT messages (e.g., TBMQ WebSocket Client).

To keep the walkthrough self-contained, this tutorial points the integration back at TBMQ itself, so you can publish and observe the forwarded message in the same WebSocket Client. In a real deployment, the host and port belong to your external broker.

1. Go to the Integrations page and click the “+” button.
2. Select MQTT as the integration type and click Next.
3. On the Filters and events step, replace the default Topic filters entry with tbmq/mqtt-integration. Narrowing the filter to one exact topic — rather than keeping the default tbmq/# — keeps this tutorial from forwarding unrelated messages. Leave Lifecycle events empty 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. With the dynamic option off, every forwarded message goes to this one fixed topic instead of the topic it arrived on. The sensors/ prefix is deliberate: the WebSocket Default Connection subscribes to sensors/#, which is what makes the forwarded message show up in Send an uplink message below. If you choose a different topic name, subscribe to it in the WebSocket Client first, or you will see nothing.
   • Set Credentials type to Basic and Username to tbmq_websockets_username. Leave Password empty — the WebSocket credentials that ship with TBMQ are username-only.
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.

Topic filters are optional if you select at least one lifecycle event type instead — an integration only has to have one of the two.

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

Topic, QoS, and retain are resolved independently — each one is either copied from the incoming message or taken from its static setting. A lifecycle event has no incoming message, so all three are fixed:

Besides the messages matched by topic filters, this integration can deliver client lifecycle events — a client connecting, disconnecting, changing its subscriptions, or failing authentication or authorization.

Pick the event types on the Filters and events step while creating the integration, or add them later:

1. Open the integration on the Integrations page and click the Toggle edit mode button (pencil icon).
2. Click the Lifecycle events field to list the available event types, then select the ones you need: Client connected, Client disconnected, Client subscribed, Client unsubscribed, Client authentication failed, Client authorization failed, Client connection failed. Each one is added as a chip; remove it with its x.
3. Set Events topic name to the topic on the external broker that should receive the events, for example tbmq/events. The field appears under Lifecycle events as soon as the first event type is selected, and a value is required.
4. Click Apply changes.

A lifecycle event has no originating MQTT message to take a topic, QoS, or retain flag from, so this integration type handles them separately from messages:

• Events go to the dedicated Events topic name, never to Topic name, and Dynamic topic name does not apply to them.
• Events are always published with QoS 1 and the retain flag off, regardless of the Dynamic QoS, QoS, Dynamic retain, and Retain settings.

These are the integration’s own events, recorded inside TBMQ for debugging and troubleshooting. They are not the client lifecycle events described above: those are about MQTT clients and are published to the external broker, while these describe the integration itself and never leave TBMQ.

• 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 and click Connect. Verify the connection status shows Connected. This connection’s default subscription is sensors/#, which covers the integration’s Topic name sensors/mqtt-integration — if you use a different connection, make sure it subscribes to that topic.
3. Set the Topic field to tbmq/mqtt-integration to match the integration’s topic filter.
4. Leave the pre-filled Payload {"temperature": 25} as is — it is what comes back through the integration.
5. 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: