Example: Using the AWS IoT Core Client SL Library

Description

The AWS IoT Core Client SL Example.project example shows how to use the AWS IoT Core Client SL library.

The AWSDeviceShadow application shows how to write and read the "Device Shadow".

The AWSPubSub application shows how to use the included function blocks to publish and subscribe to messages.

The AWS_JSON_DeviceShadow application shows how to use the JSONBuilder to update the "Device Shadow".

Getting Started

Installing a client certificate

A client certificate is used to authenticate a device on AWS IoT Core. The client certificate can be generated via the AWS web interface, downloaded, and then installed on the corresponding device.

. There are two ways to generate this kind of certificate:

A CSR file (Certificate Signing Request) is generated on the controller. This file is then used to generate a certificate.
For instructions about how to do this, see the following section.
The certificate and private key are created, downloaded, and installed on the device via AWS.
For more information, see: Import of client certificates with private key

Creating the certificate with a CSR file

. Preparation

The CODESYS Security Agent package must be installed on your computer.
For more information, see: CODESYS Security Agent
You need an AWS account.

Procedure. Creating and importing a client certificate via CSR

Create a (Thing) device in AWS IoT Core via the web interface.
You can view and manage your (Things) devices in the navigation side panel under Manage > All Devices > Things.
In the sample project, open the AWSPubSub application.
Set the endpoint to the AWSIoTClient.sHostname input.
Example: xxxxxxxxxxxxxxx.iot.yyyyyyyy.amazonaws.com)
You can find your endpoints in the navigation side panel under Connect > Domain configurations. You can also create a new endpoint there if necessary.
Set the previously assigned device name ("Name of thing") to the AWSIoTClient.sClientId input.
Use the AWSIoTClient.sCertCNPrefix input if the ClientId is identical to the host name. This prevents loading an incorrect certificate (for example from WebServer).
Tip
If the input is not displayed, then execute the Reset Pins command.
Example:
sCertCNPrefix := 'AWSClient', sClientId := 'MyHostname';
The "Common Name" (CN) of the certificate is AWSClient@MyHostname
Download the application to the controller and start it.
The application will now try to establish an encrypted connection to AWS, but it will fail due to the missing certificate. Nevertheless, this setup experiment is relevant in the following.
Set the xEnable flag of the AWSIoTClient to TRUE.
In the device editor, select the PLC Shell tab.
Run the following command:
cert-getapplist
A component with the specified device name and number is displayed in the output.
Note: The device is not displayed if you have not previously attempted to establish a connection to AWS (Step 5).
Run the following command:
cert-createcsr <number> encoding=Base64
Replace <number> with the number obtained in Step 8. Generating the CSR file may take a few seconds.
In the device editor under the Log category, a corresponding message is output after generation.
In the device editor, select the Files tab.
Copy the CSR file from the cert/export directory to the local file system.
You can now use the generated CSR file to create a certificate via the AWS web interface.
You can access a management overview of all your certificates in the navigation side panel via Security > Certificates.
Use the Add certificate > Create certificate command to create a new certificate with the exported CSR file.
Download the certificate and the root certificate.
In CODESYS, click View → Security Screen menu command.
Under Own Certificates, install your client certificate.
Under Trusted Certificates, install the root certificate.
Click Online → Reset Cold and start the application.
A new connection attempt by the AWSIoTClient function block will now set the AWSIoTClient.xConnectedToBroker output to TRUE.
The connection is established successfully.

Important

When you uninstall a certificate created via CSR from a controller, it will no longer work if you reinstall it.

The reason for this is that information on the private key is removed during uninstallation, in which case you need to create a new certificate for the device.

System requirements and restrictions

Programming system	CODESYS Development System (version 3.5.18.0 or higher)
Runtime system	CODESYS Control Win (version 3.5.18.0 or higher) Note: Use the free `Device Reader` project (available in the CODESYS Store International) to find out the functions supported by the controller.
Add-on components	-
Additional requirements	AWS Account (AWS IoT Core)

Note

DOWNLOAD projects