This document has only the specific information about the device connection settings and its address syntax.

Refer to the User Guide for more information on the Device Module.

Summary

Configuration

The software platform supports MQTT SparkplugB Protocol, configurable as a Device. Devices handle predefined, static data, ensuring control, security, and advanced metadata management, suitable for applications requiring strict validation like HMI and SCADA systems.

You can also configure this protocol as a TagProvider, which is recommended if you're working with dynamic data. Learn more at MQTT TagProvider.

MQTT SpB Device

The initial configurations for devices in the software platform solutions involve defining a Channel using a target communication Protocol, which sets communication rules between the platform and devices and creates the base instance for linking a Node. Next, define the Node linked to the created Channel, and finally, define the Point you want to monitor.

Channel

Channels define global parameters for the usage of a communication protocol.

Protocol Options

Type: Defines how the channel works when connecting to the MQTT Broker.

Collector: It is a primary MQTT client that consumes the real-time messages but also publishes commands (messages) to Publisher nodes and devices. [Scada IIoT Host]

Publisher: It is a MQTT client that has as its main function to publish messages read from field equipment. It also can receive commands from Collectors. [Eon Node]

TagProperties: Defines the tag properties beyond the Value. The names of the properties should be separated by a comma ' , '.

TimePublishRate: Indicates the time for publishing, in milliseconds. The messages that will be published to the MQTT Broker are grouped and sent using this period.

StoreAndForward: When this option is enabled a database file, named as below, will be created at the same path of the project file.

<ProjectName>.dbCh_N_<Device.Node.Id>_<GroupId>_<NodeId>

Where:

<Device.Node.Id> is the row value from the ID column in Devices / Nodes.

<GroupId> and <NodeId> come from the Address column in Devices / Points.

E.g.: MyMQTTProject.dbCh_N_0_MyGroupID_MyNodeID.

All data will be stored in this database before forwarding to Broker. The data that receives the Broker confirmation will be removed from this database. Then, when the communication with the Broker is lost, the data will stay in the local database until the connection is re-established to the Broker. The data-updating rate to the Broker is the time configured in the TimePublishRate field, even after a re-established connection and always using the first-in, first-out (FIFO) method to forward the data.

PublishDBIRTHAfterNBIRTH: Flag that indicates if a DBIRTH message will also be published when an NBIRTH message is requested.

UseParenthesesForArray: Flag that indicates if it should replace brackets by parentheses in the metric name.

Node

Nodes represent the physical field devices (like a PLC) with a unique field address (PrimaryStation).

Station Configuration

The station syntax is:

BrokerURL ; Port ; [ClientID] ; [Username] ; [Password] ; [X509Certificate] ; [X509CertificatePassword] ; [NetworkSecurity] ; [WebSocket] ; [ScadaIIoTHostID] ; [QoS] ; [KeepAlive]

Where:

BrokerURL: MQTT Broker (Server) URL. Defaults to localhost.

Port : MQTT Broker port. It must be the same port as configured in the Broker. Defaults to 1883.

[ClientID]:  A unique identifier for the client connecting to the MQTT broker. If left empty, a unique identified client will be assigned. This user-defined string can also include the following macros, intermixed with the text:

• _Guid_: Replaced by a dynamically generated Global Unique Identifier (GUID).
• _SolutionName_: Replaced by the name of the solution (without the path or file extension).
• _NodeId_: Replaced by the string defined as the NodeId.
• _GroupId_: Replaced by the string defined as the GroupId.

[Username]: Username defined on the MQTT. This is requested if the Broker needs this configuration (optional).

[Password]: Password defined on the MQTT. This is requested if the Broker needs this configuration (optional).

[X509Certificate]: Path of the X509 certificate. If using a server-side only certificate, this field does not need to be configured. This must be the complete path of the X509 certificate on the client computer. The certificate must be installed on the computer. Note: One of the easiest ways to install the certificate on the client computer is to use the wizard and use the ”Internet Options” to import the certificate in the ”Trusted Root Certification Authorities”. You need to import the certificate in the DER format (optional).

[X509Certificate Password]: Password created when X509Certificate was exported (optional).

[NetworkSecurity]: If the Broker works by using a certificate, this field is mandatory and must be the same as configured in MQTT. Options: None, Ssl2, Ssl3, Tls, Tls11, and Tls12 (optional).

[WebSocket]: Flag indicating if the connection to the MQTT Broker should be via WebSocket. Check how MQTT Broker works before checking it (optional).

[ScadaIIoTHostID]: If channel works as Publisher, some Collector is active and other MQTT Brokers are also present in the network (redundancy, scalability, etc.,), this field is used to know that the MQTT Broker must be used. A Collector publishes its ID when connecting to MQTT Broker (optional).

QoS: Quality of Service (QoS) is an agreement between the sender and the receiver of messages regarding the guarantees of delivering a message. There are 3 QoS levels:

AtMostOnce: This service level guarantees a best-effort delivery. However, there is no guarantee of delivery, due to the recipient not acknowledging the receipt of the message.

AtLeastOnce: This service guarantees that a message is delivered at least one time to the receiver. Default Value.

ExactlyOnce: Highest level of service. It is safer, but slower when compared to the others. When the message flow is complete, all parties involved in the communication are sure the message was sent and delivered with success.

KeepAlive: Ensures that the connection between the Broker and Client is open and both parties are aware of the connection. Default is 10 seconds.

Report out of Range by Exception: Uses Tag Min/Max as limits. If enabled, only publish item when value is out of range of Min and Max.

CertificateConverter.exe /certificate:"<PathToCertificateFile.pem>"
						 /key:"<PathToKeyFile.pem>"
						 /password:<PasswordForExportedCertificate>

Points Configuration

Points represent tags within a device.

Address

The syntax for the MQTT Collector communication points is called Topic:

• Topic is a string that is used by the broker to filter messages for each connected client. A topic consists of one or more topic levels. Each topic level is separated by a forward slash (topic level separator). Wildcards are not supported.

E.g.: USA/Houston/Station1/Level

Access Type

AccessType defines how the device interacts with the platform (Read and/or Write).

This communication protocol works on an exception basis, using address subscriptions. In other words, when operating in Collector mode to read values, if the value changes in the broker, it will automatically be sent to our driver without the need for polling. Therefore, there is no need to configure read pooling for the value to be read. However, for writing, whether using Collector or Publisher mode, the write access type must be configured.

TagMapping

This protocol DOES NOT support the usage of simple Tags directly into the Devices / Points table. By simple Tags, we mean variables of common DataTypes (Integer, Digital, Text, ...).

Instead of that, you need to build a DataModel / DataStucture using Templates, and use that Main element as your Communication Point. The example below illustrates that.

We have a Motor Template with members: Temperature and RPM. From that Template, two Tags are created, Motor1 and Motor2.

Once the Tags are created, we can map them to our DeviceIDs. In the Devices / Points tab, add just the main Tags (Motor1 and Motor2) to the table.

Both Tags are mapped to the same NodeID, but different DeviceIDs, as explained before

In Runtime, the Template members will be automatically expanded and your MQTTspB payload will look like the example below:

MQTT SpB TagProvider

This Communication Protocol supports the TagProvider feature, which is a tool that allows you to access your Communication Device Data Model without creating any Project Tags.

For more information, please refer to the Tag Provider document.

How to Configure

To configure the MQTTspB protocol as a TagProvider, navigate to Unified Namespace / TagProvider Connections and create a new provider for the MQTT SparkplugB protocol.

Configure the items under the PrimaryStation column the same way that was described in the Node Configuration.

The parameters configured in the Channel tab are not configured in this TagProvider feature. The default configuration is described below:

• Type: Collector.
• Tag Properties: Only the value property is used in this communication.
• Time Publish Rate: 500ms.

The Store and Forward feature can be enabled for MQTTspB TagProvider at the column with the same name, as illustrated in the image below

Simulator

Troubleshooting

The status of the driver execution can be observed through the diagnostic tools:

Diagnostic Tools

Diagnostics tools refer to the Property Watch, Trace Window, and Module Information. These tools identify communication blocks and address errors, allow property access to pinpoint error causes, and display system messages for device management and troubleshooting, offering a comprehensive approach to device management and troubleshooting for Solutions on the software platform.

Module Information

This tool provides insights into module operations and communication channels, offering information about virtual reading groups, error codes, and communication events. It helps users identify communication blocks and effectively address errors in industrial automation systems.

Property Watch

This tool enables users to access, read, and write tags and internal properties of the system. It assists in identifying the root cause of errors through negative error codes, allowing for real-time adjustments and optimizations to the system configuration.

Trace Window

This tool displays system messages in a data grid interface, providing information about the status of reads, writes, and communication frames. It is particularly useful for various PLCs and communication protocols, as it presents invalid addresses in the configuration, assisting in device management and troubleshooting.

Driver Revision History

In this section: