aws_iot.c File Reference

Detailed Description

AWS IoT example to demonstrate connecting to AWS Shadow service and demonstrate a simple light bulb example.

Note

It is assumed that you have followed the steps in the Getting Started guide and are therefore familiar with how to build, flash, and monitor an application using the MM-IoT-SDK framework.

This example application demonstrates how to use AWS IoT Core services to connect to an AWS endpoint and use the shadow service to mirror the state of a light bulb shadow state maintained by AWS.

Getting Started

The following steps need to be done to run this application:

Sign in to the AWS IoT console

• Go to https://aws.amazon.com/ and click Sign in on the top right corner. If you don't already have an Amazon/AWS account, create one or contact your company IT department to create a company account for you.
• From the services menu on the top left select Internet of Things > IoT Core

Create a Thing

• On the left hand menu select Manage > All Devices > Things
• Click Create things
• Select Create single thing
• Click Next
• Enter a Thing name. You will need to remember this for name later.
• Select Unnamed shadow (classic)
• Enter the following as shadow statement:

  {
      "state": {
          "reported": {
              "powerOn": 0
          },
          "desired": {
              "powerOn": 0
          }
      }
  }

• Click Next
• Select Auto generate new certificates
• Click Next.
• Now create an "Allow All" policy if you do not already have one (you only need to do this once).
  • Click Create Policy (this will open a new tab)
  • Enter a policy name such as AllowAll
  • In the Builder tab, in Policy document enter the following data:

    Policy effect:   Allow
    Policy action:   *
    Policy resource: *

  • Click Create.
  • Return to the Attach policies to certificate tab in your browser
• Ensure the AllowAll policy is selected
• Click Create thing

Congratulations! Your device should now be created.

Download the certificates and key files and proceed to the next step. Specifically you will need the Device Certificate, Device Private Key amd the Amazon RSA Root Certificate.

Note

You can also create the Allow All policy on the AWS CLI using the following command:

aws iot create-policy \
   --policy-name="AllowAllDev" \
   --policy-document="{ \"Version\": \"1\", \
                        \"Statement\": [{ \
                             \"Effect\": \"Allow\", \
                             \"Action\": \"iot:*\", \
                             \"Resource\": \"*\" \
                      }]}"

Likewise, you can create all certificates in the AWS CLI. You may also use third party tools like openssh to create the device certificate and keys and upload them using AWS CLI.

We show creating certificates for a single thing using the AWS IoT console as this is the easiest way to test the application. This is however not a practical way to provision devices in the field. For production we recommend Just In Time Provisioning as documented here https://docs.aws.amazon.com/iot/latest/developerguide/jit-provisioning.html This method loads all devices with a common provisioning certificate, which then gets replaced with a unique device certificate when the device first connects to the AWS endpoint.

Install device certificates and keys

• In the credentials directory replace the files AmazonRootCA.pem, certificate.pem.crt, and private.pem.key with the files downloaded from AWS in the previous step. Rename the downloaded files to match the target file names. Note: Amazon provides you with 2 root CA files to download, please use the file named AmazonRootCA1.pem.
• Open the config.hjson file.
  • Update the value of aws.thingname with the name of the thing you created in the previous section.
  • Now, in AWS IoT console, navigate to Manage > All Devices > Things
    • Click on the thing you just created and then click on the "Device Shadows" tab.
    • Click on the "Classic Shadow". Then look at the "Device Shadow URL" in the "Device Shadow details" panel.
    • Update the value of aws.endpoint with the server name in the URL. Ensure you remove the https:// and everything after amazonaws.com
      • Alternatively, you can get the endpoint from the AWS CLI by typing in the following command:

        aws iot describe-endpoint

• Follow the Programming the config store from a host PC instructions to load the config.hjson file to the device.

  Note

  The default config store key names are defined in aws_iot_config.h. You may change these names as required for your application.

Running the application

• Now build and run the application.
• You should see the device connect to AWS IoT.
  • If you see connection failures ensure your access point forwards traffic to the Internet.
• Once the device is connected look for the state of the powerOn variable.
  • Initially it should be 0 signifying the lamp is OFF - in the ST Nucleo boards this is represented by the Blue LED which should be OFF.
• Now Open the AWS IoT console and click on the "MQTT Test client" from the left hand side menu.
  • Click on "Publish to a Topic" tab and enter the following topic:

    $aws/things/<your_thing_name>/shadow/update

    Naturally, replace "<your_thing_name>" with the name of the thing you created.
  • Enter the following JSON text in the "Message payload" section and click "Publish".

    {
       "state": {
           "desired": {
               "powerOn": 1
           }
       }
    }

• You should now see the LED turn ON and the value of powerOn parameter printed on the console output should change.

What is AWS Shadow?

AWS Shadow service allows us to cache the state of an IoT device on the cloud. This allows the IoT device to go to sleep and wake up once in a while to update its state on the cloud and act on pending state change requests on the cloud. For example a temperature sensor could periodically measure and update the temperature using the AWS Shadow service and go to sleep for minutes or even hours at a time while AWS Shadow caches this data and makes it available persistently to anyone who may be interested in the temperature even though the sensor is asleep and no longer reachable on the network.

Likewise, for a light bulb, AWS Shadow remembers the state of the light bulb even though the light bulb itself may have been unplugged and so not connected to the network. In fact the AWS Shadow can accept state change requests on behalf of the light bulb when it is unplugged and then convey the desired state to the light bulb when it connects again.

This is how it works:

• A device such as a light switch that desires to change the state of the light bulb publishes a message to the topic "$aws/things/<your_thing_name>/shadow/update"

  {
     "state": {
         "desired": {
             "powerOn": 1
         }
     }
  }

• If this is a change in state, then AWS Shadow will post a delta message to "$aws/things/<your_thing_name>/shadow/update/delta" as

  {
     "state": {
         "powerOn": 1
     }
  }

  • If the device is unplugged, then AWS Shadow will automatically send this message with the latest state when the device comes online next.
• Once the device receives this delta message and acts on it, it will then report its new state by publishing to: "$aws/things/<your_thing_name>/shadow/update"

  {
     "state": {
         "reported": {
             "powerOn": 1
         }
     }
  }

• If the state change was accepted, AWS Shadow will forward the above message to: "$aws/things/<your_thing_name>/shadow/update/accepted"
• If for some reason, the state change request was rejected by the device, then AWS Shadow will publish to "$aws/things/<your_thing_name>/shadow/update/rejected"

For more information see: https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html

Integrating with Alexa

Now that we have seen AWS Shadow being used to connect to and control our IoT device, how can we put this to practice with a real world application?

Amazon shows us how we can use Alexa to post messages to AWS IoT devices with an example smart hotel application: https://aws.amazon.com/blogs/iot/implement-a-connected-building-with-alexa-and-aws-iot/

In this example they show us how to create an Alexa skill that can post JSON messages to our IoT device using AWS Shadow. You can use the tutorial above to customize this application for your specific smart device needs.

Automation and Production

In the example above we used the AWS IoT console to create certificates and publish/subscribe to MQTT messages. While this may be convenient for development and testing, it is hardly a practical approach for real world applications. Luckily, we have options - Amazon provides us with the AWS CLI (Command Line Interface), which lets us do everything above using a command line interface such as creating certificates, registering devices, publishing and subscribing to MQTT messages. This allows us to automate and script production and registration of devices and even implement M2M communications using the MQTT publish/subscribe API. A full reference of the available commands is at: https://docs.aws.amazon.com/cli/latest/index.html

Fleet Provisioning

The steps above describe how to provision one device at a time for AWS IoT. This however is not practical when we have to provision thousands of devices in the field. Thankfully AWS provides a mechanism called Fleet Provisioning that allows us to automate this process.

For more information on Fleet Provisioning see: https://docs.aws.amazon.com/whitepapers/latest/device-manufacturing-provisioning/provisioning-identity-in-aws-iot-core-for-device-connections.html

There are multiple mechanisms of implementing Fleet Provisioning - we have implemented the Fleet Provisioning by claim mechanism. In this mechanism a batch of devices (say 1000) will be loaded with a shared claim certificate and keys. The device will make first contact with the AWS endpoint using this shared certificate and key just as it would with regular device certificates and keys. The device then generates a new set of keys and sends the certificate to AWS for signing. AWS signs the certificate and assigns the device a new thing name based on the provisioning template - the provisioning template may specify the thing name is an amalgam of the device serial number (in our case the MAC address) and some prefix. The device saves the signed certificate, generated keys and thing name and uses them for all connections henceforth.

Use the steps below to implement fleet provisioning. Alternatively, if you prefer to use the AWS command line, then all the steps below are described here for the command line: https://www.freertos.org/iot-fleet-provisioning/demo.html#setting-up

Prerequisites

Ensure you have the required permissions and roles to implement fleet provisioning. Your AWS administrator can setup the roles using the following commands on the AWS command line:

• Create FleetProvisioningRole role

  aws iam create-role --role-name "FleetProvisioningRole" --assume-role-policy-document \
      '{"Version":"2012-10-17","Statement":[{"Action":"sts:AssumeRole","Effect":"Allow", \
      "Principal":{"Service":"iot.amazonaws.com"}}]}'

• Attach AWSIoTThingsRegistration policy to the role

  aws iam attach-role-policy --role-name "FleetProvisioningDemoRole" \
      --policy-arn arn:aws:iam::aws:policy/service-role/AWSIoTThingsRegistration

• Create the AllowAll policy as described in Create a Thing

Create a thing type

• Open the AWS IoT console web page.
• Go to Manage > All Devices > Thing types
• Click Create thing type
• For this example, enter _fp_demo_things_ and click Create thing type
• If you change the name remember to update it in the JSON file in the step below.

Create a claim policy

• On the AWS IoT console go to Manage > Security > Policies
• Click Create policy and give it a suitable name
• In the Policy document section, click JSON and enter the code below (which can also be found in templates/fleet_provisioning_policy.json):

  {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "iot:Connect"
          ],
          "Resource": "*"
        },
        {
          "Effect": "Allow",
          "Action": [
            "iot:Publish",
            "iot:Receive"
          ],
          "Resource": [
            "arn:aws:iot:<AWS-REGION>:<AWS-ACCOUNT-ID>:topic/$aws/certificates/create-from-csr/*",
            "arn:aws:iot:<AWS-REGION>:<AWS-ACCOUNT-ID>:topic/$aws/provisioning-templates/FleetProvisioningTemplate/provision/*"
          ]
        },
        {
          "Effect": "Allow",
          "Action": "iot:Subscribe",
          "Resource": [
            "arn:aws:iot:<AWS-REGION>:<AWS-ACCOUNT-ID>:topicfilter/$aws/certificates/create-from-csr/*",
            "arn:aws:iot:<AWS-REGION>:<AWS-ACCOUNT-ID>:topicfilter/$aws/provisioning-templates/FleetProvisioningTemplate/provision/*"
          ]
        }
      ]
    }

  Replace <aws-region> and <aws-account-id> as appropriate for your AWS account. Ensure you replace _FleetProvisioningTemplate_ with the name of the template you specified in Create provisioning template. Set the aws.provisioningtemplate key to the provisioning template name you specified here.

Create provisioning template

• On the AWS IoT console go to Connect > Connect many devices > Connect many devices
• Click Create provisioning template
• Select Provisioning devices with claim certificate then click Next
• Select Active, then enter a template name such as _FleetProvisioningTemplate_
• Select the provisioning role you created in the prerequisites step above. Ensure _Attach managed policy to IAM role_ is unchecked.
• Under Claim certificate policy select the claim certificate you created in above, Then click Next.
• In the next page select Don't use a pre-provisioning action, then click Next.
• In the next page click Next.
• Finally click Create template
• Then click on the newly created template, then click Edit JSON in the document section below. Enter the following JSON (which can also be found in templates/fleet_provisioning_template.json):

  {
      "Parameters": {
        "SerialNumber": {
          "Type": "String"
        },
        "AWS::IoT::Certificate::Id": {
          "Type": "String"
        }
      },
      "Resources": {
        "certificate": {
          "Properties": {
            "CertificateId": {
              "Ref": "AWS::IoT::Certificate::Id"
            },
            "Status": "Active"
          },
          "Type": "AWS::IoT::Certificate"
        },
        "policy": {
          "Properties": {
            "PolicyName": "AllowAll"
          },
          "Type": "AWS::IoT::Policy"
        },
        "thing": {
          "OverrideSettings": {
            "AttributePayload": "MERGE",
            "ThingGroups": "DO_NOTHING",
            "ThingTypeName": "REPLACE"
          },
          "Properties": {
            "AttributePayload": {},
            "ThingGroups": [],
            "ThingName": {
              "Fn::Join": [
                "",
                [
                  "fp_demo_",
                  {
                    "Ref": "SerialNumber"
                  }
                ]
              ]
            },
            "ThingTypeName": "fp_demo_things"
          },
          "Type": "AWS::IoT::Thing"
        }
      },
      "DeviceConfiguration": {
          "Foo": "Bar"
      }
    }

  Ensure _AllowAll_ matches the name of the AllowAll policy you created in the prerequisites. Ensure _fp_demo_things_ matches the thing type you created in Create a thing type
• Click Save as new version

Generate claim certificates and keys

• On the AWS IoT console go to Manage > Security > Certificates
• Click Add Certificate > Create Certificate
• On the next page download the private key, certificate and the root certificate.
• Use this certificate and key as the claim certificate for a batch of devices. You may create multiple certificates here, one for each batch.
• Select the certificate(s) you just created then click Attach policy and attach the claim policy you created earlier to all the claim certificates you generated now.

Setting up the device

• Once the above steps are done, load the claim certificate, private key and root certificate as described in Install device certificates and keys. The device will use these credentials for the initial connection and will be replaced by device certificate and keys provided by AWS when provisioning has successfully completed.
• Set the aws.provisioningtemplate key to the provisioning template name you set in Create provisioning template.
• Ensure the device has the necessary Wi-Fi credentials and country code.
• Power cycle the device, it should connect to AWS with the provided claim certificate. AWS will then sign the new certificate generated by the device and provide it with a Thing Name that the device will write to aws.thingname and atomically replace the claim credentials with the newly generated credentials.
• After reboot the device will connect with the newly assigned credentials and commence normal operation.

Note

If you want to provision the same device a second time, remember to delete the device from Manage > All devices > Things. Also note that the device overwrites the claim certificate and keys, so there are several options should you require to re-provision (for example if adding factory reset support):

• The application keeps a copy of the claim certificate and keys, then restores them on a factory reset and deletes the aws.thingname key. However, be aware that claim certificates are intended to be used temporarily and may expire or be revoked. So this method of re-provisioning may fail if the claim certificate is no longer valid.
• The application uses the existing device certificates as claim certificates to re-provision, provided the device policy includes permissions for the create-from-csr and provisioning-templates resources. In our case the AllowAll policy allows everything including these claim permissions. To re-provision, the application simply deletes the aws.thingname key to trigger the provisioning process. This method has the advantage of requiring less resources by not needing to keep a copy of the claim certificate and key which saves around 3KB of storage in persistent store.

Definition in file aws_iot.c.

#include <string.h>
#include "mmhal_app.h"
#include "mmosal.h"
#include "mmconfig.h"
#include "mm_app_loadconfig.h"
#include "mmipal.h"
#include "mqtt_agent_task.h"
#include "sntp_client.h"
#include "core_json.h"
#include "mm_app_common.h"
#include "aws_iot_config.h"

Include dependency graph for aws_iot.c:

Go to the source code of this file.

Macros
#define	NTP_MIN_TIMEOUT   3000
	Minimum NTP timeout per attempt. More...
#define	NTP_MIN_BACKOFF   60000
	We need to back-off at least 60 seconds or most NTP Servers will tell us to go away. More...
#define	NTP_MIN_BACKOFF_JITTER   3000
	Minimum back-off jitter per attempt. More...
#define	NTP_MAX_BACKOFF_JITTER   60000
	Maximum back-off jitter per attempt. More...
#define	SHADOW_PUBLISH_JSON
	Format string representing a Shadow document with a "reported" state. More...

Functions
void	app_init (void)
	Main entry point to the application. More...

Macro Definition Documentation

NTP_MAX_BACKOFF_JITTER

#define NTP_MAX_BACKOFF_JITTER   60000

Maximum back-off jitter per attempt.

Definition at line 386 of file aws_iot.c.

NTP_MIN_BACKOFF

#define NTP_MIN_BACKOFF   60000

We need to back-off at least 60 seconds or most NTP Servers will tell us to go away.

Definition at line 382 of file aws_iot.c.

NTP_MIN_BACKOFF_JITTER

#define NTP_MIN_BACKOFF_JITTER   3000

Minimum back-off jitter per attempt.

Definition at line 384 of file aws_iot.c.

NTP_MIN_TIMEOUT

#define NTP_MIN_TIMEOUT   3000

Minimum NTP timeout per attempt.

Definition at line 380 of file aws_iot.c.

SHADOW_PUBLISH_JSON

#define SHADOW_PUBLISH_JSON

Value:

    "{"                         \
    "\"state\":{"               \
    "\"reported\":{"            \
    "\"powerOn\":%lu"           \
    "}"                         \
    "},"                        \
    "\"clientToken\":\"%06lu\"" \
    "}"

Format string representing a Shadow document with a "reported" state.

The real json document will look like this:

{
  "state": {
    "reported": {
      "powerOn": 1
    }
  },
  "clientToken": "021909"
}

Note the client token, which is optional. The token is used to identify the response to an update. The client token must be unique at any given time, but may be reused once the update is completed. For this demo, a timestamp is used for a client token.

Definition at line 407 of file aws_iot.c.

Function Documentation

app_init()

void app_init

(

void

)

Main entry point to the application.

This will be invoked in a thread once operating system and hardware initialization has completed. It may return, but it does not have to.

Definition at line 650 of file aws_iot.c.