Create an AWS IoT image | ConnectCore 8X

Digi Embedded Yocto provides integrated support for different AWS IoT components:

AWS Greengrass core. A recipe installs this software and allows you to configure the required parameters to build firmware ready for your core.
AWS IoT device SDK for embedded C. Several recipes build the libraries and some examples to help you test AWS IoT.

With Digi Embedded Yocto, you can:

Create an AWS IoT image. Build the dedicated AWS IoT image that Digi Embedded Yocto offers as a starting point to creating images with AWS IoT demo and Greengrass core software.
Or add AWS components to your own AWS Greengrass core software and your AWS IoT applications. See Add Greengrass to your image and Add an AWS IoT application to your image.

Build an AWS IoT image

Digi Embedded Yocto offers a recipe to build an AWS dedicated image called dey-image-aws. This image is based on core-image and includes:

Greengrass core. This software is configured to be launch at startup if the system is properly configured (such as certificate files and core software configuration).
AWS IoT examples. You can generate your own certificates and set the build system to include them in your image.

You can add more packages to this image editing your project’s conf/local.conf file.

To build the AWS IoT image:

1. Prepare Greengrass core requirements

The greengrass recipe in Digi Embedded Yocto installs the required software and configures the system to create a final image ready to run the Greengrass core software:

You must download the Greengrass core software and specify where Digi Embedded Yocto can find it in your PC.
Optionally, before building, you can create the required certificates and configure the required parameters in your project’s conf/local.conf file. Digi Embedded Yocto generates a completely functional image to program in your device so it performs as a Greengrass core just after booting.

You can provide the certificates and configure the Greengrass core software later at runtime.

Download the Greengrass core software

Download the AWS Greengrass core distributable:

Go to the AWS IoT console.
Select Software from the navigation pane.
In the AWS Greengrass Core Software section, click Configure download.
Select ARMv8 (AArch64) from the combo list and click Download.
Edit your conf/local.conf to specify where the tarball you have just downloaded is located in your file system:
```
GG_TARBALL_LOCAL_PATH = "/path/to/greengrass/core/tarball"
```

Generate the certificates for the Greengrass core software

The device running the Greengrass core software needs certificates to properly establish the connection with AWS IoT. You can generate these certificates beforehand so Digi Embedded Yocto adds them directly to the build image.

Digi Embedded Yocto provides tools to help you with the creation of certificates. The script dey-aws-tool.sh facilitates the certificates generation. It also registers the Greengrass core Thing in your AWS account if a name is provided:

Run the dey-aws-tool.sh script in meta-digi layer to generate the certificates.

~> <dey-install-dir>/sources/meta-digi/scripts/dey-aws-tool.sh --create-certs <path/to/store/core/certificates> --thing-name <core_thing_name>

<path/to/store/core/certificates> is the absolute path where the tool will generate the certificates.
<core_thing_name> is the name of the core thing. The tool will register it in your AWS account if it is not already registered.

The dey-aws-tool.sh tool requires the AWS Command Line Interface (CLI) to be installed and properly configured with your account credentials.

For example, for the output directory /home/user/my-certs and a Thing name my-core, the output will be similar to the following:

~> dey-aws-tool.sh --create-certs /home/user/my-certs --thing-name my-core
[INFO] Downloading AWS root CA certificate.
[INFO] Creating Greengrass Core CA certificate and key.
[INFO] Creating verification certificate.
[INFO] Creating Greengrass Core device certificate.
[INFO] Registering Greengrass Core Thing.

For Greengrass enabled images, add the following configuration to your project:

AWS_IOT_CERTS_DIR = "/home/user/my-certs"
AWS_GGCORE_IOT_HOST = "ABCDEFG1234567.iot.us-west-2.amazonaws.com"
AWS_GGCORE_THING_ARN = "arn:aws:iot:us-west-2:ABCDEFG1234567:thing/my-core"

Please verify variables' value is correct.

The certificates are generated inside the provided directory:

~> ls -l /home/user/my-certs/
total 40
-rw-rw-r-- 1 user user 1758 jun 20  2014 aws-root-ca.pem
-rw-rw-r-- 1 user user 1070 jun 29 14:36 gg-core.csr
-rw-rw-r-- 1 user user 1675 jun 29 14:36 gg-core.key
-rw-rw-r-- 1 user user 1330 jun 29 14:36 gg-core.pem
-rw-rw-r-- 1 user user 1679 jun 29 14:36 root-ca.key
-rw-rw-r-- 1 user user 1444 jun 29 14:36 root-ca.pem
-rw-rw-r-- 1 user user   17 jun 29 14:36 root-ca.srl
-rw-rw-r-- 1 user user 1123 jun 29 14:36 root-ca-verif.csr
-rw-rw-r-- 1 user user 1675 jun 29 14:36 root-ca-verif.key
-rw-rw-r-- 1 user user 1383 jun 29 14:36 root-ca-verif.pem

The certificates generated by the dey-aws-tool.sh script must be registered and attached to the thing representing your core in your account. For more information about AWS certificates, see the official AWS IoT documentation.

Configure the required Greengrass core parameters

You need to associate your physical device running AWS Greengrass core software with the AWS IoT thing you created for it when running the dey-aws-tool.sh script.

To do that, the Greengrass recipe includes some variables you can configure for your project. Edit your project’s conf/local.conf file and set the following parameters:

AWS_GGCORE_IOT_HOST: MQTT host or endpoint, similar to "ABCDEFG1234567.iot.us-west-2.amazonaws.com". You can get it from the Settings menu on the navigation bar of the AWS IoT Console.
AWS_GGCORE_THING_ARN: The Greengrass core thing ARN, a unique identifier assigned in the cloud to your AWS Greengrass core device.
AWS_IOT_CERTS_DIR: Absolute path of the certificates directory in your PC.

The value of these required parameters are provided by the output of the dey-aws-tool.sh. In the example above:

AWS_IOT_CERTS_DIR = "/home/user/my-certs"
AWS_GGCORE_IOT_HOST = "ABCDEFG1234567.iot.us-west-2.amazonaws.com"
AWS_GGCORE_THING_ARN = "arn:aws:iot:us-west-2:ABCDEFG1234567:thing/my-core"

If you changed the name of the certificates or used another method to generate them, set the value for the following variables in your project’s conf/local.conf file:

#
# Verisign root CA server certificate used to authenticate the AWS IoT server.
#
# https://www.symantec.com/content/en/us/enterprise/verisign/roots/VeriSign-Class%203-Public-Primary-Certification-Authority-G5.pem
#
AWS_GGCORE_ROOT_CA ?= "aws-root-ca.pem"

# Greengrass core device certificate
AWS_GGCORE_CERTIFICATE ?= "gg-core.pem"

# Greengrass core device private key
AWS_GGCORE_PRIVATE_KEY ?= "gg-core.key"

2. Prepare AWS IoT example requirements

Digi Embedded Yocto provides an IoT AWS device C SDK demo to monitor the CPU temperature and load and remotely switch a device LED on and off.

The awsiotsdk-demo_git.bb recipe in Digi Embedded Yocto installs the demo application and allows you to create a pre-configured image ready to connect to the AWS IoT platform.

Use the AWS IoT demo application code and the recipe as a reference to create your own AWS IoT applications.

Generate the certificates for the AWS IoT example

Before connecting to AWS IoT, you must generate the required X.509 certificates. Follow the steps in the AWS IoT documentation.

Configure the required AWS IoT parameters

Edit your project’s conf/local.conf file and set the following parameters:

AWS_IOT_MQTT_HOST: MQTT host or endpoint, similar to "ABCDEFG1234567.iot.us-west-2.amazonaws.com". You can obtain it from the Settings menu on the navigation bar of the AWS IoT Console.
AWS_IOT_MY_THING_NAME: Thing name that represents your device in your AWS IoT account.
AWS_IOT_CERTS_DIR: Absolute path of the certificates directory in your PC. It is the same variable used at Configure the required Greengrass core parameters.

You can also configure the names of the certificate files:
- AWS_IOT_ROOT_CA_FILENAME: Name of the Verisign root CA server certificate used to authenticate the AWS IoT server. By default, 'rootCA.crt'. You can download it from https://www.symantec.com/content/en/us/enterprise/verisign/roots/VeriSign-Class%203-Public-Primary-Certification-Authority-G5.pem.
- AWS_IOT_CERTIFICATE_FILENAME: The certificate attached to your thing. By default, 'cert.pem'.
- AWS_IOT_PRIVATE_KEY_FILENAME: The thing’s private key. By default, 'privkey.pem'.
  
  When building, these certificates are copied to the /etc/ssl/certs directory of the image.
- Inspect the rest of available variables in the aws-iot bbclass, and define in your local.conf those that need a different value for your setup.

For more information about AWS certificates, see the official AWS documentation.

3. Build your firmware

Once all these parameters are configured, you can yocto_t_create-build-projects.html to upgrade your device firmware.

~> bitbake dey-image-aws-swu

This generates the update package called dey-image-aws-swu-<platform>-<timestamp>.swu under <project>/tmp/deploy/images/<platform>.

To install the update package dey-image-aws-swu-<platform>-<timestamp>.swu in your device, see Program firmware from Linux.

Add Greengrass to your image

If you already have a recipe to generate your own image, you can also integrate the Greengrass core without modifying it from your project configuration:

Download Greengrass core software. See Download the Greengrass core software.
Add Greengrass core software package.

To create an image with the Greengrass core, you must add the greengrass package to your image.

Edit your project’s conf/local.conf file and add this package to the list of packages to install:
```
IMAGE_INSTALL_append = " greengrass"
```
Note the required white space when appending a value to an array variable using the _append override syntax.
Generate the certificates for the Greengrass core software. See Generate the certificates for the Greengrass core software.
Configure the Greengrass core required parameters. See Configure the required Greengrass core parameters.
Build your firmware as usual.

Add an AWS IoT application to your image

You can build your applications to connect to AWS IoT platform using the AWS IoT support already included in Digi Embedded Yocto. Use the AWS IoT demo code and its recipe as a reference to create your own AWS IoT applications and recipes. For more information on creating your AWS IoT application, see AWS IoT device SDK for embedded C.

Add your AWS IoT application package.

Edit your project’s conf/local.conf file and add the package to the list of packages to install. For example, to add the AWS IoT demo:
```
IMAGE_INSTALL_append = " awsiotsdk-demo"
```
Note the required white space when appending a value to an array variable using the _append override syntax.
Generate the certificates for the AWS IoT application. See Generate the certificates for the AWS IoT example.
Configure the required AWS IoT parameters. See Configure the required AWS IoT parameters.
Build your firmware as usual.