Push Agent¶

Push agent allows sending data from a Data logger to the Cloud. This script periodically acquires data from a Data logger and sends it to the Cloud encapsulated in a JSON. The Push agent implements the Store&Forward mechanism that acquires data from a Data logger and saves it in a auxiliary store from which the data is extracted and sent to the Cloud.

The script supports two transfer modes:

By line: send one line of the Data logger per packet
By variable: send one or more variables with their related information. If the selected mode of the Data logger is Value change (the sampled values are changed only if one of the monitored variables changes) the Push agent sends the values of a certain variable only if it differs from its previous sent value.

Furthermore, it is possibile to set the mode used to send historicize data in the Data logger in addition to how they are sent to the cloud. If you do not want data to be historicized, they will be removed once the are fetched.

SETUP

This script uses the following libraries:

M2MQTT
NewtonSoft.Json

Once the libraries are installed from NuGet, import them in your project by following these steps:

Open the NetLogic
Click on the project’s .csproj file
Modify it by adding <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies> after <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
Build the project

If you want secure communication, the following items are required:

The CA certificate in .pem format. The following command generates the certificate in the desired format:
```
$ openssl x509 -inform DER -outform PEM -in certificate.crt -out certificate.pem
```
The client certificate generated by a CA. The format is .pfx and it can be generated using the following command:
```
$ openssl pkcs12 -export -out YOURPFXFILE.pfx -inkey *****-private.pem.key -in *****-certificate.pem.crt
```

Configuration Parameters

DataLogger: reference to the Data logger instance
PushFullSample: if the value is True then the transfer mode per line is activated otherwise the transfer mode per variable is activated
PreserveData loggerHistory: if the value is True then in addition to sending the data is also active the historicization otherwise every time the data is transferred to the auxiliary Store it is deleted from the Data logger
MaximumStoreCapacity: indicates the maximum capacity of the auxiliary store used by the PushAgent
MaximumRecordsPerPacket: the number of records encapsulated in a packet. In case of a by line transfer mode, currently only one line per packet is sent
MaximumPublishTime: maximum time interval after which data is taken from the auxiliary Store and sent to the Cloud. This interval is used when there are at most MaximumRecordsPerPacket records in the auxiliary Store
MinimumPublishTime: minimum time interval after which data is taken from the auxiliary Store and sent to the Cloud. This interval is used when there are at least MaximumRecordsPerPacket records in the auxiliary Store and consequently you want to increase the sending frequency to download the queue of the Store
ClientId: the Id of the client that has to send the data
BrokerIPAddress: contains the address of the BrokerIPAddress
BrokerPort: Broker port (8883 if you want to communicate via SSL)
BrokerTopic: name of the topic you want to publish on
QoS: Quality Of Service used to send information. The possible values are:
- 0: AT_MOST_ONCE
- 1: AT_LEAST_ONCE
- 2: EXACTLY_ONCE
UseSSL: enables/disables secure communication
- CACert: the path to the file containing the CA (must be in a .pem format)
- ClientCert: il percorso che contiene il certificato del Client (deve essere in formato .pfx)
- ClientCertPassword: the password of the Client certificate
Username: contains username for an authenticated communication with the Broker
Password: contains the password for authenticated communication with the Broker

Once the Data logger and the Push agent are configured, it is possible test sending data to the cloud using MQTT.

Example configuration of Eclipse Mosquitto

Some valid configurations to communicate with the Broker using the different supported modes:

Anonymous:
- ClientId: testId
- BrokerIPAddress: 127.0.0.1
- BrokerPort: 1883
- BrokerTopic: my_custom_topic
- QoS: 2
- UseSSL: false
- Username:
- Password:
Authenticated:
- ClientId: testId
- BrokerIPAddress: 127.0.0.1
- BrokerPort: 1883
- BrokerTopic: my_custom_topic
- QoS: 2
- UseSSL: false
- Username: pippo
- Password: pluto
Secured:
- ClientId: testId
- BrokerIPAddress: 127.0.0.1
- BrokerPort: 8883
- BrokerTopic: my_custom_topic
- QoS: 2
- UseSSL: true
  - CACert: path/to/certificate/CA
  - ClientCert: path/to/client/certificate/
  - ClientCertPassword:clientCertificatePassword
- Username: pippo
- Password: pluto

Example configuration of Azure IoT Hub

Una configurazione valida per l’invio e ricezione dati con IoT Hub è la seguente:

ClientId: MyDevice01
BrokerIPAddress: contoso.azure-devices.net
BrokerPort: 8883
BrokerTopic: devices/MyDevice01/messages/event/
QoS:1
- Iot Hub does not support level 2 QoS. In case a level 2 QoS is used, IoT Hub closes the connection every time a message is sent.
UseSSL: true
- CACert:
- ClientCert:
- ClientCertPassword:
Username: contoso.azure-devices.net/MyDevice01/?api-version=2018-06-30
Password: SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}

Example configuration of Subscriber

Il Push agent include tutta la parte relativa all’invio dei dati sul cloud; tuttavia, c’è anche la possibilità di ricevere i dati dal cloud configurando correttamente la parte di Subscribe.

La ricezione viene gestita da una funzione custom che viene richiamata ad ogni ricezione del messaggio. La funzione riceve il messaggio e lo elabora in base alla logica definita nella funzione. Un esempio di funzione che elabora un messaggio ricevuto aggiornando il valore di una variable Message è illustrato di seguito:

private void SubscribeClientMqttMsgPublishReceived(object sender, MqttMsgPublishEventArgs e)
{
   var messageVariable = Project.Current.GetVariable("Model/Message");
   messageVariable.Value = "Message received: " + System.Text.Encoding.UTF8.GetString(e.Message);
}

This function is passed as a configuration parameter of the Subscriber. The configuration of the subscriber method is done in the Start() method in addition to the base configuration of the Publisher:

public void Start()
{
   // PushAgent Default configuration

   // Add subscriber
   mqttClientConnector.AddSubscriber("my_custom_subscriber_topic", 1, SubscribeClientMqttMsgPublishReceived);
}

Push agent example

L’esempio mostra le principali funzionalità del Push agent. L’interfaccia grafica contiene una griglia di dati che illustra i campioni rilevati dal Data logger in base alla modalità selezionata, che può essere cambiata nel menù a tendina.

In prosimità alla griglia dati troviamo il pulsante Refresh che aggiorna la griglia e il pulsante Log che inserisce nel Data logger una riga con i valori delle variabili campionate. In questo esempio le variabili monitorate sono 5 ed ognuna di queste è stata configurata per mostrare le varie modalità supportate dal Data logger.

Nella parte inferiore dell’interfaccia è possibile modificare i parametri di configurazione delle variabili monitorate e del Data logger. Per inviare i dati sul cloud è necessario configurare tutti i parametri relativi al broker.

A titolo di esempio è stata inserita un configurazione che si collega ad un broker Mosquitto in locale. I dati inviati possono essere visualizzati da un qualsiasi Subscriber, ad esempio utilizzando il programma MQTT.fx.

Scarica il progetto di esempio da qui.