Helmholz 700-162-3MQ02 PN-MQTT Coupler User Guide
- June 5, 2024
- Helmholz
Table of Contents
Helmholz 700-162-3MQ02 PN-MQTT Coupler
Safety instructions
Target audience
This description is only intended for trained personnel qualified in control
and automation engineering who are familiar with the applicable national
standards. For installation, commissioning, and operation of the components,
compliance with the instructions and explanations in this operating manual is
essential. The specialist personnel is to ensure that the application or the
use of the products described fulfills all safety requirements, including all
applicable laws, regulations, provisions, and standards.
Intended use
The device has a protection rating of IP 20 (open type) and must be installed
in an electrical operating room or a control box/cabinet in order to protect
it against environmental influences. To prevent unauthorized operation, the
doors of control boxes/cabinets must be closed and possibly locked during
operation. The consequences of improper use may include personal injury to the
user or third parties, as well as property damage to the control system, the
product, or the environment. Use the device only as intended!.
Operation
Successful and safe operation of the device requires proper transport, storage, setup, assembly, installation, commissioning, operation, and maintenance. Operate the device only in flawless condition. The permissible operating conditions and performance limits (technical data) must be adhered to. Retrofits, changes, or modifications to the device are strictly
Security
The device is a network infrastructure component and therefore an important
element in the security consideration of a plant. When using the device,
therefore, observe the relevant recommendations to prevent unauthorized access
to installations and systems. Further information on this can be found in the
device manual.
Introduction
This document explains the initial commissioning of the PN/MQTT Coupler. The latest version of the document and a detailed manual can be found at www.helmholz.de or scan the QR code directly.
Function of the PN/MQTT Coupler
The MQTT protocol has become established in recent years as a simple transmission protocol for messages in the IoT world. MQTT stands for “Message Queue Telemetry Transport Protocol” and is an OASIS standard. Information on the MQTT protocol can be found here: mqtt.org
The MQTT protocol always uses a central broker for communication between
devices, which receives messages from e.g. a sensor and forwards them to
interested devices, e.g. a control unit. When a sensor sends data to the
broker, this is called “publish”. If a device needs data, it must subscribe to
the broker (“Subscribe”). The broker delivers the data to all subscribers when
new data has arrived from the publisher. Data is always transmitted under a
freely definable identifier – the “Topic”. The “Topic” is a descriptive text,
e.g. “Temperature”. In order to distinguish between different topics of the
same type, groupings are used, e.g. “Living room/temperature”. The groupings
are divided by a slash (‘/’). Thus the data can be mapped into more complex
structures: “Upper floor/Living room/Temperature” or “Upper floor/Living
room/Humidity”. The data delivered via MQTT can be transmitted in binary
format, text format or structured in JSON format. With the PN/MQTT Coupler a
transfer of values between a PROFINET controller (PLC) and a MQTT broker is
possible. It is possible to send values from the PLC via PROFINET to a broker
(“Publish”) as well as to subscribe values from a MQTT broker and receive them
in the PLC via PROFINET (“Subscribe”).
The integration into the PLC engineering tool is enabled by a GSDML file, an
additional extra configuration software is not necessary. The configuration of
the I/O data to be exchanged is done in the Siemens engineering tool. All
settings for the MQTT connection can be done on the web page of the device.
MQTT brokers can be connected both locally (“On-premise”) and via the Internet
(“Cloud”). A local broker can be operated, for example, with the open-source
software “Mosquitto” in the company network on a PC/server or also on a small
computer, such as a Raspberry PI. Such an application is described in this
QuickStart Guide.
Connection
Power supply
The PN/MQTT coupler must be supplied with DC 24 V at the wide-range input DC
18 … 30 V via the supplied connector plug. The power supply is redundant, at
least one supply path PS 1 or PS 2 must be connected.
Network
The left RJ45 sockets “X1 P1” and “X1 P2” are used to connect the PROFINET
network, the right RJ45 sockets “X2 P1” and “X2 P2” are used to connect the
Ethernet network in which the MQTT broker is accessible. The ports X1 P1 and
X1 P2, as well as X2 P1 and X2 P2 are each internally connected to a switch.
The interfaces X1 and X2 are logically separate networks and not physically
connected. Thus a clear separation between the machine data (PROFINET) and the
MQTT data connection is possible. A network penetration with other functions
by the PN/MQTT coupler is not possible.
The configured values are exchanged in the PN/MQTT coupler only as IO data between both network sides.
Install GSDML file
Please download the GSDML file (“GSDML-V2.35-Helmholz-PN-MQTT-coupler-
____.xml”) at www.helmholz.de or scan the QR code. Install the GSDML file in
the “Tools” / “Manage device description file (GSD)” menu in the TIA
Portal.
The PN/MQTT Coupler can be found in the hardware catalog at “Other field devices / PROFINET IO / Gateway / Helmholz GmbH & Co. KG”.
Configuration in TIA Portal
Add the PN/MQTT coupler to the project and connect the coupler to the PROFINET
network.
Name the device name and check the Ethernet address for the device.
Parameterization of the PN/MQTT coupler
The parameterization of the PN/MQTT coupler is performed via the PROFINET
hardware configurator (e.g. TIA Portal). The PROFINET parameters and the I/O
data to be transmitted via MQTT are defined here. The configuration of the
MQTT network connection (connection to the MQTT broker) is set via the web
page of the device.
- Static IP address: If the address mode is set to “Static IP”, the static IP address of the X2 network can be specified here.
- Static IP subnet mask: If the address mode has been set to “Static IP”, the subnet mask of the X2 network can be specified here.
- Static IP gateway: If the address mode has been set to “Static IP”, the gateway of the X2 network can be specified here.
- Hostname mode: “From PROFINET configuration” or “From webpage”.
- DHCP hostname: Name of the device
- Webpage: On which network interfaces should the web page be displayed.
Operating principle of the PN/MQTT coupler
The data exchange between the PLC and the MQTT broker is organized via
individual values. A value can be 1, 2 or 4 bytes in size and is in the I/O
area of the PROFINET controller. Depending on the data direction, the value is
writable to outputs (MQTT Publish) or readable from inputs (MQTT
Subscribe).
A module always represents exactly one value, which is exchanged with the
broker via an MQTT topic name. A value is usually sent via MQTT in a readable
form (direct text or JSON formatted). For this reason, there are different
representation forms for each value size (1, 2, 4 bytes): hexadecimal,
unsigned decimal, signed decimal.
Configuration example:
The value of the input modules is initialized with 0 after restarting the
coupler and is permanently taken over into the input area when a new value is
received via MQTT. A bit additionally indicates the reception of a value in
the PLC.
For each module, the Topic name must be defined unambiguously in the module parameters. The name can be chosen suitable to the symbolic name of the PLC value. Up to 40 characters are available. As another parameter, the method of Quality of Service (QoS) of the topic can be specified. Transmission without acknowledgment (0): The topic is sent without an acknowledgment from the broker („fire-and-forget“) Transmission with acknowledges (1): The topic is sent, and an acknowledgment (“PU BACK”) is expected from the broker. If no acknowledgment is received, the topic is sent again. Transmission with acknowledge and confirmation (2): Provides the guarantee that a message has been “delivered exactly once”. In order to be able to keep this guarantee, MQTT uses a two-stage acknowledgment of receipt. Retain: This option tells the broker to save the last message or value in the broker even if the connection to the MQTT client fails.
Assign a name to the PN/MQTT coupler
When the configuration of the PN/MQTT coupler is completed in the hardware
configurator of the engineering tool, it can be imported into the PLC. To
enable the PN/MQTT Coupler to be found by the PROFINET controller, the
PROFINET device name must be assigned to the PN/MQTT Coupler. To do this, use
the “Assign device name” function, which you can access with the right mouse
button or in the Online menu if the PN/MQTT Coupler is selected. Use the
“Update list” button to search the network for PROFINET stations. With “Assign
name” the PROFINET device name can be assigned to the
device.
If the PN/MQTT coupler has received the correct PROFINET name, it is recognized and configured by the PLC. If the configuration is correct, the PROFINET “BF” LED should be off.
Configuration of MQTT connection
Access to the web page
As soon as the PN/MQTT coupler has been configured via the PROFINET PLC, the
web page of the device is accessible via the PROFINET network. If the IP
address is also available on the MQTT network page (static IP, DHCP
successful), the web page is also accessible via the MQTT network. When
accessing the device for the first time, a password must be assigned for the
user “admin”. After logging in, you will see the “Overview”
view:
The error “System error (SF)” on the PROFINET page is also displayed due to the unconfigured MQTT connection.
MQTT Configuration
After the configuration of the PROFINET side, the connection to the MQTT
broker must still be configured on the web page of the PN/MQTT coupler. The
configuration can be done in the “MQTT” menu. First, select the “IP
Settings”.
In the section “IP Address X2” the IP address of the right network port “X2”
of the PN/MQTT Coupler is displayed. This can be set if it was not specified
via the PROFINET configuration or received via DHCP. The MQTT broker is
addressed via interface X2. If the MQTT broker is located in the same network
as the PROFINET PLC, see note in chapter 4.2.
The necessary settings for connecting to a local MQTT broker can be made on in the menu “MQTT Client Settings”.
-
MQTT version: The PN/MQTT Coupler supports the MQTT standard “3.1.1” and the new standard “V5”. Since the two standards are not compatible, the MQTT version must be set to match the broker.
-
ClientID: Name of the MQTT client when logging on to a broker
-
Username/Password: Authentication at the broker
-
Broker Address: IP address of the broker. The broker must be in the same subnet as the IP address of the coupler’s X2 network.
-
Broker TCP Port: Port for the MQTT connection to the broker. Common are “1883” for unencrypted and “8883” for TLS encrypted connections.
-
Clean session (MQTT V3.1.1): Information to the broker when establishing the connection whether old messages should be deleted or saved.
-
Clean start (MQTT V5): If Clean Start is enabled, the client and broker must discard all existing sessions and start a new session when a connection is established.
If Clean Start is disabled and a session is associated with this client ID, the server must resume communication with the client based on the state of the session. If no session is associated with this client ID, the server must create a new session. -
Session expiry interval [Seconds] (MQTT 5.0 only): In the context of “Clean start”, if “Session expiry interval” is set to 0, the session is terminated when the network connection is closed. Otherwise, the session is kept open until the time expires.
-
MQTT payload data format: The value of a topic is always sent in simple text form. Example: -12345 Some MQTT applications expect a structured form in JSON format.
-
Timestamp Type: The PN/MQTT coupler can (only for JSON formatted messages) add a timestamp to the message.
-
Publish interval: An MQTT message is sent automatically when the output value in the PLC changes. If PLC values are sent that change very fast it is possible to limit the send interval. ‘0′ tells the coupler to send as fast as possible and a number greater than zero tells it not to send faster than x * 0.1 seconds.
Connection Tester
To test the MQTT Broker connection, the PN/MQTT Coupler provides a “Connection
Tester” in the “MQTT” menu.
The Connection Tester tests in 4 subsequent steps if a connection to the internet can be established if the name resolution and the time server works and if the MQTT Broker port is reachable.
MQTT encryption and authentication
The transmission between the client and the broker can be encrypted and the
devices can authenticate each other, i.e. verify their
identity.
In the “MQTT” menu under “MQTT Encryption”, encryption can be activated,
certificates can be stored, and self-generated certificates can also be
created.
Enabled – Encryption only:
Enables encryption without authentication. This option does not require a CA
or client certificate or client key.
Encryption + Broker authentication: enables encryption with broker
authentication done by the client. With this option, a CA must be uploaded for
broker verification (see below).Enabled + Broker & Client authentication:
enables encryption with mutual broker and client authentication. This option
requires a CA and client certificate. In addition to broker verification by
the client, the broker can also verify the client as it sends its certificate
during the TLS handshake.
Verify broker certificate (SNTP must be active): Certificates contain an
expiration date and must be updated regularly. This option checks whether the
broker certificate is still valid. For encryption and authentication,
certificates and keys must be provided (uploaded) to the PN/MQTT Coupler.
- CA File: certificate of broker
- Client Certificate: Certificate for the PN/MQTT Coupler
- Client Key: Private Key File for the PN/MQTT Coupler
For an encrypted and authenticated connection with a broker – whether “on
premise” or in the cloud – the certificate of the broker and the certificate
of the parent certification authority (‘CA’) should be downloadable or
generated by IT for the own network. The certificate for the client should
then also either be generated by the broker application or also created by
IT.
To make
it easier to work with certificates during internal testing, the PN/MQTT
Coupler includes a built-in generator for self-signed certificates or SAS
tokens (Microsoft Azure). Please refer to the PN/MQTT Coupler manual for the
use of these functions.
Module status
If all parameters were set correctly and accepted with “Update settings”, the
PN/MQTT Coupler should automatically connect to the MQTT broker and the red
LEDs should go off. The status can be checked in the “Overview”
view:
On the web page “Module status” the configured module configuration and the
current IO data are displayed. If there is a configuration error, the error is
displayed in the “Diagnostic message” column.
Status and control via the PLC
Status of PN/MQTT Coupler
The PN/MQTT Coupler provides a status (4 bytes) via the PROFINET input image:
| Byte/Bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|
| Input Byte 0 | PROFINET |
configuration OK
|
0
| PS 1
Voltage available
| PS 2
Voltage available
|
0
|
0
| X2 network IP address
available
| X2 network cable
detected
Input Byte 1|
0
|
0
|
0
|
0
|
0
|
0
|
0
| MQTT Broker connection
active
Input Byte 2| Last MQTT error code (MQTT V5) or Connect Return/Reason-Code
Input Byte 3| Reserved
Control of PN/MQTT Coupler
The PN/MQTT coupler can be controlled via the following control bits (1 byte)
in the PROFINET output image:
| Byte/Bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|
| Output- Byte 0 | Clear MQTT Error Code |
–
|
–
|
–
|
–
| MQTT Disconnect connection| MQTT lock data exchange
Subscribe Module
In addition to the input data for the actual value, the subscriber modules
additionally have a status byte and a control byte.
Status bits of Subscribe Module:
| Byte/Bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|
| Input Byte 0 | 1 = new data received | **** |
Receive counter
Control bits of Subscribe Module:
| Byte/Bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|
| Output Byte 0 | 1 = Reset data receive bit | **** |
–
| ****
–
| ****
–
| ****
–
| ****
–
| ****
–
| ****
–
Technical data
| Order no. | 700-162-3MQ02 |
|---|---|
| Article designation | PN/MQTT Coupler |
| PROFINET interface (X1) | |
| Connection | 2x RJ45, integrated switch |
| Protocol | PROFINET IO Device as defined in IEC 61158-6-10 |
| Transmission rate | 100 Mbit/s full duplex |
| I/O image size | Up to 1024 Byte of input and output data |
| Number of configurable slots | 100 |
| Features | PROFINET Conformance Class B, media redundancy (MRP-Client), |
automatic addressing, Topology detection (LLDP, DCP), diagnosis alarms
MQTT interface (X2)|
Connection| 2x RJ45, integrated switch
Protocol| MQTT V3.1.1 & MQTT V5
Transmission rate| 10/100 Mbit/s, full-/half duplex
Status indicator| 9 LEDs function status, 8 LEDs Ethernet-status
Voltage supply| DC 24 V (18 – 28 V DC)
Current draw| max. 210mA
Power dissipation| max. 5 W
Dimensions (D x W x H)| 35 x 58 x 72 mm
Weight| approx. 135 g
Certifications| PROFINET Conformance Class B
Ambient conditions|
Ambient temperature| 0° C to 60° C
Transport and storage temperature| -20° C to 80° C
Protection rating| IP 20
Relative humidity| 95% non-condensing
Mounting position| any
LED status information
| X1 PROFINET (left side) | X2 MQTT network (right side) |
|---|
SF (red)
Off| Configuration correct| Configuration correct
On| PROFINET diagnostic alarm pending| PROFINET side not configured or failed
Flashing| PROFINET function “LED flashing” for finding the device is executed|
–
BF (red)
Off| Connection to PROFINET controller is established| MQTT broker connection
is active
On
| The device has no configuration, the PROFINET
device name is incorrect, or there is no connection with the PROFINET controller
|
No connection to the MQTT broker can be established
Flashing| PROFINET function “LED flashing” for finding the device is executed|
–
MT (yellow)
Flashing| A firmware update is being carried out| A firmware update is being
carried out
Flashing with SF and BF| PROFINET function “LED flashing” for finding the
device is being carried out| –
PWR (green)
On| PS1 Power supply present| PS2 Power supply present
RUN (green)
Off| Firmware or device defective. Please contact Support
On| The device is ready to operate
RJ45 LEDs| X1 P1/P2 und X2 P1/P2
Green (Link)| Connected
Orange (Act)| Data transfer at the port active
The contents of this Quick Start Guide have been checked by us so as to ensure that they match the hardware and software described. However, we assume no liability for any existing differences, as these cannot be fully ruled out. The information in this Quick Start Guide is, however, updated on a regular basis. When using your purchased products, please make sure to use the latest version of this Quick Start Guide, which can be viewed and downloaded on the Internet from www.helmholz.de.Our products contain open source software, among others. This software is subject to the respectively relevant license conditions. We can send you the corresponding license conditions, including a copy of the complete license text together with the product. They are also provided in our download area of the respective products under www.helmholz.de. We also offer to send you or any third party the complete corresponding source text of the respective open source software for an at-cost fee of 10.00 Euro as a DVD upon request. This offer is valid for a period of three years, starting from the date of product delivery. Our customers are important to us, we are happy to receive suggestions and ideas for improvement. If you have any questions regarding the use of the product, please contact Helmholz Support by phone or send an e-mail to support@helmholz.de. All trademarks shown or mentioned in this document are the property of their respective owners or manufacturers. The representation and naming serve exclusively to explain the use and setting options of the products documented here.