MQTT Collection Client

The MQTT Collection Client subscribes to broker topics and maps fields from valid JSON messages to gateway variables. RawString controls write publishing; it does not enable telemetry mapping from arbitrary non-JSON text.

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

Setting	Description
Connection type	Default Tcp. Select TCP or WebSocket according to the broker endpoint.
IP address	Default localhost. MQTT broker host name or IP address.
Port	Default 1883. Use the broker's TLS or WebSocket port when applicable.
WebSocket path	Default /mqtt. Used only for WebSocket connections.
Client ID	Client identifier. It must be unique on the broker.
Clean session	Default enabled. Controls whether the broker removes the previous session state.
MQTT version	Default 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

Setting	Description
Enable SSL	Enables TLS for the broker connection.
SSL target host	Host name used for certificate validation.
Client certificate	Client certificate configured in Certificate Management.
CA certificate	CA certificate used to validate the broker.
Allow untrusted certificate	Temporary commissioning option for self-signed certificates. Disable it in production.
SSL protocol	Select a TLS protocol only when required by the broker or security policy.
Check certificate revocation	Enables certificate revocation checks.
Username / password	Broker 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

Setting	Description
Keep-alive	Default 60 seconds. The broker and network policy must allow this interval.
Connection timeout	Default 3000. The current collection connection path does not consume this field to set the handshake budget; inspect actual connection logs.
QoS	Default 0. QoS used for subscriptions and publishes.
Detailed log	Enables detailed message logs during commissioning; restore the normal setting afterward.
Check and cleanup interval	Default 60000 seconds. A readable variable becomes offline after this time without a sample; this is unrelated to disk-cache cleanup.

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.

The current client treats subscription return code 2 as a failure. A Broker can accept QoS 2 and deliver messages while the confirmed-subscription list is missing, affecting RPC readiness. Use QoS 1 when a complete confirmation path is required and handle duplicates. Protocol QoS does not establish equipment execution.

WebSocket paths default to /mqtt and gain a leading slash if needed. TCP does not consume the path. Empty Client ID creates a random identity that may change with connection reconstruction; use a unique stable ID for session or ID-based authorization. Prefer verified V311 or V500; the current V310 protocol-name behavior differs from MQTT 3.1 requirements, so its presence in the list does not establish interoperability.

Start with an exact Topic such as SubscribeTopic=telemetry/line1;Path=$.data.value; and publish {"data":{"value":31}}, then another value. Verify new times and quality before adding wildcards, fallback JSONPaths, or conditions. Topic wildcards and JSONPath wildcards apply to different layers. For RPC use matching request/response {RequestId} positions and verify actual device feedback.

Address rule

Use PropertyName=Value; for each configured property. Property order is unrestricted and names are case-insensitive. Omit unused properties; the final semicolon is optional. Duplicate properties and mixed named/positional fields are rejected.

SubscribeTopic=vendor/device;Path=$.data.temperature;Condition=TelemetryCondition;

Property	Description
SubscribeTopic	Telemetry subscription topic or filter. Configure together with Path.
Path	JSONPath into a valid JSON payload. Separate candidate paths with ||.
Condition	Optional compiled DataTrans script name. The message is accepted only when the script returns true.
ConditionParameters	Optional JSON object mapping script input names to parameter text. Every value is a string, for example {"Minimum":"12.5"}.
PublishTopic	Control or RPC request topic. Omit for read-only variables.
PayloadMode	Json preserves the JSON type; RawString sends unwrapped string text. Default: Json.
Retain	true or false. Default: false; the Broker determines retention support.
ResponseTopic	RPC response topic using the same final {RequestId} level as the request.
Timeout	RPC timeout in milliseconds, 100–60000. Configure together with ResponseTopic.

Examples:

Use	Address
Read a JSON value	SubscribeTopic=vendor/device;Path=$.data.temperature;
Condition with parameters	SubscribeTopic=vendor/device;Path=$.data.temperature;Condition=TelemetryCondition;ConditionParameters={"Minimum":"12.5"};
Publish a raw write	PublishTopic=factory/a/reboot;PayloadMode=RawString;Retain=false;
RPC request and response	PublishTopic=factory/a/command/{RequestId};PayloadMode=Json;Retain=false;ResponseTopic=factory/a/response/{RequestId};Timeout=5000;

Path=$.data.temperature;SubscribeTopic=vendor/device; is equivalent to the first example.

Configure condition parameters in the Web editor

1. Open the variable form and click Edit fields beside Variable Address.
2. Enter the subscribe topic and JSONPath, enable the condition field, and select a compiled DataTrans script.
3. Fill in the inputs shown with their names, types, and descriptions. The order of inputs does not affect their binding.
4. Click Confirm and fill, then save the variable. Applying a changed legacy address generates the named format; viewing or cancelling leaves the original text unchanged.

Parameter text is parsed as a JSON value when possible, otherwise as a string, and is converted to the declared input type. Use 12.5 for a number, true for a Boolean, and JSON for an object or array. Strings may be entered directly; use a quoted JSON string such as "true" to preserve a string resembling a Boolean, null, or number. Unknown inputs and invalid types prevent saving. Each variable stores its own parameter values.

Clearing an input removes its explicit override. Unspecified inputs keep their script defaults; Topic, MqttTopic, ClientId, and MqttClientId receive message context when not explicitly configured. The client plugin receives no publisher ClientId, so those inputs are empty.

Only the first = separates a property from its value; JSONPath filters containing == work unchanged. In named address values, encode ; as %3B and % as %25. Values are decoded once and + remains literal. The editor handles escaping automatically. For example, ConditionParameters={"Marker":"a%3Bb%25"} supplies the string a;b%.

Legacy eight-segment addresses

Existing positional addresses remain supported. Keep unused intermediate segments empty and omit trailing empty segments as needed. Use the named format or Web editor to add condition parameters.

{subscribeTopic};{jsonPath1||jsonPath2};{condition};{publishTopic};{Json|RawString};{retain};{rpcResponseTopic};{rpcTimeoutMs}
vendor/device;$.data.temperature;TelemetryCondition
;;;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.

A present field with null does not guarantee fallback to the next path. Multiple JSONPath matches select the first result rather than creating multiple variables. Use Object to retain an object value and check scalar types against the actual payload.

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.

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.

Device debug

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

MQTT client protocol 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.

Functions

Function	Purpose
Publish message	Use Publish message with an approved test point and confirm site safety before execution.
Subscription management	Create, refresh, or remove subscriptions and inspect the received updates.
Refresh subscriptions	Reload the subscriptions confirmed by the current MQTT session.

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.

Keep the broker connected and stop new telemetry to test freshness. For a short test, set Check and cleanup interval to 5 seconds, wait for the point to become offline, then publish a new valid value and confirm recovery. Restore the production interval afterward. MQTT keepalive maintains a session; it does not establish that a point is receiving fresh data.

For control, enable the variable's RPC write permission, inspect the exact Topic and raw payload with an independent subscriber, and verify field feedback. Json preserves the input JSON type; RawString accepts only a JSON string and publishes its unwrapped text. For RPC, an old retained response, a different RequestId, or a response arriving after timeout cannot complete the new request.

Enabling Retain stores the last message for later subscribers; it does not store history or confirm command execution. Publishing later with Retain false does not delete an older retained message. Use a fresh test topic or clear the old retained message through the Broker before verifying the disabled setting.

Troubleshooting

Symptom	Check
Cannot connect	Broker address, port, Client ID, credentials, TLS settings, firewall, and broker ACL.
Message arrives but variable is unchanged	Exact topic, JSONPath, condition script, payload shape, and variable data type.
Wrong device value is updated	Avoid a shared wildcard topic or filter by Topic in the condition script.
Publish or RPC fails	Publish topic, {RequestId} position, QoS, response topic, timeout, and permissions.
Certificate is rejected	Client certificate, CA, target host name, and trust settings.

Related links

• Collection Configuration: Devices, variables, common permissions, and import.
• Certificate Management: Manage MQTT client and CA certificates.
• Plugin Manual Index: Other collection and data-forwarding plugins.