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

The simplest way to configure and run the MQTT broker is through the software itself. With your solution open, navigate to Runtime / Startup and click on the icon next to "Publish to Built-in MQTT Broker," under Execution Environment. With the checkbox marked, the broker will automatically start with the desired configurations whenever the solution is run.

The TMQTT Broker Settings dialog window will appear, allowing you to configure the broker in two different tabs: General and Local/Remote.

To confirm that the MQTT broker is working, check Data Explorer / MQTT Tools. The message "TMQTTBroker is running" confirms that the broker is active.

This screen contains three additional broker options:

Alternatively, you may start the MQTT broker by running TMQTTBroker.exe. In this case, the broker will base its settings on an XML file, which it looks for in the following order:

1. ConfigFile parameter: If you need the broker to look for a specific XML configuration file, you can pass the file as a command line parameter: TMQTTBroker.exe /ConfigFile:[FileName]
2. MachineSettings folder: If you don't specify a ConfigFile parameter, the broker will look for TMQTTBroker.exe.config.xml. This is a default file found in C:\Users\Public\Documents\FrameworX\MachineSettings.
3. Base directory: If all other options are unavailable, the broker looks for TMQTTBroker.exe.config.xml in the product installation path, in the fx-10 folder.

You can create or edit XML configuration files to apply custom settings to the broker. When creating your own file, it is recommended that you copy and paste from one of the default configuration files, since they already contain the basic structure you need to set up the broker. The XML elements and attributes you can use to configure the broker are described in the table below.

As an example, suppose you want to change the backlog, retained file and listening port parameters. You can edit the values between the tags, like this:

<Backlog>500</Backlog>

<DisableRetainedFile>true</DisableRetainedFile>

<ListeningPort>7777</ListeningPort>

Certain parameters come empty by default. For example, the certificate file parameter comes as <RemoteBrokerURL/>. You can edit this tag to include a URL as follows:

<RemoteBrokerURL>Custom URL</RemoteBrokerURL>

Parameters such as TServerInfo can be configured like so:

<TServerInfo SolutionName="BrokerTest" IpAddress="127.0.0.1" Port="3101"/>

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: