2023.1.1344.2 MQTT
- Bas Botermans
Overview
This feature is used to make an MQTT connection between Prespective(acts as a client) and an external MQTT server to transport messages via a publish/subscribe messaging architecture.
Architectural view of MQTT.
Ref: What is MQTT and How It Works | Random Nerd Tutorials
Where to find
The feature can be found under Prespective Menu > Logic > Add Logic Simulator > Adapter Settings > Adapter Target > MQTT
Feature Layout
The image below shows the complete feature layout of the MQTT Adapter.
Gateway settings |
|
|---|---|
Adapter Target | Select a different adapter, please see respective documentation for more information |
Adapter Setting (MQTTServerSettings) |
|
IP Address | The address of the MQTT broker. This can be a be in IPv4 address or a hostname like localhost |
Port | The port on which the MQTT broker is running, |
use TLS | Should be turned on when the broker is using TLS authentication. (off by default) Default port for MQTT over TLS is 8883, please check your broker for the correct port |
Username | Is passed to the server for authentication if the field is not empty (not used by default) |
Password | Is passed to the server for authentication when the UserName field is not empty (not used by default) |
QoS | (Quality Of Server) is an agreement between the broker and client that defines the guarantee of delivering a message: 0 : At most once => There is acknowledgement between broker and client other than regular TCP , fast, unreliable (packet loss)) 1 : At least once => The sender buffers the value until a ‘PUBACK’ is returned by the broker. Message can be sent multiple times (, slower, reliable) 2 : Exactly once => The sender sends the message, the broker returns a ‘PUBREC’. The sender is returning a ‘PUBREL’ and the server again returns a ‘PUBCOMP’ command to finalize the sending process. (slow, very reliable) See below for more detail. |
Protocol Version | This field determines the version of the MQTT protocol used. |
Content Life Cycle Settings | Not implemented for MQTT |
QoS (Quality of Server) - Detailed agreements
QoS | known as | speed | reliability | remarks |
|---|---|---|---|---|
0 | fire & forget | fast | poor | Messages can get lost in unstable connections. Very suitable for wires local connection |
1 | single handshake | slower | good | No message is lost. Can lead to duplicate messages, but is much faster than QoS 2 |
2 | double handshake | slowest | exact | If getting the message exactly once is more important than performance. Quite an overhead compared to the other 2 levels |
How to use
Step 1
Start the MQTT Server (in this case mosquitto) and optionally another MQTT client (in this case mqtt.fx) for testing. This can also be your own MQTT enabled application.
Step 2
Add the Prelogic Simulator to your Unity scene and set the Adapter Target to MQTT
Step 3
Set up the naming convention and the MQTT adapter settings according to the user’s choice.
Step 4
a) Create a MQTTSignalDefinition.cs script that derives from the Prelogic Component and contains all the input and output signal definitions
a.) Create an empty game object and add to it the created MQTT signal definition script.
b.) Make the game object a child to the Prelogic Simulator and then export the policy.
The PreLogic MQTT client can now subscribe and publish values to signals defined in the MQTT Signal Definition Script.
Prerequisites for MQTT
MQTT can work with an online broker, but is more commonly used with a local broker. There are a lot of brokers available. An overview can be found at: Comparison of MQTT implementations
ActiveMQ also has an MQTT broker when installed, but feel free to choose one to your liking.
For testing purposes we recommend using a client like i.e. MQTT.fx https://mqttfx.jensd.de/
Used Protocol
To communicate with the MQTT adapter in Prespective you need to apply the following protocol:
The structure for the message is:
<PLCADDRESS/<VALUE>
Topic to write is the address defined by the PLC address in the signal naming
Value is the value that is within the range of the specified type
Supported Types
BOOL
BYTE
BYTEARRAY
SBYTE
WORD
DWORD
SHORT
USHORT
INT16
UINT16
INT32
UINT32
INT64
UINT64
REAL32
REAL64
STRING
STRUCT
Naming Rules
Setting up the component works as like any other PreLogic component. The thing you have to take into account is how the PLC Address Path Format (or implicit naming rule) is configured. The output of this Address is the topic to which the component is reading and/or writing.
WARNING : < Make sure both paths are unique >
Each defined input writes the value to the PLC address path topic.
Each defined output reads the value from the PLC address path topic.
The PLC path separator has to be '/'
< Spaces are allowed but not recommended >
A leading '/' is not recommended because it leads to an extra parent topic with id 0.
For an overview of all variables for signal naming, please go to the PreLogic component page.
Prespective Documentation