AWS IoT Device SDK C  202011.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.

It is required to setup an AWS account and access the AWS IoT Console for running demos and tests. Follow the links to:

  • Setup an AWS account.

  • Sign-in to the AWS IoT Console after setting up the AWS account.

    Note: If using the Provisioning library, a fleet provisioning template, a provisioning claim, IoT policies and IAM policies need to be setup for the AWS account. Complete the steps to setup your device and AWS IoT account outlined here.*

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 (or Provisioning Claim for Fleet Provisioning) in AWS IoT Account Setup.
    • Set CLIENT_CERT_PATH to the path of the client certificate downloaded when setting up the device certificate (or Provisioning Claim for Fleet Provisioning) in AWS IoT Account Setup.
    • Set CLIENT_PRIVATE_KEY_PATH to the path of the private key downloaded when setting up the device certificate (or Provisioning Claim for Fleet Provisioning) 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.

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.

    docker pull eclipse-mosquitto:latest

  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:latest

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