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 Devices or TagProviders. Devices handle predefined, static data, ensuring control, security, and advanced metadata management, suitable for applications requiring strict validation like HMI and SCADA systems. TagProviders manage dynamic data, enabling flexible device addition and real-time updates, ideal for IoT and monitoring applications needing situational awareness.

In summary, devices are ideal for applications where data structures are stable and predefined. These environments often require strict regulatory compliance, such as FDA validation in pharmaceutical production or stringent monitoring in manufacturing plants. Devices provide detailed metadata management, including retentiveness, security settings, and visibility control within the platform. This ensures precise control over data access and modifications, enhancing security and reliability. For example, in a manufacturing plant, Devices can monitor equipment performance with predefined tags, ensuring data integrity and compliance with safety standards.

TagProviders are suitable for environments where data and device configurations change frequently, necessitating real-time updates. This is common in IoT and monitoring applications, such as smart city infrastructures or home automation systems. TagProviders allow for seamless addition and modification of devices without extensive reconfiguration, facilitating quick adaptation to new data sources. They connect to external systems, enabling real-time data integration and situational awareness. For instance, TagProviders can dynamically integrate new environmental sensors in a smart energy grid, providing continuous updates and allowing city managers to respond promptly to changing conditions.

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]

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

Time Publish Rate: Indicates the time for publishing in ms. The messages that will be published to the MQTT Broker are grouped and sent using this period.

Store And Forward: 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 in the Devices > Channels even after a re-established connection and always using the first-in, first-out (FIFO) method to forward the data.

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

Use Parenthesis for Array: 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, which can also include the following macros, intermixed with the text:

• _Guid_: Replaced by a dynamically generated Global Unique Identifier (GUID).
• _Solution_: 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 Client. 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 MQTT Broker works by using a certificate, this field is mandatory and must be the same as configured in the MQTT Options: None, Ssl2, Ssl3, Tls, Tls11, and Tls12 (optional).

[WebSocket]: Flag indicating if the connection to the MQTT Broker should be via the 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 sender and receiver of a message 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 communication points are:

<GroupId> / <EdgeNodeId> / <DeviceId>

Where:

• <GroupId>: Provides a logical grouping of Edge Nodes. Wildcards are not supported.
• <EdgeNodeId>: Identifies ID of Edge Nodes. Wildcards are not supported.
• <DeviceId>: Identifies ID of Device from Edge Node. This field can be empty while accessing main Egde Node. Wildcards are not supported.

The GroupId combined with the EdgeNodeId element must be unique from any other GroupId / EdgeNodeId assigned in the MQTT infrastructure

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. At the Devices / Points tab, add just the main Tags (Motor1 and Motor2) to the table.

Both Tags are mapped to the same EdgeNodeId, 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 / External TagProviders, and create a new provider for the MQTT +SparkplubB 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: 100ms.

The Store and Forward feature can be enabled for MQTTTspB 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: