Automatically Applying Configuration to IoT Devices with AWS IoT and AWS Step Functions - Part 1

Contents

1. Introduction
2. Assumptions
3. Tools and Services
4. What workflow are we building?
5. How it works
6. Why this Developer Technique
7. Conclusion
8. Author

Introduction

Explicitly defining processes involving IoT devices and externalizing their management and orchestration is a useful mechanism to break down complexity, centralize state management, ensure bounded context and encapsulation in your system design. It is also a useful technique for modelling workflows that must survive external factors which impact IoT device operation in the field, such as intermittent connectivity, reboots or battery loss, causing temporary offline behavior.

In this blog post series, we will look at a simple example of modeling an IoT device process as a workflow, using primarily AWS IoT and AWS Step Functions. Our example is a system where, when a device comes online, you need to get external settings based on the profile of the user the device belongs to and push that configuration to the device. The system that holds the external settings is often a third party system you need to integrate with at API level (HTTPS), based on the API specification and system SLAs.

A real world example is home automation. A user sets up a default desired temperature for his apartment, based on a User Settings Profile they created when they purchased the gateway responsible for managing the different sensors, including temperature.

Assumptions

To narrow down this implementation example, here is a list of assumptions:

• We refer to the gateway that controls the different sensors as the device.
• The workflow starts every time a device comes online.
• Nothing happens when devices disconnect. The profile is checked only upon reconnects.
• AWS IoT Core interacts only with the gateway, and not with individual sensors. The gateway reports back to confirm the settings have been correctly configured by the respective sensors.
• We will simulate the device behavior using an MQTT client application built with the MQTT.js open-source library.

Note that:

• This is a sample implementation to get you started. It is not meant to be lifted and shifted for a production environment. It can definitely be used as a starting point.
• The focus point in this solution is on development techniques and not on the type of device or type of configuration that needs to be applied. Therefore, this solution simulates the device device behavior, the config, and the external API.

Tools and Services

To build the above described scenario, we use the following technologies:

• AWS Step Functions for workflow management and execution. The state machine is available in GitHub. The following AWS Step Function features are used in the sample project:
  • Tasks - to break down each unit of work.
  • Choice state
  • AWS SDK service integrations.
  • Wait for a Callback with the Task Token.
• AWS IoT Core and AWS IoT Rules Engine for the communication with the IoT Device over MQTT and routing of messages from the device and automatically triggering actions based on message content.
• Amazon DynamoDB for storing of Task Tokens needed for the callback service integration pattern of AWS Step Functions.
• AWS Lambda for publishing messages to the device. AWS Lambda is also used for processing responses to temperature set requests from the IoT Device, as well as simulating the Third Party system call to retrieve the user default desired temperature.
• The device simulator is build in JavaScript, using the open-source Node.js MQTT.js client library.
• All the AWS resources are created and deployed using AWS SAM. The AWS SAM template is available in GitHub

You can have a look at the GitHub repository for the entire solution, here: https://github.com/aws-iot-builder-tools/iot-config-management-sample.

What workflow are we building?

The flow is as follows:

• Every time the device comes online, the workflow for retrieving the user profile, to understand their desired room temperature kicks off. The desired temperature is stored in the user profile, available via an API call to an external system. We simulate this system call using an AWS Lambda function.
• The workflow retrieves the external ID connecting the device to the user it belongs to from IoT thing attributes. It then makes the call to the third party system to retrieve the user profile with the desired temperature value, publishes a message with the configuration setting to the MQTT topic the device is subscribed to, and enters a callback Task, which pauses waiting for the event from the device to come back on the configured response MQTT topic.
• Upon receiving and parsing the response, success or failure is determined, the paused Task is terminated on callback with the respective result, and the AWS Step Functions workflow terminates.

Building an automatically triggered workflow contributes to a nice user experience. There is no need for manual intervention to synchronize the IoT device with user specific configuration settings. This is a simple example to introduce the concept. The workflow can get more complex, with more settings and more involved systems.

How it works

Fig. 1 below shows the interactions between the different components.

Fig. 1 - How it works diagram

The interactions can be described as follows:

• The device comes online and an MQTT presence event is published on the AWS topic $aws/events/presence/connected/+. (1 in Fig. 1 )
• An AWS IoT Rule is configured on the above topic, with the Rule Action being an AWS Step Function State Machine execution trigger. The Rule SQL looks as follows: SELECT *, topic(5) AS thingName FROM $aws/events/presence/connected/+ (2 in Fig. 1 )
• On MQTT connect presence event, the Rule will pick up the event and pass it as input to the state machine, which will be started on Rule execution (3 in Fig. 1 ). The workflow steps will execute as follows:
  • Firstly, the IoT DescribeThing SDK call will be made to retrieve the thing from the Device Registry. The external ID thing attribute will be retrieved and passed on to the next step. Note that the AWS Step Functions SDK integration is used at this step.
  • 3Party_GetUserProfileForDevice is executed as a next step. This is an AWS Lambda function which simulates a call to a third party system. 3Party_GetUserProfileForDevice returns a randomly generated desired temperature value for an external ID and thing name. (4 in the Fig. 1 ).
  • The SetConfigurationOnDevice AWS Lambda function uses the IoTDataPlaneClient to publish a message to the IoT Device on the MQTT request topic with the desired temperature value. (5 in Fig. 1 ), and go next into a “Wait for Callback” Task, waiting for confirmation of the configuration setting from the device.
  • The “Wait for Callback” Task integrates an AWS DynamoDB PutItem SDK call. A task token is generated by AWS Step Functions and sent into the Task as input. We store the token so that we can identify and correlate which token corresponds to the request the device sends the response for. The token is stored in an Amazon DynamoDB table, together with the name of the operation (in this case SET_TEMP), a unique operation ID (passed as input from the Rules Engine MQTT event session ID ), the device ID (thing name) and a status value of ACTIVE. The DynamoDB table is configuration is shown below:

  CMTaskTokens:
    Type: AWS::DynamoDB::Table
    Properties:
      TableName:  CMTaskTokens
      AttributeDefinitions:
        - AttributeName: operationId
          AttributeType: S
        - AttributeName: token
          AttributeType: S

      KeySchema:
        - AttributeName: operationId
          KeyType: HASH
        - AttributeName: token
          KeyType: RANGE
      BillingMode: PAY_PER_REQUEST

• The device receives the request (6 in Fig. 1 ), attempts the operation, and sends the event confirming the result on the MQTT response topic (7 in Fig. 1 ). An IoT Rule picks up the incoming event, and invokes an AWS Lambda Function (8 in Fig. 1 ) which :
  • Parses the response and establishes success or failure.
  • Retrieves the token entry based on the operation ID from the database table and uses it to terminate the AWS Step Function WaitForConfirmationEventFromDevice state with either success or failure.(9 in Fig. 1 ).
• The result from the evaluation of the MQTT response event from the IoT device is passed further into a Choice Task, which determines state machine termination with with either success or failure.

How to Deploy and Run this in your AWS Account

Pre-requisites:

• Clone the GitHub repo: iot-config-management-sample

• In the root directory, iot-config-management-sample, run the following commands:
  

      sam build 
      sam deploy --guided 

• Start the device simulator:
  • Add and validate your configuration in iot-config-management-sample/device/config.js:

export const config =
{
    iotEndpoint: '<YOUR IoT Endpoint>',
    clientId: '<YOUR Thing Name>',
    policyName: '<YOUR IoT Policy>',
    verbosity: 'warn',
    region: '<YOUR AWS Region>',
    shouldCreateThingAndIdentity: <true or false> // if true, the simulator will create the AWS IoT Thing and unique identity. Certificate and Key will be stored in certs/
}

If your shouldCreateThingAndIdentity flag is set to false, you need to make sure the IoT thing, certificate and key have already been created, and store the certificate and key in the certs folder prior to running the MQTT client.

• Start the simulator: node simulator.js
• If the simulator is successfully started, you should already see that an AWS Step Functions workflow was triggered automatically, once your device successfully connected to AWS IoT. Note that the simulator implements a delay of 10 seconds between receiving the request and sending a successful response.
• Verify that the workflow was successfully triggered:
  • Log into the AWS Console, navigate to AWS Step Functions, find the ConfigManagement State Machine, and explore the execution, as shown in the 2 images below.

Fig. 2 - Waiting for MQTT response from the device

Fig 3- Successful workflow execution

Why this Developer Technique?

The advantages of modeling the workflow using AWS Step Functions are as follows:

• The workflow is explicitly defined and exists outside of various system interactions or the IoT device.
• Flexibility in configuring retries, error handling and timeouts, at each step:
  • DescribeThing can run into TPS limits caused by too many concurrent calls to AWS IoT. You can configure your state machine to retry this step, with an exponential back-off strategy.
  • Calls to the Third Party systems can fail with various errors, some of which are worth retrying on. Exception Handling and Retries can be configured at Task level.
  • If the device goes offline temporarily during the workflow execution for whatever reason, you can configure a reasonable Heartbeat on the Callback Task. The workflow then pauses until either a message from the device arrives or the timeout is reached. In this way, workflows can exist in the cloud outside of whatever is going on with the device, for as long as needed.
• AWS Step Functions centralizes state management for each step in the workflow, as well as the workflow as a whole. Tracing, logging and metrics are available as execution level, and at task level. These observability features, as well as the integration with AWS X-Ray and Amazon CloudWatch will be covered in Part 2 of this blog series.

Conclusion

In the first part of this blog series, we looked at modelling and building the process of automatically applying configuration to an IoT device, based on default settings in a user profile, using AWS Steps Functions, AWS IoT, Amazon Dynamo DB, AWS Lambda and the open-source MQTT.js client library. This is a developer technique used to reduce complexity in workflows involving IoT devices. To understand more about the implementation, have a look at the code in GitHub.

For a more complex example of an IoT Workflow, you can have a look at the firmware upgrade (OTA) flow built using AWS IoT and AWS Step Functions in the iot-workflow-management-and-execution GitHub repo.

If you are curious to learn more about IoT workflow orchestration, watch our IoT Builders YouTube episodes:

Stay tuned for the next blog of the series, where we explore in detail observability aspects such as logging, tracing and metrics for this workflow.

If you have any feedback about this post, or you would like to see more related content, please reach out to me here, or on Twitter or LinkedIn.

Author

Alina DimaFollow

An engineer for about 20 years, love solving real world problems with code. I simplify complex problems to help developer communities build better and faster with AWS IoT.