MQTT Server Forwarding

Purpose

This target starts an embedded MQTT server and publishes gateway variables, devices, alarms, and plugin events to connected MQTT clients.

Configure the forwarding group and target through Data Forwarding. This page covers the MQTT server's listener, security, Topic templates, and server debug operations.

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 MQTT Server Forwarding, and fill in the basic target information.
3. Open Target properties and configure the listener, security, message topics, scripts, templates, and cache.
4. Save and enable the target, connect a test MQTT client, and then use Target debug.

Basic target information

Setting	Default	Configuration
Group	-	Select a saved forwarding group.
Target name	-	Required and unique within the group.
Enable	Enabled	Disable to stop listening.
Log level	Info	Temporarily use Debug for listener, authentication, or publish diagnostics.
Start timeout	60 seconds	Valid range is 1 to 3600 seconds.

Target properties

Listener and security

Setting	Default	Configuration
Connection type	Tcp	Tcp listens for MQTT TCP; WebSocket listens through HTTP WebSocket.
Port	1883	Listener port. Use the deployed TLS or WebSocket port when applicable.
WebSocket path	/mqtt	Used only for WebSocket and must start with /.
Enable SSL	Disabled	Enables TLS. A server certificate is required.
Server certificate	Empty	Select a server certificate with private key from Certificate Management.
CA certificate	Empty	Select a CA when validating client certificates for mutual TLS.
Allow untrusted certificate	Disabled	Temporary self-signed testing only; keep disabled in production.
SSL protocol	None (system default)	Select a specific TLS version only when required.
Check certificate revocation	Disabled	Enable according to the security policy.
Allowed Client ID prefix	Empty	Non-empty values accept only Client IDs beginning with this text.
Username	Empty	When non-empty, clients must provide this exact username.
Password	Empty	Password paired with the username.

Messages and RPC

Setting	Default	Configuration
QoS	0	QoS used for server publications.
Retain	Disabled	Retains the last message for each Topic; clear old retained messages when disabling.
RPC write Topic	RpcWrite	Prefix without wildcards. Requests use {prefix}/+; responses use {prefix}/{requestId}/Response.
Historical-read RPC Topic	RpcHistory	Prefix without wildcards for history requests and chunked responses.
Data request Topic	Empty	Any message publishes variable, device, and alarm snapshots; empty disables it.
Device Topic template	Empty	Empty disables device records; otherwise use ${field}.
Variable Topic template	ThingsGateway/Variable	Use ${DeviceName}, ${Name}, or other variable 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.

Target-variable properties

The server target adds RPC permission and inherits the optional text fields Data1 to Data10. A variable must already be inside the forwarding-group range.

Setting	Default	Configuration
Allow RPC write	Enabled	Allows a connected MQTT client to write this variable. Keep it disabled for monitoring-only points.
Data1 to Data10	Empty	Project-specific metadata. MQTT does not publish these values automatically; reference them in a script or upload template when needed.

Data and scripts

The target inherits Detail log, JSON indentation, Ignore JSON nulls, device/variable/alarm/plugin-event list and dictionary upload, four entity scripts, and Upload template configuration. Configure these the same way as MQTT Client Forwarding; the server and client use the same entity fields and ${field} placeholders.

Upload template fields

In Upload Template Configuration, choose Text or Json for each entity and insert ${field} placeholders. Empty content uses default JSON serialization; preview before saving.

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 runs before Topic grouping and payload rendering. An empty Topic template disables that entity type.

Cache and capacity

Setting	Default	Configuration
Enable failed-write retry cache	Disabled	Enable to keep failed publications in CacheDB and replay them after recovery.
Cache file maximum rows	262144	Maximum CacheDB outbox rows.
Upload chunk size	2000	Maximum records per replay batch.
Memory queue limit	100000	Maximum in-memory records before CacheDB handoff.
Filter offline data	Disabled	Filters offline variables at dequeue; the group filter also applies.
Upload concurrency	1	Server publishes over shared connections; keep 1 until load is tested.

Target debug

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

MQTT server protocol panel

Inspect the server state, connected clients, subscriptions, and MQTT operations.

Publish message

Enter a test Topic and payload to verify server publishing.

Status monitor

Check client connections, subscriptions, and message activity.

Disconnecting a client interrupts its connection. Confirm the affected client before using a kick or disconnect action.

Verify the target

1. Start the target and confirm the listener is available.
2. Connect a test MQTT client with an approved Client ID.
3. Subscribe to the configured variable Topic.
4. Change one variable inside the forwarding group.
5. Confirm Topic, payload, QoS, retain flag, and message count.

Troubleshooting

Symptom	Check
Client cannot connect	Port, connection type, firewall, TLS certificate, credentials, and allowed Client ID prefix.
Subscriber receives no message	Group range, target state, Topic template, QoS, client subscription, and target log.
Retained message is unexpected	Disable Retain and clear the old retained message in the client or broker workflow.
RPC write fails	Target and variable RPC permissions, RPC Topic, payload format, and response Topic.
Template output is invalid	Template preview, placeholder names, JSON syntax, and the entity values used by ${key}.

Related links

• Data Forwarding: Forwarding groups, triggers, cache, redundancy, and common target operations.
• Certificate Management: Manage MQTT server and CA certificates.
• Plugin Manual Index: Other collection and data-forwarding plugins.