MQTT Client Forwarding
Purpose
This target connects to an MQTT broker and publishes gateway variables, devices, alarms, and plugin events.
Configure the forwarding group and target through Data Forwarding. This page covers only MQTT target properties, variable-level RPC permission, templates, and MQTT debug actions.
Open the plugin
Open Development Configuration → Data Forwarding and:
- Configure and save the forwarding group range, trigger, interval, online filter, and batching.
- Add a target, choose MQTT Client Forwarding, and fill in the basic target information.
- Open Target properties and configure the MQTT endpoint, security, message topics, scripts, templates, and cache.
- Save and enable the group and target, confirm it is online, then use Target debug for publish and subscription checks.
Basic target information
| Setting | Default | Configuration |
|---|---|---|
| Group | - | Select a saved forwarding group. |
| Target name | - | Required and unique within the group. Include Broker and environment. |
| Enable | Enabled | Disable to stop the MQTT client. |
| Log level | Info | Temporarily use Debug for connection, subscription, or publish diagnostics. |
| Start timeout | 60 seconds | Valid range is 1 to 3600 seconds. |
Target properties
Connection
| Setting | Default | Configuration |
|---|---|---|
| Connection type | Tcp | Use TCP or WebSocket. TLS changes the scheme to ssl or wss. |
| IP address | localhost | Broker host or IP without a scheme or port. |
| Port | 1883 | Common TCP port is 1883; TLS often uses 8883; WebSocket uses the Broker's configured port. |
| WebSocket path | /mqtt | Used only for WebSocket. It must start with /. |
| Client ID | Empty | Empty generates a GUID. A fixed ID must be unique on the Broker. |
| MQTT version | V311 (MQTT 3.1.1) | Match the Broker's supported protocol version. |
| Clean session | Enabled | Disable for a persistent session, if the Broker supports it. |
| Keep-alive | 60 seconds | Keep Alive interval. Follow the Broker maximum and network policy. |
TLS and authentication
| Setting | Default | Configuration |
|---|---|---|
| Enable SSL | Disabled | Enable for TLS and use the Broker's TLS port. |
| SSL target host | Empty | DNS name in the certificate SAN; empty uses the IP address. |
| Client certificate | Empty | Select a client certificate with private key for mutual TLS. |
| CA certificate | Empty | Select a custom CA when the Broker certificate is not publicly trusted. |
| Allow untrusted certificate | Disabled | Temporary self-signed-certificate testing only; keep disabled in production. |
| SSL protocol | None (system default) | Keep system default unless the Broker explicitly requires TLS 1.2 or 1.3. |
| Check certificate revocation | Disabled | Enable according to the security policy. |
| Username | Empty | Broker username when authentication is required. |
| Password | Empty | Broker password; never place it in templates, screenshots, or logs. |
Messages and RPC
| Setting | Default | Configuration |
|---|---|---|
| QoS | AtMostOnce (0) | Select 0, 1, or 2 as required by the receiver. |
| Retain | Disabled | Retains the last message per Topic; use only for state topics. |
| RPC write Topic | RpcWrite | Enter a prefix without + or #. The client subscribes to {prefix}/+ and replies on {prefix}/{requestId}/Response. |
| Historical-read RPC Topic | RpcHistory | Enter a prefix without wildcards. Requests use {prefix}/{requestId} and chunked responses use {prefix}/{requestId}/Response. |
| Data request Topic | Empty | Any message on this Topic publishes the configured variable, device, and alarm snapshots. Empty disables it. |
| Device Topic template | Empty | Empty disables device records; otherwise use a fixed Topic or ${field} template. |
| Variable Topic template | ThingsGateway/Variable | Use a fixed Topic or ${DeviceName}/${Name} fields. |
| Alarm Topic template | Empty | Empty disables alarm records. |
| Plugin event Topic template | Empty | Empty disables plugin-event records. |
| RPC script | Empty | Select a saved MQTT dynamic RPC script when custom request/response handling is needed. |
${field} must be present on the corresponding entity or script result. Topics control routing only; forwarding-group range controls membership.
Target-variable properties
This plugin inherits the optional text fields Data1 to Data10 and adds RPC permission. The variable must already be in the forwarding-group range.
| Setting | Default | Configuration |
|---|---|---|
| Allow RPC write | Enabled | Allows an external MQTT client to write this variable. Enable only for approved control points. |
| Data1 to Data10 | Empty | Project-specific metadata. MQTT does not publish these values automatically; reference them explicitly from a script or upload template. |
Data and scripts
| Setting | Default | Configuration |
|---|---|---|
| Detail log | Disabled | Enable briefly to inspect publish payloads or counts. |
| JSON indentation | Enabled | Disable to reduce payload size. |
| Ignore JSON nulls | Enabled | Disable when null fields must remain. |
| Device list upload | Enabled | Publish devices as a list; disable for one message per device. |
| Variable list upload | Enabled | Publish variables as a list; disable for one message per variable. |
| Variable dictionary upload | Disabled | Applies only to variable-list mode; groups by DeviceName → Name → Value. |
| Alarm list upload | Enabled | Publish alarms as a list; disable for one message per alarm. |
| Alarm dictionary upload | Disabled | Applies only to alarm-list mode; groups by device and variable. |
| Plugin-event list upload | Enabled | Publish plugin events as a list; disable for one message per event. |
| Entity scripts | Empty | Select saved scripts for device, variable, alarm, or plugin-event entities; script output is used for Topic and payload rendering. |
Upload template configuration
For each entity, choose Text or Json and optionally enter a ${field} content template. Empty content uses default JSON serialization. Preview before saving; JSON mode must be valid JSON and Text mode does not add quoting or escaping.
| Entity | Available fields |
|---|---|
| Variable | Id, Name, DeviceName, Value, RawValue, LastSetValue, CollectGroup, CollectTime, CreateTime, ChangeTime, IsOnline, DataType, Unit, RegisterAddress, OtherMethod, Description, ProtectType, RpcWriteEnable, Remark1 to Remark5, ValueInited, IsMemory |
| Device | Id, Name, ActiveTime, DeviceStatus, PluginName, Description, LastErrorMessage, Remark1 to Remark5 |
| Alarm | AlarmId, VariableId, Name, DeviceName, AlarmCode, AlarmLevel, AlarmLimit, AlarmText, RecoveryCode, AlarmTime, EventTime, FinishTime, ConfirmTime, ConfirmText, AlarmType, EventType, Remark1 to Remark5 |
| Plugin event | DeviceName, ObjectValue |
An entity script changes the object before Topic grouping and template rendering. Keep template fields aligned with the script output. An empty corresponding Topic disables that entity type.
Cache and capacity
| Setting | Default | Configuration |
|---|---|---|
| Enable failed-write retry cache | Disabled | Enable in production to retain failed publishes in local CacheDB and replay them after recovery. |
| Cache file maximum rows | 262144 | Maximum CacheDB outbox rows; oldest rows are removed after the limit. |
| Upload chunk size | 2000 | Maximum records per write or replay batch. |
| Memory queue limit | 100000 | Maximum in-memory records before handoff to CacheDB; sustained overload can still discard old data. |
| Filter offline data | Disabled | Filters offline variables at dequeue; the forwarding-group filter also applies. |
| Upload concurrency | 1 | MQTT publishes over one connection; keep 1. |
Target debug
Open Development Configuration → Data Forwarding, select the forwarding group and target, and open Debug.
MQTT client protocol panel
Use the plugin-specific panel to publish a test message, subscribe to a test topic, or remove a subscription. The target must be online before protocol operations can run.
Debug checklist
Use a test Topic and small payload. Check connection state, QoS, retain flag, broker response, and message log. Use a separate test topic for RPC writes.
Verify the target
- Subscribe on the receiver side before sending a test value.
- Change or write one safe variable included in the forwarding group.
- Confirm Topic, payload, QoS, retain flag, and message count.
- Check the target log for reconnect, authentication, or publish errors.
Troubleshooting
| Symptom | Check |
|---|---|
| No message at the receiver | Broker address, port, Client ID, credentials, Topic, ACL, and target online state. |
| Connection repeatedly drops | Keep-alive, TLS settings, broker limits, firewall, and network stability. |
| Topic is unexpected | Topic templates, ${key} fields, entity script output, and group alias. |
| Retained message is unexpected | Disable Retain when the receiver does not need retained state, then clear the old retained message at the broker. |
| RPC write fails | Target and variable RPC permissions, RPC Topic, payload format, and the variable data type. |
| Template output is invalid | Run template preview and check placeholder names, JSON syntax, and entity-script output. |
| TLS handshake fails | IP, SSL target host, client certificate, CA, SSL protocol, certificate validity, and the allow-untrusted setting. |
| Failed publishes disappear | Check the failed-write retry cache, CacheDB pending rows, memory queue limit, and cache file maximum rows. |
Related links
- Data Forwarding: Forwarding groups, triggers, cache, redundancy, and common target operations.
- Plugin Manual Index: Other collection and data-forwarding plugins.