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:

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_X.X.X.bb 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:

  1. You must download the Greengrass core software and specify where Digi Embedded Yocto can find it in your PC.
  2. 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.

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

1.1. Download the Greengrass core software

Download the AWS Greengrass core distributable:

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

1.2. 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:

  1. Source your project's dey-setup-environment script to set up the build environment.
    2. ~> source dey-setup-environment
  1. Launch the dey-aws-tool.sh script to generate the certificates.
    2. ~> 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.

    Note 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

Note 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 AWS IoT official documentation.

1.3. 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:

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"

Note 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 on/off a device LED.

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.

2.1. 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.

2.2. Configure the required AWS IoT parameters

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

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

3. Build your firmware

Once all these parameters are configured, you can create an update package 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 the firmware from Linux.