Skip to main content

MQTT Collection Client

Purpose​

The MQTT Collection Client subscribes to broker topics and maps JSON or raw payload values to gateway variables.

Open the plugin​

Open Development Configuration → Collection Configuration, create a device, and select MQTT Collection Client.

This plugin manages its broker connection in device properties and does not use an ordinary TCP, UDP, or serial channel. Configure common variable fields through Collection Configuration.

Plugin properties​

Connection​

SettingDescription
Connection typeDefault Tcp. Select TCP or WebSocket according to the broker endpoint.
IP addressDefault localhost. MQTT broker host name or IP address.
PortDefault 1883. Use the broker's TLS or WebSocket port when applicable.
WebSocket pathDefault /mqtt. Used only for WebSocket connections.
Client IDClient identifier. It must be unique on the broker.
Clean sessionDefault enabled. Controls whether the broker removes the previous session state.
MQTT versionDefault 4 (MQTT 3.1.1). Select the version required by the broker.

Connection type options are Tcp and WebSocket. MQTT version options are V310 (MQTT 3.1), V311 (MQTT 3.1.1), and V500 (MQTT 5.0). For WebSocket, the effective URL is ws://IP:port/path, or wss:// when SSL is enabled.

TLS and authentication​

SettingDescription
Enable SSLEnables TLS for the broker connection.
SSL target hostHost name used for certificate validation.
Client certificateClient certificate configured in Certificate Management.
CA certificateCA certificate used to validate the broker.
Allow untrusted certificateTemporary commissioning option for self-signed certificates. Disable it in production.
SSL protocolSelect a TLS protocol only when required by the broker or security policy.
Check certificate revocationEnables certificate revocation checks.
Username / passwordBroker credentials. Do not expose the password in screenshots or logs.

Disable Allow untrusted certificate in production and configure the target host name and CA. Select a client certificate for mutual TLS. When Username is non-empty, the broker credentials must match the configured username and password exactly.

Runtime and messages​

SettingDescription
Keep-aliveDefault 60 seconds. The broker and network policy must allow this interval.
Connection timeoutDefault 3000 ms. Maximum wait for establishing the broker connection.
QoSDefault 0. QoS used for subscriptions and publishes.

QoS options are 0 (at most once), 1 (at least once), and 2 (exactly once). The selected level is used for subscriptions and plugin control publishes. | Detailed log | Enables detailed connection, payload, and message logs during commissioning. Disable it after troubleshooting. | | Check and cleanup interval | Default 60000 ms. Interval used to clean connection or request state. |

Address rule​

The variable address is a semicolon-separated mapping:

{subscribeTopic};{jsonPath1||jsonPath2};{condition};{publishTopic};{Json|RawString};{retain};{rpcResponseTopic};{rpcTimeoutMs}

Examples:

UseAddress
Read a JSON valuevendor/device;$.data.temperature;TelemetryCondition
Publish a raw write;;;factory/a/reboot;RawString;false
RPC request and response;;;factory/a/command/{RequestId};Json;false;factory/a/response/{RequestId};5000

Payload paths support $, dot paths such as items.0.value, filters [?()], wildcards [*] and .*, and recursive search $..name. With ||, the first existing candidate path is used. Exact case-sensitive property names are preferred; a unique case-insensitive match is used only when no exact name exists.

The condition is a DataTrans script name. Its raw input contains the complete JSON payload; it may also declare Topic or MqttTopic to inspect the published topic. A wildcard subscription updates the same variable for every matching message, so use an exact topic or filter by Topic when values must be separated by device.

The subscribed message does not include the publisher's client ID. ClientId and MqttClientId inputs are therefore empty for this plugin. Publish topics cannot contain + or #; {RequestId} must be the final topic level.

The address has at most eight segments. A subscribe topic and JSONPath must be provided together; publish options require a publish topic. RPC response topic and timeout are a pair, and the timeout must be 100–60000 ms. A read-only variable cannot contain publish fields, a write-only variable cannot contain telemetry fields, and every variable must configure at least one route.

Functions​

FunctionPurpose
Publish messageUse Publish message with an approved test point and confirm site safety before execution.
Subscription managementCreate, refresh, or remove subscriptions and inspect the received updates.
Refresh subscriptionsReload the subscriptions confirmed by the current MQTT session.

Device debug​

Open Development Configuration → Collection Configuration, select the MQTT device, and click More Functions, then open Debug.

MQTT client protocol panel​

MQTT Collection Client protocol debug panel

Use the panel to connect, subscribe, publish a test message, or inspect the result. Start with a safe test topic and a small payload.

Verify the configuration​

  1. Subscribe to an exact test topic.
  2. Publish a JSON payload containing one known field.
  3. Confirm that the JSONPath or condition script selects the expected value.
  4. Check that the variable value and collection time update.
  5. Test publishing or RPC only when the variable and device permissions allow it.

Troubleshooting​

SymptomCheck
Cannot connectBroker address, port, Client ID, credentials, TLS settings, firewall, and broker ACL.
Message arrives but variable is unchangedExact topic, JSONPath, condition script, payload shape, and variable data type.
Wrong device value is updatedAvoid a shared wildcard topic or filter by Topic in the condition script.
Publish or RPC failsPublish topic, {RequestId} position, QoS, response topic, timeout, and permissions.
Certificate is rejectedClient certificate, CA, target host name, and trust settings.