Matrikon Data Broker MQTT Publisher User Manual

Matrikon® Data Broker
MQTT Publisher
User Manual
R1.0
User Guide
Document ID: MOPCDOC-X701-en-10A
Release Date: June 2021

ABOUT THIS MANUAL
Copyright and Trademark Information

SOFTWARE VERSION
Version: 1.0
DOCUMENT VERSION
Version: A
COPYRIGHT INFORMATION
© Copyright 1997 - 2021, Matrikon® International. All rights reserved. No part of this document may be
reproduced, stored in a retrieval system, translated, or transmitted in any form or by any means, electronic,
mechanical, photocopying, recording, or otherwise, without prior written permission of Matrikon® International
CONFIDENTIAL
The information contained herein is confidential and proprietary to Matrikon® International, a business unit of
Honeywell Limited (Matrikon® International). It may not be stored, disclosed, or transferred, directly or
indirectly, to any third party without the explicit written permission of Matrikon® International.
LIMITATIONS
Although every endeavor has been made to ensure that the information contained within this document is up
to date and accurate, Matrikon® International cannot be held responsible for any inaccuracy or error in the
information contained within this document. Matrikon® International makes no warranty of any kind with
regards to the information contained within this document and Matrikon® International shall not be liable for
any direct, indirect, incidental or consequential damages which may arise in connection with the furnishing,
reliance, or use of the information contained within this document.
Specifications and statements as to performance in this document are Matrikon® International estimates,
intended for general guidance. Matrikon® International reserves the right to change the information contained
within this document and any product specification without notice.
Statements in this document are not part of a contract or program product license insofar as they are
incorporated into a contract or license by express preference. Issue of this document does not entitle the
recipient to access or use of the products described, and such access or use shall be subject to separate
contracts or licenses.
The receiving party shall not disclose, publish, report, communicate, or otherwise transfer any information in
this document to any third party, and shall protect all information contained herein from unauthorized
disclosure. The receiving party shall permit access to this document only to its employees, agents,
subcontractors, and affiliates who reasonably require access to such information contained herein, have been
made aware of the confidential nature of this document and have executed a written employment or other
confidentiality agreement party to maintain the confidential status of this document.
Matrikon® Data Broker MQTT Publisher User Guide 2

ABOUT THIS MANUAL
LICENSE AGREEMENT
This document and the software described in this document are supplied under a license agreement and may
only be used in accordance with the terms of that agreement. Matrikon® International reserves the right to
make any improvements and/or changes to product specifications at any time without notice.
TRADEMARK INFORMATION
The following are either trademarks or registered trademarks of their respective organizations:
Matrikon® International, Matrikon® Data Broker™, Matrikon® Data Broker MQTT Publisher, and Matrikon®
FLEX™ are trademarks or registered trademarks of Matrikon® International.

ABOUT THIS MANUAL
Table of Contents
TABLE OF CONTENTS ........................................................................................................................................................... 4
ABOUT THIS MANUAL .......................................................................................................................................................... 6
Revision history ............................................................................................................................................................................ 6
Intended audience ...................................................................................................................................................................... 6

INTRODUCTION TO MATRIKON DATA BROKER MQTT PUBLISHER ................................................................... 8
BEFORE YOU BEGIN............................................................................................................................................................. 9
System Requirements............................................................................................................................................................... 9
Software Requirements ....................................................................................................................................................9
Hardware Requirements ..................................................................................................................................................9
Security Considerations........................................................................................................................................................... 9
Change initial passwords ................................................................................................................................................9
Secure the certificate key store .................................................................................................................................10
Run Matrikon Data Broker MQTT Publisher with lowest privileges possible .....................................10
Secure auxiliary files........................................................................................................................................................10
Logging and diagnostics ..............................................................................................................................................10
Monitor certificate chains ............................................................................................................................................10
INSTALLATION OF MATRIKON DATA BROKER MQTT PUBLISHER .................................................................. 11
Installation on Windows OS ................................................................................................................................................ 11
Deployed Files Location in Windows ......................................................................................................................15
Deploy as a Container ............................................................................................................................................................ 15

Deploy the Matrikon Data Broker MQTT Publisher Container ..................................................................16
Start/Stop/Restart the Dispatch Container ........................................................................................................17
Manage PKI Certificate of MQTT Publisher Container ..................................................................................18
Deployed Files Location in Container ....................................................................................................................18
CONFIGURATION OF MATRIKON DATA BROKER MQTT PUBLISHER ............................................................. 19
Prerequisites............................................................................................................................................................................... 19
Matrikon FLEX Dispatch ...............................................................................................................................................19
Matrikon OPC UA Explorer...........................................................................................................................................19
Matrikon FLEX Dispatch License key ....................................................................................................................19
Optional: Matrikon OPC UA Tunneller ...................................................................................................................19
Configuration ............................................................................................................................................................................. 19
Configuration of Matrikon FLEX Dispatch ..........................................................................................................20
Connecting Matrikon OPC UA Explorer to Data Broker MQTT Publisher ............................................21
Topology of Matrikon Data Broker MQTT Publisher Configuration........................................................23
Configuring Matrikon Data Broker MQTT Publisher ......................................................................................24

ABOUT THIS MANUAL
Adding OPC UA Client Connections .......................................................................................................................25

Configuring the Files for Publishing .......................................................................................................................29
Configuration of MQTT Publisher’s MQTT Client Connections ................................................................31
Changing the initial password for the operator user for the Data Broker MQTT Publisher ........38
Configuring Optional Settings ...................................................................................................................................40
Configuration of Publishing Type ............................................................................................................................45
Configuration of Sampling and Publishing Intervals.....................................................................................46
STORE AND FORWARD FOR PUBLISHING RECOVERY ........................................................................................... 47
IMPORTANT USAGE CONSIDERATIONS FOR MATRIKON DATA BROKER MQTT PUBLISHER................ 48
Configuration Changes......................................................................................................................................................... 48
Other Considerations ............................................................................................................................................................. 48

APPENDIX ............................................................................................................................................................................. 49
Appendix A: MQTT Publisher configuration fields description ......................................................................... 49
OPC UA Client Connections ........................................................................................................................................49
MQTT Client Connections ............................................................................................................................................49
Writer Group ........................................................................................................................................................................50
Writer Datasets ..................................................................................................................................................................58
Appendix B: Understanding dataset.json file............................................................................................................. 63

CONTACTING SUPPORT.................................................................................................................................................... 65

ABOUT THIS MANUAL
About this Manual

This manual describes the procedure to configure and use the Matrikon Data Broker MQTT Publisher
extension.
When you use links, and navigate within the document, to go back to the
section that you were reading, in the keyboard, press alt + left arrow < or
Tip right arrow >.
Throughout the document, there are reference to Forge IoT or Forge

Platform for completeness of the document. This document is mainly
NOTE
targeted to explain the usage of MQTT Publisher component for publishing
the data to MQTT Broker or Azure IoT Hub.
To understand how to use the MQTT Publisher component in Forge solution
(Forge Connect for Industrial), please reach out to your Matrikon or
Honeywell Account Manager.
Throughout the document, Matrikon FLEX Dispatch and Matrikon

Data Broker are used inter changeably. Both these names refer to the
Tip same product Matrikon FLEX Dispatch.
Revision history
Revision Supported Date Description
Release
A 1.0 June 2021 New document.
Intended audience
This document is intended for system administrators, engineers, and those who want to configure Matrikon
Data Broker MQTT Publisher for publishing data from Matrikon FLEX Dispatch to different platforms like,
Forge IoT, Azure IoT and MQTT brokers in general. It is expected that the users of this document are aware of
the following:
1. OPC UA standard and its applications.
2. Matrikon FLEX Dispatch.
3. Matrikon OPC UA Explorer.
4. How to create Microsoft Azure IoT Hub and working knowledge of Azure IoT Hub.
5. How to create and configure On-Prem MQTT Brokers.

ABOUT THIS MANUAL
For more information on Matrikon FLEX Dispatch and Matrikon OPC UA Explorer, kindly refer to the Matrikon
FLEX Dispatch User Manual.

INTRODUCTION TO MATRIKON DATA BROKER MQTT PUBLISHER
Introduction to Matrikon Data Broker MQTT Publisher

The Matrikon Data Broker MQTT Publisher extension is a cross-platform application that bridges Matrikon
Data Broker (Matrikon FLEX Dispatch) with on-prem MQTT Brokers like Eclipse Mosquitto and Cloud based
brokers like Forge IoT or Azure IoT Hub. Matrikon Data Broker MQTT Publisher reads data from the Matrikon
FLEX Dispatch OPC UA server (local or remote) and publishes the data as MQTT messages to the required
platform.
Azure IoT Hub Forge IoT MQTT Connection
MQTT 3.1 AMQP* MQTT 3.1

Matrikon Data Broker
MQTT Publisher
Matrikon FLEX Dispatch
* - Data is sent to Forge IoT as AMQP data as currently only AMQP messages are supported with Forge IoT.

BEFORE YOU BEGIN
Before You Begin

This chapter contains important information you should read before installing Matrikon Data Broker MQTT
Publisher.
System Requirements
The following are minimum system configuration requirements for Matrikon Data Broker MQTT Publisher.
Software Requirements
Software Supported Version(s)
Windows Operating System Client: Windows 10 64-bit

Server: Servers 2019, 2016, 2012 R2 (All 64-bit)
Linux Operating System Red hat Linux 8.0, Centos 8.0, Ubuntu 18.04, 20.04 for
running as Container
Matrikon FLEX Dispatch Minimum version R1.4
Matrikon OPC UA Explorer Minimum version R1.4
Hardware Requirements
Hardware Minimum Requirements
RAM 4 GB
CPU 2 Cores
Disk Space 1GB
Processor Architecture x86-64
Security Considerations
This section describes essential security considerations for ensuring that Matrikon Data Broker MQTT
Publisher operates as securely as possible. As all considerations may not apply to your situation, you must
decide which considerations to follow and to what extent.
Change initial passwords

After installation, you must log in to Matrikon Data Broker MQTT Publisher and change the initial passwords
so that malicious users cannot reconfigure or misuse Dispatch. For changing the password, follow the
instructions in Changing initial password for operator user of Data Broker MQTT Publisher Component
section.

BEFORE YOU BEGIN
Secure the certificate key store

Certificates are only as secure as the storage that they are kept in. Secure your certificate key store in
accordance with your IT group’s procedures. Examples of these procedures may include locking down access
permissions to a file system and disabling file system access from peripherals. Matrikon Data Broker MQTT
Publisher locks the certificate key store at installation time, but your IT department may have additional
policies.
Run Matrikon Data Broker MQTT Publisher with lowest privileges possible
To protect the device from external access, ensure that Matrikon Data Broker MQTT Publisher runs with the
lowest user privileges possible. Running communication software with elevated privileges is not
recommended.
Secure auxiliary files

Matrikon Data Broker MQTT Publisher uses auxiliary files such as configuration files, cache and, log files. It is
strongly recommended that these files are stored in a protected folder on the host and that the this is a
different storage location from the certificate key store. Matrikon Data Broker MQTT Publisher locks the
location of auxiliary files during installation, but your IT department may have additional policies.
Logging and diagnostics

Matrikon Data Broker MQTT Publisher can produce logging and diagnostics information. It is recommended
to configure Matrikon Data Broker MQTT Publisher to limit the amount of disk space used by diagnostics, so
that it is not accidentally exhausted. Matrikon Data Broker MQTT Publisher limits individual log file size to 100
megabytes (MB) by default and the number of log files is limited 10, which are rolled over when limit is
reached. Log files must be protected from any user that does not need to access them.
Monitor certificate chains

You must monitor your certificates for expiration and new revocation lists, and periodically check with the
Master Certificate Authority for news and updates that may require you to revoke and re-issue certificates.

INSTALLATION OF MATRIKON DATA BROKER MQTT PUBLISHER
Installation of Matrikon Data Broker MQTT Publisher

Matrikon Data Broker MQTT Publisher is distributed both as a Windows installer and as a Container. The
following sections describe how to install MQTT Publisher on Windows and how to set it up as a Container.
Installation on Windows OS
Before you proceed to install Data Broker MQTT Publisher, please note the windows component must be
installed on the system where Matrikon FLEX Dispatch R1.4 is installed. Older versions of FLEX Dispatch are
not supported.
To install Matrikon Data Broker MQTT Publisher:


• In the Port Number field, type a valid Port Number that the MQTT Publisher UA Server must
listen to. Valid values are 2048 to 65535. Port numbers below 2048 are generally reserved for
specific applications. The default port number is 44444.
• In the User Name field, type a username in the following format:

For local accounts: .\<user name>
For domain users: <Domain Name>\<user name>
• In the Password field, type the password for the account you specified.
The user entered in User Name field must have “Log on as a service”
privileges so that the MQTT Publisher UA Server service can run as a
NOTE
service.
As a security best practice, it is not recommended to run any Windows

service under an account with administrative privileges. The Installer
warns you if the account provided has administrative rights.

You can also Launch Matrikon Data Broker MQTT Publisher User Manual
by selecting the checkbox from the same window.
NOTE

Once Matrikon Data Broker MQTT Publisher installation is successful, the Matrikon Data Broker- MQTT
Publisher service starts automatically. To confirm if Matrikon Data Broker- MQTT Publisher is registered and
running, do the following:
If you do not see the Matrikon Data Broker – MQTT Publisher service
in the services list or if you are not able to manage (start or stop) the
STOP
service, contact Matrikon Support for further assistance.
Deployed Files Location in Windows

Files related to Matrikon Data Broker MQTT Publisher are deployed in the following locations:
File Type Default Location
MQTT Publisher exe C:\Program Files\Matrikon\MDB-MQTTPublisher
MQTT Publisher C:\ProgramData\Matrikon\MDB-MQTTPublisher\Config

Configuration files
MQTT Publisher PKI folder C:\ProgramData\Matrikon\MDB-MQTTPublisher\pki
MQTT Publisher Log Files C:\ProgramData\Matrikon\MDB-MQTTPublisher\logs
MQTT Publisher options C:\ProgramData\Matrikon\MDB-

configuration file MQTTPublisher\Config\options.config
MQTT Publisher User Manual C:\Program Files\Matrikon\MDB-MQTTPublisher\Documentation
Deploy as a Container
Matrikon Data Broker MQTT Publisher can run as a Docker or podman container in the following Linux flavors:
• Centos
• RedHat Enterprise edition 8
• Ubuntu 18.04 LTS or later
You can also use the MQTT Publisher as a Linux Docker container in the Windows operating system.

The container version of MQTT Publisher is based on the base image of

Ubuntu 18.04.5 LTS.
NOTE
Running MQTT Publisher as a container on Windows is in Beta for the

current release.
NOTE
Windows support for Linux containers is still evolving field, as such, you
need to run MQTT Publisher as a container on Windows system. If you are
not familiar with doing this, seeking the help of engineers experienced in
using Linux containers on the Windows OS is recommended.
This section explains how containers can be setup on a Linux operating system. Similar steps can be used to
setup the containers on systems running the Windows versions that support containerization.
For setup and management of the MQTT Publisher container use the MQTT Publisher docker container image.
This section is divided into 3 sub-sections:
• Deploy the MQTT Publisher Container

• Start/Stop/Restart the MQTT Publisher Container
• Manage PKI Certificate of the MQTT Publisher Container
Deploy the Matrikon Data Broker MQTT Publisher Container

Prerequisites
Before you begin with the set-up of MQTT Publisher, ensure that the Docker or Podman are properly installed
and setup in the machine.
Deployment Steps
To set-up the MQTT Publisher, as a container:
1. Copy the matrikondatabrokermqttpublisher-1.0.tgz file and save it in your system.
2. Load the image into the Docker by executing the following command:
Ex: sudo docker load -i matrikondatabrokermqttpublisher-1.0.tgz
3. Create the MQTT Publisher container by executing the following command:
docker run -d --network host --name <<CONTAINER NAME>> -u root -v <<Folder to store container volume
data>>:/mnt/uapublisher matrikondatabrokermqttpublisher
Ex: docker run -d --network host --name MQTTPublisher -u root -v

/home/ubuntu/Desktop/MQTTPublisher:/mnt/uapublisher matrikondatabrokermqttpublisher

The following table describes the parameter options used in above example command:
Parameters Description
--network host The network mode that you wish to use. It is

recommended to set as host.
--name <CONTAINER NAME> <CONTAINER NAME> is name of the MQTT Publisher

container used for managing the container in docker.
-u root This runs the MQTT Publisher container with root

privileges. You can also use a non-root user as long as
that user has RW permissions on the volume folder
used below.
-v <<Folder to store container -v option is used for mapping a folder on system to

volume>>:/mnt/uapublisher store the container data. In the above example
command, the folder
/home/ubuntu/Desktop/MQTTPublisher holds the
MQTT Publisher container data from container’s
/mnt/uapublisher folder.
If this option is not used, you can find the data of
container at below location:
/var/lib/docker/volumes/<<volume ID>>/_data
You can find the volume ID of the container by doing
docker inspect <CONTAINER NAME> | grep volume
and looking for volume details in the result.
1. By default, the MQTT Publisher container’s OPC UA Server runs on port#

44444. Currently there is no option to change this to an alternate port.
NOTE
2. If you are running MQTT Publisher with log level as INFO, the docker log
available will grow quickly and could consume all available Hard Disk
space. So, it is recommended to run the log level as ERROR only, which is
default setting.
3. There are many options available for how Docker runs. However, it is not
advisable to use other options without understanding their impact.
Start/Stop/Restart the Dispatch Container

You can start, stop, and restart the MQTT Publisher container once the MQTT Publisher container starts running
on your machine.
1. To start the MQTT Publisher container,

• Open a Terminal.
• Execute the following command to start the container:
docker start <CONTAINER NAME>

• To verify whether the MQTT Publisher container is running, run the following command:
docker container Is-a
• The list of all containers will appear shown below.
2. To stop the MQTT Publisher container,

• Open the Terminal.
• To stop the MQTT Publisher container, execute the following command:
docker stop <CONTAINER NAME>
3. To restart the MQTT Publisher container,
• Once you stop service, you can restart the MQTT Publisher container by executing the following
command:
docker restart <CONTAINER NAME>
Manage PKI Certificate of MQTT Publisher Container

Once you run the MQTT Publisher container, a mapped volume is created on the host machine the MQTT
Publisher container is running on. You must locate the mapped volume location and copy the PKI certificate from
the rejected folder to the trusted folder.
To locate the mapped volume information,
• Open a Terminal.
• To locate the mapped volume location, execute the following command:
docker inspect <CONTAINER NAME> | grep volume
• Once you get the location, copy the PKI certificate from Rejected folder to Trusted folder.
• If you have followed the above example, you will find the PKI certificate in the below location:
/home/ubuntu/Desktop/MQTTPublisher
Deployed Files Location in Container

At the end of the MQTT Publisher container setup, files used by the MQTT Publisher are deployed in the
following locations. Please note the paths shown in table here are relative to the volume mapped in example
above.
File Type Default Location
MQTT Publisher Configuration files /home/ubuntu/Desktop/MQTTPublisher/Config
MQTT Publisher PKI folder /home/ubuntu/Desktop/MQTTPublisher/pki
MQTT Publisher Log Files /home/ubuntu/Desktop/MQTTPublisher/logs
MQTT Publisher options configuration file /home/ubuntu/Desktop/MQTTPublisher/Config/options.c

onfig

CONFIGURATION OF MATRIKON DATA BROKER MQTT PUBLISHER
Configuration of Matrikon Data Broker MQTT Publisher
Prerequisites
Before configuring and using Data Broker MQTT Publisher, ensure you have the following components
installed and configured.
Matrikon FLEX Dispatch

Matrikon Data Broker MQTT Publisher acts as an OPC UA server that can only be connected to by Matrikon
FLEX Dispatch. Ensure that you have completed the installation and configuration of Matrikon FLEX Dispatch
before proceeding. Please refer to the Matrikon FLEX Dispatch User Manual for further assistance on this
product.
Matrikon OPC UA Explorer

Matrikon OPC UA Explorer is used for to configure Matrikon Data Broker MQTT Publisher. Ensure that you
have it installed on a system (local or remote) at a network location from which you can reach the MQTT
Publisher component.
Matrikon FLEX Dispatch License key

You are expected to have Matrikon FLEX Dispatch license key on hand before you start your configuration of
the solution. In case you do not have the license key, please contact your Account Manager before proceeding.
Matrikon Data Broker MQTT Publisher does not require a separate license. As a Matrikon
FLEX Dispatch expansion, it uses Matrikon FLEX Dispatch as Data Source for the data it
NOTE
publishes.
Optional: Matrikon OPC UA Tunneller

If you need to access data from OPC Classic Servers, you will first need to use Matrikon OPC UA Tunneller to
wrap your OPC Classic Servers so they behave like OPC UA Servers. Note: this will not require you to
reconfigure the underlying OPC Classic servers.
→ Contact your Account Manager to obtain Matrikon OPC UA Tunneller license(s).
→ If you need help in using Matrikon OPC UA Tunneller product, please contact Matrikon support team at
support@matrikonopc.com
Configuration
A typical architecture using the MQTT Publisher component is shown below. This solution is made up of the
following key components:

• Azure IoT Hub.
• MQTT Brokers like Eclipse Mosquitto.
• Forge IoT Platform.
MQTT Broker Azure IoT Hub Forge IoT Platform
Matrikon Data Broker

MQTT Publisher
Configuration Matrikon
Matrikon OPC UA Explorer
Data Broker
OPC UA Servers
The Matrikon OPC UA Explorer is used to configure the following:
Configuration of Matrikon FLEX Dispatch

Matrikon Data Broker MQTT Publisher requires an instance of Matrikon FLEX Dispatch running on the same
network to access data to be published.
Note: If you do not have Matrikon FLEX Dispatch up and running yet, please STOP here and refer to Matrikon
FLEX Dispatch user manual for installation and configuration of Matrikon FLEX Dispatch.
• Installation of Matrikon FLEX Dispatch
• Licensing of Matrikon FLEX Dispatch.

• Adding external OPC UA Servers as data sources to Matrikon FLEX Dispatch.
• Adjusting any other configuration options of Matrikon FLEX Dispatch.
Connecting Matrikon OPC UA Explorer to Data Broker MQTT Publisher

To configure Matrikon Data Broker MQTT Publisher, you must first establish a connection from Matrikon OPC
UA Explorer to the Data Broker MQTT Publisher OPC UA Server. Connecting to the Matrikon Data Broker
MQTT Publisher OPC UA Server involves similar steps to those used for connecting to the Matrikon FLEX
Dispatch OPC UA Server, as explained below:
• Discovery: You can search for an existing server by either typing its host name or IP address,
and the respective port number.
• Manual: You can manually type the server URL.
• In the Hostname / IP field, type the hostname or IP address of the server.

• In the Port field, type the opc.tcp server port number.
For Manual:
In the URL field, type the server URL in the following format:
opc.tcp://<hostname or IP address>:<port number>.
For example, opc.tcp://192.1.55.75:44444, OR opc.tcp://localhost:44444.
• Click Search.
The server details are fetched and displayed in the right-side panel.
• Expand the OPC UA server entry of interest to display all the supported Endpoints and
associated security policies configured in the server.
• Select a security policy you want to use for the session.

Based on the selection, the server information appears as shown below.
• In the Server Information section, provide a unique Server Alias Name.
• From the Authentication section, choose a suitable authentication setting to connect to the
server. The only way to connect to the Matrikon Data Broker MQTT Publisher OPC UA Server is
by using User Details. For security reasons, the Anonymous option is not supported.
⎯ User Details: Select this to connect using the UserName and Password.

The only username supported for connecting to the MQTT Publisher component is
“operator” with initial password as “operator”. It is recommended that you change the
NOTE
initial password on first connection. See the section Changing initial password for
operator user of Data Broker MQTT Publisher Component for steps on how to achieve
this.
The MQTT Publisher OPC UA Server does not support OPC UA Reverse Connect functionality
NOTE
Topology of Matrikon Data Broker MQTT Publisher Configuration

Matrikon Data Broker MQTT Publisher configuration consists of 4 main elements:
1. OPC UA Client Connections -> This configuration establishes connection to an instance of Matrikon FLEX
Dispatch OPC UA Server from which MQTT Publisher collects the data to publish.
2. Write Groups -> This configuration defines a group of data sets (containing tags to publish). This also
defines some of the configuration options which are applicable for all the tags configured with this Writer
Group.

3. Writer Data Set(s) -> This configuration defines a group of tags that should be collected from Matrikon
FLEX Dispatch OPC UA Server to publish.
4. MQTT Client Connection -> This configuration establishes connection to MQTT Brokers (on-prem or
cloud) to which MQTT Publisher component should publish the tag data.
The relation between these different elements is as explained in below picture for a single MQTT Client
Connection.
As you can see here:
• A single MQTT Client Connection can contain multiple Writer Groups.
• A single Write group can contain multiple Dataset Writes (Data Sets).
• Each Dataset can contain one or more Tags from Matrikon FLEX Dispatch to be collected for
publishing.
The structure of each of the configuration element is based on OPC UA Pub Sub specifications as described in
Appendix ‘A’ at the end of this document.
Configuring Matrikon Data Broker MQTT Publisher

To use Matrikon Data Broker MQTT Publisher, you must perform the following configuration steps. You can
use the MQTT Publisher Configuration screen to complete this process.
Configuration of Writer groups.
• Configuration of Writer Datasets Tags in datasets.json file -> This file contains the tags which
need to be published to the Forge IoT platform. Each of the datasets.json files is an array of
either a single data set group or multiple data set groups. If there are a huge number of tags to
configure, it is recommended to create multiple datasets.json files.

Adding OPC UA Client Connections

To add an OPC UA Client connection to the Matrikon FLEX Dispatch OPC UA Server, follow the steps below:
1. Here, you can only connect to Matrikon FLEX Dispatch OPC UA

Server.
Tip 2. In this screen, connecting to Matrikon FLEX Dispatch OPC UA
Server through Reverse Connect is not supported.

Parameter Description
Hostname/ IP Hostname or the IP address of the system in which the Matrikon FLEX
Dispatch server is running. Note that the Matrikon MQTT Publisher will
not support connections to any third-party UA Server.
Port Port number in which the Matrikon FLEX Dispatch Server is running.
Endpoint Url Url to establish connection with the target OPC UA server.
For example, opc.tcp://<Hostname or IP>:Port number
Policy Security policy to establish connection with the target OPC UA server.
For example, Aes256_Sha256_RsaPss
Mode Security mode to establish connection with the target OPC UA server.
For example, Sign & Encrypt.
Anonymous Enables an anonymous user connection.
User Details • UserName: Username to establish connection with the target

OPC UA server.
• Password: Password to establish connection with the target
OPC UA server.
Note: When the Matrikon Data Broker MQTT Publisher service or container restarts, it tries to connect to
Matrikon FLEX Dispatch. Since this is a first-time connection, there is no trust established between these two
components, so their respective certificates need to be exchanged so trust can be established. To trust the

Matrikon Data Broker MQTT Publisher certificate in Matrikon FLEX Dispatch, follow the steps provided in the
Matrikon FLEX Dispatch User Manual.
• The Matrikon Data Broker MQTT Publisher can only connect to a single instance of
Matrikon FLEX Dispatch UA Server. If you want to publish data from additional UA Servers,
NOTE
including other Dispatch UA instances, they should be federated into the Matrikon FLEX
Dispatch (Matrikon Data Broker) instance you are connecting to MQTT Publisher.
• You cannot configure any other UA Server apart from Data Broker UA Server in this step.
Any attempts to connect to any other UA Server will be rejected.
Trust the Rejected Certificates in Matrikon Data Broker MQTT Publisher for the First Time.
For Windows Deployment:
For Deployment as Container:
Trust the Rejected Certificates in Matrikon Data Broker MQTT Publisher
If you are using an OPC UA Explorer instance whose certificate was already manually trusted by Matrikon
FLEX Dispatch, then you can use this same instance to trust additional certificates in the future. If you have
not completed this step yet, please see the Trust the Rejected Certificates in Dispatch for the First-Time
section in Matrikon FLEX Dispatch User Manual
Trust the Rejected

Certificates in Data Broker MQTT Publisher for the First Time section.
In OPC UA Explorer, the Certificate Management screen is used to trust one or more certificates at a time.
This screen shows both trusted and rejected certificates and their trust status. Additional certificate details are
also available in the Certificate Details window.
To trust the certificates:

Viewing Certificate Details
You can view the details of both trusted and rejected certificates from within OPC UA Explorer.
To view the details,

Configuring the Files for Publishing

Matrikon Data Broker MQTT Publisher uses several files to configure publishing options that include the data
to be published, target platforms, and so on. Use these configuration files to publish the data from Matrikon
FLEX Dispatch through MQTT Publisher to other platforms like Azure IoT, and other MQTT Brokers using
Matrikon OPC UA Explorer.
Config Files Description
writergroups.json The writer group determines how the data sets should be used to publish messages to
the required platform.
datasets.json The writer dataset describes the fields of the published message as well as the
published tags associated with each field. There can be multiple of these datasets.json
files.
It is recommended to not configure more than 2K tags in each of these data set file.
mqttclientconnectio This file holds the connection information to platforms to which the data should be
ns.json published.
Configuration for these files can be done by using below three steps,

For example, the Dataset configuration screens are used for configuration of the data files.
Export and modify the Configuration file
Import the modified Configuration file.

Apply the modified Configuration file
Configuration of MQTT Publisher’s MQTT Client Connections

Matrikon Data Broker MQTT Publisher collects data from various OPC UA Servers federated by Matrikon Data
Broker and publishes that data out to MQTT Brokers or Cloud platforms like Azure IoT Hub or Forge IoT.
Matrikon Data Broker MQTT Publisher can publish data to the following three platforms. Follow the steps
below to establish connections to these platforms as MQTT Client connections:

When you open MQTT Client Connection tab for the first time, you will be presented with below screen.
Here you can see there are 3 connections added by default, one each for MQTT-Broker, Azure-IoT and Forge-
IoT. However, all of these are in disabled state. When you open each of the connection for editing by double
clicking the row, the configuration screen will present the options that can be entered for that connection type.
You can choose to edit the same connection or create a new connection all together. You need to enable the
connection you are planning to use for your deployment and configure it accordingly.
At any given time, using MQTT Publisher, you can publish data to one or more different end points
(destinations) like MQTT Broker, Azure IoT Hub or Forge IoT. One care should be taken would be to not share
the write groups between these different destinations. Also, there can be ONLY one connection to Forge IoT at
any given time.
Various actions you can perform on this screen are described in below table.
Icon/Button Action
Click this Icon to Add New Connections. Follow instructions below

this table to add different types of MQTT end point connections.
Click on this Icon to edit the connection of the row selected in

below table of connections.
Click this Icon to delete the connection row selected in below table
of connections.
Click this button to Apply the changes to MQTT Publisher. If the

changes are not applied, they will only become applicable after you
restart MQTT Publisher service or container.
Click this button to import the connection information file

(mqttclientconnections.json). It is generally not required unless you
are configuring in one system and want to transfer the
configuration to another system.
Click this button to Export the connection information on the

screen into a file (mqttclientconnections.json). It is generally not
required unless you are configuring in one system and want to
transfer the configuration to another system.

Icon/Button Action
Click this button to register the system you are running MQTT
Publisher (container ONLY) to Forge IoT system. This button will be
enabled when you add or edit a MQTT Client connection of type
“Forge IoT”.
Establishing Connection to Azure IoT Hub
Before you try to create and configure a connection to the Azure IoT platform, ensure that you have the
following:
• An active Azure IoT hub.
• A device configured in Azure IoT Hub.
• The connection primary key for the device.
To establish a connection to Azure IoT Hub, you must first connect to Matrikon Data Broker MQTT Publisher’s
OPC UA Server using Matrikon OPC UA Explorer. Once you do this, establish a connection to the IoT Hub
device as follows:
Pre-requisite:

To add a connection to this IoT Hub device in Matrikon Data Broker MQTT Publisher:

Connection Details Description
Broker Enter Azure IoT Hub Hostname.
Publisher Topic Enter the Publisher Topic in the format of

devices/<DeviceId>/messages/events/
Client ID Enter IoT Hub Device ID.
Primary Key Enter the primary/secondary key of your device in Azure IoT Hub.
Publishing Types select the publishing types. The following publishing types are only
supported:
• OPC UA Pub-Sub.
Use TLS Enable
Establishing a connection to On-Prem MQTT Broker
Before you establish a connection to register a MQTT Broker, ensure that you have the following:
To establish a connection to an MQTT Broker, you must first connect to Matrikon Data Broker MQTT
Publisher’s OPC UA Server using Matrikon OPC UA Explorer. Once you establish the connection, you can then
configure the connection to MQTT Broker, using the steps below:

Broker Type the IP Address/Host Name of the system where MQTT Broker
is running.
Publisher Topic <<Free field to enter Topic of your choice>> (Without any Spaces)
Ex: MatrikonPublisherTopic
Client ID Enter a Client ID of your choice.

Make sure that the ClientID is unique in your deployment, means
the same ClientID should not be used between 2 different MQTT
Client Connections.
Publishing Types select the publishing types. The following publishing types are
supported:
• OPC UA Pub-Sub.
Use TLS Disable
Establishing a connection to the Forge IoT Platform (Container version only)
If you do not have a user ID and Password to register your device to Forge IoT platform, DO NOT proceed. Stop and
contact your Matrikon or Honeywell Account Manager.
Please refer to the Forge Connect for Industrial User Manual for more detailed information.
To create and configure the Forge IoT Platform, you must connect to Data Broker MQTT Publisher’s OPC UA
Server using Matrikon OPC UA Explorer. Once you establish the connection, you can create and configure the
device as follows:

Publishing Types By default, it is FORGE IOT.
Use TLS Enabled.

Changing the initial password for the operator user for the Data Broker MQTT Publisher
You can change the initial password for the operator user of the Matrikon Data Broker MQTT Publisher
container.
To change the password,


Configuring Optional Settings

If you wish to change the optional parameters of the Matrikon Data Broker MQTT Publisher container, you can
modify them in the options.config file by exporting it from OPC UA Explorer, modifying it, and importing it
back in. The options available for modification are listed in the image and table below. Additional options are
available beyond what is listed here but, you are not expected to modify those values.
It is not recommended to change the path /mnt/Uapublisher/ in any of the config options. If
you change the path, the changes in the configuration file will not be persistent.
NOTE
Please refer to Deployed Files Location in Windows and Deployed Files Location in Container
for right location of these variables for different deployments.

The following table lists parameters are applied ONLY after the MQTT Publisher service or container is
restarted.
Parameter Type Description
maxstoreforwardmemoryfoot Long The size of buffer in bytes to store the offline

printinmb messages in-memory.
The default value is 100 MB
The following table lists parameters you should NOT change at any time.
ConfigPath String The default path of the Options.config file.
Certificatestorepath String The default storage path of the certificate.
Changes made to the parameters listed in the table below are applied immediately.
LogFileName String The filename of the log file.

Changes to the LogFileName are applied
immediately.
DO NOT change the location of the log file
location path.
LogLevel String The logging threshold level. All log

statements with a lower log level than the
threshold level are ignored by the logger. The
possible values are: None, Error, Warning,
Info and Debug.
The default value is Error.
Changes to the LogValue are applied
immediately.
LogSize String The maximum size in Kilobytes that the

output file can reach before being rolled over
to backup files.
The default value is 10240 (10MB).
The changes to the LogSize are applied
immediately.

MaxSizeRollBackups Integer The maximum number of log files that are

created before deleting the oldest file. The
default value is 10.
Changes to the MaxSizeRollBackups are
applied immediately.
ImmediateFlush Boolean Setting this value to true, will only keep a

single log file with a maximum file size as
defined in LogSize parameter.
Setting this value to false, will keep multiple
log files upto MaxSizeRollBackups limit.
The Default value is true.
Changes to the ImmediateFlush are applied
immediately.
The changes to the following parameters are applied only when a new connection/session is established.
OperationTimeout Integer The amount of time in milliseconds before

reporting timeout or cancelling an operation.
The default is 15000.
Changes to the OperationTimeout is applied
on a new connection/ session.
SessionTimeout Integer The amount of time in milliseconds before an

OPC UA session reports a timeout.
The default value is 60000.
Changes to the SessionTimeout is applied on
a new connection/ session.
MaxNotificationsPerPublish Integer The maximum number of notifications as

part of the same publish response. This
means number of tag values which will be
bundled into a single publish data sent to
MQTT broker/Azure IoT Hub.
Changes to the MaxNotificationsPerPublish
is applied on a new connection/ session.
MaxMonitoredItemsPerCall Integer The maximum number of monitored items as

part of the same publish response.

Retries Integer The number of times an operation can be

retried.
Changes to the Retries is applied on a new
connection/ session.
RetryDelay Integer The amount of time in milliseconds to wait

before retrying an operation.
Changes to the RetryDelay is applied on a
new connection/ session.
Any parameters not described in above tables are not used and should be left untouched.
You can modify the Options.config file using the three steps below:
Export and modify the Configuration file

Import the modified Configuration file
Apply the modified Configuration file

Configuration of Publishing Type

Data from MQTT publisher can be published in 2 modes. This configuration is defined for each Writer Group in
writergroup.json file(s).
• Scan based publishing
When a writer group is configured to publish the data on scan basis, then for every publishing interval,
irrespective of data has changed or not, data will be published to MQTT end points. This mode is used, when
you want to publish the data always irrespective of whether the data is changed at source or not. This mode is
generally a data intensive operation as the data is always published irrespective of data changes, which will
increase the data traffic on wire (either on prem or to cloud). Also, the applications consuming the data being
published should be aware of the potential duplicate data and should be able to process the data accordingly.
To use this option set "PublishingType" option in writergroup file as “Scan” as shown below.
"PublishingType": "Scan"
• Subscription based publishing
When a write group is configured to publish the data on subscription basis, then data will be published to MQTT
end options, ONLY when the data has changed. This mode is generally less data intensive as only changed data is
published. However, this mode may also give an assumption of not receiving data by end applications if they do
not receive data for a period. When using this mode, the end data consuming applications should be aware of this
and be able to process the data accordingly.
Some of the applications consuming the data from MQTT Publisher, want the data to be sent only when it is
changed, but also want some or all of the data to be sent irrespective of data changes every ‘X’ period of time.
In these cases, it is recommended to configure 2 write Groups, one with scan-based publishing and another
with subscription-based publishing. You can control the publishing interval at these Write Group level.
To use this option set "PublishingType" option in writergroup file as “Subscription” as shown below.
"PublishingType": "Subscription"

Configuration of Sampling and Publishing Intervals

Sampling and Publishing intervals are two important timings in MQTT Publisher which controls data
transmission from end OPC UA Servers to MQTT destinations.
Publishing interval determines, how often the data should be published to MQTT destinations. This is
configured in milliseconds in each of the Writer Group using the option "PublishingInterval".
Sampling interval determines, how often the data should be read/sampled from end OPC UA Server. This is
configured for every tag in each of the dataset files in milliseconds using the option “SamplingIntervalHint”.
In case you want the Sampling interval to same as Publishing interval, then set the SamplingIntervalHint value
to -1. If you are setting a different value to Sampling interval, make sure that the value is such that a multiple
of that value should result to Publishing Interval used for that Writer Group. Unless, there is a valid reason to
set this to a different value than Publishing Interval, it is recommended always to be -1 so that Sampling and
Publishing intervals are always in sync.

STORE AND FORWARD FOR PUBLISHING RECOVERY
Store and Forward for Publishing Recovery

In case of short-term network connectivity loss from MQTT Publisher to an MQTT Broker or Azure IoT Hub,
MQTT Publisher can buffer the data being published for certain periods of time. When the network connection
recovers, the buffered data will be re-published in chronological order.
The amount of data that can be buffered is defined by the “maxstoreforwardmemoryfootprintinmb” setting
in the Options.config file. This value defines the amount of memory to reserve in-process for unpublished
data buffering in megabytes (MB). The maximum amount of memory that can be reserved is capped at
500MB. If a higher value is provided, MQTT Publisher will limit the buffering memory to 500MB.
As a reference, with 10K string data type tags, it takes 40KB of space in memory for one publishing message.
With this reference, you can calculate how much data can be stored in memory based on your data types used
and publishing intervals.
Please note there is no store and forward capability between Matrikon FLEX Dispatch and
MQTT Broker. If the network connectivity between MQTT Publisher and FLEX Dispatch is lost,
NOTE there would be a data loss for that period.

IMPORTANT USAGE CONSIDERATIONS FOR MATRIKON DATA BROKER MQTT
PUBLISHER
Important Usage Considerations for Matrikon Data Broker MQTT

Publisher
Configuration Changes
1. For an active MQTT Publisher connection to either MQTT Broker or Azure IoT Hub: changes to the active
connection like adding or removing Writer Groups or Writer Data Sets will not be applied immediately to
the active connection.
• You need to stop the connection by Disabling it first and then Start it back up by Enabling the
connection.
2. If new tags are added to a Data Set in an active connection, the changes will not be applied immediately.
• You need to Restart the MQTT Publisher Service or Container for those new tags additions to
take effect.
• An alternative option is to Add the Tags in a new Data set and Writer group, add that Writer
group to connection and then follow the steps mentioned in #1 above for changes to be
applied.
3. it is best to group tags with the same Publishing internal into a single Writer Group. These tags could be
separated out into multiple Data Sets but kept in same Writer Group.
If you have multiple writer groups with same publishing interval, there is a possibility of incorrect
behavior of MQTT Publisher based on the number of tags you have in Writer Group.
Other Considerations
1. You need to be cognizant of the limitations of end OPC UA Server you are connecting to. For example, if
the end OPA UA Server cannot handle more than 1000 monitored items in a single request, you need to
set the value of “MaxMonitoredItemsPerCall” in options.config file to a number less than 1000.
2. Use caution when setting the limit setting for the Log Level to anything other than Error only for limited
periods of time, especially in a container deployment. If the docker default log management is not
configured correctly, it can fill up the Hard Disk very quickly and cause problems with the running of MQTT
Publisher Container.
3. MQTT Publisher supports all the basic OPC UA data types except the Location data type.

APPENDIX
Appendix
Appendix A: MQTT Publisher configuration fields description

OPC UA Client Connections
Field Type Description
Identifier String Numeric value that uniquely identifies the OPC UA

connection.
Alias String A user-friendly name for the OPC UA Connection.
Url String Url to use in order to establish connection with the

target OPC UA server
SecurityMode SecurityMode Security mode to use in order to establish connection

with the target OPC UA server
SecurityProfile SecurityProfile Security profile to use in order to establish connection

with the target OPC UA server
UserName String Username to use in order to establish connection with

the target OPC UA server
Password String Password to use in order to establish connection with

the target OPC UA server
MQTT Client Connections
Name String The name of the PubSubConnection.
Enabled Boolean True when the connection is enabled, False otherwise.
PublisherId BaseDataTyp The PublisherId is a unique identifier for a Publisher within a

e Message Oriented Middleware. It can be included in sent
NetworkMessage for identification or filtering. The value of the
PublisherId is typically shared between PubSubConnections
but the assignment of the PublisherId is vendor specific.
Valid DataTypes are UInteger and String.
TransportProfil String The TransportProfileUri parameter with DataType String

eUri indicates the transport protocol mapping and the message
mapping used

APPENDIX
Address NetworkAddre The Address parameter contains the network address used for
ssDataType the communication relation.
TransportSettin ConnectionTr
gs ansportDataT Transport mapping specific.
ype
Broker String IP address of the MQTT broker.
PublisherTopic String The topic used to publish MQTT messages.
SubscriberTopi String
The topic used to subscribe for MQTT messages.
c
ClientId String The MQTT client connection identifier.
UseTls Boolean True when the MQTT connection uses the TLS protocol.
CredentialType Enumeration Determines the type of connection credentials:
1: username
2: certificate
3: Azure shared access key
CredentialNam String When username credentials are used, this field contains the
e username. When certificate or Azure shared access key is used,
this field is formed of the broker hostname and the device id:
[broker-hostname]/[device-id]. For example:
iot-hub.azure-devices.net/device-id
CredentialSecre String When username credentials are used, this field contains the
t password. When Azure shared access key used, this field
contains the shared access key: [shared-key]. For example,
1hijdnC8ryKWsmWw+J/uzNoOiM/kt/xw48mKLsb+st8=
WriterGroupNa String[] List of writer group names associated with the MQTT client
mes connection.
Writer Group
Name String The name assigned to the writer

group. It must be unique across
writer group definition files.

APPENDIX
Enabled Boolean True when the writer group is

enabled.
SecurityMode The SecurityMode indicates the

level of security applied to the
network messages published by
a WriterGroup or received by a
ReaderGroup.
MaxNetworkMessageSize UInt32 The MaxNetworkMessageSize

with DataType UInt32 indicates
the maximum size in bytes for
network messages created by
the WriterGroup. It refers to the
size of the complete network
message including padding and
signature without any additional
headers added by the transport
protocol mapping. If the size of a
network message exceeds the
MaxNetworkMessageSize, the
behavior depends on the
message mapping.
WriterGroup WriterGroupDataType
WriterGroupId UInt16 The WriterGroupId with

DataType UInt16 is an identifier
for the WriterGroup and shall be
unique across all WriterGroups
for a PublisherId. All values,
except for 0, are valid. The value
0 is defined as null value.
PublishingInterval Duration The PublishingInterval with the

DataType Duration defines the
interval in milliseconds for
publishing NetworkMessages
and the embedded
DataSetMessages created by the
related DataSetWriters.

APPENDIX
KeepAliveTime Duration The KeepAliveTime with

DataType Duration defines the
time in milliseconds until the
Publisher sends a keep alive
DataSetMessage in the case
where no DataSetMessage was
sent in this period by a
DataSetWriter. The minimum
value shall equal the
PublishingInterval.
Priority Byte The Priority with DataType Byte

defines the relative priority of the
WriterGroup to all other
WriterGroups across all
PubSubConnections of the
Publisher.
If more than one WriterGroup

needs to be processed, the
priority number defines the order
of processing. The highest
priority is processed first.
The lowest priority is zero and

the highest is 255.
LocaleIds String[]
TransportSettings WriterGroupTransportDataType
QueueName String The QueueName parameter with

DataType String specifies the
queue in the Broker that receives
NetworkMessages sent by the
Publisher for the DataSetWriter.
This could be the name of a
queue or topic defined in the
Broker. This parameter is only
valid if the NetworkMessages
from the WriterGroup contain
only one DataSetMessage.

APPENDIX
RequestedDeliveryGuarante BrokerTransportQualityOfService The

e RequestedDeliveryGuarantee
parameter with DataType
BrokerTransportQualityOfService
specifies the delivery guarantees
that shall apply to all
NetworkMessages published by
the WriterGroup unless
otherwise specified on the
DataSetWriter transport settings.
NotSpecified_0: The value is not

specified and the value of the
parent object shall be used.
BestEffort_1: The transport shall

make the best effort to deliver a
message. Worst case this means
data loss or data duplication are
possible.
AtLeastOnce_2: The transport

guarantees that the message
shall be delivered at least once,
but duplication is possible.
Readers must de-duplicate
based on message id or
sequence number.
AtMostOnce_3: The transport

guarantees that the message
shall be sent once, but if it is lost
it is not sent again.
ExactlyOnce_4: The transport

handshake guarantees that the
message shall be delivered to
the broker exactly once and not
more or less.
MessageSettings WriterGroupMessageDataType
NetworkMessageContentMa JsonDataSetMessageContentM The

sk ask DataSetMessageContentMask

APPENDIX
defines the flags for the content

of the DataSetMessage header.
The JSON message mapping
specific flags are defined by the
JsonDataSetMessageContentM
ask data type.
DataSetWriterId (Bit 1): If this

flag is set, a DataSetWriterId
shall be included in the
DataSetMessage header.
MetaDataVersion (Bit 2): If this

flag is set, the
ConfigurationVersion is included
in the DataSetMessage header.
SequenceNumber (Bit 3): If this

flag is set, the
DataSetMessageSequenceNum
ber is included in the
DataSetMessage header.
Timestamp (Bit 4): If this flag is

set, a timestamp shall be
included in the DataSetMessage
header.
Status (Bit 5): If this flag is set,

an overall status is included in
the DataSetMessage header.
DataSetWriters DataSetWriterDataType[]
Name String The name assigned to the

DataSetWriter.
Enabled Boolean True when the dataset writer is

enabled.
DataSetWriterId UInt16 The DataSetWriterId with

DataType UInt16 defines the
unique ID of the DataSetWriter
for a PublishedDataSet. It is
used to select DataSetMessages

APPENDIX
for a PublishedDataSet on the

Subscriber side.
It shall be unique across all

DataSetWriters for a PublisherId.
All values, except for 0, are valid

DataSetWriterIds.
DataSetFieldContentMask DataSetFieldContentMask A Dataset field consists of a

value and related metadata. In
most cases the value comes with
status and timestamp
information.
This data type defines flags to

include Dataset field related
information like status and
timestamp in addition to the
value in the DataSetMessage.
Dataset fields can be
represented as RawData, Variant
or DataValue. If none of the flags
are set, the fields are
represented as Variant. If the
RawData flag is set, the fields are
represented as RawData and all
other bits are ignored. If one of
the bits 0 to 4 is set, the fields
are represented as DataValue.
StatusCode (Bit 0): The

DataValue structure field
StatusCode is included in the
DataSetMessages. If this flag is
set, the fields are represented as
DataValue.
SourceTimestamp (Bit 1): The

SourceTimestamp is included in
the DataSetMessages. If this flag

APPENDIX
is set, the fields are represented

as DataValue.
ServerTimestamp (Bit 2): The

ServerTimestamp is included in
the DataSetMessages. If this flag
is set, the fields are represented
as DataValue.
SourcePicoSeconds (Bit 3): The

SourcePicoSeconds is included
in the DataSetMessages. If this
flag is set, the fields are
represented as DataValue. This
flag is ignored if the
SourceTimestamp flag is not set.
ServerPicoSeconds (Bit 4): The

ServerPicoSeconds is included
in the DataSetMessages. If this
flag is set, the fields are
represented as DataValue. This
flag is ignored if the
ServerTimestamp flag is not set.
RawData (Bit 5): If this flag is set,

the values of the Dataset are
encoded as Structure and all
other field related flags shall be
ignored. The RawData
representation is handled like a
Structure DataType where the
Dataset fields are handled like
Structure fields and fields with
Structure DataType are handled
like nested structures. All
restrictions for the encoding of
Structure data types also apply
to the RawData Field Encoding.

APPENDIX
Fields shall not have an abstract

DataType or shall have a fixed
ValueRank. Fields shall have
dimensions defined if the
DataType is String or ByteString
or if it is an array. This includes
Structure fields with such fields.
The flag shall be ignored and the
fields shall be represented as
Variant if the fields do not fulfil
these requirements.
KeyFrameCount UInt32 The multiplier of the

PublishingInterval that defines
the maximum number of times
the PublishingInterval expires
before a key frame message with
values for all published Variables
is sent. The delta frame
DataSetMessages contains just
the changed values. If no
changes exist, the delta frame
DataSetMessage shall not be
sent. If the KeyFrameCount is set
to 1, every message contains a
key frame.
DataSetName String The name of the corresponding

PublishedDataSet.
TransportSettings DataSetWriterTransportDataTyp
e
MetaDataQueueName String The parameter

MetaDataQueueName with the
DataType String specifies the
Broker queue that provides
messages with
DataSetMetaData sent by the
Publisher for the Dataset of
interest. This could be the name

APPENDIX
of a queue or topic defined in the

Broker.
MetaDataUpdateTime Duration Specifies the interval in

milliseconds with Data Type
Duration at which the Publisher
shall send the DataSetMetaData
to the MetaDataQueueName. A
value of 0 or any negative value
shall be interpreted as infinite
interval.
Writer Datasets
Name String The name assigned to the

published dataset. It must
be unique across dataset
definition files.
DataSetMetaData
Name String The name of the dataset.
Description Localized Text Description of the Dataset.
Fields FieldMetaData[] The metadata for the fields

in the Dataset.
Name String Name of the field. The

name shall be unique in
the Dataset.
Description Localized Text Description of the field.
BuiltInType Byte The built-in data type of

the field. The possible
built-in type values are
defined in OPC 10000-6.
DataType NodeId The NodeId of the

DataType of this field.
ValueRank Int32 Indicates whether the data

type is an array and how
many dimensions the array
APPENDIX
has. It may have the

following values:
n > 1: the data type is an

array with the specified
number of dimensions.
OneDimension (1): The

data type is an array with
one dimension.
OneOrMoreDimensions
(0): The data type is an
array with one or more
dimensions.
Scalar (−1): The data type is

not an array.
Any (−2): The data type can

be a scalar or an array with
any number of dimensions.
ScalarOrOneDimension
(−3): The data type can be a
scalar or a one dimensional
array.
NOTE All Data types are

considered to be scalar,
even if they have array-like
semantics like ByteString
and String.
ArrayDimensions UInt32[] This field specifies the

maximum supported
length of each dimension.
If the maximum is
unknown the value shall be
0.
MaxStringLength UInt32 If the data type field is a

String or ByteString then
this field specifies the
maximum supported

APPENDIX
length. If the maximum is

unknown the value shall be
0.
If the data type field is not

a String or ByteString the
value shall be 0.
If the ValueRank is greater

than 0 this field applies to
each element of the array.
DataSetFieldId Guid The unique ID for the field

in the Dataset. The ID is
generated when the field is
added to the list. A change
of the position of the field
in the list shall not change
the ID.
Properties KeyValuePair[] List of Property values

providing additional
semantic for the field.
If at least one Property

value changes, the
MajorVersion of the
ConfigurationVersion shall
be updated.
If the Property is
EngineeringUnits, the unit
of the Field Value shall
match the unit of the
FieldMetaData.
The KeyValuePair data type

is defined in OPC 10000-5.
For this field the key in the
KeyValuePair structure is
the BrowseName of the
Property and the value in
the KeyValuePair structure
is the Value of the Property.

APPENDIX
DataSetClassId Guid This field provides the

globally unique identifier of
the class of Dataset.
ConfigurationVersion Configuration Version The configuration version

for the current
configuration of the
Dataset.
ExtensionFields KeyValuePair[] The ExtensionFields

parameter allows the
configuration of fields with
values to be included in the
Dataset when the existing
address apace of the
Publisher does not provide
the necessary information.
The ExtensionFields are
represented as array of
KeyValuePair Structures.
DataSetSource PublishedDataSetSourceDataType
PublishedData PublishedVariableDataType[]
PublishedVariable NodeId The NodeId of the

published Variable.
AttributeId IntegerId Id of the Attribute to

publish e.g. the Value
Attribute. This shall be a
valid Attribute id. The
Attributes are defined in
OPC 10000-3.
SamplingIntervalHint Duration A recommended rate of

acquiring new values for
change or deadband
evaluation. A Publisher
should use this value as
hint for setting the internal
sampling rate.

APPENDIX
The value 0 indicates that

the Server should use the
fastest practical rate.
The value -1 indicates that

the default sampling
interval defined by the
PublishingInterval of the
WriterGroup is requested.
Any negative number is
interpreted as -1.
DeadbandType UInt32 A value that defines the

deadband type and
behavior.
DeadbandValue Double The deadband value for the

corresponding
DeadbandType. The
meaning of the value
depends on
DeadbandType.
IndexRange NumericRange This parameter is used to

identify a single element of
an array, or a single range
of indexes for arrays. The
NumericRange type and
the logic for IndexRange
are defined in OPC 10000-
4.
SubstituteValue BaseDataType The value that is included

in the Dataset if the
StatusCode of the
DataValue is Bad. In this
case the StatusCode is set
to
Uncertain_SubstituteValue.
This Value shall match the

DataType of the
PublishedVariable since

APPENDIX
DataSetWriters may
depend on a valid Value
with the right DataType
that matches the
ConfigurationVersion.
If the SubstituteValue is
Null, the StatusCode of the
DataValue is processed.
MetaDataProperties QualifiedName[] This parameter specifies

an array of Properties to be
included in the
FieldMetaData created for
this Variable.
Appendix B: Understanding dataset.json file

You can refer to below pictures to understand the relation between some of the fields defined in Dataset.json
file and fields in Matrikon OPC UA Explorer.

APPENDIX

Contacting Support
The Matrikon Customer Services department (www.opcsupport.com) is available 24 hours a day, seven days a
week. Contact Matrikon Support using the information below, or send an email to support@MatrikonOPC.com.
For Monday to Friday daytime support requests, contact Matrikon Support using the regional phone numbers
as provided below:
Region Office Hours Contact Information
North America 8:00 am-5:00 pm +1-877-OPC-4-ALL

UTC/GMT -7 hours (MST) (672-4255)
+1-780-945-4011
South America 9:00 am-5:00 pm +55 (11) 3475-1846

UTC/GMT -3 hours (BRT)
Europe /Africa/Middle East 9:00 am-5:00 pm +49-221-969-77-10

UTC/GMT +1 hours (CET) (Request OPC Support)
Australia/Asia 9:00 am-5:00 pm +61-2-4908-2198

UTC/GMT +10 hours (AEST)
Region Contact Information
All* +1-780-231-9480
For after-hours support in all regions, please use the following number. There is no extra charge from
Matrikon OPC for calling their after-hours support number.
*Available only to priority and premium support customers.
Matrikon®
#1800, 10405 Jasper Avenue

Edmonton, AB T5J 3N4 MOPCDOC-X701-en-10A
June 2021
Canada
© 2021 Honeywell International Sàrl
www.matrikonopc.com
Matrikon®
#1800, 10405 Jasper Avenue

Edmonton, AB T5J 3N4 MOPCDOC-X701-en-10A
June 2021
Canada
© 2021 Honeywell International Sàrl
www.matrikonopc.com

Matrikon Data Broker MQTT Publisher User Manual

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Matrikon Data Broker MQTT Publisher User Manual

Uploaded by

Copyright:

Available Formats

Matrikon® Data Broker

Release Date: June 2021

Copyright and Trademark Information

Matrikon® Data Broker MQTT Publisher User Guide 2

Matrikon® Data Broker MQTT Publisher User Guide 3

Intended audience ...................................................................................................................................................................... 6

Deploy as a Container ............................................................................................................................................................ 15

Matrikon® Data Broker MQTT Publisher User Guide 4

Adding OPC UA Client Connections .......................................................................................................................25

Other Considerations ............................................................................................................................................................. 48

Appendix B: Understanding dataset.json file............................................................................................................. 63

Matrikon® Data Broker MQTT Publisher User Guide 5

About this Manual

Throughout the document, there are reference to Forge IoT or Forge

Throughout the document, Matrikon FLEX Dispatch and Matrikon

A 1.0 June 2021 New document.

1. OPC UA standard and its applications.

2. Matrikon FLEX Dispatch.

3. Matrikon OPC UA Explorer.

5. How to create and configure On-Prem MQTT Brokers.

Matrikon® Data Broker MQTT Publisher User Guide 6

Matrikon® Data Broker MQTT Publisher User Guide 7

Introduction to Matrikon Data Broker MQTT Publisher

Azure IoT Hub Forge IoT MQTT Connection

MQTT 3.1 AMQP* MQTT 3.1

Matrikon FLEX Dispatch

Matrikon® Data Broker MQTT Publisher User Guide 8

Before You Begin

Software Supported Version(s)

Windows Operating System Client: Windows 10 64-bit

Matrikon FLEX Dispatch Minimum version R1.4

Matrikon OPC UA Explorer Minimum version R1.4

Hardware Minimum Requirements

Disk Space 1GB

Processor Architecture x86-64

Change initial passwords

Matrikon® Data Broker MQTT Publisher User Guide 9

Secure the certificate key store

Secure auxiliary files

Logging and diagnostics

Monitor certificate chains

Matrikon® Data Broker MQTT Publisher User Guide 10

Installation of Matrikon Data Broker MQTT Publisher

To install Matrikon Data Broker MQTT Publisher:

Matrikon® Data Broker MQTT Publisher User Guide 11

Matrikon® Data Broker MQTT Publisher User Guide 12

• In the User Name field, type a username in the following format:

As a security best practice, it is not recommended to run any Windows

Matrikon® Data Broker MQTT Publisher User Guide 13

Matrikon® Data Broker MQTT Publisher User Guide 14

Deployed Files Location in Windows

File Type Default Location

MQTT Publisher exe C:\Program Files\Matrikon\MDB-MQTTPublisher

MQTT Publisher C:\ProgramData\Matrikon\MDB-MQTTPublisher\Config

MQTT Publisher PKI folder C:\ProgramData\Matrikon\MDB-MQTTPublisher\pki

MQTT Publisher Log Files C:\ProgramData\Matrikon\MDB-MQTTPublisher\logs

MQTT Publisher options C:\ProgramData\Matrikon\MDB-

MQTT Publisher User Manual C:\Program Files\Matrikon\MDB-MQTTPublisher\Documentation

Matrikon® Data Broker MQTT Publisher User Guide 15

The container version of MQTT Publisher is based on the base image of

Running MQTT Publisher as a container on Windows is in Beta for the

This section is divided into 3 sub-sections:

• Deploy the MQTT Publisher Container

Deploy the Matrikon Data Broker MQTT Publisher Container