AWS IoT Device SDK C  202108.00
SDK for connecting to AWS IoT from a device using embedded C.
Building and Running Demos

Instructions for building and running demos.

The libraries in this SDK are not dependent on any operating systems. However, the demos for the libraries in this SDK are built and tested on a Linux platform. This SDK builds with CMake, a cross-platform build tool.

Prerequisites

Prerequisites needed to run the demos.

Precondition
  • CMake 3.2.0 or later and a C90 compiler.
  • A supported operating system. The ports provided with this repo are expected to work with all recent versions of the following operating systems, although we cannot guarantee the behavior on all systems.
    • Linux system with POSIX sockets and timer APIs. (CI tests on Ubuntu 18.04).
      • On Linux systems, installation of OpenSSL development libraries and header files, version 1.1.0 or later, are required. The OpenSSL development libraries are usually called something like libssl-dev or openssl-devel when installed through a package manager.
      • Although not a part of the C90 standard, stdint.h is required for fixed-width integer types (e.g int32_t).

AWS IoT Account Setup

Setting up AWS IoT to run demos.

You need to setup an AWS account and access the AWS IoT console for running the AWS IoT Device Shadow library, AWS IoT Device Defender library, AWS IoT Jobs library, AWS IoT OTA library and coreHTTP S3 download demos. Also, the AWS account can be used for running the MQTT mutual auth demo against AWS IoT broker. Note that running the AWS IoT Device Defender, AWS IoT Jobs and AWS IoT Device Shadow library demos require the setup of a Thing resource for the device running the demo.

Configuring the Mutual Auth Demo

Passing configuration settings to run the mutual auth demo.

  • You can pass the following configuration settings as command line options in order to run the mutual auth demos:
    cmake .. -DAWS_IOT_ENDPOINT="aws-iot-endpoint" -DROOT_CA_CERT_PATH="root-ca-path" -DCLIENT_CERT_PATH="certificate-path" -DCLIENT_PRIVATE_KEY_PATH="private-key-path"
  • In order to set these configurations manually, edit demo_config.h in demos/mqtt/mqtt_demo_mutual_auth/ to #define the following:
    • Set AWS_IOT_ENDPOINT to your custom endpoint. This is found on the Settings page of the AWS IoT Console and has a format of ABCDEFG1234567.iot.us-east-2.amazonaws.com.
    • Set ROOT_CA_CERT_PATH to the path of the root CA certificate downloaded when setting up the device certificate in AWS IoT Account Setup.
    • Set CLIENT_CERT_PATH to the path of the client certificate downloaded when setting up the device certificate in AWS IoT Account Setup.
    • Set CLIENT_PRIVATE_KEY_PATH to the path of the private key downloaded when setting up the device certificate in AWS IoT Account Setup.

Configuring the HTTP S3 Demos

Generating pre-signed URLs and passing configuration settings to run the S3 upload, download, and multi-threaded download demos.

The S3 upload, download, and multi-threaded download demos require user-generated pre-signed URLs to be configured. A python script presigned_url_gen.py (located in demos/http/common/src/) is provided to easily generate pre-signed PUT and GET URLs.

Using the Pre-signed URL Generator

Dependencies

  • Python 3+
  • boto3
  • argparse

Pre-requisites

  1. Install the dependencies.

    pip install boto3 argparse

  2. You will need an AWS Account with S3 access before beginning. You must install and configure the AWS CLI in order to use this script.
    aws configure

Usage

  1. Run presigned_url_gen.py with your S3 bucket-name, S3 object-key, and optionally, your S3 bucket's region-name (if not specified, the region configured in AWS CLI will be used).

    python presigned_urls_gen.py --bucket <YOUR BUCKET NAME> --key <YOUR OBJECT KEY> --region <YOUR BUCKET'S REGION NAME>

    An example expected output:

    #define S3_PRESIGNED_GET_URL "https://aws-s3-endpoint/object-key.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ABABABABABABABABABAB%2F20201027%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20201027T194726Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=SomeHash12345UrlABcdEFgfIjK"
    #define S3_PRESIGNED_PUT_URL "https://aws-s3-endpoint/object-key.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ABABABABABABABABABAB%2F20201027%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20201027T194726Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=SomeHash12345UrlLMnmOPqrStUvW"

  2. Copy and paste the output into demo_config.h for macro S3_PRESIGNED_GET_URL and S3_PRESIGNED_PUT_URL.

    #define S3_PRESIGNED_GET_URL "https://aws-s3-endpoint/object-key.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ABABABABABABABABABAB%2F20201027%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20201027T194726Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=SomeHash12345UrlABcdEFgfIjK"
    #define S3_PRESIGNED_PUT_URL "https://aws-s3-endpoint/object-key.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ABABABABABABABABABAB%2F20201027%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20201027T194726Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=SomeHash12345UrlLMnmOPqrStUvW"

    You may also pass any or all of the following configuration settings as command line options in order to run the demos:

    cmake .. -DS3_PRESIGNED_GET_URL="your-get-url" -DS3_PRESIGNED_PUT_URL="your-put-url"

    Note: A pre-signed GET URL is required for all HTTP S3 demos. For upload demos, in addition to the GET URL, a pre-signed PUT URL is also required.

Parameter Info

  • --bucket : The name of the target S3 bucket used in the demos.
  • --key : The name of the existing object you wish to download (GET), or the name of the object you wish to upload (PUT).
  • --region : The name of the region in which your S3 bucket was created. If this is not passed in, the region configured in AWS CLI (or us-east-1, if not configured) will be used.

Configuring the Over-the-air Update Demos

Configurations and Prerequisites for the OTA Demo

Requirements for OTA demo

Prerequisites

  1. To perform a successful OTA update you would need to complete the prerequisites mentioned here: https://docs.aws.amazon.com/freertos/latest/userguide/ota-prereqs.html
  2. A code signing certificate is required to authenticate the update. A code signing certificate based on the SHA-256 ECDSA algorithm will work with the current demos. An example of how to generate this kind of certificate can be found here: https://docs.aws.amazon.com/freertos/latest/userguide/ota-code-sign-cert-esp.html

Configuration

You will need to specify the following parameters in the file demo_config.h (located in demos/ota/ota_demo_[mqtt/http]/)

  1. AWS_IOT_ENDPOINT: This is the endpoint for your account. The endpoint should be for the region that your thing was created in. This can be found by going to the AWS IoT Core console, pressing the “Settings” tab on the left hand side of the page. It is under the section labeled “Custom endpoint”.
  2. CLIENT_CERT_PATH: This is the client certificate that was downloaded when you created your thing. The path specified needs to be either an absolute path, or a path that is relative to the “cloned-repo-root-dir/build/bin" directory where the demo will be ran from.</li> <li> CLIENT_PRIVATE_KEY_PATH: This is the client private key that was downloaded when you created your thing. The path specified needs to be either an absolute path, or a path that is relative to the “cloned-repo-root-dir/build/bin" directory where the demo will be ran from.
  3. CLIENT_IDENTIFIER: This is the name of the thing you created during the OTA Prerequisites section.

An example expected output:

#define AWS_IOT_ENDPOINT "endpoint##-ats.iot.us-west-2.amazonaws.com"
#define CLIENT_CERT_PATH "/home/ubuntu/certificates/thing#-certificate.pem.crt"
#define CLIENT_PRIVATE_KEY_PATH "/home/ubuntu/certificates/thing#-private.pem.key"
#define CLIENT_IDENTIFIER "testclient"

Scheduling an OTA Update Job

After you build and run the initial executable you will have to create another executable and schedule an OTA update job with this image.

  1. Increase the version of the application by setting macro APP_VERSION_BUILD in demos/ota_demo_core_[mqtt/http]/demo_config.h to a different version than what is running.
  2. Rebuild the application using Build Steps from below into a different directory, say build-dir-2
  3. Rename the demo executable to reflect the change, e.g. mv ota_demo_core_mqtt ota_demo_core_mqtt2
  4. Create an OTA job:
    1. Go to the AWS IoT Core console console.aws.amazon.com/iot/ (https://console.aws.amazon.com/iot/)
    2. Manage → Jobs → Create → Create a FreeRTOS OTA update job → Select testclient from the thing list
    3. Sign a new firmware → Create a new profile → Select any SHA-ECDSA signing platform → Upload the code signing certificate(from prerequisites) and provide its path on the device.
    4. Select the image → Select the bucket you created in prerequisites → Upload the binary build-dir-2/bin/ota_demo2
    5. The path on device should be the complete path to place the executable and the binary name: eg /home/ubuntu/aws-iot-device-sdk-embedded-C-staging/build-dir/bin/ota_demo_core_mqtt2
    6. Select the IAM role created in prerequisites
    7. Create the Job
  5. Run the initial executable again with the following command: sudo ./ota_demo_core_mqtt or sudo ./ota_demo_core_http

Build Steps

How to build the demo applications on the command-line.

  • While in the root directory of AWS IoT Device SDK C, create a build directory, then change to that build directory.
    mkdir build && cd build
  • Run cmake while inside build directory.
    cmake ..
  • Run this command to build the demos.
    make

All demo executables can now be found in the build/bin directory and should be run while inside that directory.

Installing Docker Containers for Demos

Alternative option of using Docker containers for running demos locally.

Install Docker:

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

Installing Mosquitto Broker to run MQTT demos locally

The following instructions have been tested on an Ubuntu 18.04 environment with Docker and OpenSSL installed.

  1. Download the official Docker image for Mosquitto 1.6.14. This version is deliberately chosen so that the Docker container can load certificates from the host system. Any version after 1.6.14 will drop privileges as soon as the configuration file has been read (before TLS certificates are loaded).

    docker pull eclipse-mosquitto:1.6.14

  2. BROKER_ENDPOINT defined in demos/mqtt/mqtt_demo_basic_tls/demo_config.h can now be set to localhost.

  3. For TLS communication with Mosquitto broker, server and CA credentials need to be created. Use OpenSSL commands to generate the credentials for the Mosquitto server.

    • Generate CA key and certificate. Provide the Subject field information as appropriate.
      openssl req -x509 -nodes -sha256 -days 365 -newkey rsa:2048 -keyout ca.key -out ca.crt
    • Generate server key and certificate and sign with the CA cert.
      openssl req -nodes -sha256 -new -keyout server.key -out server.csr
      openssl x509 -req -sha256 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 365

  4. Create a mosquitto.conf file to use port 8883 (for TLS communication) and providing path to the generated credentials.

    port 8883
    cafile /mosquitto/config/ca.crt
    certfile /mosquitto/config/server.crt
    keyfile /mosquitto/config/server.key
    # Use this option for TLS mutual authentication (where client will provide CA signed certificate)
    #require_certificate true
    tls_version tlsv1.2
    #use_identity_as_username true

  5. Run the docker container from the local directory containing the generated credential and mosquitto.conf files.

    docker run -it -p 8883:8883 -v $(pwd):/mosquitto/config/ --name mosquitto-basic-tls eclipse-mosquitto:1.6.14

  6. Set ROOT_CA_CERT_PATH to the absolute path of the CA certificate created in step 3. for the local Mosquitto server.