Page History

...

Introduction

There is an executable file called TMQTTBroker.exe inside the product installation folder. To run it you need to double-click over the file. After running, you can see a blue icon in the Windows tray bar. MQTT Broker will run following the specification configured in the file TMQTTBroker.exe.config, you can find more information about it in the next section.

There is the possibility to run the Broker as Windows Service running the file InstallTMQTTBrokerAsService.exe also found in the product installation folder. This MQTT Broker accepts connection with MQTT Clients following the SparkplugB specification and pure MQTT Clients that do not use SparkplugB as the Mosquitto clients.

Also, it is possible to connect the TMQTTBroker with a runtime project where it can make available all namespaces and properties from the specific projects. In this case the project information will be available following the SparkplugB specification.

TMQQTBroker.exe.config

Before running the TMQTTBroker.exe the file TMQTTBroker.exe.config must be configured with the desire configuration.  It can be found in the product installation folder and you can open it  in any Text Editor. However, it is very important that the file name and extension (.exe.config) remains the same.

Open the TMQTTBroker.exe.config file, you are going to find all the possible configured parameters already there, but they will be in comments (between <!−−   −−> ). Then, to set a specific parameter you need to move the whole line of the parameter outside the comments (<!−−    −−>) but keep it into the section <configuration> <appSettings>.

Example of whole line to move:

<add key="ListeningPort" value="1883"/>

Running the MQTT Broker with the default configuration (without changing the .config file) it will assume the parameters below:

• Listening port: 1883
• UserNameAndPassword1: none
• CertificateFile: none
• CertificatePassword: none

See below the complete list of parameters found in the .config file and their respective description.

MQTT

As defined in http://mqtt.org/:

”MQTT is a machine-to-machine (M2M)/”Internet of Things” connectivity protocol. It was designed as an extremely lightweight publish/subscribe messaging transport. It is useful for connections with remote locations where a small code footprint is required and/or network bandwidth is at a premium. For example, it has been used in sensors communicating to a broker via satellite link, over occasional dial-up connections with healthcare providers, and in a range of home automation and small device scenarios. It is also ideal for mobile applications because of its small size, low power usage, minimized data packets, and efficient distribution of information to one or many receivers (more...)”.

Sparkplug B

As defined in https://www.bevywise.com/blog/sparkplug-b-mqtt-simulation/.

Sparkplug provides an open and freely available specification for how Edge of Network (EoN) gateways or native MQTT enabled end devices and MQTT Applications communicate bi-directionally within an MQTT Infrastructure. One of the unique aspects of MQTT is that it was originally designed for real time SCADA systems to help reduce data latency over bandwidth limited and often unreliable network infrastructure. Similarly the intent of the Sparkplug specification is to take full advantage of MQTT’s native Continuous Session Awareness capability as it applies to real time SCADA/IIoT solutions.

Inside the product installation folder, you will find an executable file called TMQTTBroker.exe. To run it, double click on the file. Once the file is running, a blue icon will appear in the Windows System Tray. The MQTT Broker will run by following the specifications configured in the TMQTTBroker.exe.config file. You can find more information regarding this in the next section. 

The Broker can run as a Windows service by running the file InstallTMQTTBrokerAsService.exe, which is also found in the product installation folder. The MQTT Broker accepts connections with MQTT clients by following the SparkplugB specification. Also, it accepts connections with pure MQTT clients, who do not use SparkplugB, as Mosquitto clients.

The TMQTTBroker can be connected to a runtime project, and it will make all of the project's namespaces and properties available. When connected like this, the project information will be available following the SparkplugB specification. 

...

TMQTTBroker.exe.config

Before running TMQTTBroker.exe, the file TMQTTBroker.exe.config must be configured with the desired configuration. TMQTTBroker.exe.config is in the product installation folder, and you can open it in any text editor. It is very important that the file name and extension (.exe.config) remain the same.

When you open the TMQTTBroker.exe.config file, you will find all of the possible configured parameters. The parameters will be comments surrounded by (<!−−   −−>). To set a specific parameter, you need to move the whole line of the parameter outside the comments (<!−−    −−>) but keep it in the section <configuration> <appSettings>.

Example of the whole line you need to move:

<appSettings>
<add key="ListeningPort" value="1883"/>

When you run the MQTT Broker with the default configuration (without changing the .config file), it will assume the parameters below:

• Listening port: 1883
• UserNameAndPassword1: none
• CertificateFile: none   
• CertificatePassword: none

Below is the complete list of parameters found in the .config file and their respective description.

<appSettings>
<add key="ListeningPort" value="1883
<add key="Backlog" value="100"/>
<add key="GroupId" value="TServer"/>
<add key="TimeUpdateTServers" value="500"/>
<add key="DisableRetainedFileBacklog" value="false100"/>
<add key="CertificateFileGroupId" value="TServer"/>
<add key="CertificatePasswordTimeUpdateTServers" value="500"/>
<add key="SslProtocolsDisableRetainedFile" value="Tls12false"/>
<add key="UserNameAndPassword1CertificateFile" value="Test;#3B43F58BFF9AFF8CFF8BFFCDFF"/>
<add  key="ClientID1CertificatePassword"  value=""/>
<add key="SslProtocols" value="Tls12"/>
<add key="UserNameAndPassword1" value="Test;#3B43F58BFF9AFF8CFF8BFFCDFF"/>
<add  key="ClientID1"  value="ClientID01;Topic1=*,Subscribe1=True,Publish1=True"/>
<add  key="ClientID2"  value="ClientID02;Topic1=*,Subscribe1=True,Publish1=True"/>
<add key="TServer1" value="<ProjectName>;localhost:3101"/>
<add  key="TagProperties"  value="Min;Max"/>
</appSettings>

...

• ListeningPort: Server listening port. Default The default is 1883 if it is not configured 
• CertificateFile: Certificate file to use in the SSL
• CertificatePassword: Certificate password to use in the SSL
• SslProtocols: SSL protocol
• UserNameAndPassword1: UserName and Password password required to Access access the Broker, following using the syntax UserName;Password.

...

The password can be a string (with no encryption ) or an encrypted password. For encrypting To encrypt a password you can use in any coder (ex. Visual Studio), use the following code:

string Encrypted_password = T.Library.StringUtilities.ToHex(string <password>);

The encrypted password will be is a hex character that will be an input is in the .config file.   To  make  To make sure the Broker knows it is required to decrypt it in order to check  must decrypt the password to check for matches, you must add the  ’# ’ symbol before the password. 

<add key="UserNameAndPassword1" value="<UserName>;< Password>" />
E.g.: <add key="UserNameAndPassword1" value="test;1234" />

...

• Backlog: Sets the number of connections to keep a backlog. Default: 100The default is 100. 

• DisableRetainedFile: The broker stores the last retained message and the corresponding QoS for that topic. Valid The valid value is true or false. Default The default is false.

• ClientID: This parameter can enable limitation  This parameter enables limitations for specific MQTT Clients related to For configuring clients. To configure more than one MQTT Client client, you need to create a whole new whole line changing and change the last number of the ClientID to the next sequence sequential number.

  
  

  Code Block
  add key="ClientID1" value="<MQTTClientID>; Topic1=<Topic>, Subscribe1=<True or False>, Publish1=<True or False>" />

  
  

  There are 4 internal parameters:

• value: Sets the MQTT Client Id;ID
• Topic: Specific Topic topic that will set the limitation;
• Subscribe: flag Flag (true or false) that allows Client the client to subscribe to a topic (can receive messages);

• Publish: flag Flag (true or false) that allows Client the client to publish to a topic (can write messages). 

  Code Block
  <add  key="ClientID1"  value="MQTTClientTest;Topic1=*,Subscribe1=True,  Publish1=True"/> <add  key="ClientID2"  value="32443fsa6546fa;Topic1=*,Subscribe1=True,  Publish1=False"/> <add  key="ClientID3"  value="7323rt304343r4;Topic1=*,Subscribe1=False,Publish1=True"/>

  
  

The parameters below are used to make the TMQTTBroker connecting connect with a running project (TServer).

• TServer: Project Name and TServer IP Address and Port Number. For connection The project name as well as the TServer's IP address and port number. To connect the TMQTTBroker with more than one runtime project, you need to create a whole new whole line changing and change the last number to the next sequence. 

add key="TServer1" value="<ProjectName>;<TServerIPAddress>:<TServerPort> " />

E.g.
<add key="TServer1" value="ProjectTest1;localhost:3101" />
<add key="TServer2" value="ProjectDemo;localhost:3201" />
<add key="TServer3" value="ProjectMQTT;192.168.1.10:3101" />

...

• TimeUpdateTSevers: Time between update updates to TServer; Default is 500 milliseconds 
• GroupId: Alias that will be used in the Topictopic
• TagProperties: List of Tag tag properties that will be are sent to the MQTT Client client when they change values.

<add  key="TagProperties"  value="Minl;Max;AlarmState;Acked"  />

...

Topologies

There are two ways the The TMQTTBroker can be implemented in two ways. It can be used as a simple gateway to exchange that exchanges data between any MQTT Clients client or through a direct connection with runtime projects and by publishing project data for MQTT Clients clients using the SparkplugB specification. 

Simple Gateway

 In this scenario, the TMQTTBroker only will exchange exchanges data between MQTT Clients clients following the SparkplugB specification or not. Then, the Clients clients are responsible to subscribe and publish topics to the Broker. Any topic format is supported All topic formats are shown in this scenario.

Connected to Runtime project

 In this scenario, the TMQTTBroker will connect with  connects to one or several more runtime projects through the TServer. It will publish only publishes the project data only for topics by following the SparkplugB specification.

...

spBv1.0/<Group_Id>/<message_type>/<Project_Name>/<MQTT_Device_Name>

Where the:

• Group Id: is a the name that is configured in the .config
• Message Type: The following message type Message Type elements are defined for the Sparkplug specifi- cation. Almost of the Clients specification. For most clients that support SparkplugB should set , the message type automat-will automatically be set. 
• NBIRTH – Birth certificate for MQTT EoN
• NDEATH – Death certificate for MQTT EoN
• DBIRTH – Birth certificate for devices
• DDEATH – Death certificate for devices
• NDATA – Node data
• DDATA – Device data
• NCMD – Node command
• DCMD – Device command
• STATE – Critical application state
• Project Name: is the same name configured in the .config
• MQTT Device Name: it can be a namespace or an object from the runtime project. The However, individual objects should be avoided and uses the namespaces for . Use a namespace for better performance

Examples of namespaces: Tag, Script, Device, Info, Script, Server, Security, Alarm, Historian DataSets, TemplatesName and MainTag for arrays.

...

spBv1.0/TServer/DDATA/Project1/Tag

Gateway + Connected to Project

In this scenario, the TMQTTBroker will work  works as if the last two scenarios are combined together. As This means a simple gateway exchange any exchanges data between the MQTT Clients and publishing publishes project data projects to the topics that match the project configuration in the TMQTTBroker.exe.config.

...

MQTT driver (without SparkPugB)

To The first step to set up a communication between the TMQTTBroker and the MQTTdriver , the first step is to create a Channel using this the protocol shown in the image below.

In the Engineering Environmentenvironment, go to Edit > Devices > Channels Edit>Devices>Channels and find the desired protocol inside the list.

In the Nodes tab, the primary station is configured in configured using the following syntax below:

<BrokerURL> ; <port> ; [Username] ; [Password] ; [X509Certificate] ; [QoS]

...

Where, Username, Password, X509Certificate, and QoS are optional.

In the Points tab, you need to configure the Topic in which topic so that your variable may can publish or subscribe to messages ( according to its AccessType). More information on is available for each item is available in the MQTT driver documentationAddress columns, under Edit > Devices > Points.

Mosquitto Client (without SparkPlugB)

The TMQTT Broker can have other clients connect to it in Clients can connect with TMQTT Brokers the same way as others Brokers available they connect to other available Brokers (e.g: mosquitto). 

In order to test itthe connection, you can use mosquitto (Mosquitto either as a publisher or as a subscriber). The syntax required to publish a message and subscribe to a topic with mosquitto Mosquitto is:

mosquitto_pub -p <portNumber> -t <Topic> -m <Message>
mosquitto_sub -p <portNumber> -t <Topic>

...

MQTTSpB driver (SparkPlugB)

To The first step to set up a communication between MQTT + SparkPlug Driver and the TMQTT Broker , the first step is to create a Channel using this the protocol shown in the image below. 

In the Engineering Environmentenvironment, go to Edit > Devices > Edit>Devices>Channels and find the desired protocol inside the list.

In the ProtocolOptions column ProtocolOptions, there are some fields that must be filled., you need to fill out the following fields:

• Type;
  • Application Node;
  • Scada IIoT Host;
  • EoN

...

More information on each item is available in the MQTT + SparkPlugB driver documentation. In the Nodes tab, the primary station is configured in configured using the following syntax below:

<BrokerURL> ; <port> ; [Username] ; [Password] ; [X509Certificate] ; [SslProtocol] ; [WebSocket] ; [ScadaIIoTHostID]

...

The topics are configured using the following syntax.:

<GroupId>;<EdgeNodeId>;<DeviceId>;<QoS>

...

Using Third Party MQTT Clients – MQTT fx (SparkplugB)

It is possible to You can set up a communication between the TMQTT Broker with Third Parties and third party MQTT Clients. In this example, we will use MQTT.fx.

To configure this client MQTT.fx, the following steps are required:

Step 1: The TMQTT Broker must be running (look . Look for the icon in the Windows TaskBar).

Step 2: In the Clientclient, go to Extras > Edit Extras>Edit Connections Profiles. In the opened Window you will fill the properties  In the window that opens, fill in the MQTT Broker Profile Settings according to your Broker broker (e.g.: Broker Address and Broker Portbroker address and broker port). Then, click on connect. 

Step 3: In the subscribe Tab tab, the Topic topic will follow the syntax below:

spBv1.0/<Group_Id>/<message_type>/<Project_Name>/<MQTT_Device_Name>

Let’s imagine an example , in which the Project Name project name is ’Project1’, and we have an integer tag called ’Tag.Integer1’.

In this situation, order to correctly subscribe to the Tagtag, first you need to create a Device Birth Certificate (to start device birth certificate, which starts the communication channel).

spBv1.0/TServer/DBIRTH/Project1/Tag.Integer1 // create channel for this specific tag
// or
spBv1.0/TServer/DBIRTH/Project1/Tag // create channel for all tags

...

There are some other More data that can exchange be exchanged between the running project and TMQTT Broker. Some examples can be seen below.

...

Step 4: After subscribing for to the desired topics, the exchanged data can be seen in the top - right corner.

...

Step 5: To correctly format the received data, copy the message and paste it in into any JSON formatter (e.g.: https://jsonformatter.org/json-pretty-print). The result should be something like the code below.

{
"timestamp": 1580152490182, "metrics": [
{
"name":  "Integer1", "timestamp": 1580152489659, "dataType": "Int32", 
"value": 30
}
],
"seq": 1
}

Appendix

MQTT

As defined in http://mqtt.org/:

”MQTT is a machine-to-machine (M2M)/”Internet of Things” connectivity protocol. It was de- signed as an extremely lightweight publish/subscribe messaging transport. It is useful for connec- tions with remote locations where a small code footprint is required and/or network bandwidth is at a premium. For example, it has been used in sensors communicating to a broker via satellite link, over occasional dial-up connections with healthcare providers, and in a range of home automation and small device scenarios. It is also ideal for mobile applications because of its small size, low power usage, minimised data packets, and efficient distribution of information to one or many receivers (more...)”.

Sparkplug B

As defined in https://www.bevywise.com/blog/sparkplug-b-mqtt-simulation/.

...