SIEMENS MQTT Industrial Edge Connector Connector HurBtor V1.5 User Manual

MQTT Industrial Edge Connector Connector HurBtor V1.5

Product Information: Industrial Edge MQTT Connector

The Industrial Edge MQTT Connector is a software tool that enables industrial IoT data connectivity by exchanging data between the Siemens Industrial Edge platform and MQTT-based cloud platforms. The tool is designed to help you configure, test, and deploy an MQTT connector to facilitate the transfer of data between your industrial machines and cloud applications.

General Data Protection Regulation (GDPR)

The Industrial Edge MQTT Connector complies with the General Data Protection Regulation (GDPR) which is a regulation in EU law on data protection and privacy. The tool enables secure and reliable data exchange while protecting the privacy of personal data.

Operating Manual

The operating manual provides detailed instructions on the installation, configuration, and usage of the Industrial Edge MQTT Connector. The manual includes a warning notice system that highlights the precautions to be taken to ensure personal safety and prevent damage to property.

User Interface for Industrial Edge MQTT Connector

The user interface for the Industrial Edge MQTT Connector is designed to be intuitive and easy to use. The Configurator Home Page is the main entry point for configuring the MQTT connector. The user interface provides options to configure the connection settings, data mapping, and security settings.

Additional Information

The Industrial Edge MQTT Connector is a Siemens product that should be used only for the applications described in the catalog and relevant technical documentation. Proper transport, storage, installation, assembly, commissioning, operation, and maintenance are required to ensure that the product operates safely and without any problems. The permissible ambient conditions must be complied with.

Product Usage Instructions

1. Install the Industrial Edge MQTT Connector software on your computer.
2. Launch the software and navigate to the Configurator Home Page.
3. Configure the connection settings by specifying the broker address, port number, and credentials.
4. Map the data variables between your industrial machines and cloud applications by specifying the source and destination variables.
5. Configure the security settings by specifying the SSL/TLS settings and authentication credentials.
6. Test the MQTT connector by sending sample data between your industrial machines and cloud applications.
7. Deploy the MQTT connector to your production environment and monitor the data exchange for any issues.

It is important to follow the instructions in the operating manual and observe the warning notices to ensure personal safety and prevent damage to property. Only personnel qualified for the specific task should operate the product/system described in this documentation.

Legal information

Warning notice system
This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert symbol, notices referring only to property damage have no safety alert symbol. These notices shown below are graded according to the degree of danger.

DANGER
indicates that death or severe personal injury will result if proper precautions are not taken.

WARNING
indicates that death or severe personal injury may result if proper precautions are not taken.

CAUTION
indicates that minor personal injury can result if proper precautions are not taken.

NOTICE
indicates that property damage can result if proper precautions are not taken.

If more than one degree of danger is present, the warning notice representing the highest degree of danger will be used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to property damage.

Qualified Personnel
The product/system described in this documentation may be operated only by personnel qualified for the specific task in accordance with the relevant documentation, in particular its warning notices and safety instructions. Qualified personnel are those who, based on their training and experience, are capable of identifying risks and avoiding potential hazards when working with these products/systems.

Proper use of Siemens products
Note the following:

WARNING
Siemens products may only be used for the applications described in the catalog and in the relevant technical documentation. If products and components from other manufacturers are used, these must be recommended or approved by Siemens. Proper transport, storage, installation, assembly, commissioning, operation and maintenance are required to ensure that the products operate safely and without any problems. The permissible ambient conditions must be complied with. The information in the relevant documentation must be observed.

Trademarks All names identified by ® are registered trademarks of Siemens AG. The remaining trademarks in this publication may
be trademarks whose use by third parties for their own purposes could violate the rights of the owner.

Disclaimer of Liability
We have reviewed the contents of this publication to ensure consistency with the hardware and software described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the information in this publication is reviewed regularly and any necessary corrections are included in subsequent editions.

General Data Protection Regulation (GDPR)

Siemens adheres to the principles of data protection, in particular the principles of data minimization (Privacy by Design).
For this product, Industrial Edge MQTT Connector Configurator, this means:

Personal data
There is no personal data* collected but following data is stored to allow machine to machine communication:

• Individual client credentials for connecting to IE MQTT Connector
• Topics associated with each user for publishing, subscribing, or both over IE MQTT Connector
• App usage data

If the customer links the data mentioned above to other data (e.g. shift plans) or if the customer saves personal information on the same medium (e.g. hard disk) and thus creates a personal reference, the customer has to ensure that the guidelines regarding data protection are observed.

Note

• This section refers to any personal data processed by the Application other than the personal data contained in log-files / tracking data (if any). “Personal data” are any information relating to an identified or identifiable natural person. Please note that IP-addresses, device identifiers such as IMEI, UDID, IMSI, MAC-address, MSISDN, location data or machine data (if machine data tracks events triggered by user interaction with the machine) usually qualify as personal data.

Purposes
The data mentioned above is required for the following purpose:

• Access protection and security measures

Storage of the data is affected for a suitable purpose and is limited to what is strictly necessary, as the information is indispensable in order to identify the authorized clients.

Securing of data
The above data will not be stored anonymously or pseudonymized, as the purpose (identification of the operating personnel) cannot be achieved otherwise. This data will be used only within the product and within the Edge eco-system and will not be automatically passed on to third parties or unauthorized persons. This data is secured by adequate technical measures, such as encryption.
The customer must ensure the access protection as part of his process configuration while using IE MQTT Connector.

Deletion policy
This product does not provide an automatic deletion for the IE MQTT Connector and server user credentials already provided by the user. IE MQTT Connector user credentials can be deleted.

Data configuration
The customer can configure the above data for the product using the App Configurator on Industrial Edge Management. Once the configuration is completed, the data will be stored securely.

Introduction to Industrial Edge MQTT Connector

The Industrial Edge MQTT Connector (IE MQTT Connector) allows you to connect remote clients to the IED over MQTT. The data pushed to IE MQTT Connector is pushed to IE Databus on the configured topics and is available to be consumed by other apps within the IED.

The IE MQTT Connector consists of the following two components:

1. Industrial Edge Databus Configurator (IE Databus Configurator) in Industrial Edge Management:
   The IE Databus Configurator in Industrial Edge Management includes a user interface. The IE Databus and IE MQTT Connector use the same configurator app and the IE MQTT Connector Configurator functionalities are performed using IE Databus Configurator app. The IE MQTT Connector Configurator gives you an overview of the IE MQTT Connector-specific details of the corresponding Industrial Edge Device.

2. IE MQTT Connector:
   The IE MQTT Connector is a distributed application that runs on the individual Industrial Edge Device.

User Interface for Industrial Edge MQTT Connector Configurator Home Page

Prerequisite

• IE MQTT Connector app must be installed and running on the Industrial Edge Device.
• IE Databus Configurator app must be installed and running on the Industrial Edge Management.

Home page
When you launch IE MQTT Connector Configurator, the Configurator home page is displayed as follows:

1. User View Tab
2. Add User Icon
3. Topic View Tab
4. Certificate Tab
5. Bridge Configure
6. Deploy Button
7. Delete User Icon
8. Add Topic Icon
9. User Information
10. Delete Topic Icon
11. Logs/Import/Export Icons

UI Elements
The following table lists the different UI elements in the IE MQTT Connector Configurator home page.

access rights.
Add User Icon| Enables to add a user.
Topic View Tab| Displays all the topics as an individual row with the related user and associated access rights.
Certificate Tab| Enables to configure secure/unsecure connection.
Bridge Configure| Allows you to set up connection between data bus to external applications through MQTT connector
Symbol| Description
---|---
Deploy Button| Opens the “Deploy” dialog box to deploy configuration to specific IEDs. If you close the IE MQTT Connector Configurator, then all the unsaved con‐ figurations are lost.

“Deploy” button enables to deploy the configuration to Industrial Edge Runtime. It saves the configuration on the Industrial Edge Runtime.

Delete User Icon| Enables to delete a user.
Add Topic Icon| Enables to add a topic.
User Information| Displays the users and their assigned topics and associated access rights.
Delete Topic Icon| Enables to delete a topic.
Logs/Import/Export Icons| Displays the activities of users and its associated topics.

Enable to import and export the configuration. For more information, refer Import/Export Configuration .

Working with Industrial Edge MQTT Connector Configurator

The IE MQTT Connector Configurator provides you information about all available users including their access rights for the corresponding Industrial Edge Device. In addition, you can create users and grant users access rights to the IE MQTT Connector of the corresponding Industrial Edge Devices.

The data pushed to IE MQTT Connector is pushed to IE Databus on the configured topics. You can connect any external client and apps to IE MQTT Connector and thereby obtain access rights to the IE MQTT Connector. This allows you to use the data from the remote clients for your individual application.

The IE MQTT Connector Configurator supports multiple user access with the following scenarios:

• One user can access IE MQTT Connector Configurator on multiple Industrial Edge Device (IED).
  But the user cannot access IE MQTT Connector Configurator on the same IED in multiple tabs of same browser or multiple browsers.

• Two users can access IE MQTT Connector Configurator on two different IEDs simultaneously. When the two users access IE MQTT Connector Configurator on the same IED, a message is displayed to the second user that the IED is in use already. Therefore, the second user cannot access IE MQTT Connector Configurator.

Managing Users

Add Users
You can add a user in the IE MQTT Connector Configurator and provide the necessary access rights to a topic of the IE MQTT Connector of the corresponding Industrial Edge Device.

Prerequisite
The IE MQTT Connector application must be running.

Procedure
To add a user, follow these steps:

1. Launch the IE MQTT Connector Configurator.
   The IE MQTT Connector Configurator home page is displayed.

2. Click + in the “Users” section.
   The “Add User” dialog box is displayed as follows:

3. Complete the following fields:
   Field Name| Definition
   ---|---
   Username| Defines the username of the new user.
   Password| Defines the corresponding password of the user.

User is successfully added, and is displayed under the “User” view tab.

Delete Users

The IE MQTT Connector Configurator allows you to delete a user. When you delete a user, the “Users” section is updated with the updated list of the users to IE MQTT Connector of the corresponding Industrial Edge Device.
Once a user is deleted, the user no longer has access to the IE MQTT Connector of the corresponding Industrial Edge Device.

Prerequisite
The IE MQTT Connector application must be running, and a user must be available.

Procedure
To delete a user, follow these steps:

1. Launch the IE MQTT Connector Configurator.
   The IE MQTT Connector Configurator home page is displayed.

2. Click on the user that you want to delete.
   The delete icon is enabled.

3. Click DELETE..
   The user is deleted and removed from the IE MQTT Connector.
   You must click “Deploy” to deploy the changes to Industrial Edge Runtime.

User View Tab
The “User View” tab is the default view tab when you launch the IE MQTT Connector Configurator. It displays all the available users including their access rights for the assigned topics.
The user list gives you an overview of the users that are created in the IE MQTT Connector of the corresponding Industrial Edge Device. If you click on a user from the user list, the “Topics” list displays the topics that the user can access, including the topic’s access rights.

As depicted in the above image, the “User View” tab provides you the following features:

• Sorting Feature
  You can sort the users, topics, or access rights column using the sorting icon in their respective column.

• Searching Feature
  You can search a user, topic, or access rights using the available filter area in their respective column

• The green check box indicates the status of the MQTT connector.

Managing Topics

Add Topics
You can add a topic in the IE MQTT Connector Configurator and assign the required access rights for a user. The user based on the assigned permissions can access the topic.

Prerequisite
The IE MQTT Connector application must be running, and a user must be available.

Procedure
To add a topic, follow these steps:

1. Launch the IE MQTT Connector Configurator.
   The IE MQTT Connector Configurator home page is displayed. You can add topics using:

   • User View
   • Topic View

Adding topics in User View tab
To assign “Topics” to users in “User “view tab, perform the following:

1. Click in the “Topics” section. The The “Add Topic” pop-up appears as follows:

2. You can choose to enter a new topic by clicking “New” tab, and select the “Permission” type. Complete the following fields:
   Field| Description
   ---|---
   Topic name| Specifies the topic name that is used for the unique to assign it to users. You can search the topics using the “Search Topic” option. The relevant topics are displayed in the drop-down list.
   Permission| Specifies the access rights of the user to the IE MQTT Connector. The available options are as follows:

   • “No Permission”: The user has no access rights.
   • “Subscribe Only”: The user can only read data from the IE MQTT Connector and use it for other applications.
   • “Publish and Subscribe”: The user can send data to the IE MQTT Connector and use data from the IE MQTT Connector for further applications.
     Actions| Allows you to delete the topics.

3.  Click “Add”.The topic is added, and is displayed in the “New” tab area.  You can choose to search and import topics “From MQTT”, and assign it to user as shown below:

4. You can choose to search for topics “From Databus”, and assign it to user as shown below:

5. Click “Add”. The topic is assigned to the user and displayed in the “Users” section. You must click “Deploy” to deploy the changes to Industrial Edge Runtime.

Adding Topics in Topic View tab
To assign “Topics” to users in “Topic” view tab, perform the following:

1. Click +  in the “Topics” section.
   The The “Add Topic” pop-up appears as follows:

2. Complete the following fields:
   Field Name| Description
   ---|---
   Username| Lists the username to which you are adding the topic.
   Topic name| Defines the topic name. Alternatively, you can select an existing topic from the drop-down list. The topic name is used for the unique assign‐ ment of the user to the access area.
   Permission| Specifies the access rights of the user to the topic. The available options are as follows:

   • “No Permission”: The user has no access rights.
   • “Subscribe Only”: The user can only read data from the IE MQTT Connector and use it for other applications.
   • “Publish and Subscribe”: The user can send data to the IE MQTT Connector and use data from the IE MQTT Connector for further applications.

Note: The above options are available in Topic view only.

3. You can use to add up to five topics as follows:
4. Click “OK”.The topic is added to the user’s topic list and to the Industrial Edge Device’s IE MQTT Connector with the appropriate access permissions.
   You must click “Deploy” to deploy the changes to Industrial Edge Runtime.

Topic View Tab
The “Topic View” tab displays a complete overview of all the topics including their assigned users and access rights.

As depicted in the above image, the “Topic View” tab provides you the following features:

• Sorting Feature
  You can sort the topics, users, or access rights column using the sorting icon in their respective column.

• Searching Feature
  You can search a topic, user, or access rights using the available filter area in their respective column.

• Delete Topic Feature
  You can delete a topic using available in “Topics” and “Users” section. When you delete a topic from “Topics” section, it is deleted for all the users.

Delete Topics
You can delete a topic assigned to a user as required. Once a topic is deleted, the user no longer has access to the corresponding topic.

Prerequisite

• The IE MQTT Connector application must be running, and a user must be available.
• A topic must be assigned to a user.

Procedure
To delete a topic, follow these steps:

1. Launch the IE MQTT Connector Configurator.
   The IE MQTT Connector Configurator home page is displayed.

2. Select the user of which you want to delete a topic.
   The topic list is displayed.

3. Select the records that you want to delete.

4. Click DELET.
   The topics are deleted and removed from the topic list.
   You must click “Deploy” to deploy the changes to Industrial Edge Runtime.

Enable End-to-end Secure Connection

By default, the end-to-end secure connection is enabled. You must provide certificate, private key, and certificate authority, and deploy the configuration to the Industrial Edge Runtime.
You can disable the secure connection at your own risk by selecting “Unsecure” radio-button. You must be cautious when you disable the secure connection, as the data in transit is not encrypted with unsecure connection and any hacker can intercept the traffic and gain access. This communication is then dependent on the external network security.

Prerequisite

• The IE MQTT Connector application must be running.

Procedure
To enable end-to-end secure connection, follow these steps:

1. Select “Certificate” tab.
   The following page is displayed: The “End to end security” radio-button is selected by default.

2. Upload certificate, private key, and certificate authority in “Certificate”, “Private Key”, and “Certificate Authority” fields respectively.
   Note
   You must ensure to upload CA (Certificate Authority) certificates that can accurately validate client certificates.
   You must click “Deploy” to deploy the changes to Industrial Edge Runtime.
   Note

   • You can select “Unsecure” radio-button if you want to disable end-to-end secure connection.

Import/Export Configuration

The IE MQTT Connector allows you to import and export the configuration. This functionality is helpful when you want to use an existing configuration of one Industrial Edge Device (IED) in other IEDs. This enables to take the back-up of the configuration and restore it as required. You can export the configuration file from the required IED and import this configuration file in the desired IED where you want to use this configuration. The configuration file is a JSON file, and is exported in .json format.

To export the configuration, follow these steps:

1. Click in the upper-right corner.
   The “Export Configuration” dialog box is displayed as follows:

2. Define a password in “Password” field. Password must contain at least one number, one special character, one lowercase, and one uppercase letter. The minimum length must be at least 8 characters.

3. Enter the same password in “Confirm Password” field.

4. Click “Ok”.
   The configuration file is exported.
   You must remember this defined password. This password is used while importing this configuration file. This exported file must not be modified externally. If the exported .json file is modified externally, then the file cannot be imported. This provides a unique means of verifying that the integrity of the file has been maintained.

To import the configuration, follow these steps:

1. Click in the upper-right corner and select the .json file from which you want to import the configuration.
   The “Import Configuration” dialog box is displayed as follows:

2. Enter the password for the .json file which was defined while exporting it.

3. Click “Ok”.
   The configuration file is imported.
   You must click “Deploy” to deploy the changes to Industrial Edge Runtime.
   Logs
   You can check the status of the MQTT subscription by clicking the logs option. The logs will display the the applications that subscribed to MQTT connector along with timestamp.

Configuring Bridge
MQTT connector allows you to connect to client applications through Databus. Using “Bridge Configure”, client applications can push and subscribe data to Databus using MQTT connector.

To perform “Bridge Configure”, follow the steps below:

1. By default None is chosen. This indicates that no data is exchanged between the Databus and client applications. You will always be alerted with the below message when you perform any changes in the “Bridge Configure” area.
   ” Any changes to this configuration will trigger a restart of the server. All clients must reconnect in order to maintain communication with IE MQTT Connector.”

2. To publish or subscribe data, select “Enable custom bridge”.

3. You must add users and its associated topics in the Databus Connector which can be accessed by client applications using MQTT Connector. For more details on adding user, and topics refer Add User/Topic. (Page 16)

4. Deploy the user and topic details configured in Databus.

5. Enter the “Username” and “Password” used to connect to Databus.

6. Click “Connect”.

7. Click “Add Row”. The MQTT connector application now displays the topics that were associated for a respective user.

8. Choose a topic that you would like to expose it to client applications for use.

9. The “Direction” column consists of:

   • Applications can subscribe data to Databus through IE MQTT Connector.
   • Applications can publish data to Databus through IE MQTT Connector.
   • Applications can publish/subscribe data through MQTT Connector.

10. Select the Quality of Service “QOS” . MQTT uses connector to set up a connection between client and the broker. Every topic is referred to as the subject that the broker uses to determine the authenticity of the subscribing client. Every connection to the broker is determined by three Quality of Service (QoS) levels.

    • 0 – Topic data is delivered to the client application only once, but without acknowledgement.
    • 1- Topic data can be delivered more than once to client application with an acknowledgment.
    • 2- The request/response for a topic data is acknowledged by the client and broker.

See also
Managing Users (Page 13)
Managing Topics (Page 16)

Deploy Updates

When you perform the following tasks:

• Add User
• Delete User
• Add Topic
• Delete Topic
• Import/Export Configuration
• Enable/Disable end-to-end secure connection
  You must deploy these updates to Industrial Edge Runtime to save them.

To deploy the changes, follow these steps:

1. Click “Deploy”.
   The “Deploy” dialog box is displayed as follows:
   Note: You can deploy the changes only when the Industrial Edge Devices are in “Online” state.

2. Select the required Industrial Edge Devices on which you want to deploy the changes.
   Note: You can deploy your changes (configurations) to multiple devices as required. When you deploy your configurations to other IEDs, the previous existing configuration is overwritten.

3. Click “Deploy”.
   The changes are deployed, and the success message is displayed.

Additional Information

A.1 Connect to IE MQTT Connector
If you want your app to connect to the IE MQTT Connector from an external client (for example, MQTTX), you can use the device IP and connect to server on ‘9883’. You must enable secure (SSL/TLS) connection and upload certificate as required. You can configure MQTTX as follows:

For SIMATIC Flow Creator, you can configure as follows:

The “Use legacy MQTT 3.1 support” checkbox is optional. You must enable secure (SSL/TLS) connection and upload certificate, private key, and certificate authority as follows:

When you publish from an external client to a topic and this topic is subscribed for both IE Databus and IE MQTT Connector, both applications receive the published data.
Whereas when you publish from an internal client to a topic and this topic is subscribed for both IE Databus and IE MQTT Connector, only the IE Databus receives the published data.

A.2

Notes on use
The following restrictions apply with the delivery of the Industrial Edge MQTT Connector Configurator.

System Requirement
The RAM requirement to install the app on an IED is as follows:

• IE MQTT Connector: 250 MB
  You must use the retain feature of client judiciously, because in the long run, it may increase the size of the underlying database in a linear fashion on the IED.

Configuration update
Whenever you change the configuration in the IE MQTT Connector Configurator, the system app on the respective Industrial Edge Device (IED) gets updated only when you click on the “Deploy” button.
You can check the status of the configuration update using the tasks icon in the IED UI.

Multiple deploy
When you perform deploy to multiple IEDs:

• If the UI is launched while the deploy is in progress for an IED, the updated configuration that was deployed is not displayed. You must wait for the deploy to be completed and relaunch the UI.
• If the deploy process is already running on an IED, it is not possible to start another deploy on this IED using multiple deploy feature till the already running deploy is completed.

Managing the IE MQTT Connector Configurator
Only the owner of IEDs and user with access permissions on IEDs can manage the IE MQTT Connector Configurator for these IEDs.

Multiple user access to system configurators
For the system configurators, it is not possible to use the same system configurator of an IED with two or more users’ instances at the same time. When another user launches a system configurator at the same time while a current user is working with the same system configurator, the second user will be blocked, and the primary users continues working with the system configurator. Just when the primary user closes the system configurator, the second user can launch the same system configurator.

User and topics in the IE MQTT Connector Configurator
All created users have access to the data of a topic according to the set permissions for the respective topic. When you create a new user, the new user does also have access to the data of a topic according to the set permissions for the respective topic. When you create a new topic, the same behavior is valid.

Supported language
When you provide the necessary information in input fields, the Industrial Edge Management (IEM), the system configurators, and other components only support characters from the English language. For example, when you add a topic and enter the topic name in the IE MQTT Connector Configurator, special characters like “ö”, “ä”, or “ü” are not supported and result in error messages.

Updating system configurators
Before you update the system configurators, take a snapshot of the cluster respectively the VM.

• When you update the system configurators in the IEM, there is no specific defined sequence for updating the configurators. For the update sequence of other components, refer https://support.industry.siemens.com/cs/document/10979314
• If you are using IEM version v1.3, then all the system configurators must be updated to version v1.3.
• When you update the system configurators, you must ensure to select the ‘nginx conf’ file during the process. The selected file is displayed with green-check circle.

Note

• It is recommended to export the configuration using the export icon before upgrading/uninstalling the app.
• During IE MQTT Connector update to the newer version, you must make sure to export the existing configuration from the IE MQTT Connector Configurator (v1.2 or v1.3) as all the configurations are lost and the clients are disconnected after the update.
  On import of this configuration, only the ‘users’ and their ‘permissions’ are retained. You must reconfigure the certificates and security as required.

Job management for system configurators
The job management for all system configurators is not handled by the system configurators themselves but by the IEM. In case of any job failure, you will be notified by the configurators. In that case, check the jobs in the IED UI respectively in the IEM and delete the failed or skipped jobs from the “Job Status” screen.

First time login to IE MQTT Connector Configurator
You must switch between “End-to-end Security” and “Unsecure” at least once during the very first launch of the IE MQTT Connector Configurator.

A.3 Known issues

The following are the known issues:

It is not recommended to leave the IE MQTT Connector Con‐ figurator open resulting in a session time-out.| If you are facing any such issues with Client Conflict due to the session time-out, please reinstall the IE Databus Configurator application.
When you use the application in Mozilla Firefox web browser and try to export the configuration using “Export” icon, the export configuration does not work.| You must use Google Chrome or Opera web browser.

Industrial Edge MQTT Connector Configurator V1.5 Operating Manual, 02/2022

References

• SIOS

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>