IotMqttSampleAwsIoT

Sample for MQTT communication with AWS IoT Core

This sample illustrates the communication with the AWS IoT Core message broker, which is part of the AWS IoT platform. The message broker requires authentication via a TLS client certificate. As a prerequisite for this, the corresponding certificate must have been created and be known and activated on the AWS IoT platform.

Initial setup of AWS IoT Core

Information on creating and registering client certificates and the initial setup of AWS IoT Core can be found in the official AWS IoT Core documentation. The certificate created and activated there is used by the MQTT function blocks to establish a connection with the message broker. Ensure that you have linked a valid AWS IoT policy with the certificate you created. Further information can be found in the following articles, which are part of the AWS IoT Core documentation:

AWS IoT Core Security and Identity

X.509 Certificates Authentication

Topic structure

The topic structure of the AWS IoT Core message broker is essentially freely selectable, although some restrictions apply. Certain system topics cannot be used. Please refer to the AWS IoT Core documentation for more information. We also recommend the AWS documentation on AWS IoT Core MQTT topic design.

QoS and Retain

AWS IoT Core currently does not support QoS 2 or Retain messages. To store persistent messages, additional services, such as AWS IoT Device Shadow or a database service, must be used.

AWS IoT Core Service Limits

When using AWS IoT Core, please also refer to the notes on AWS Service Limits.

In this sample, messages are sent to and received from the AWS IoT Core message broker. Since this sample is essentially based on the sample IotMqttSampleUsingQueue, only the parts that are relevant for establishing a connection to AWS IoT Core are explained in this section.

Parameters for establishing a connection

The following code snippet shows the parameters required for establishing a connection to AWS IoT Core. The parameters are essentially static parameters. These can also be specified in the declaration part during instantiation of the MQTT client.

The following information is required for establishing a connection to AWS IoT Core.

Parameter

Description

fbMqttClient.stTLS.sCA

Root CA certificate, which is regarded as trusted by the AWS IoT broker. If certificates generated by the AWS IoT platform are used (“one-click certificate”), the corresponding root certificate of AWS IoT can be used. It can be downloaded from the AWS IoT website when certificates are generated.

fbMqttClient.stTLS.sCert

Certificate of the “thing”, which is required as authentication for establishing a connection to AWS IoT. If the certificates generated by the AWS IoT platform are used (“one-click certificate”), this certificate can be downloaded from the AWS IoT website, once it has been generated.

fbMqttClient.stTLS.sKeyFile

Private key of the “thing”, which is required for securing the communication link. If the certificates generated by the AWS IoT platform are used (“one-click certificate”), the private key can be downloaded from the AWS IoT website, once it has been generated.

fbMqttClient.sHostname

FQDN of the AWS IoT broker instance

fbMqttClient.nHostPort

Since a connection to the AWS IoT broker can only be established via TLS, the default MQTT TLS port must be used here (8883).

fbMqttClient.sClientId

The MQTT client ID can be the same as the name of the "thing".

Exponential backoff

The use of an exponential backoff algorithm, as shown in the code snippet, is optional but recommended. See below.

 

IF bSetParameter THEN
  bSetParameter := FALSE;
  fbMqttClient.stTLS.sCA := 'c:\TwinCAT\3.1\Config\Certificates\root.pem';
  fbMqttClient.stTLS.sCert := 'c:\TwinCAT\3.1\Config\Certificates\7613eee18a-certificate.pem.crt';
  fbMqttClient.stTLS.sKeyFile := 'c:\TwinCAT\3.1\Config\Certificates\7613eee18a-private.pem.key';
  fbMqttClient.sHostName:= 'a35raby201xp77.iot.eu-west-1.amazonaws.com';
  fbMqttClient.nHostPort:= 8883;
  fbMqttClient.sClientId:= 'CX-12345';
  fbMqttClient.ipMessageQueue := fbMessageQueue;
  fbMqttClient.ActivateExponentialBackoff(T#1S, T#30S);
END_IF

Exponential backoff

A feature referred to as "exponential backoff" can be used to avoid burdening the message broker with unnecessary connection requests in case of a connection error. In the event of a TLS connection error involving the message broker, the reconnect rate is adjusted multiplicatively. This function can be activated using the ActivateExponentialBackoff() method. The parameters of the method specify the minimum and maximum time for the algorithm. The minimum time describes the initial delay value for the new connection attempt. The maximum time describes the highest delay value. The delay values are doubled until the maximum value is reached. Once a connection has been established, the backoff rate is reset to the original value. The DeactivateExponentialBackoff() method can be used to deactivate this function programmatically.

Device Shadow Service

The AWS IoT Device Shadow Service enables persistent storage of status information of a connected device. A separate shadow is managed for each device. The shadow of a device can be read and updated via MQTT. Certain system topics of the AWS IoT Core must be used for this purpose. For example, the following topic enables updating the shadow.

sTopicShadowUpdate : STRING(255) := '$$aws/things/CX-12345/shadow/update';

The message sent to this topic describes the new shadow of the device. It is specified in JSON notation and corresponds to a particular format, e.g.:

{
  "state": {
    "reported": {
      "Vendor": "Beckhoff Automation",
      "CpuTemperature": 42,
      "OperatingSystem": "Windows 10"
    }
  }
}

The PLC library Tc3_JsonXml can be used to create and adapt this format to suit your application.

In the PLC code provided here, the device shadow is updated once at the start of the sample and then on request (depending on the variable bUpdateShadow).

For more information about the AWS IoT Device Shadow Service and its topics and data formats see the AWS IoT Device Shadow Service documentation.

Requirements

Development environment

Target platform

PLC libraries to include

TwinCAT v3.1.4022.0

IPC or CX (x86, x64, ARM)

Tc3_IotBase,
Tc2_Utilities (>= v3.3.19.0)