mqtt

Publish incoming message payload to the topic of the configured MQTT broker with QoS AT_LEAST_ONCE.

Configuration:

• Topic pattern - can be a static string, or pattern that is resolved using Message Metadata properties. For example ${deviceType}.
• Host - MQTT broker host.
• Port - MQTT broker port.
• Connection timeout - timeout in seconds for connecting to MQTT broker.
• Client ID - optional client identifier used for connecting to MQTT broker. If not specified, default generated clientId will be used.
• Add Service ID as suffix to Client ID - optional flag. Server id will be added as a suffix to the client id when enabled. It is helpful when running in microservices mode to allow rule nodes on each node to connect to the broker without the errors.
• Clean session - establishes a non persistent connection with the broker when enabled.
• SSL Enable/Disable - enable/disable secure communication.
• Credentials - MQTT connection credentials. Can be either Anonymous, Basic or PEM.

Different Authentication credentials are supported for external MQTT broker:

• Anonymous - no authentication
• Basic - username\password pair is used for authenticating
• PEM - PEM certificates are used for Authentication

If PEM credentials type is selected, the following configuration should be provided:

• CA certificate file
• Certificate file
• Private key file
• Private key password

Published body - Node will send full Message payload to the MQTT topic. If required, Rule Chain can be configured to use chain of Transformation Nodes for sending correct Payload to the MQTT broker.

In case of successful message publishing, original Message will be passed to the next nodes via Success chain, otherwise Failure chain is used.

MQTT retransmission mechanism

The MQTT node uses ThingsBoard’s internal MQTT client.

ThingsBoard’s internal MQTT client includes a retransmission mechanism designed to improve reliability for message types that require acknowledgment.
This mechanism applies specifically to the following MQTT message types:

• PUBLISH (only for QoS 1 or 2)
• SUBSCRIBE
• UNSUBSCRIBE
• PUBREL (only for QoS 2)

When one of these messages is sent, the client waits for an acknowledgment within a configurable delay period.
If no acknowledgment is received, the message is retransmitted. The delay between retransmissions follows an exponential backoff strategy, starting from an initial delay and doubling with each attempt.
A jitter factor introduces random variance into the delay to help prevent synchronized retries.

For example, if the retransmission configuration is set to three attempts, with an initial delay of 5,000 ms and a jitter factor of 0.15, the retransmission attempts would be scheduled at approximately 5,000 ms, 10,000 ms, and 20,000 ms, each adjusted by ±15% jitter.
If no acknowledgment is received after the final attempt, the system waits through the next scheduled delay—based on exponential backoff with jitter—before finally considering the message undeliverable and dropping it.

You can configure retransmission parameters globally in the thingsboard.yml file. These settings affect all MQTT clients on the platform:

1
2
3
4
5
6
mqtt:
  client:
    retransmission:
      max_attempts: "${TB_MQTT_CLIENT_RETRANSMISSION_MAX_ATTEMPTS:3}"
      initial_delay_millis: "${TB_MQTT_CLIENT_RETRANSMISSION_INITIAL_DELAY_MILLIS:5000}"
      jitter_factor: "${TB_MQTT_CLIENT_RETRANSMISSION_JITTER_FACTOR:0.15}"

When the message is dropped, the corresponding rule engine message is routed via Failure chain with the appropriate exception message.