Skip to main content

ThingsBoard MQTT

Purpose​

This target connects to ThingsBoard through MQTT and publishes gateway telemetry and device attributes. It can also handle ThingsBoard gateway RPC requests when write permissions are enabled.

Configure the forwarding group and target through Data Forwarding. This page covers ThingsBoard connection properties, fixed platform Topics, variable write permission, and debug verification.

Open the plugin​

Open Development Configuration → Data Forwarding and:

  1. Configure and save the forwarding group range, trigger, interval, online filter, and batching.
  2. Add a target, choose ThingsBoard MQTT, and fill in the basic target information.
  3. Open Target properties and configure the ThingsBoard MQTT endpoint, token authentication, TLS, and runtime options.
  4. Save and enable the target, confirm the gateway device is online in ThingsBoard, and then open Target debug.

Basic target information​

SettingDefaultConfiguration
Group-Select a saved forwarding group.
Target name-Required and unique within the group.
EnableEnabledDisable to stop the connection.
Log levelInfoTemporarily use Debug for connection or publish diagnostics.
Start timeout60 secondsValid range is 1 to 3600 seconds.

Target properties​

Connection​

SettingDefaultConfiguration
Connection typeTcpUse TCP or WebSocket according to the platform endpoint.
IP addresslocalhostThingsBoard host or IP without a scheme.
Port1883Common MQTT port is 1883; TLS commonly uses 8883; WebSocket uses the platform port.
WebSocket path/mqttUsed only for WebSocket and must start with /.
Client IDEmptyEmpty generates a client ID; fixed IDs must be unique.
MQTT versionV500 (MQTT 5)Match the ThingsBoard endpoint.
Clean sessionEnabledDisable when a persistent session is required.
Keep-alive60 secondsKeep Alive interval accepted by the platform.

TLS and authentication​

SettingDefaultConfiguration
Enable SSLDisabledEnable TLS and use the platform TLS port.
SSL target hostEmptyDNS name in the server certificate SAN; empty uses the IP.
Client certificateEmptySelect a client certificate with private key for mutual TLS.
CA certificateEmptySelect a custom CA when required.
Allow untrusted certificateEnabledCurrent default is enabled for development self-signed certificates; disable in production.
SSL protocolNone (system default)Select a specific TLS version only when required.
Check certificate revocationDisabledEnable according to security policy.
UsernameEmptyThingsBoard commonly expects the device Access Token in this field.
PasswordEmptyFill according to the platform authentication mode; token setups commonly leave it empty.

Runtime and message options​

SettingDefaultConfiguration
QoSAtMostOnce (0)Select the level required by the ThingsBoard deployment.
RetainDisabledUsually keep disabled; enable only when the platform requires retained state.
Detail logDisabledEnable temporarily for MQTT connection and message diagnostics.

The plugin uses the current ThingsBoard gateway Topics:

PurposeTopic
Device attributesv1/gateway/attributes
Telemetryv1/gateway/telemetry
RPC requestsv1/gateway/rpc

This target does not expose the generic device/variable/alarm Topic templates. Topic names are fixed by the ThingsBoard Gateway MQTT contract.

Target variable property​

SettingDescription
Allow RPC writeDefault enabled. Allows ThingsBoard gateway RPC to write this variable. Enable only for approved control points.

The variable must already be inside the forwarding group's range. A target variable property does not add a member to the group.

Cache and capacity​

SettingDefaultConfiguration
Enable failed-write retry cacheDisabledEnable to retain telemetry and device-connect messages in CacheDB while the platform is unavailable and replay them after recovery.
Cache file maximum rows262144Maximum CacheDB outbox rows; oldest rows are removed after the limit.
Upload chunk size2000Maximum replay batch size.
Memory queue limit100000Maximum in-memory records, including the device-connect queue.
Filter offline dataDisabledFilters offline variables at dequeue; the forwarding-group filter also applies.
Upload concurrency1This target publishes over one connection; keep 1.

Target debug​

Open Development Configuration → Data Forwarding, select the forwarding group and target, and open Debug.

ThingsBoard MQTT protocol panel​

ThingsBoard MQTT protocol debug panel

Use the panel to inspect connection state, endpoint, client ID, TLS, QoS, Retain, device-connect queue, mapped variables, subscriptions, and the three fixed Topics.

Verify the target​

  1. Confirm the ThingsBoard host, port, MQTT version, credentials, and TLS settings.
  2. Confirm that the forwarding group includes one test variable.
  3. Check that telemetry appears in the ThingsBoard gateway device or telemetry view.
  4. Compare device, key, value, and timestamp with GatewayRuntime.
  5. Test an RPC write only when the target and variable permissions allow it, then verify the response and the variable value.

Troubleshooting​

SymptomCheck
No telemetry in ThingsBoardHost, port, credentials/device token, MQTT version, fixed telemetry Topic, group range, target state, and platform device state.
Authentication failsThingsBoard device token or credentials, client ID, TLS, and endpoint port.
Telemetry key is missingSource variable name, forwarding group membership, variable value, and target log.
RPC write failsTarget variable RPC permission, source variable write permission, ThingsBoard RPC payload, and target log.
Connection repeatedly dropsKeep-alive, broker/platform limits, TLS settings, firewall, and network stability.
Device-connect messages accumulateCheck acceptance of v1/gateway/attributes, enable the failed-write retry cache, and inspect the device-connect queue and CacheDB pending count.
Changing a Topic has no effectThingsBoard uses fixed Topics and does not expose generic Topic templates; check the platform subscription and target type.