Built-in MQTT Broker

Highlighted Features

Our included MQTT broker and clients help you get connected safely, securely, and economically to a wide and growing variety of devices and systems.

• Connects with MQTT Clients following the SparkplugB specification or pure MQTT Clients.
• Can execute on Windows, Linux, and any operating platform that supports NET 8.0.
• Tied integration with FrameworX servers, exposing native FX Tags on the Broker for client subscription.
• Speeds up the development of solutions, with no need to set up extra modules or custom installs.

Configuration

TMQTTBroker Executable

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 operate according to the specifications configured in the TMQTTBroker.exe.config file. You can find more information regarding this in the next section.

The MQTT Broker can also be executed from the Solution Designer interface under the Runtime options, or as a service. The MQTT Broker accepts connections from MQTT clients following the Sparkplug B specification. Additionally, it accepts connections from pure MQTT clients that do not use Sparkplug B, such as Mosquitto clients.

Running as a Windows Service

On Windows, the TMQTTBroker can be set up to run as a Windows service, automatically starting its execution when the computer is powered on.

To enable the MQTT Broker as a service, open the Solutions Manager, go to the Server Information page and click on the MQTTBroker option, under Connected Server Information.

Connecting to Runtime

The TMQTTBroker can be connected to a runtime project, making all of the project's namespaces and properties available. When connected this way, the project information will be available according to the Sparkplug B specification.

This configuration can be enabled in the Runtime Startup page, through the Publish to Built-in MQTT Broker checkbox.

The execution is very efficient, as all the Unified Namespace is made visible to Broker clients for subscriptions, but only when there is a client subscribed to the data being published.

MQTT Broker Configuration

Configuration files

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.

Configuration Dialog

When you click on the icon next to the command buttons in Runtime Startup page, it opens the TMQTT Broker Settings dialog window. This configuration dialog has two tabs: General and Local/Remote.

General 

This tab has the following configuration items:

• Backlog: Manages the queue of pending messages that the broker can handle. Proper configuration ensures the broker effectively manages high volumes of messages without dropping or delaying data.

• DisableRetainedFile: Disables retained message storage. Disabling it can improve performance and reduce storage needs but may cause clients to miss important retained messages.

• MaxPendingMessagesPerClientOut: Specifies the maximum number of pending messages allowed per client. It prevents any single client from overwhelming the broker, ensuring fair resource allocation and avoiding potential denial of service conditions.

• User Credentials: Manages user authentication details, including UserName and Password. Proper user authentication secures the broker, preventing unauthorized access to the IoT network and ensuring only authenticated clients can publish or subscribe to topics.

• Client Connections: Manages client connections, including ClientName, Topic, and permissions (Can Subscribe, Can Publish). Managing client permissions ensures that clients can access only authorized data, enhancing security and data integrity.

Local/Remote

This tab has similar configuration items for both Local and Remote. The difference is that Remote has additional configuration items.

Local

• Listening Port: Specifies the port on which the broker listens for incoming MQTT connections. Default is 1883. Proper configuration ensures the broker accepts connections on the correct port, establishing and maintaining communication.

• Certificate File: Uploads the SSL/TLS certificate file used for secure connections. Using SSL/TLS certificates encrypts data in transit, protecting against eavesdropping and tampering, and securing communication between clients and the broker.

• Certificate Password: Enters the password for the SSL/TLS certificate. This adds an additional security layer by protecting the certificate itself, ensuring only authorized personnel can configure or update the certificate for secure communications.

• SSL Protocols: Selects the desired security protocol (none, TSL, TSL 1.0, TSL 1.2). Choosing the appropriate SSL/TLS protocol encrypts data transmitted between clients and the broker, protecting against security threats and ensuring compliance with industry standards.

Remote

The settings for remote MQTT broker include the previous items plus the following:

• Broker URL: Specifies the address of the remote MQTT broker.

• KeepAlive: Configures the keep-alive interval for maintaining the connection. It ensures the connection remains open by sending periodic keep-alive messages, preventing inadvertent disconnection and ensuring consistent data flow between clients and the broker.

• WebSocket: This checkbox option enables WebSocket connections for MQTT. WebSockets allow MQTT to be used over web-based applications, integrating MQTT communication into web interfaces and applications that use web protocols, broadening the applicability and accessibility of MQTT communication.

• Allow Untrusted Certificates: This checkbox option allows using untrusted SSL/TLS certificates. This flexibility aids development and testing environments where strict security measures are not required. However, this setting should be avoided in production environments due to potential security risks.

The message "TMQTTBroker is running" confirms that the broker is active. In Data Explorer / MQTT Tools, there are three extra configuration options for the broker: 

• Enable Trace: When enabled, it provides the option to enable tracing of MQTT messages. It logs detailed information about MQTT messages, including their content, source, destination, and timestamps.

• Enable Raw View Mode: When selected, it displays the raw data of MQTT messages without any formatting or parsing, providing a clear view of the actual transmitted data. It presents raw data and low-level information for debugging and shows unprocessed data streams, memory contents, register values, and network packets that facilitate in-depth troubleshooting.

• Solution Connection: This configuration option has a drop-down menu that allows users to select predefined MQTT TagProviders or Devices Nodes to discover their data. When selected, the Solution Connection option generates a connection string with the connection details of the selected TagProvider or Device Node. It contains the parameters for connecting to the target MQTT broker. Enabling this configuration may require creating an MQTT External TagProvider or configuring an MQTT Device. For more details, refer to the TagProviders.
  

When you open the TMQTTBroker.exe.config file, you will find all possible configured parameters. The parameters will have comments between (<!−−   −−>). 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>.

Here is an example of the complete line that needs to be relocated:

<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="DisableRetainedFile" value="false"/> 
<add key="CertificateFile" value=""/> 
<add key="CertificatePassword" 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="<SolutionName>;localhost:3101"/> 
<add key="TagProperties" value="Min;Max"/> 
</appSettings>

• ListeningPort: Server listening port. 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 required to access the Broker, using the syntax UserName;Password.

The password can be a string with no encryption or an encrypted password. 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 is a hex character that is in the .config file. To make sure the Broker knows it 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" />

No encrypted password:

Encrypted password:

<add key="UserNameAndPassword1" value="<UserName>;#<Encrypted_Password>" /> 

E.g.:

<add key="UserNameAndPassword1" value="test;#21B4F78BFF9AFF8CFF8BFF" />

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

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

• ClientID: This parameter enables limitations for specific MQTT clients. To configure more than one MQTT client, you need to create a whole new line and change the last number of the ClientID to the next sequential number

<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

• Topic: Specific topic that will set the limitation

• Subscribe: Flag (true or false) that allows the client to subscribe to a topic (can receive messages)

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

<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 connect with a running solution (TServer).

• TServer: The solution name as well as the TServer's IP address and port number. To connect the TMQTTBroker with more than one runtime solution, you need to create a whole new line and change the last number to the next sequence. 

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

E.g.

<add key="TServer1" value="SolutionTest1;localhost:3101" /> 
<add key="TServer2" value="SolutionDemo;localhost:3201" /> 
<add key="TServer3" value="SolutionMQTT;192.168.1.10:3101" />

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

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

Topologies

The TMQTTBroker can be implemented in two ways. It can be used as a simple gateway that exchanges data between any MQTT client or through a direct connection with runtime Solutions by publishing Solution data for MQTT clients using the SparkplugB specification. 

Simple Gateway

In this scenario, the TMQTTBroker only exchanges data between MQTT clients following the SparkplugB specification. In this case, the clients are responsible for subscribing and publishing topics to the Broker. All topic formats are shown in this scenario.

Connected to Runtime Solution

In this scenario, the TMQTTBroker connects to one or more runtime Solutions through the TServer. It only publishes the Solution data topics by following the SparkplugB specification.

The topic is configured following the syntax below:

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

Where the:

• Group Id: The name that is configured in the .config

• Message Type: The following Message Type elements are defined for the Sparkplug specification. For most clients that support SparkplugB, the message type 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

• Solution Name: is the same name configured in the .config

• MQTT Device Name: can be a namespace or an object from the runtime Solution. However, individual objects should be avoided. Use a namespace for better performance

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

Examples of objects: Tag.Test, Server.Second, etc.

Examples of topics:

spBv1.0/TServer/DBIRTH/Solution1/Tag
spBv1.0/TServer/DDATA/Solution1/Tag

Gateway + Connected to Solution

In this scenario, the TMQTTBroker works as the a combination of the two scenarios above. This means a simple gateway exchanges data between the MQTT Clients and publishes Solution data topics that match the Solution configuration in the TMQTTBroker.exe.config.

Examples of Communication

MQTT driver (without SparkPlugB)

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

In the Engineering environment, go to Devices / Channels and find the desired protocol inside the list.

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

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

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

In the Points tab, you need to configure the topic so that your variable can publish or subscribe to messages according to its AccessType. More information is available for each item in the Address columns, on Devices / Points.

Mosquitto Client (without SparkPlugB)

Clients can connect with TMQTT Brokers the same way they connect to other available Brokers (e.g: Mosquitto). 

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

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

An example of its implementation is:

mosquitto_sub -p 1883 -t Furnace/Temperature/Value 
mosquitto_pub -p 1883 -t Furnace/Temperature/Value -m 22

MQTTSpB driver (SparkPlugB)

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

In the Engineering environment, go to Devices / Channels and find the desired protocol inside the list.

In the ProtocolOptions column, you need to fill out the following fields:

• Type;

  • Application Node;

  • Scada IIoT Host;

  • EoN

• ClientID;

• TagProperties;

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

<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)

You can set up communication between the TMQTT Broker and third party MQTT Clients. In this example, we use MQTT.fx.

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

Step 1: The TMQTT Broker must be running. Look for the icon in the Windows Taskbar.

Step 2: In the client, go to Extras / Edit Connections Profiles. In the window that opens, fill in the MQTT Broker Profile Settings according to your broker (e.g.: broker address and broker port). Then, click Connect. 

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

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

Let us imagine an example in which the Solution name is ’ Solution1’, and we have an integer tag called ’Tag.Integer1’.

In order to correctly subscribe to the tag, you need to create a device birth certificate, which starts the communication channel.

spBv1.0/TServer/DBIRTH/ Solution1/Tag.Integer1 //create channel for this specific tag

or

spBv1.0/TServer/DBIRTH/ Solution1/Tag //create channel for all tags

After the device certificate is created, the subscription for data becomes available. The following topic is required to fetch data:

spBv1.0/TServer/DDATA/ Solution1/Tag.Integer1

or

spBv1.0/TServer/DDATA/ Solution1/Tag

More data can be exchanged between the running Solution and TMQTT Broker. Some examples can be seen below.

spBv1.0/TServer/DDATA/ Solution1/Devices //Channel, Node and Points info 
spBv1.0/TServer/DDATA/ Solution1/Alarms //All properties 
spBv1.0/TServer/DDATA/ Solution1/Dataset //DB Status, etc 
spBv1.0/TServer/DDATA/ Solution1/Script //Tasks info 
spBv1.0/TServer/DDATA/ Solution1/Historian //All properties 
spBv1.0/TServer/DDATA/ Solution1/Server //All properties 
spBv1.0/TServer/DDATA/ Solution1/Info //TSolution, License and Module info 
spBv1.0/TServer/DDATA/ Solution1/Security //User, Permission and Policies info

Step 4: After subscribing 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 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
}

Example of Communication with JSON Data Format

Here is an example of particle count readings from a counter that uses JSON to communicate with FactoryStudio via the MQTT protocol.

As JSON is not a communication protocol, but a data format, a communication protocol, like MQTT, is needed to transmit data between applications. This driver does not filter JSON format string data directly. However, you can implement a script that will filter your message and pass the corresponding value to a Tag. See below for an example:

For data of this type:

{
"temperature1": 43,"temperature2": 100,
"temperatureName": "Tank45",
}

• First, you need to create a Tag Template with each element of your JSON string and assign it to a Tag.

• Next, you will create a Text type Tag to receive the JSON message. In this example, the @Tag.ReceiverJSONData acts as our receiving CommunicationPoint (configured in Devices / Points) for the MQTT protocol.

• The next step is to create a Task with Trigger set as our receiving data Tag (@Tag.ReceiverJSONData). By doing this, whenever your Communication Point receives a new message from the MQTT topic, the task will be executed.

• The code below allows you to obtain information from a JSON string and pass the values to Solution Tags.

string[] parts = @Tag.ReceiverJSONData.Value.Split(',');
string receiver = "";

foreach (string part in parts)
{
	receiver = part;
	
	if(receiver.StartsWith("{")) // remove bracket from string
		receiver = receiver.Remove(receiver.IndexOf('{'),1);
	
	if (receiver.EndsWith("}")) // remove bracket from string
		receiver = receiver.Remove(receiver.IndexOf('}'),1);
	
	while (receiver.Contains('"')) // remove quotes from string
	{
		receiver = receiver.Remove(receiver.IndexOf('"'),1);

	}
	
	TK.SetObjectValue("Tag.ParametersJSON. " + receiver.Split(':')[0], receiver.Split(':')[1]);
	
}

In this section: