MQTT Publisher

About 14 min read

MQTT Publisher publishes the value and quality changes of 2WinScada tags to an MQTT broker. IoT platforms, energy management, MES/ERP and maintenance systems, or MQTT clients such as Node-RED, can receive SCADA data this way without connecting to the database or the API.

This feature is different from the MQTT Client channel, which reads data from devices over MQTT. MQTT Publisher does not read data; it passes tag changes in the running SCADA to the outside.

Publishing is done by the MQTT publisher service, which runs separately from the main service. The main service filters tag changes and passes them to the publisher service; the publisher service sends them to the broker.

The main system is not affected

MQTT Publisher is optional. Even if the publisher service or the broker is stopped, unreachable or misconfigured, tag reading/writing, archiving, alarms and the web interface keep working.

Requirements

• The installed license must include MQTT integration. If the license does not include it, settings can be saved, but no data is published and the connection test cannot be run.
• The MQTT publisher component must be installed and enabled with the setup tool.
• You need a reachable MQTT broker and a user defined on this broker for the publisher.

Accessing the Page

The settings are managed on the Settings > MQTT Publisher Settings page.

User	Sees it in the menu	Can save
SystemAdmin group	Yes	Yes
Administrators group	Only when the installed license includes MQTT integration	Yes
Other users	No	No

Permission is checked again on the server for every request, based on the user's stored group. Even if the page address is typed by hand, an unauthorized user cannot see the settings.

Depending on the situation, these notices can appear at the top of the page:

• This installation's license does not include MQTT integration...: Settings are saved, but no data is published until the license includes this feature.
• No settings have been saved from the web yet...: The form was filled with the current values from the service configuration files (see Relation to the Configuration File).
• MQTT publisher settings have not been configured yet.: There is no saved web setting and the values in the configuration file could not be read; the form opened with default values.
• You are not allowed to change these settings...: Values are shown read-only.

Service Status

The Service status card shows how the main service sees the publisher service. The Refresh status button at the top right of the card reads the information again.

Publisher service	Meaning	What to do
Not installed	The MQTT publisher component is not enabled on this installation.	Install the component with the setup tool. Settings can already be saved; they are applied when the component is installed.
Reachable	The publisher service responds.	Check the other rows of the card.
Unreachable	The publisher service is stopped, its address is wrong or network access is blocked.	Check that the service is running. Saved settings are applied automatically when the service becomes reachable.
Producer key rejected	Authentication between the publisher service and the main service failed.	Repair the installation with the setup tool or contact your system integrator.
Outdated	The publisher service is an old version that does not support web settings.	Upgrade the publisher service to the same version as the main service.
Insecure address	The publisher service address is a remote http address; for security reasons the password is not sent.	Use https or a local address on the same server.

Other rows of the card:

Row	Expected	If not
Active settings source	Web settings after saving	If Service configuration file is shown, the settings have not reached the publisher service yet. Wait about 30 seconds and click Refresh status.
Settings in sync	Yes	Wait for the settings to be delivered.
Connected to broker	Yes	The publisher service opens the broker connection only when there is a message to send. If it stays No while tags are changing, check the broker with Test connection.
License includes MQTT	Yes	The installed license does not include MQTT integration; nothing is published.
Service allowed to publish	Yes	Restart the publisher service after a license change; if the problem persists, contact your system integrator.

Settings

General

Publishing enabled: When on, tag changes are published to the broker. If the MQTT publisher component is not installed, this setting has no effect. To stop publishing temporarily, turn the switch off and save; no restart is needed.

The bottom of the card shows when the settings were last saved (Last updated).

Broker

Field	Description
Broker host	Host name or IP address of the broker. Required while publishing is enabled. At most 255 characters; cannot contain spaces.
Port	1–65535. Usually 1883 for unencrypted MQTT and 8883 for TLS. Default 1883.
Client ID	The MQTT client identifier on the broker, at most 128 characters. If left empty, the service uses a client ID. It must be unique for each publisher that connects to the same broker.

Authentication

Field	Description
Username	Broker user, at most 256 characters. If left empty, the connection is anonymous.
Password	At most 512 characters. If a password is stored, A password is stored is shown under the field. Leaving the field empty keeps the stored password; to change it, enter the new password.
Remove the stored password	Visible only while a password is stored. If checked and saved, the password is deleted.

The stored password is bound to the connection target it was entered for. If Broker host, Port, Username or Use TLS changes, or one of the certificate exceptions is newly turned on, the page asks for the password again. Enter the password again or check Remove the stored password. Turning a certificate exception off keeps the password.

The The stored password could not be decrypted warning appears in cases such as when the password was restored from another installation. Enter the password again.

TLS

Field	Description
Use TLS	Encrypts the broker connection with TLS. Recommended in production.
Allow untrusted certificates	Connects even if the broker certificate is not trusted.
Ignore certificate chain errors	Connects even if the certificate chain cannot be validated.
Ignore certificate revocation errors	Connects even if the revocation status of the certificate cannot be checked.

Certificate exceptions can be selected only while Use TLS is checked.

Certificate exceptions

Certificate exceptions leave the connection open to man-in-the-middle attacks. Use them only in test environments or on trusted networks.

Publishing

Field	Description
Topic style	Flat (Channel.Device.Tag), Path (Channel/Device/Tag) or Both. Both publishes every change to two separate topics.
Topic prefix	Optional, at most 128 characters. Added to the start of the topic with the separator of the selected style. Cannot start with /; cannot contain + or #.
Example topic	Shows the topics that the selected style and prefix produce.
Quality of service (QoS)	0 - At most once, 1 - At least once (default) or 2 - Exactly once.
Retain messages	When on, the broker keeps the last message of each topic; a newly connected subscriber gets the last value immediately. Off by default.

• Do not put / or . at the end of the prefix; the separator is added automatically. A separator at the end creates an empty level in the topic.
• Before you select QoS 2, make sure the broker supports it; some brokers do not support QoS 2 or downgrade it.
• If you change the topic style or prefix while retain is on, the messages retained on the old topics stay on the broker. Clear them with the broker's tools.

Change for subscriber systems

The topic style and prefix decide the address subscriber systems listen to. Prepare subscriber systems for the new topics before you change them.

Tag Filters

Decide which tags are published. Each line holds one regular expression (regex). The expression is applied to the tag's full name in the form Channel.Device.Tag and is case-insensitive.

• If the list is empty, all tags are published (Every tag is published.).
• A tag is published if it matches any of the expressions.
• At most 100 expressions can be defined; each expression can be at most 512 characters long.
• Lookarounds, backreferences and atomic groups are not supported.

Examples:

Expression	Selected tags
^Kanal1\..*	All tags in the Kanal1 channel
^Kanal1\.Analizor1\..*	All tags of the Analizor1 device in the Kanal1 channel
^.*\.Sicaklik$	All tags whose name ends with Sicaklik

For the first commissioning, we recommend starting with a narrow filter to limit the data volume.

Connection Test and Saving

The Test connection button opens a temporary connection to the broker with the connection details in the form (host, port, client ID, username, password, TLS options):

• The test does not save the settings and does not affect the running publishing.
• The publisher service runs the test; the result reflects the network access of the server the publisher service runs on.
• The temporary connection adds -test- and a random suffix to the end of the client ID. If the broker's access rules depend on the client ID, they must cover this form too.
• A test takes at most about 10 seconds, and only one test runs at a time.
• If the license does not include MQTT integration, the test cannot be run.

A successful test shows the Connected to the broker (… ms). message. The messages shown for failed tests are in the Troubleshooting section.

Save writes the settings to the database and sends them to the publisher service immediately; there is no need to restart the services:

• Publishing enabled and the tag filters take effect immediately.
• If the broker host, the credentials or the TLS options changed, the publisher service closes the current connection and connects with the new settings for the next message.
• Topic style, prefix, QoS and retain apply from the next message on.
• The main service checks about every 30 seconds whether the settings in the publisher service are current and sends them again if needed. Settings saved while the publisher service is unreachable are applied automatically when the service becomes reachable again.

Topic and Message Format

Topics are made of the channel, device and tag names. Examples:

Topic style	Without prefix	With prefix tesis1
Flat	Kanal1.Analizor1.AktifGuc	tesis1.Kanal1.Analizor1.AktifGuc
Path	Kanal1/Analizor1/AktifGuc	tesis1/Kanal1/Analizor1/AktifGuc
Both	Separate publish to both topics	Separate publish to both topics

The Path style suits subscribing with MQTT wildcards:

Kanal1/#          All messages in the Kanal1 channel
+/Analizor1/#     The Analizor1 device in every channel
+/+/Sicaklik      All tags named Sicaklik

Renaming a channel, device or tag also changes the topic; subscriber systems should treat this as an interface change.

Every message is a JSON object with the following fields:

Field	Meaning	Type
Cn	Channel name	String
Dn	Device name	String
Tn	Tag name	String
Q	2WinScada numeric quality code	Integer
V	Tag value; can be a number, a Boolean, a string, an object or null	JSON value
Ts	Time of the change, Unix epoch milliseconds in UTC	Integer

{
  "Cn": "Kanal1",
  "Dn": "Analizor1",
  "Tn": "AktifGuc",
  "Q": 192,
  "V": 42.5,
  "Ts": 1786280400000
}

The subscriber application should process the V field keeping its JSON value type, not only as text. The topic style, prefix, QoS and retain settings do not change the content of the message.

Delivery Behavior

• QoS 1 (default) delivers at least once; on network retries the same message can occasionally arrive twice. If needed, the subscriber application should filter out duplicates with the Cn, Dn, Tn and Ts fields.
• With retain off, a subscriber that connects later does not get the last value automatically; it waits for the next change.
• Changes waiting to be sent are kept only in memory, in queues with limited capacity. If the publisher service or the broker is unreachable for a long time, the queue fills up and new changes can be dropped. Waiting changes are not kept when the service restarts.
• When the connection comes back, waiting changes are sent in order; the subscriber application should take delayed timestamps into account.
• MQTT Publisher does not resend historical data; it passes on only the changes that occur while it is running.
• The Both topic style produces two messages for every change and increases the load on the broker.

Security

• The broker password is stored encrypted and is never sent back to the page.
• In production, turn on Use TLS and keep the certificate exceptions off.
• Use a separate broker user and client ID for each plant or publisher; give this user write permission on the broker only for the topics it needs.
• The main service sends the broker password to the publisher service only over https or a local address on the same server. Do not open the publisher service's ports to the external network.

Relation to the Configuration File

Before 2.10, MQTT Publisher could be set up only in the service configuration files. These settings keep working after the upgrade:

Situation	Settings source in effect
Never saved from the web page yet	The service configuration files; the previous behavior continues unchanged.
Saved from the web page at least once	The web settings. The publish switch, broker, TLS, topic, QoS, retain and filter values in the file are no longer used.

If nothing has been saved on the web yet, the page fills the form with the current file settings:

• The password is not imported. If the current configuration uses a password, the page says so; before saving or testing, enter the password or check Save without a password.
• Nothing changes until you click Save, and the file settings stay in effect.

After you save from the web once, you cannot go back to the file settings from the interface. To stop publishing, turn off the Publishing enabled switch.

Some technical settings always stay in the service configuration files and cannot be changed on the web page; contact your system integrator for these. The Publishing enabled switch turns publishing on only while the component is enabled.

Backup and Restore

The MQTT publisher settings are part of the configuration backup as the MQTT Publisher Settings module (see Backup and Restore):

• The broker password is never written to the backup.
• This module is written only to backups taken by users who can manage this page, and is applied only in restores they start.
• On restore, the password stored on the target is kept only if the connection target (host, port, username, TLS) is the same and certificate validation was not relaxed. Otherwise, enter the password again on the page.
• A record with invalid settings is restored with publishing turned off.
• Restored settings are applied within about 30 seconds, without restarting the service.

Troubleshooting

Connection Test Messages

Message	What to do
Wrong username or password.	Check the broker user and the password.
The broker did not authorize this client.	Check the permissions of the user and the client ID on the broker.
The broker did not accept the client ID.	Try a different Client ID.
The broker banned this client.	Remove the ban on the broker side.
The broker is currently unavailable.	Check the state of the broker.
The broker does not support the MQTT protocol version.	Check the settings of the broker's MQTT listener.
The connection timed out.	Check the host, the port and the firewall rules.
The broker could not be reached (host not resolved or connection refused).	Check that the host can be resolved from the publisher service's server and that the port is open.
The TLS handshake failed (certificate or protocol error).	Check the TLS port, the broker certificate and the trusted certificates on the server.
Another connection test is running; try again shortly.	Try again after a few seconds.
The stored password could not be decrypted; enter the password again.	Enter the password again.

Error Messages

Code	Message	What to do
4930	The MQTT publisher service could not be reached.	Check that the publisher service is installed and running.
4931	The MQTT publisher service rejected this installation's producer key.	Repair the installation with the setup tool or contact your system integrator.
4932	The connection test is not available because this installation's license does not include MQTT integration.	Install a license that includes MQTT integration.
4933	The MQTT broker connection test failed.	Use the table above, based on the detail that follows the message.
4934	The MQTT publisher settings are invalid; nothing was saved.	Check the field rules and the password warnings.

Status Card Is Positive but No Messages Arrive

• The tag's full name must match one of the tag filters.
• The subscribed topic must fit the selected topic style and prefix.
• The tag must actually produce a value or quality change; no message is sent for a tag whose value stays the same.
• If the publisher service has just started, publishing waits until the settings are sent again (at most about 30 seconds).
• During long outages the queue may have filled up; narrow the tag filters to reduce unnecessary traffic.