search

br-automation-com / paho.mqtt.c-ar

MQTT Client for Automation Runtime based on eclipse/paho.mqtt.c
21 stars 7 forks source link

readme

paho.mqtt.c-ar

MQTT Client Library for Automation Runtime based on eclipse/paho.mqtt.c

Introduction

This repository includes compiled binary MQTT client libraries for Automation Runtime. The libraries are based on

The libraries come in two different forms

Version Information

The libraries have been built for following runtime versions:

These version have no strict dependency on that very AR version, but you should try to use a Library version as close to the AR version as possible.

Releases

Using IotMqtt

The IotMqtt library enables simple usage within IEC programs. It consists on 3 different types of Function Blocks:

Every time a new connection with a MQTT broker is desired, an IotMqttClient FUB must be used. Then, depending on the pubish/subscribe needs, it is possible to associate from 0 to 50 IotMqttPublish or IotMqttSubscribe FUBs. IotMqttRegParPublish and IotMqttRegParSubscribe also count as IotMqttPublish or IotMqttSubscribe

Here are some simple samples. Before running them, it is important to change the ClientID parameter to a customized one, since the ClientID must be unique in the broker.

It is possible to use more than one client, just declare a new IotMqttLink variable, a new parameters variable and associate them with a new IotMqttClient FUB.

Network parameters

File Devices and Certificates

Some MQTT connections will need to use certificates. They can be stored in the project's certificate store or in a user defined File Device.

Depending where they are, we will need to add a prefix to the certificate name in the program. When using the certificate store we will use the following prefixes depending on which container they are:

In case the certificates are stored in the file system, then the prefix is the name of the file device. E.g.

If the certificate is stored in the default file device, it's not needed to write the file device as prefix.

Logfiles

IotMqtt is able to generate log files to help us diagnose connections or simply keep a register of connection errors. For this functionality, it will use the File Device IOTMQTT as default, that the user needs to prepare in the CPU configuration, in the project.

Using the function IotMqttConfig in the _INIT part of the client program, it is possible to change the default File Device as well as choosing the log level (verbosity), the name of the output file and if we also want log messages to be written in the logger.

This function will only make an effect the first time is called, so it is not possible to adjust those parameters on runtime.

Persistence

Messages sent or received with QoS (Quality of Service) > 0 have the possibility of being stored in the PLC's flash memory or CF until they have been correctly processed. This will keep messages alive in case of network problems, getting rid of them just when a confirmation of delivery has arrived.

To use this feature it must be enabled in the client parameters structure. It will use the file device IOTMQTT as default but it can be changed with the function IotMqttConfig

Samples

Additionally to the Publish and Subscribe samples shown above, more samples are provided inside the Samples directory. There you will find programs the following samples:

Using PahoMQTT

As mentioned in the Introduction, only use PahoMQTT directly in special circumstances, for legacy reasons or when you need to access the C-API of the paho.mqtt.c directly. For any other use cases, or new projects, refer to the IotMqtt instead.

Include Directories

In order to find the headerfiles, set the following Additional Include Directory in the Build Options of your configuration (Under Project/Change Runtime Versions..)

Static Linking

The PahoMQTT only comes as a static archive, meaning you need to link you task towards the archive files in the SG4 or SG4/Arm directory of the PahoMQTT library.

Further, and very important is that you cannot assign the library to a CPU, as it contains no .br file. Therefore remove it from your CPU configuration if it showed up there, you link directly to the archive file instead.

Archive File Directories:

Library Archive Files (order of the files is important):

File Devices

Specify a File Device called CERTS under CPU Configuration to a Folder that is accesible from AR.

Compatibility with older PahoMQTT versions

As mentioned in the introduction, the PahoMQTT library offers basic compatibility with older versions of the library. A benefit with the new version, additional to being built on new paho and openssl sources, is that it also runs on ArSim. Please see the chapter above (Using PahoMQTT) for basic settings that need to be made when using PahoMQTT. Four double checking your code, you can find a "converted version" of the SampleParam task under LegacySamples.

Function Blocks

As the libary only comes as an archive, the PahoMQTT_Cyclic and PahoMQTT_Init cannot be declared inside the .var file anymore and need to be declared inside the c-code. Further, the PahoMQTT.h is not part of the <AsDefaults.h> but need to be specifically included.

If not already set, you need to Enable declaration of PLC variables (_GLOBAL, _LOCAL) in the Project/Settings.

Example:

#include <bur/plctypes.h>
#include "PahoMQTT.h"

#ifdef _DEFAULT_INCLUDES
    #include <AsDefault.h>
#endif

void sample(unsigned long param_adr);

_LOCAL PahoMQTT_Init_typ PahoMQTT_Init_0;
_LOCAL PahoMQTT_Cyclic_typ PahoMQTT_Cyclic_0;

File Devices and Certificates

File devices work in the same way as for IotMqtt, with the difference that the former CERTS filedevice is used as a default file device, to maintain compatibility with the former PahoMQTT. If you need to access files from other devices, you should use //DEVICENAME/path/filename.ext.

Logging

If the Logger is activated, the output is no longer directed to the AR logger, but placed inside a PahoMQTTLog.txt located under the CERTS filedevice. This logfile uses the standard Paho output file format, and has unix lineendings (LF instead of CRLF). Therefore open the logfile in an editor that can understand that format, like Notepad++.

If you dont see any logging, even though you have set a high log level, it is probably because you set the loglevel before starting the asynchronous thread, meaning it was started Suspended. In that case, trigger the activation of the log by changing the PahoMQTT_Cyclic_0.LogLevel. Anything above 0 (for example: 1) will activate the PROTOCOL log. If you really have some debugging issues with your solution and you dont know what is going on, you can activate the trace log to see which Paho functions are being called by setting the loglevel to 10, but only do this if youre in trouble - its very verbose.

Example of the PahoMQTTLog.txt on LogLevel 1

=========================================================
               Trace Output
=========================================================
=========================================================
                Trace Output
Product name: Eclipse Paho Synchronous MQTT C Client Library
Version: 1.3.5
Build level: 2020-09-15 21:58
OpenSSL version: OpenSSL 1.1.1g  21 Apr 2020
OpenSSL flags: -DBR_AUTOMATION_RUNTIME
OpenSSL build timestamp: 2020-09-01
OpenSSL platform: BR_AUTOMATIONRUNTIME
OpenSSL directory: OPENSSLDIR: "//OSSLROOT"
=========================================================
20201001 114500.061 2176 SamplePara -> PUBLISH msgid: 100 qos: 1 retained: 0 rc 0 payload len(18): Hello World plain!
20201001 114500.061 2176 SamplePara <- PUBACK msgid: 100
20201001 114500.361 2176 SamplePara -> PUBLISH msgid: 101 qos: 1 retained: 0 rc 0 payload len(18): Hello World plain!
20201001 114500.361 2176 SamplePara <- PUBACK msgid: 101
20201001 114500.681 2176 SamplePara -> PUBLISH msgid: 102 qos: 1 retained: 0 rc 0 payload len(18): Hello World plain!
20201001 114500.681 2176 SamplePara <- PUBACK msgid: 102
20201001 114500.981 2176 SamplePara -> PUBLISH msgid: 103 qos: 1 retained: 0 rc 0 payload len(18): Hello World plain!
20201001 114500.981 2176 SamplePara <- PUBACK msgid: 103

The former PahoMQTT also contained basic Log functionality which has been removed completely. If you need to fill anything into the Paho logfile alongside other loggings as you might previosly have done using the PahoLog.. functions, simply use printf.

Example:

printf("here is my result:%i\n", res);