AWS IoT Developer Guide - AWS Documentation

AWS IoT Developer Guide - AWS Documentation
AWS IoT
Developer Guide
AWS IoT Developer Guide
AWS IoT: Developer Guide
Copyright © 2016 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner
that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not
owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by
Amazon.
AWS IoT Developer Guide
Table of Contents
What Is AWS IoT? ......................................................................................................................... 1
AWS IoT Components ............................................................................................................ 1
How to Get Started with AWS IoT ............................................................................................. 2
Accessing AWS IoT ............................................................................................................... 2
Related Services ................................................................................................................... 2
How AWS IoT Works .............................................................................................................. 2
Quickstart .................................................................................................................................... 4
Install the AWS CLI ................................................................................................................ 4
Create a Device in the Thing Registry ....................................................................................... 5
Secure Communication Between a Device and AWS IoT .............................................................. 5
Provision a Certificate .................................................................................................... 5
Create and Attach an AWS IoT Policy to Your Certificate ...................................................... 6
Attach your Certificate to Your Device ................................................................................ 6
Verify MQTT Subscribe and Publish .......................................................................................... 7
Configure MQTT.fx ........................................................................................................ 7
Subscribe to an MQTT Topic ........................................................................................... 9
Publish to an MQTT Topic ............................................................................................... 9
Configure and Test Rules ...................................................................................................... 10
Create an IAM Role for AWS IoT .................................................................................... 10
Grant Permissions to the Role ........................................................................................ 10
Create a Rule to Insert a Message into a DynamoDB Table ................................................. 48
Create a Rule to Invoke a Lambda Function ..................................................................... 50
Use the Device Registry and Device Shadows .......................................................................... 13
Register a Device ........................................................................................................ 13
Simulate a Device ........................................................................................................ 13
Simulate an App Controlling a Device .............................................................................. 14
Delete a Device from the Thing Registry .......................................................................... 14
Device Registry ........................................................................................................................... 15
Security and Identity ..................................................................................................................... 17
Identity in AWS IoT .............................................................................................................. 18
X.509 Certificates ........................................................................................................ 18
IAM Users, Groups, and Roles ....................................................................................... 19
Amazon Cognito Identities ............................................................................................. 19
Authorization ....................................................................................................................... 20
AWS IoT Policies ......................................................................................................... 20
Transport Security ........................................................................................................ 35
Message Broker .......................................................................................................................... 36
Protocols ............................................................................................................................ 36
MQTT ........................................................................................................................ 36
HTTP ........................................................................................................................ 37
MQTT over the WebSocket Protocol ................................................................................ 37
Topics ................................................................................................................................ 40
Reserved Topics .......................................................................................................... 40
Rules ......................................................................................................................................... 41
Granting AWS IoT the Required Access ................................................................................... 41
Creating an AWS IoT Rule .................................................................................................... 43
Viewing Your Rules .............................................................................................................. 45
Troubleshooting a Rule ......................................................................................................... 46
Deleting a Rule ................................................................................................................... 46
AWS IoT Rule Actions .......................................................................................................... 46
CloudWatch Alarm Action ............................................................................................. 46
CloudWatch Metric Action ............................................................................................. 47
DynamoDB Action ....................................................................................................... 48
Elasticsearch Action ..................................................................................................... 49
Kinesis Action ............................................................................................................. 50
iii
AWS IoT Developer Guide
Lambda Action ............................................................................................................
S3 Action ...................................................................................................................
SNS Action .................................................................................................................
Firehose Action ...........................................................................................................
SQS Action .................................................................................................................
Republish Action .........................................................................................................
AWS IoT SQL Reference ......................................................................................................
Expressions ................................................................................................................
SELECT Clause ..........................................................................................................
FROM Clause .............................................................................................................
WHERE Clause ...........................................................................................................
Functions ...................................................................................................................
JSON Extensions ........................................................................................................
Substitution Templates ..................................................................................................
Device Shadows ..........................................................................................................................
Device Shadows Data Flow ...................................................................................................
Device Shadows Documents .................................................................................................
Document Properties ...................................................................................................
Versioning of a Thing Shadow ........................................................................................
Client Token ................................................................................................................
Example Document ......................................................................................................
Empty Sections ...........................................................................................................
Arrays ........................................................................................................................
Using Device Shadows .........................................................................................................
Protocol Support .........................................................................................................
Updating a Thing Shadow .............................................................................................
Retrieving a Thing Shadow Document .............................................................................
Deleting Data ..............................................................................................................
Deleting a Thing Shadow ..............................................................................................
Delta State .................................................................................................................
Observing State Changes .............................................................................................
Message Order ...........................................................................................................
Trim Device Shadow Messages ......................................................................................
RESTful API .......................................................................................................................
GetThingShadow .........................................................................................................
UpdateThingShadow ....................................................................................................
DeleteThingShadow .....................................................................................................
MQTT Pub/Sub Messages ....................................................................................................
/update ......................................................................................................................
/update/accepted .........................................................................................................
/update/rejected ..........................................................................................................
/update/delta ...............................................................................................................
/get ...........................................................................................................................
/get/accepted ..............................................................................................................
/get/rejected ................................................................................................................
/delete .......................................................................................................................
/delete/accepted ..........................................................................................................
/delete/rejected ...........................................................................................................
Document Syntax ................................................................................................................
Request State Documents .............................................................................................
Response State Documents ..........................................................................................
Error Response Documents ...........................................................................................
Error Messages ...................................................................................................................
AWS IoT SDKs ............................................................................................................................
Device SDK ........................................................................................................................
Device SDK Feature Set ...............................................................................................
Platform Support .........................................................................................................
AWS IoT Device SDK for C ...................................................................................................
iv
50
51
52
53
53
54
54
55
56
57
57
57
60
61
62
62
67
67
68
68
68
69
70
70
71
71
71
74
75
76
78
78
79
80
80
81
81
82
83
83
83
84
85
85
86
86
87
87
88
88
89
90
90
92
92
93
93
94
AWS IoT Developer Guide
Prerequisites .............................................................................................................. 94
Connecting Your Raspberry Pi ........................................................................................ 94
AWS IoT Device SDK for Node.js ......................................................................................... 106
Prerequisites ............................................................................................................. 106
Connecting Your Raspberry Pi ...................................................................................... 106
Troubleshooting ......................................................................................................................... 121
Diagnosing Connectivity Issues ............................................................................................ 121
Authentication ........................................................................................................... 121
Authorization ............................................................................................................. 121
Setting Up CloudWatch Logs ............................................................................................... 122
Configuring an IAM Role for Logging ............................................................................. 122
CloudWatch Log Entry Format ..................................................................................... 123
Logging Events and Error Codes .................................................................................. 124
Diagnosing Rules Issues ..................................................................................................... 126
Diagnosing Problems with Thing Shadows ............................................................................. 127
AWS IoT Limits .......................................................................................................................... 128
Throttling Limits ................................................................................................................. 130
v
AWS IoT Developer Guide
AWS IoT Components
What Is AWS IoT?
AWS IoT provides secure, bi-directional communication between Internet-connected things (such as
sensors, actuators, embedded devices, or smart appliances) and the AWS cloud. This enables you to
collect telemetry data from multiple devices and store and analyze the data. You can also create
applications that enable your users to control these devices from their phones or tablets.
AWS IoT Components
AWS IoT consists of the following components:
• Message broker—Provides a secure mechanism for things and IoT applications to publish and receive
messages from each other. You can use the MQTT protocol to publish and subscribe. You can use
the HTTP REST interface to publish.
• Rules engine—Provides message processing and integration with other AWS services. You can use
a SQL-based language to select data from message payloads, process the data, and send the data to
other services, such as Amazon S3, Amazon DynamoDB, and AWS Lambda. You can also use the
message broker to republish messages to other subscribers.
• Thing Registry—Sometimes referred to as the Device Registry. Organizes the resources associated
with each thing. You register your things and associate up to three custom attributes with each thing.
You can also associate certificates and MQTT client IDs with each thing to improve your ability to
manage and troubleshoot your things.
• Thing Shadows service—Provides persistent representations of your things in the AWS cloud. You
can publish updated state information to a thing shadow, and your thing can synchronize its state when
it connects. Your things can also publish their current state to a thing shadow for use by applications
or devices.
• Thing shadow— Sometimes referred to as a device shadow. A JSON document used to store and
retrieve current state information for a thing (device, app, and so on).
• Device gateway—Enables devices to securely and efficiently communicate with AWS IoT.
• Security and identity service—Provides shared responsibility for security in the AWS cloud. Your
things must keep their credentials safe in order to send data securely to the message broker. The
message broker and rules engine use AWS security features to send data securely to devices or other
AWS services.
1
AWS IoT Developer Guide
How to Get Started with AWS IoT
How to Get Started with AWS IoT
• To learn more about AWS IoT, see How AWS IoT Works (p. 2).
• To learn how to connect a thing to AWS IoT, see Quickstart for AWS IoT (p. 4).
Accessing AWS IoT
AWS IoT provides the following interfaces to create and interact with your things:
• AWS Command Line Interface (AWS CLI)—Run commands for AWS IoT on Windows, Mac, and
Linux. To get started, see the AWS Command Line Interface User Guide. For more information about
the commands for AWS IoT, see iot in the AWS Command Line Interface Reference.
• AWS SDKs—Build your IoT applications using language-specific APIs. For more information, see AWS
SDKs and Tools.
• AWS IoT API—Build your IoT applications using HTTP or HTTPS requests. For more information about
the API actions for AWS IoT, see Actions in the AWS IoT API Reference.
• AWS IoT Thing SDK for C—Build IoT applications for resource-constrained things, such as
microcontrollers.
Related Services
AWS IoT integrates directly with the following AWS services:
• Amazon Simple Storage Service—Provides scalable storage in the AWS cloud. For more information,
see Amazon S3.
• Amazon DynamoDB—Provides managed NoSQL databases. For more information, see Amazon
DynamoDB.
• Amazon Kinesis—Enables real-time processing of streaming data at a massive scale. For more
information, see Amazon Kinesis.
• AWS Lambda—Runs your code on virtual servers from Amazon EC2 in response to events. For more
information, see AWS Lambda.
• Amazon Simple Notification Service—Sends or receives notifications. For more information, see
Amazon SNS.
• Amazon Simple Queue Service—Stores data in a queue to be retrieved by applications. For more
information, see Amazon SQS.
How AWS IoT Works
AWS IoT enables Internet-connected things to connect to the AWS cloud and lets applications in the
cloud interact with Internet-connected things. Common IoT applications either collect and process telemetry
from devices or enable users to control a device remotely.
Things report their state by sending messages, in JSON format, to MQTT topics. Each MQTT topic has
a hierarchical name, such as "myhouse/livingroom/temperature." The message broker sends each
message received by a topic to all the clients subscribed to the topic.
You can create rules that define one or more actions to perform based on the data in a message. For
example, you can insert, update, or query a DynamoDB table or invoke a Lambda function. Rules use
expressions to filter messages. When a rule matches a message, the rules engine invokes the action
2
AWS IoT Developer Guide
How AWS IoT Works
using the selected properties. You can use all JSON properties in a message or only the properties you
need. Rules also contain an IAM role that grants AWS IoT permission to the AWS resources used to
perform the action.
Each thing has a thing shadow that stores and retrieves state information. Each item in the state information
has two entries: the state last reported by the thing and the desired state requested by an application.
An application can request the current state information for a thing. The shadow responds to the request
by providing a JSON document with the state information (both reported and desired), metadata, and a
version number. An application can control a thing by requesting a change in its state. The shadow accepts
the state change request, updates its state information, and sends a message to indicate the state
information has been updated. The thing receives the message, changes its state, and then reports its
new state.
3
AWS IoT Developer Guide
Install the AWS CLI
Quickstart for AWS IoT
In this quickstart, you will use the AWS CLI to connect a thing to AWS IoT, create rules to process
messages sent by a thing, and use the Thing Registry and Thing Shadows service to interact with your
device.
Tasks
• Install the AWS CLI (p. 4)
• Create a Device in the Thing Registry (p. 5)
• Secure Communication Between a Device and AWS IoT (p. 5)
• Verify MQTT Subscribe and Publish (p. 7)
• Configure and Test Rules (p. 10)
• Use the Device Registry and Device Shadows (p. 13)
Install the AWS CLI
Before you get started, you must install the latest version of the AWS CLI and configure the AWS CLI
with your AWS credentials. For more information, see Getting Set Up with the AWS Command Line
Interface.
Note
The AWS credentials you configure in the AWS CLI must be the credentials for an IAM user who
has permissions to perform IAM and AWS IoT operations used in this quickstart. If you are
unsure, go to the IAM console and attach the IAMFullAccess and AWSIoTFullAccess policies
to the account you are using. These roles allow full access to both IAM and AWS IoT and are
used here to enable you to go through the quickstart easily. These roles should not be used in
a production environment.
To verify your installation, run the following command to list the commands available for AWS IoT:
aws iot help
The help for each subcommand describes its function, options, output, and usage. Use the following
command to get help for each subcommand:
aws iot command help
4
AWS IoT Developer Guide
Create a Device in the Thing Registry
For more information about formatting commands, JSON parameters, and more, see Specifying Parameter
Values for the AWS Command Line Interface.
Create a Device in the Thing Registry
To connect a thing to AWS IoT, we recommend you first create a device in the Thing Registry. The Thing
Registry allows you to keep a record of all things connected to AWS IoT.You can use the create-thing
CLI command or the AWS IoT console to create a thing.
In a command prompt/terminal, run the following command:
aws iot create-thing --thing-name "myLightBulb"
This command takes a thing name, creates a thing, and displays the thing ARN and name:
{
"thingARN": "arn:aws:iot:us-east-1:aws-account-id:thing/myLightBulb",
"thingName": "myLightbulb"
}
You can use the list-things command to confirm the thing has been created in the Thing Registry:
aws iot list-things
This command lists all things in the Thing Registry for your AWS account:
{
"things": [
{
"attributes": {},
"thingName": "myLightBulb"
}
]
}
Secure Communication Between a Device and
AWS IoT
Communication between a thing and AWS IoT is protected through the use of X.509 certificates. AWS
IoT can generate a certificate for you or you can use your own X.509 certificate. This quickstart assumes
AWS IoT will be generating the X.509 certificate for you. The process of creating a certificate with AWS
IoT is called provisioning. Certificates must also be activated prior to use.
Provision a Certificate
You can provision a certificate in AWS IoT with an AWS IoT-provided public and private key pair or use
your own key pair. In this example, the certificate and key pair is created by AWS IoT.
Use the create-keys-and-certificate command to create and activate a certificate:
5
AWS IoT Developer Guide
Create and Attach an AWS IoT Policy to Your Certificate
aws iot create-keys-and-certificate --set-as-active --certificate-pem-outfile
cert.pem --public-key-outfile publicKey.pem --private-key-outfile privateKey.pem
This command generates a certificate, a public key, and a private key.
Now that you have created a certificate, you must create an AWS IoT policy that controls which AWS IoT
operations the certificate owner can perform and then attach that policy to your certificate.
Create and Attach an AWS IoT Policy to Your
Certificate
Use the create-policy command to create an AWS IoT policy. The --policy-document argument
contains JSON that specifies the permissions assigned to the policy:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action":["iot:*"],
"Resource": ["*"]
}]
}
This JSON policy document allows all AWS IoT operations on all resources. Save this text to a file and
specify it in the create-policy command:
aws iot create-policy --policy-name "PubSubToAnyTopic" --policy-document
file://path-to-your-policy-document
Use the following attach-principal-policy command to attach the policy to your certificate:
aws iot attach-principal-policy --principal "certificate-arn" --policy-name
"PubSubToAnyTopic"
Attach your Certificate to Your Device
You use the attach-thing-principal CLI command to attach a certificate to a thing. The command
takes two parameters:
--thing-name
The name of the thing to which to attach the certificate.
--principal
The ARN of your certificate.
The following shows how to call attach-thing-principal:
aws iot attach-thing-principal --thing-name "thing-name" --principal "certific
ate-arn"
6
AWS IoT Developer Guide
Verify MQTT Subscribe and Publish
Verify MQTT Subscribe and Publish
The steps in this section show you how to verify you can use your certificate to communicate with AWS
IoT over MQTT. You will use an MQTT client to subscribe and publish to an MQTT topic. MQTT clients
require a root CA certificate to authenticate with AWS IoT. Download the root CA certificate file from root
certificate.
This quickstart assumes you are using MQTT.fx, an MQTT client written in Java based on Eclipse Paho.
You can install it from Download MQTT.fx.
Note
Before you begin, ensure egress to port 8883 is allowed on your network.
Use the following command to retrieve your AWS account-specific AWS IoT endpoint:
aws iot describe-endpoint
This command will return an endpoint in the form of
"<random-string>.iot.us-east-1.amazonaws.com." You will use this endpoint to configure
MQTT.fx to connect to AWS IoT.
Configure MQTT.fx
To configure MQTT.fx, open the app and choose the gear icon at the top of the page.
Type a profile name. In Broker Address, type your account-specific AWS IoT endpoint URL. Use the
describe-endpoint CLI command to find your account-specific AWS IoT endpoint URL. In Broker Port,
type 8883, as shown here:
7
AWS IoT Developer Guide
Configure MQTT.fx
Choose the SSL/TLS button to view the SSL/TLS settings page. Type the paths to your private key,
certificate, and root CA certificate as shown here:
Choose the OK to save your settings, and then choose Connect to connect to AWS IoT.
8
AWS IoT Developer Guide
Subscribe to an MQTT Topic
Subscribe to an MQTT Topic
Choose Subscribe and the Subscribe page will be displayed. Type my/topic in the text box, From the
drop-down list, select QoS 0, and then choose Subscribe.
Publish to an MQTT Topic
Choose the Publish link and the publish page will be displayed. Type my/topic in the text box, and then
type some text in the message area. From the drop-down box, choose QoS 0, and then choose Publish.
Choose Subscribe to display the Subscribe page. You should see the message has been received by
MQTT.fx.
9
AWS IoT Developer Guide
Configure and Test Rules
Configure and Test Rules
Now that you can send and receive MQTT messages through AWS IoT, you can configure rules to specify
what AWS IoT should do with the messages it receives.You can configure AWS IoT rules to continuously
process messages published on topics, insert message data into a DynamoDB table, or call a Lambda
function. You can configure multiple rules on a single topic.
Create an IAM Role for AWS IoT
Create an IAM role that AWS IoT can assume to perform actions when rules are triggered.
Save the following Assume Role policy document (that is, trust relationship) to a file:
{
"Version": "2012-10-17",
"Statement": [{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}]
}
To create the IAM role, run the create-role command, passing in the Assume Role policy document:
aws iam create-role --role-name iot-actions-role --assume-role-policy-document
file://path-to-file/trust-policy-file
Save the role ARN from the command output. You will need it when you create a rule.
Grant Permissions to the Role
Grant the IAM role permissions to write to DynamoDB and invoke Lambda functions. To do this, create
an IAM policy and attach the policy to your role. Save the following policy document to a file:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [ "dynamodb:*", "lambda:InvokeFunction"],
"Resource": ["*"]
}]
}
Call create-policy and specify the IAM policy document:
aws iam create-policy --policy-name iot-actions-policy --policy-document
file://IAM-policy-document-file-path
To attach the policy to the role, run the attach-policy-role command:
10
AWS IoT Developer Guide
Create a Rule to Insert a Message into a DynamoDB
Table
aws iam attach-role-policy --role-name iot-actions-role --policy-arn "policyARN"
Create a Rule to Insert a Message into a
DynamoDB Table
Use the DynamoDB console to create a DynamoDB table.The DynamoDB table must have both a partition
key of type String and a sort key of type String configured. The names of the columns must match
the name you define in your rule. Use the defaults for all other values.
Create a rule to trigger on a topic and insert an item into the sample DynamoDB table. Rules are specified
in JSON using an SQL-like syntax.The following JSON shows how to specify a rule that writes all messages
sent to the topic/test topic to the sampleTable DynamoDB table:
{
"sql": "SELECT * FROM 'topic/test'",
"ruleDisabled": false,
"actions": [{
"dynamoDB": {
"tableName": "sampleTable",
"hashKeyField": "key",
"hashKeyValue": "${topic(2)}",
"rangeKeyField": "timestamp",
"rangeKeyValue": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/iot-actions-role"
}
}]
}
Note
When entering topics on the command line, enclose the full topic name in single quotation marks.
Save this text to a file (for example, DynamoDbRule) and specify it in the create-topic-rule command:
aws iot create-topic-rule --rule-name saveToDynamoDB --topic-rule-payload
file://path-to-file/DynamoDbRule
Use MQTT.fx to invoke the rule by publishing the following message on the topic/test topic:
{
"msg" : "Hello, World"
}
Note
Make sure egress to port 8883 is allowed on your network.
To verify the data is written to the DynamoDB table, open the DynamoDB console, and open (double-click)
the sampleTable to display the contents of the table.
Note
Non-JSON data is written to DynamoDB as binary data. The DynamoDB console will display
the data as base 64 encoded text.
11
AWS IoT Developer Guide
Create a Rule to Invoke a Lambda Function
Create a Rule to Invoke a Lambda Function
To create a Lambda function
1.
Open the Lambda console, and choose Create a Lambda Function.
2.
Choose the hello-world blueprint, and name the function myHelloWorld.
3.
4.
5.
In Lambda function handler and role, under Handler, leave the default value (index.handler).
From Role, choose Basic Execution Role.
On the Role page, choose Allow.
On the new function page, choose Next, and then choose Create function.
6.
On the page displayed, make a note of the function ARN. You will need it when you create a rule.
To create a rule to trigger on a topic, call the myHelloWorld Lambda function. Rules are specified in
JSON using an SQL-like syntax.
The following JSON shows how to specify a rule that calls the myHelloWorld Lambda function when
any message is published on the topic/test topic:
{
"sql": "SELECT * FROM 'topic/test'",
"ruleDisabled": false,
"actions": [{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-1:123456789012:function:my
HelloWorld"
}
}]
}
Save this text to a file (for example, LambdaRule) and specify it in the create-topic-rule command:
aws iot create-topic-rule --rule-name invokeLambda --topic-rule-payload
file://path-to-file/LambdaRule
7.
Provide a resource-based policy so AWS IoT can invoke the Lambda function.
aws lambda add-permission --function-name "function_name" --region "region"
--principal iot.amazonaws.com --source-arn arn:aws:iot:us-east-1:ac
count_id:rule/rule_name --source-account "account_id" --statement-id
"unique_id" --action "lambda:InvokeFunction"
For more information, see Lambda add-permission.
Invoke the rule by publishing an MQTT message on the topic/test topic using MQTT.fx. In MQTT.fx,
choose Publish to show the Publish page. Type topic/test in the text box, and then type the following
JSON into the message area. Choose Publish.
{
"msg" : "Hello, World"
}
12
AWS IoT Developer Guide
Use the Device Registry and Device Shadows
Note
Make sure egress to port 8883 is allowed on your network.
To verify the Lambda function was invoked and the message was received, go to the Lambda console
and view the logs in CloudWatch Logs.
Use the Device Registry and Device Shadows
The Thing Registry allows you to keep a record of all things connected to AWS IoT. The Thing Shadows
service allows applications to interact with the things connected to AWS IoT.
Here is the data flow:
• A thing, such as an internet-connected light bulb, is registered in the Thing Registry.
• The light bulb publishes its current state (for example, "power = on" and "color = green") to AWS IoT.
AWS IoT stores the state in the thing shadow document.
• An application, such as a mobile app controlling the light bulb, uses a RESTful API to query AWS IoT
for the last reported state of the light bulb.
• An application uses a RESTful API to request a change in thing state. For example, a mobile app
requests that the light bulb change its color to red. The application does not have to communicate
directly with the thing or be resilient to issues like intermittent connectivity. AWS IoT will synchronize
the desired state with the thing the next time the thing is connected.
For quick tour of a thing shadow document, we will use the MQTT.fx app to simulate the light bulb and
the AWS CLI commands to simulate the mobile application.
Register a Device
Open a command prompt and run the create-thing command:
aws iot create-thing --thing-name myLightBulb
To confirm the thing is created in the Thing Registry, run the list-things command:
aws iot list-things
Simulate a Device
A thing uses MQTT publish/subscribe (or a RESTful API) to synchronize with its shadow in AWS IoT. To
report its state over MQTT, the thing publishes on topic $aws/things/thingName/shadow/update. If there
is an error, such as a version conflict when merging the reported state with the shadow, AWS IoT publishes
an error message on topic $aws/things/thingName/shadow/update/rejected. The thing should subscribe
on this error topic so it will be notified of any error. To receive updates from the shadow, the thing should
subscribe to topic $aws/things/thingName/shadow/update/accepted.
To use the MQTT.fx app to simulate the thing, subscribe to the
$aws/things/myLightBulb/shadow/update/rejected and
$aws/things/myLightBulb/shadow/update/accepted topics.
Now use MQTT.fx to publish the following message to the $aws/things/myLightBulb/shadow/update
topic.
13
AWS IoT Developer Guide
Simulate an App Controlling a Device
{
"state": {
"reported": {
"color": "RED"
}
}
}"
This will simulate reporting the state of the thing to AWS IoT. In this example, the light bulb is reporting
its current color is red.
Simulate an App Controlling a Device
An application, such as a mobile app or a web application, can authenticate by using AWS credentials.
It can use the AWS IoT RESTful API to get or set the state of a thing.
To get the last reported state of a thing, use the get-thing-shadow command:
aws iot-data get-thing-shadow --thing-name myLightBulb output.txt && cat out
put.txt
Note
On Windows, use && type output.txt.
To request an update (for example, to set state on a thing), use the update-thing-shadow command:
aws iot-data update-thing-shadow --thing-name myLightBulb --payload "{ \"state\":
{\"desired\": { \"color\": \"GREEN\" } } }" output.txt && cat output.txt
This example sets the color of the light bulb to green.
Note
On Windows, use && type output.txt.
Delete a Device from the Thing Registry
To use MQTT.fx to delete a device from the thing registry, publish the following message to the
$aws/things/myLightBulb/shadow/update topic:
{
"state": null
}
To use the delete-thing command to delete the thing from the Thing Registry:
aws iot delete-thing --thing-name myLightBulb
Note
You must detach any attached principals using the detach-thing-principal CLI command
before deleting a thing from the Thing Registry.
14
AWS IoT Developer Guide
Device Registry for AWS IoT
AWS IoT deployments can range from a small number of mission-critical devices to large fleets with
thousands of individual device units in the field. AWS IoT provides a Thing Registry to organize the
resources associated with each device.
The Thing Registry allows you to register your units (both real devices and virtual applications) with the
service and associate up to three custom attributes with each unit. Authentication certificates used by
these things can also be associated to the thing, to allow for easy viewing and diagnosis of customers’
IoT fleets.
Here is an example thing:
aws iot describe-thing --thing-name "MyDevice3"
{
"thingName": " MyDevice3",
"defaultClientId": "MyDevice3",
"attributes": {
"Manufacturer": "Amazon",
"Type": "IoT Device A",
"Serial Number": "10293847562912"
}
}
A thing can then be associated with one or more certificates it can use to authenticate to the service. The
registry allows for easy organization of the customer’s fleet.
aws iot list-thing-principals --thing-name "MyDevice3"
{
"principals": [
"arn:aws:iot:us-east1:101010101010:cert/e7dc0fe48c148734641f2ba54312ba54641f2ba543fac37f2ba54348c1487ca7",
"arn:aws:iot:us-east1:101010101010:cert/302ba54348c1487fe691284c5eaa6bbadc02ba54348c1487fe641fac37fb
cda5"
15
AWS IoT Developer Guide
]
}
You can list all of your things in the Thing Registry and can search and filter based on the attributes you
have provisioned. For example, you can search for all things where "manufacturer" is "Amazon" or for all
things that have a serial number, and so on.
A typical use case for a device might involve using the thing name as the default MQTT client ID. However,
because IoT scenarios can involve constraints and complexities, we do not enforce a mapping between
a thing’s registry name and its usage of MQTT client IDs, certificates, or shadow state. We recommend
you choose a thing name for the Thing Registry and use the same name as the MQTT client ID for both
the Thing Registry and the Thing Shadows service. This will add organization and convenience to your
IoT fleet without taking away the flexibility of the underlying device certificate model or thing shadows.
16
AWS IoT Developer Guide
Security and Identity for AWS IoT
The AWS IoT security model is one of shared responsibility, with an emphasis on security in the cloud.
Each connected device needs a credential to access the message broker or the Thing Shadows service.
All traffic to and from AWS IoT must be encrypted over TLS. Device credentials must be kept safe in
order to send data securely to the message broker. After data reaches the message broker, AWS cloud
security mechanisms protect data as it moves between AWS IoT and other devices or AWS services.
17
AWS IoT Developer Guide
Identity in AWS IoT
• You are responsible for managing credentials (X.509 certificates, AWS credentials) on your devices
and policies in AWS IoT. You are responsible for assigning unique identities to each device and
managing the permissions for a device or group of devices.
• Devices connect using your choice of identity (X.509 certificates or AWS principals) over a secure
connection according to the AWS IoT connection model.
• The AWS IoT message broker authenticates and authorizes all actions in your account. The message
broker is responsible for authenticating your devices, securely ingesting device data, and honoring the
access permissions you place on devices using policies.
• The AWS IoT rules engine forwards device data to other devices and other AWS services according
to rules you define. It is responsible for leveraging AWS access management systems to securely
transfer data to its final destination.
Identity in AWS IoT
AWS IoT supports three types of identity principals:
• X.509 certificates
• IAM users, groups, and roles
• Amazon Cognito identities
Each identity type enables different use cases for accessing the AWS IoT message broker and Thing
Shadows service.
The type of identity you use depends on your choice of application protocol. If you use HTTP, use IAM
(users, groups, and roles) or Amazon Cognito identities. If you use MQTT, use X.509 certificates.
The following sections provide more information about each identity type.
X.509 Certificates
X.509 certificates provide several benefits over other identification and authentication mechanisms. X.509
certificates enable asymmetric keys to be used with devices. Your manufacturing process and devices
can be in control of keys and do not need to rely on AWS for generating security credentials. This means
you can burn private keys into secure storage on a device without ever allowing the sensitive cryptographic
material to leave the device. Certificates provide stronger client authentication over other schemes, such
as user name and password or bearer tokens, because the secret key never leaves the client.
AWS IoT authenticates certificates using the Transport Layer Security (TLS) protocol’s client authentication
mode. TLS is widely available in many programming languages and operating systems and is commonly
used for encrypting data. In TLS client authentication, AWS IoT requests a client X.509 certificate and
validates the certificate’s status and AWS account against a registry of certificates. It then challenges the
client for proof of the private key that corresponds to the public key contained in the certificate.
Clients must support all of the following in their TLS implementation to use AWS IoT certificates:
• TLS 1.2
• SHA-256 RSA certificate signature validation
• One of the cipher suites from the TLS cipher suite support section
Managing Device Certificates
You can use the AWS IoT CLI to create and manage certificates. The following operations are available:
18
AWS IoT Developer Guide
IAM Users, Groups, and Roles
• Create a new certificate.
• Revoke, deactivate, or activate a certificate.
• Transfer a certificate to another AWS account.
Certificates generated by AWS IoT do not expire. You can use the UpdateCertificate API to revoke a
certificate at any time. For more information about managing device certificates, see the AWS Command
Line Interface User Guide.
IAM Users, Groups, and Roles
IAM users, groups, and roles are the standard mechanism for managing identity and authentication in
AWS. As with any other AWS service, you can use them to connect to AWS IoT HTTP interfaces using
the AWS SDK and CLI .
IAM roles are also the basis for AWS IoT security in the cloud. Roles allow AWS IoT to issue calls to
other AWS resources in your account on your behalf. If you want to have a device publish its state to a
DynamoDB table, for example, IAM roles allow AWS IoT to do the heavy lifting securely. For more
information, see IAM Roles.
For message broker connections, AWS IoT authenticates IAM users, groups, and roles using the signature
version 4 signing process. For information about authentication with AWS security credentials, see Signing
AWS API Requests.
When using AWS signature version 4 with AWS IoT, clients must support the following in their TLS
implementation:
• TLS 1.2, TLS 1.1, TLS 1.0
• SHA-256 RSA certificate signature validation
• One of the cipher suites from the TLS cipher suite support section
You can manage AWS security credentials using AWS Identity and Access Management (IAM). For
information, see IAM for reference.
Amazon Cognito Identities
Amazon Cognito Identity allows you to use your own identity provider or leverage other popular identity
providers, such as Login with Amazon, Facebook, or Google. You exchange a token from your identity
provider for AWS security credentials. The credentials represent an IAM role and can be used with AWS
IoT.
AWS IoT extends Amazon Cognito and allows policy attachment to Amazon Cognito identities. You can
attach a policy to an Amazon Cognito identity and give fine-grained permissions to an individual user of
your AWS IoT application. This can be used to assign permissions between specific customers and their
devices.
19
AWS IoT Developer Guide
Authorization
For more information, see Amazon Cognito Identity. For more information about using Amazon Cognito
Identity policies with AWS IoT, see the AWS IoT SDK and CLI reference.
Authorization
Communication with AWS IoT follows the principle of least privilege. An identity can only execute AWS
IoT operations if you grant the appropriate permission. You use access policies to give permissions to
identities in AWS IoT.
Policies give permissions to AWS IoT clients regardless of the authentication mechanism they use to
connect to AWS IoT. You can attach AWS IoT policies to certificates or Amazon Cognito identities. You
can attach IAM policies to AWS users, groups, and roles.
Policy-based authorization is a powerful tool. It gives you complete control over the topics and topic filters
in your AWS account. For example, consider a device connecting to AWS IoT with a certificate. You can
open its access to all topics, or you can restrict its access to a single topic. The latter example allows you
to assign a topic per device. For example, the device ID 123ABC can subscribe to /device/123ABC and
you can grant other identities permission to subscribe to this topic, effectively opening a communication
channel to this device.
AWS IoT Policies
AWS IoT policies are JSON documents and they follow the same conventions as IAM policies. For more
information, see Overview of IAM Policies.
An AWS IoT policy looks like the following:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action":["iot:Publish"],
"Resource": ["arn:aws:iot:us-east-1:123456789012:topic/foo/bar"]
},
{
"Effect": "Allow",
"Action": ["iot:Connect"],
20
AWS IoT Developer Guide
AWS IoT Policies
"Resource": ["*"]
}]
}
This policy allows the principal to connect and publish messages to AWS IoT.
Managing AWS IoT Policies
AWS IoT supports named policies so many identities can reference the same policy document. Named
policies are versioned for rollback convenience. For more information about managing AWS IoT policies,
see the AWS IoT SDK and CLI reference.
AWS IoT Policy Actions
The following actions are available for use with AWS IoT:
iot:Publish
The Publish permission is checked every time a publish request is sent to the broker. The Publish
action is used to allow clients to publish to specific topic patterns.
iot:Subscribe
The Subscribe permission is checked every time a subscribe request is sent to the broker. The
Subscribe action is used to allow clients to subscribe to topics that match specific topic patterns.
iot:Receive
The Receive permission is checked every time a message is delivered to a client. Because the
Receive permission is checked on every delivery, it can be used to revoke permissions to clients that
are currently subscribed to a topic.
iot:Connect
The Connect permission is checked every time a connect request is sent to the broker. The message
broker does not allow two clients with the same client ID to stay connected at the same time. After
the second client connects, the broker detects this case and disconnects one of the clients. The
Connect permission can be used to ensure only authorized clients can connect using a specific client
ID.
iot:UpdateThingShadow
The UpdateThingShadow permission is checked every time a request is made to update the state
of a thing shadow document.
iot:GetThingShadow
The GetThingShadow permission is checked every time a request is made to get the state of a thing
shadow document.
iot:DeleteThingShadow
The DeleteThingShadow permission is checked every time a request is made to delete the thing
shadow document.
Action Resources
The following table shows the resource to specify for each action type:
Action
Resource
iot:DeleteThingShadow
thing ARN
iot:Connect
client ID ARN
iot:Publish
topic ARN
21
AWS IoT Developer Guide
AWS IoT Policies
Action
Resource
iot:Subscribe
topic filter ARN
iot:Receive
topic ARN
iot:UpdateThingShadow
thing ARN
iot:GetThingShadow
thing ARN
AWS IoT Policy Variables
AWS IoT defines two policy variables that can be used in AWS IoT policies: iot:ClientId and
aws:SourceIp. When a policy is evaluated, the variables will be replaced by the actual values.
iot:ClientId is replaced by the client ID that sent an MQTT or HTTP message. aws:SourceIp is
replaced by the IP address where the message originated.
The following AWS IoT policy illustrates the use of policy variables:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["iot:Connect"],
"Resource": [
"arn:aws:iot:us-east-1:123451234510:client/${iot:ClientId}"
]
},
{
"Effect": "Allow",
"Action": ["iot:Publish"],
"Resource": [
"arn:aws:iot:us-east-1:123451234510:topic/foo/bar/${iot:ClientId}"
]
}]
}
Example Policies
AWS IoT policies are specified in a JSON document. These are the components of an AWS IoT policy:
Version
Must be set to "2012-10-17."
Effect
Must be set to "Allow" or "Deny."
Action
Must be set to "iot:<operation-name>" where <operation-name> is one of the following:
"iot:Publish" - MQTT publish.
"iot:Subscribe" - MQTT subscribe.
"iot:UpdateThingShadow" - Update a thing shadow.
22
AWS IoT Developer Guide
AWS IoT Policies
"iot:GetThingShadow" - Retrieve a thing shadow.
"iot:DeleteThingShadow - Delete a thing shadow.
Resource
Must be set to one of the following:
Client - arn:aws:iot:<region>:<accountId>:client/<clientId>
Topic ARN - arn:aws:iot:<region>:<accountId>:topic/<topicName>
Topic filter ARN - arn:aws:iot:<region>:<accountId>:topicfilter/<topicFilter>
Connect Policy Examples
The following policy allows a set of client IDs to connect:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:client/clientid1",
"arn:aws:iot:us-east-1:123456789012:client/clientid2",
"arn:aws:iot:us-east-1:123456789012:client/clientid3"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Subscribe",
"iot:Receive"
],
"Resource": [
"*"
]
}
]
}
The following policy prevents a set of client IDs from connecting:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"iot:Connect"
],
23
AWS IoT Developer Guide
AWS IoT Policies
"Resource": [
"arn:aws:iot:us-east-1:123456789012:client/clientid1",
"arn:aws:iot:us-east-1:123456789012:client/clientid2"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"*"
]
}
]
}
The following policy allows the certificate holder using any client ID to subscribe to topic filter foo/*:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/foo/*"
]
}
]
}
Publish/Subscribe Policy Examples
The policy you use will depend upon how you are connecting to &IoT;. You can connect to &IoT; using
an MQTT client, HTTP, or WebSockets. When connecting with an MQTT client you will be authenticating
with an X.509 certificate. When connecting over HTTP or the WebSocket protocol you will be authenticating
with Signature Version 4 and Amazon Cognito.
Policies for MQTT Clients
The following policy allows the certificate holder using any client ID to publish to all topics and subscribe
to all topic filters in the AWS account:
24
AWS IoT Developer Guide
AWS IoT Policies
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:*"
],
"Resource": [
"*"
]
}
]
}
The following policy allows the certificate holder using any client ID to publish to all topics in the AWS
account:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Connect"
],
"Resource": [
"*"
]
}
]
}
The following policy allows the certificate holder using any client ID to publish to the foo/bar and foo/baz
topics:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/foo/bar",
25
AWS IoT Developer Guide
AWS IoT Policies
"arn:aws:iot:us-east-1:123456789012:topic/foo/baz"
]
}
]
}
The following policy prevents the certificate holder using any client ID from publishing to the foo/bar topic:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"*"
]
},
{
"Effect": "Deny",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/foo/bar"
]
}
]
}
The following policy allows the certificate holder using any client ID to subscribe to topic filter foo/+/bar:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/foo/+/bar"
]
}
26
AWS IoT Developer Guide
AWS IoT Policies
]
}
The following policy allows the certificate holder using any client ID to publish on topic foo and subscribe
to topic filter foo/bar/*:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/foo"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/foo/bar/*"
]
}
]
}
The following policy allows the certificate holder using any client ID to publish on topic foo and prevents
the certificate holder using any client ID from publishing to topic bar:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
27
AWS IoT Developer Guide
AWS IoT Policies
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/foo"
]
},
{
"Effect": "Deny",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/bar"
]
}
]
}
The following policy allows the certificate holder using any client ID to subscribe to topic filter foo/bar:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/foo/bar"
]
}
]
}
The following policy allows the certificate holder using any client ID to publish on the
"arn:aws:iot:us-east-1:123456789012:topic/iotmonitor/provisioning/8050373158915119971" topic and
allows the certificate holder using any client ID to subscribe to the topic filter
"arn:aws:iot:us-east-1:123456789012:topicfilter/iotmonitor/provisioning/8050373158915119971:"
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
28
AWS IoT Developer Guide
AWS IoT Policies
"iot:Connect"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/iotmonitor/provision
ing/8050373158915119971"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/iotmonitor/pro
visioning/8050373158915119971"
]
}
]
}
Policies for HTTP and WebSocket Clients
For the following operations, AWS IoT uses policies attached to cognito identities (via AWS IoT
AttachPrincipalPolicy API) to scope down the permissions attached to the cognito identity pool with
authenticated identities. That means a cognito identity needs permission from the role policy attached to
the pool as well as the policy attached to the cognito identity via the AWS IoT AttachPrincipalPolicy API.
• iot:Connect
• iot:Publish
• iot:Subscribe
• iot:Receive
• iot:GetThingShadow
• iot:UpdateThingShadow
• iot:DeleteThingShadow
Note
For other AWS IoT operations or for unauthenticated identities, AWS IoT does not scope down
the permissions attached to the Amazon Cognito identity pool role. This is the most permissive
policy that we recommend attaching to the Amazon Cognito pool role for both authenticated and
unauthenticated identities.
To allow unauthenticated Amazon Cognito identities to HTTP Publish on any topic attach the following
policy to the Amazon Cognito identity pool role.
29
AWS IoT Developer Guide
AWS IoT Policies
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect",
"iot:Publish",
"iot:Subscribe",
"iot:Receive",
"iot:GetThingShadow",
"iot:UpdateThingShadow",
"iot:DeleteThingShadow"
],
"Resource": ["*"]
}]
}
To allow unauthenticated Amazon Cognito identities to publish MQTT messages over HTTP on any topic
in your account, attach the following policy to the Amazon Cognito identity pool role.
Note
The example below is for illustration only. We recommend having a more restrictive policy that
does not allow unauthenticated Amazon Cognito identities to publish on any topic unless your
service absolutely requires it.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["iot:Publish"],
"Resource": ["*"]
}]
}
To allow unauthenticated Amazon Cognito identities to publish MQTT messages over HTTP on topic1 in
your account, attach the following policy to your Amazon Cognito identity pool role.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["iot:Publish"],
"Resource": ["arn:aws:iot:us-east-1:123456789012:topic/topic1"]
}]
}
For an authenticated Amazon Cognito identity to publish MQTT messages over HTTP on topic1 in your
AWS account, you must specify two policies as outlined below. The first policy must be attached to a
Amazon Cognito identity pool role and allows identities from that pool to make a publish call. The second
policy is attached to a Amazon Cognito user using the AWS IoT AttachPrincipalPolicy API and allows the
specified Amazon Cognito user access to the "topic1" topic.
Amazon Cognito identity pool policy:
30
AWS IoT Developer Guide
AWS IoT Policies
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [ "iot:Publish"],
"Resource": ["arn:aws:iot:us-east-1:123456789012:topic/topic1"]
}]
}
Amazon Cognito user policy:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["iot:Publish"],
"Resource": ["arn:aws:iot:us-east-1:123456789012:topic/topic1"]
}]
}
Similarly, the example policy below, allows the Amazon Cognito user to publish MQTT messages over
HTTP on the "topic1" and "topic2" topics. Two policies are required. The first policy gives the Amazon
Cognito identity pool role the ability to make the publish call. The second policy gives the Amazon Cognito
user access to the "topic1" and "topic2" topics.
Amazon Cognito identity pool policy:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["iot:Publish"],
"Resource": ["*"]
}]
}
Amazon Cognito user policy:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["iot:Publish"],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/topic1",
"arn:aws:iot:us-east-1:123456789012:topic/topic2"
]
}]
}
The following policies allow multiple Amazon Cognito users to publish to a topic. Two policies per Amazon
Cognito identity are required. The first policy gives the Amazon Cognito identity pool role the ability to
make the publish call. The second and third policies give the Amazon Cognito users access to the topics
topic 1 and topic 2 respectively.
31
AWS IoT Developer Guide
AWS IoT Policies
Amazon Cognito identity pool policy:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["iot:Publish"],
"Resource": ["*"]
}]
}
Amazon Cognito User1 policy:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["iot:Publish"],
"Resource": ["arn:aws:iot:us-east-1:123456789012:topic/topic1"]
}]
}
Amazon Cognito User2 policy:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["iot:Publish"],
"Resource": ["arn:aws:iot:us-east-1:123456789012:topic/topic2"]
}]
}
Receive Policy Examples
The following policy prevents the certificate holder using any client ID from receiving messages from a
topic:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/foo/restricted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:*"
],
32
AWS IoT Developer Guide
AWS IoT Policies
"Resource": [
"*"
]
}
]
}
The following policy allows the certificate holder using any client ID to subscribe and receive messages
on one topic:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [*]
},
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/foo/bar"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/foo/bar"
]
}
]
}
IAM IoT Policies
AWS IoT provides a set of IAM policy templates you can either use as-is or as a starting point for creating
custom IAM policies. These templates allow access to configuration and data operations. Configuration
operations allow you to create things, certificates, policies, and rules. Data operations send data over
MQTT or HTTP protocols. The following table describes these templates.
Policy Template
Description
AWSIotLogging
Allows the associated identity to configure CloudWatch logging. This policy is attached to your
CloudWatch logging role.
AWSIoTConfigAccess
Allows the associated identity access to all AWS
IoT configuration operations.
33
AWS IoT Developer Guide
AWS IoT Policies
Policy Template
Description
AWSIoTConfigReadOnlyAccess
Allows the associated identity to call read-only
configuration operations.
AWSIoTDataAccess
Allows the associated identity full access to all AWS
IoT data operations. Data operations send data
over MQTT or HTTP protocols. When MQTT over
the WebSocket protocol is used, only policies
stored in IAM will apply to the WebSocket connection.
AWSIoTFullAccess
Allows the associated identity full access to all AWS
IoT configuration and data operations.
AWSIoTRuleActions
Allows the associated identity access to all AWS
services supported in AWS IoT rule actions.
Cross Account Access
AWS IoT allows you to enable a principal to publish or subscribe to a topic that is defined in an AWS
account not owned by the principal. You configure this by creating an IAM policy and IAM role and then
attaching the policy to the role.
First, create an IAM policy just like you would for other users and certificates in your AWS account. For
example, the following policy grants permissions to connect and publish to the /foo/bar topic.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/foo/bar"
]
}]
}
Next, follow the steps in Creating a Role for an IAM User. Enter the AWS account ID of the AWS account
with which you want to share access. Then, in the final step, attach the policy you just created to the role.
If, at a later time, you need to modify the AWS account ID to which you are granting access, you can use
the following trust policy format to do so.
34
AWS IoT Developer Guide
Transport Security
{
"Version":"2012-10-17",
"Statement":[{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam:us-east-1:123456789012:user/MyUser"
},
"Action": "sts:AssumeRole"
}]
}
Transport Security
The AWS IoT message broker and Thing Shadows service encrypt all communication with TLS. TLS is
used to ensure the confidentiality of the application protocols (MQTT, HTTP) supported by AWS IoT. TLS
is readily available in a variety of programming languages and operating systems.
For MQTT, TLS encrypts the connection between the device and the broker. TLS client authentication is
used to identify devices to AWS IoT. For HTTP, TLS encrypts the connection between the device and
the broker. Authentication is delegated to AWS signature version 4.
TLS Cipher Suite Support
AWS IoT supports the following cipher suites:
•
•
•
•
•
•
•
•
•
•
•
ECDHE-ECDSA-AES128-GCM-SHA256 (recommended)
ECDHE-RSA-AES128-GCM-SHA256 (recommended)
ECDHE-ECDSA-AES128-SHA256
ECDHE-RSA-AES128-SHA256
ECDHE-ECDSA-AES128-SHA
ECDHE-RSA-AES128-SHA
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES256-SHA384
ECDHE-RSA-AES256-SHA384
ECDHE-RSA-AES256-SHA
• ECDHE-ECDSA-AES256-SHA
• AES128-GCM-SHA256
• AES128-SHA256
• AES128-SHA
• AES256-GCM-SHA384
• AES256-SHA256
• AES256-SHA
35
AWS IoT Developer Guide
Protocols
Message Broker for AWS IoT
The AWS IoT message broker is a pub/sub broker service that enables sending and receiving messages
to and from AWS IoT. When communicating with AWS IoT, a client sends a message addressed to a
topic like "Sensor/temp/room1." The message broker, in turn, sends the message to all clients that have
registered to receive messages for that topic. The act of sending the message is referred to as publishing.
The act of registering to receive messages for a topic filter is referred to as subscribing.
The topic namespace is isolated for each AWS account and region pair. For example, the
"Sensor/temp/room1" topic for an AWS account is independent from the "Sensor/temp/room1" topic for
another AWS account. This is true of regions, too. The "Sensor/temp/room1" topic in the same AWS
account in us-east-1 is independent from the same topic in us-west-2. AWS IoT does not support sending
and receiving messages across AWS accounts and regions.
The message broker maintains a list of all client sessions and the subscriptions for each session. When
a message is published on a topic, the broker checks for sessions with subscriptions that map to the
topic. The broker then forwards the publish message to all sessions that have a currently connected
client.
Protocols
The message broker supports the use of the MQTT protocol to publish and subscribe and the HTTPS
protocol to publish. Both protocols are supported through IP version 4 and IP version 6. The message
broker also supports MQTT over the WebSocket protocol.
MQTT
MQTT is a widely adopted lightweight messaging protocol designed for constrained devices. For more
information, go to MQTT. Although the AWS IoT message broker implementation is based on MQTT
v3.1.1, it deviates from the specification as follows:
• In AWS IoT, subscribing to a topic with Quality of Service (QoS) 0 means a message will be delivered
zero or more times. A message may be delivered more than once. Messages delivered more than once
may be sent with a different packet ID. In these cases, the DUP flag is not set.
• AWS IoT does not support publishing and subscribing with QoS 2. The AWS IoT message broker does
not send a PUBACK or SUBACK when QoS 2 is requested.
36
AWS IoT Developer Guide
HTTP
• When responding to a connection request, the message broker sends a CONNACK message. This
message contains a flag indicating if the connection is resuming a previous session. The value of this
flag may be incorrect when two MQTT clients connect with the same client ID simultaneously.
• When a client subscribes to a topic, there may be a delay between the time the message broker sends
a SUBACK and the time the client starts receiving new matching messages.
• The MQTT specification provides a provision for the publisher to request that the broker retain the last
message sent to a topic and send it to all future topic subscribers. AWS IoT does not support retained
messages. If a request is made to retain messages, the connection is disconnected.
• The message broker uses the client ID to identify each client. The client ID is passed in from the client
to the message broker as part of the MQTT payload. Two clients with the same client ID are not allowed
to be connected concurrently to the message broker. When a client connects to the message broker
using a client ID that another client is using, a CONNACK message will be sent to both clients and the
currently connected client will be disconnected.
• The message broker does not supports persistent sessions (clean session set to 0). All sessions are
assumed to be clean sessions and messages are not stored across sessions. If an MQTT client sends
a message with the clean session attribute set to false, the client will be disconnected.
• On rare occasions, the message broker may resend the same logical publish message with a different
packet ID.
• The message broker does not guarantee the order in which messages and ACK are received.
HTTP
The message broker supports clients connecting with the HTTP protocol using a REST API. Clients can
publish by sending a POST message to <AWS IoT
Endpoint>/topics/<url_encoded_topic_name>?qos=1".
MQTT over the WebSocket Protocol
AWS IoT supports MQTT over the WebSocket protocol to enable browser-based and remote applications
to send and receive data from AWS IoT-connected devices using AWS credentials. AWS credentials are
specified using AWS signature version 4. For more information, see AWS Signature Version 4. WebSocket
support is available on port tcp:443, which allows messages to pass through most firewalls and web
proxies.
A WebSocket connection is initiated on a client by sending an HTTP GET request. The URL you use is
of the following form:
wss://<endpoint>.iot.<region>.amazonaws.com/mqtt
wss
Specifies the WebSocket protocol.
endpoint
Your AWS account-specific AWS IoT endpoint. You can use the AWS IoT CLI describe-endpoint
command to find this endpoint.
region
The AWS region of your AWS account.
mqtt
Specifies you will be sending MQTT messages over the WebSocket protocol.
When the server responds, the client sends an upgrade request to indicate to the server it will communicate
using the WebSocket protocol. After the server acknowledges the upgrade request, all communication
37
AWS IoT Developer Guide
MQTT over the WebSocket Protocol
is performed using the WebSocket protocol. The WebSocket implementation you use acts as a transport
protocol. The data you send over the WebSocket protocol are MQTT messages.
Using the WebSocket Protocol in a Web Application
The WebSocket implementation provided by most web browsers does not allow the modification of HTTP
headers, so you must add the signature version 4 information to the query string. For more information,
see Adding Signing Information to the Query String.
The following JavaScript defines some utility functions used in generating a signature version 4 request.
/**
* utilities to do sigv4
* @class SigV4Utils
*/
function SigV4Utils(){}
SigV4Utils.sign = function(key, msg){
var hash = CryptoJS.HmacSHA256(msg, key);
return hash.toString(CryptoJS.enc.Hex);
};
SigV4Utils.sha256 = function(msg) {
var hash = CryptoJS.SHA256(msg);
return hash.toString(CryptoJS.enc.Hex);
};
SigV4Utils.getSignatureKey = function(key, dateStamp, regionName, serviceName)
{
var kDate = CryptoJS.HmacSHA256(dateStamp, 'AWS4' + key);
var kRegion = CryptoJS.HmacSHA256(regionName, kDate);
var kService = CryptoJS.HmacSHA256(serviceName, kRegion);
var kSigning = CryptoJS.HmacSHA256('aws4_request', kService);
return kSigning;
};
To create a signature version 4 request
1.
Create a canonical request for signature version 4.
The following JavaScript code creates a canonical request:
var
var
var
var
var
var
var
var
var
var
var
time = moment.utc();
dateStamp = time.format('YYYYMMDD');
amzdate = dateStamp + 'T' + time.format('HHmmss') + 'Z';
service = 'iotdevicegateway';
region = this.options.regionName;
secretKey = this.options.secretKey;
accessKey = this.options.accessKey;
algorithm = 'AWS4-HMAC-SHA256';
method = 'GET';
canonicalUri = '/mqtt';
host = this.options.endpoint;
var credentialScope = dateStamp + '/' + region + '/' + service + '/' +
'aws4_request';
var canonicalQuerystring = 'X-Amz-Algorithm=AWS4-HMAC-SHA256';
38
AWS IoT Developer Guide
MQTT over the WebSocket Protocol
canonicalQuerystring += '&X-Amz-Credential=' + encodeURIComponent(accessKey
+ '/' + credentialScope);
canonicalQuerystring += '&X-Amz-Date=' + amzdate;
canonicalQuerystring += '&X-Amz-SignedHeaders=host';
var canonicalHeaders = 'host:' + host + '\n';
var payloadHash = SigV4Utils.sha256('');
var canonicalRequest = method + '\n' + canonicalUri + '\n' + canonicalQuerys
tring + '\n' + canonicalHeaders + '\nhost\n' + payloadHash;
console.log('canonicalRequest ' + canonicalRequest);
2.
Create a string to sign, generate a signing key, and sign the string.
Take the canonical URL you created in the previous step and assemble it into a string to sign. You
do this by creating a string composed of the hashing algorithm, the date, the credential scope, and
the SHA of the canonical request. Next, generate the signing key and sign the string, as shown in
the following JavaScript code.
var stringToSign = algorithm + '\n' + amzdate + '\n' + credentialScope
+ '\n' + SigV4Utils.sha256(canonicalRequest);
var signingKey = SigV4Utils.getSignatureKey(secretKey, dateStamp, region,
service);
var signature = SigV4Utils.sign(signingKey, stringToSign);
3.
Add the signing information to the request.
The following JavaScript code shows how to add the signing information to the query string.
canonicalQuerystring += '&X-Amz-Signature=' + signature;
var requestUrl = 'wss://' + host + canonicalUri + '?' + canonicalQuerys
tring;
4.
If you have session credentials (from an STS server, AssumeRole, or Amazon Cognito), append the
session token to the end of the URL string after signing:
requestUrl += "&X-Amz-Security-Token=" + encodeURIComponent(sessionToken);
5.
Open the WebSocket.
The following JavaScript code shows how to create a Paho MQTT client and call CONNECT to AWS
IoT.The endpoint argument is your AWS account-specific endpoint.The clientId is a text identifier
that is unique among all clients simultaneously connected in your AWS account.
var client = new Paho.MQTT.Client(endpoint, clientId);
var connectOptions = {
onSuccess: function(){
// connect succeeded
},
39
AWS IoT Developer Guide
Topics
useSSL: true,
timeout: 3,
mqttVersion: 4,
onFailure: function() {
// connect failed
}
};
client.connect(connectOptions);
Using the WebSocket Protocol in a Mobile Application
We recommend using one of the AWS IoT Device SDKs to connect your device to AWS IoT when making
a WebSocket connection. The following AWS IoT Device SDKs support WebSocket-based
MQTT-connections to AWS IoT:
• node.js
• iOS
If you are using a programming or scripting language that is not currently supported, any existing
WebSocket library can be used as long as the initial WebSocket upgrade request (HTTP POST) is signed
using AWS signature version 4. Some MQTT clients, such as Eclipse Paho for JavaScript, support the
WebSocket protocol natively.
Topics
The message broker uses topics to route messages from publishing clients to subscribing clients. The
forward slash (/) is used to separate topic hierarchy. The following tables lists the wildcards that can be
used in the topic filter when subscribing.
Topic Wildcards
Wildcard
Description
#
Must be the last character in the topic to which you
are subscribing. Works as a wildcard by matching
the current tree and all subtrees. For example, a
subscription to "Sensors/#" will receive messages
published to "Sensor/," "Sensor/temp,"
"Sensor/temp/room1," but not the messages published to "Sensor."
+
Matches exactly one item in the topic hierarchy.
For example, a subscription to "Sensors/+/room1"
will receive messages published to
"Sensor/temp/room1," "Sensor/moisture/room1,"
and so on.
Reserved Topics
Any topics beginning with '$' are considered reserved and are not supported for publishing and subscribing
except when working with the Thing Shadows service. For more information, see Thing Shadows.
40
AWS IoT Developer Guide
Granting AWS IoT the Required Access
Rules for AWS IoT
Rules give your things the ability to interact with AWS services. Rules are analyzed and actions are
performed based on the MQTT topic stream. You can use rules to support tasks like these:
•
•
•
•
•
•
•
•
•
•
Augment or filter data received from a device.
Write data received from a device to an Amazon DynamoDB database.
Save a file to Amazon S3.
Send a push notification to all users using Amazon SNS.
Publish data to an Amazon SQS queue.
Invoke a Lambda function to extract data.
Process messages from a large number of devices using Amazon Kinesis.
Send data to the Amazon Elasticsearch Service.
Capture a CloudWatch metric.
Change a CloudWatch alarm.
Before AWS IoT can perform these actions, you must grant it permission to access your AWS resources
on your behalf. When the actions are performed, you incur the standard charges for the AWS services
you use.
Contents
• Granting AWS IoT the Required Access (p. 41)
• Creating an AWS IoT Rule (p. 43)
• Viewing Your Rules (p. 45)
• Troubleshooting a Rule (p. 46)
• Deleting a Rule (p. 46)
• AWS IoT Rule Actions (p. 46)
• AWS IoT SQL Reference (p. 54)
Granting AWS IoT the Required Access
You use IAM roles to control the AWS resources to which each rule has access. Before you create a rule,
you must create an IAM role with a policy that allows access to the required AWS resources. AWS IoT
assumes this role when executing a rule.
41
AWS IoT Developer Guide
Granting AWS IoT the Required Access
To create an IAM role (AWS CLI)
1.
Save the following trust policy document, which grants AWS IoT permission to assume the role, to
a file called iot-role-trust.json:
{
"Version":"2012-10-17",
"Statement":[{
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}]
}
Use the create-role command to create an IAM role specifying the iot-role-trust.json file:
aws iam create-role --role-name my-iot-role --assume-role-policy-document
file://iot-role-trust.json
The output of this command will look like the following:
{
"Role": {
"AssumeRolePolicyDocument": "url-encoded-json",
"RoleId": "AKIAIOSFODNN7EXAMPLE",
"CreateDate": "2015-09-30T18:43:32.821Z",
"RoleName": "my-iot-role",
"Path": "/",
"Arn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
2.
Save the following JSON into a file called iot-policy.json.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "dynamodb:*",
"Resource": "*"
}]
}
This JSON is an example policy document that grants AWS IoT administrator access to DynamoDB.
Use the create-policy command to grant AWS IoT access to your AWS resources upon assuming
the role, passing in the iot-policy.json file:
aws iam create-policy --policy-name my-iot-policy --policy-document file://myiot-policy-document.json
42
AWS IoT Developer Guide
Creating an AWS IoT Rule
For more information about how to grant access to AWS services in policies for AWS IoT, see Creating
an AWS IoT Rule (p. 43).
The output of the create-policy command will contain the ARN of the policy. You will need to attach
the policy to a role.
{
"Policy": {
"PolicyName": "my-iot-policy",
"CreateDate": "2015-09-30T19:31:18.620Z",
"AttachmentCount": 0,
"IsAttachable": true,
"PolicyId": "ZXR6A36LTYANPAI7NJ5UV",
"DefaultVersionId": "v1",
"Path": "/",
"Arn": "arn:aws:iam::123456789012:policy/my-iot-policy",
"UpdateDate": "2015-09-30T19:31:18.620Z"
}
}
3.
Use the attach-role-policy command to attach your policy to your role:
aws iam attach-role-policy --role-name my-iot-role --policy-arn
"arn:aws:iam::123456789012:policy/my-iot-policy"
Creating an AWS IoT Rule
You configure rules to route data from your connected things. Rules consist of the following:
Rule name
The name of the rule.
Optional description
A textual description of the rule.
SQL statement
A simplified SQL syntax to filter messages received on an MQTT topic and push the data elsewhere.
For more information, see AWS IoT SQL Reference (p. 54).
One or more actions
The actions AWS IoT performs when executing the rule. For example, you can insert data in a
DynamoDB table, write data to an Amazon S3 bucket, publish to an Amazon SNS topic, or invoke a
Lambda function.
When you create a rule, be aware of how much data you are publishing on topics. If you create rules that
include a wildcard topic pattern, they might match a large percentage of your messages, and you might
need to increase the capacity of the AWS resources used by the target actions. Also, if you create a
republish rule that includes a wildcard topic pattern, you can end up with a circular rule that causes an
infinite loop.
Note
Creating and updating rules are administrator-level actions. Any user who has permission to
create or update rules will be able to access data processed by the rules.
To create a rule (AWS CLI)
43
AWS IoT Developer Guide
Creating an AWS IoT Rule
Use the create-topic-rule command to create a rule:
aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://myrule.json
The following is an example payload file with a rule that inserts all messages sent to the iot/test topic into
the specified DynamoDB table. The SQL statement filters the messages, and the role ARN grants AWS
IoT permission to write to the DynamoDB table.
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"actions": [{
"dynamoDB": {
"tableName": "my-dynamodb-table",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
"hashKeyField": "topic",
"hashKeyValue": "${topic(2)}",
"rangeKeyField": "timestamp",
"rangeKeyValue": "${timestamp()}"
}
}]
}
The following is an example payload file with a rule that pushes data to Elasticsearch:
{
"sql":"SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled":false,
"actions":[
{
"elasticsearch":{
"roleArn":"arn:aws:iam::123456789012:role/aws_iot_es",
"endpoint":"https://my-endpoint",
"index":"my-index",
"type":"my-type",
"id":"${newuuid()}"
}
}
]
}
The following is an example payload file with a rule that invokes a Lambda function:
{
"sql": "expression",
"ruleDisabled": false,
"actions": [{
"lambda": {
"functionArn": "arn:aws:lambda:us-west-2:123456789012:function:mylambda-function"
}
}]
}
44
AWS IoT Developer Guide
Viewing Your Rules
The following is an example payload file with a rule that publishes to an Amazon SNS topic:
{
"sql": "expression",
"ruleDisabled": false,
"actions": [{
"sns": {
"targetArn": "arn:aws:sns:us-west-2:123456789012:my-sns-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}]
}
The following is an example payload file with a rule that republishes on a different MQTT topic:
{
"sql": "expression",
"ruleDisabled": false,
"actions": [{
"republish": {
"topic": "my-mqtt-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}]
}
The following is an example payload file with a rule that pushes data to an Amazon Kinesis Firehose
stream:
{
"sql": "SELECT * FROM 'my-topic'",
"ruleDisabled": false,
"actions": [{
"firehose": {
"roleArn": ""arn:aws:iam::123456789012:role/my-iot-role",
"deliveryStreamName": "my-stream-name"
}
}]
}
Viewing Your Rules
Use the list-topic-rules command to list your rules:
aws iot list-topic-rules
Use the get-topic-rule command to get information about a rule:
aws iot get-topic-rule --rule-name my-rule
45
AWS IoT Developer Guide
Troubleshooting a Rule
Troubleshooting a Rule
If you are having an issue with your rules, you should enable CloudWatch Logs. By analyzing your logs,
you can determine whether the issue is authorization or whether, for example, a WHERE clause condition
did not match. For more information, see Troubleshooting AWS IoT (p. 121).
Deleting a Rule
When you are finished with a rule, you can delete it.
To delete a rule (AWS CLI)
Use the delete-topic-rule command to delete a rule:
aws iot delete-topic-rule --rule-name my-rule
AWS IoT Rule Actions
AWS IoT rule actions are used to specify what to do when a rule is triggered. You can define actions to
write data to a DynamoDB database or an Amazon Kinesis stream or to invoke a Lambda function, and
more. The following actions are supported:
• cloudwatchAlarm to change a CloudWatch alarm.
• cloudwatchMetric to capture a CloudWatch metric.
• dynamoDB to write data to a DynamoDB database.
• elasticsearch to write data to a Amazon Elasticsearch Service domain.
• kinesis to write data to a Amazon Kinesis stream.
• lambda to invoke a Lambda function.
• s3 to write data to a Amazon S3 bucket.
• sns to write data as a push notification.
• firehose to write data to an Amazon Kinesis Firehose stream.
• sqs to write data to an SQS queue.
• republish to republish the message on another MQTT topic.
The following sections discuss each action in detail.
CloudWatch Alarm Action
The CloudWatch alarm action allows you to change CloudWatch alarm state. You can specify the state
change reason and value in this call. When creating an AWS IoT rule with a CloudWatch alarm action,
you must specify the following information:
roleArn
The IAM role that allows access to the CloudWatch alarm.
alarmName
The CloudWatch alarm name.
stateReason
Reason for the alarm change.
46
AWS IoT Developer Guide
CloudWatch Metric Action
stateValue
The value of the alarm state. Acceptable values are OK, ALARM, INSUFFICIENT_DATA.
Note
Ensure the role associated with the rule has a policy granting the cloudwatch:SetAlarmState
permission.
The following JSON example shows how to define a CloudWatch alarm action in an AWS IoT rule:
{
"rule": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"actions": [{
"cloudwatchAlarm": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw",
"alarmName": "IotAlarm",
"stateReason": "Temperature stabilized.",
"stateValue": "OK"
}
}]
}
}
For more information, see CloudWatch Alarms.
CloudWatch Metric Action
The CloudWatch metric action allows you to capture a CloudWatch metric. You can specify the metric
namespace, name, value, unit, and timestamp. When creating an AWS IoT rule with a CloudWatch metric
action, you must specify the following information:
roleArn
The IAM role that allows access to the CloudWatch alarm.
metricNamespace
CloudWatch metric namespace name.
metricName
The CloudWatch metric name.
metricValue
The CloudWatch metric value.
metricUnit
The metric unit supported by CloudWatch.
metricTimestamp
An optional Unix timestamp.
Note
Ensure the role associated with the rule has a policy granting the cloudwatch:PutMetricData
permission.
The following JSON example shows how to define a CloudWatch metric action in an AWS IoT rule:
{
"rule": {
47
AWS IoT Developer Guide
DynamoDB Action
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"actions": [{
"cloudwatchMetric": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw",
"metricNamespace": "IotNamespace",
"metricName": "IotMetric",
"metricValue": "1",
"metricUnit": "Count",
"metricTimestamp": "1456821314"
}
}]
}
}
For more information, see CloudWatch Metrics.
DynamoDB Action
The dynamoDB action allows you to write all or part of an MQTT message to a DynamoDB table. When
creating a DynamoDB rule, you must specify the following information:
hashKeyField
The name of the hash key (also called the partition key).
hashKeyValue
The value of the hash key.
rangeKeyField
The name of the range key (also called the sort key).
rangeKeyValue
The value of the range key.
payloadField
Optional. The name of the field where the payload will be written. If this value is omitted, the payload
is written to payload field.
table
The name of the DynamoDB table.
roleARN
The IAM role that allows access to the DynamoDB table. At a minimum, the role must allow the
dynamoDB:PutItem IAM action.
The data written to the DynamoDB table is the result from the SQL statement of the rule. The
hashKeyValue and rangeKeyValue fields are usually composed of expressions (for example, “${topic()}”
or “${timestamp()}").
Note
Non-JSON data is written to DynamoDB as binary data. The DynamoDB console will display
the data as Base64-encoded text.
Ensure the role associated with the rule has a policy granting the dynamodb:PutItem permission.
The following JSON example shows how to define a dynamoDB action in an AWS IoT rule:
{
"rule": {
"ruleDisabled": false,
"sql": "SELECT * AS message FROM 'some/topic'",
48
AWS IoT Developer Guide
Elasticsearch Action
"description": "A test Dynamo DB rule",
"actions": [{
"dynamoDB": {
"hashKeyField": "key",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDB",
"tableName": "my_ddb_table",
"hashKeyValue": "${topic()}",
"rangeKeyValue": "${timestamp()}",
"rangeKeyField": "timestamp"
}
}]
}
}
For more information, see the Amazon DynamoDB Getting Started Guide.
Elasticsearch Action
The elasticsearch action allows you to write data from MQTT messages to an Amazon Elasticsearch
Service domain. Data in Elasticsearch can then be queried and visualized by using tools like Kibana.
When you create an AWS IoT rule with an elasticsearch action, you must specify the following
information:
endpoint
The endpoint of your Elasticsearch domain.
index
The Elasticsearch index where you want to store your data.
type
The type of document you are storing.
id
The unique identifier for each document.
Note
Ensure the role associated with the rule has a policy granting the es:ESHttpPut permission.
The following JSON example shows how to define an elasticsearch action in an AWS IoT rule:
{
"rule":{
"sql":"SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled":false,
"actions":[
{
"elasticsearch":{
"roleArn":"arn:aws:iam::123456789012:role/aws_iot_es",
"endpoint":"https://my-endpoint",
"index":"my-index",
"type":"my-type",
"id":"${newuuid()}"
}
}
]
49
AWS IoT Developer Guide
Kinesis Action
}
}
For more information, see the Elasticsearch Developer Guide.
Kinesis Action
The kinesis action allows you to write data from MQTT messages into an Amazon Kinesis stream.
When creating an AWS IoT rule with a kinesis action, you must specify the following information:
stream
The Amazon Kinesis stream to which to write data.
partitionKey
The partition key used to determine to which shard the data is written. The partition key is usually
composed of an expression (for example, “${topic()}” or “${timestamp()}").
Note
Ensure that the policy associated with the rule has the kinesis:PutRecord permission.
The following JSON example shows how to define a kinesis action in an AWS IoT rule:
{
"rule": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"actions": [{
"kinesis": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_kinesis",
"streamName": "my_kinesis_stream",
"partitionKey": "${topic()}"
}
}],
}
}
For more information, see the Amazon Kinesis Developer Guide.
Lambda Action
A lambda action calls a Lambda function, passing in the MQTT message that triggered the rule. In order
for AWS IoT to call a Lambda function, you must configure a policy granting the lambda:InvokeFunction
permission to AWS IoT. Lambda functions use resource-based policies, so you must attach the policy to
the Lambda function itself. Use the following CLI command to attach a policy granting
lambda:InvokeFunction permission:
aws lambda add-permission --function-name "function_name" --region "region" -principal iot.amazonaws.com --source-arn arn:aws:iot:us-east-1:ac
count_id:rule/rule_name --source-account "account_id" --statement-id "unique_id"
--action "lambda:InvokeFunction"
The following are the parameters for the add-permission command:
50
AWS IoT Developer Guide
S3 Action
--function-name
Name of the Lambda function whose resource policy you are updating by adding a new permission.
--region
The AWS region of your account.
--principal
The principal who is getting the permission. This should be iot.amazonaws.com to allow AWS IoT
permission to call a Lambda function.
--source-arn
The ARN of the rule. You can use the get-topic-rule CLI command to get the ARN of a rule.
--source-account
The AWS account where the rule is defined.
--statement-id
A unique statement identifier.
--action
The Lambda action you want to allow in this statement. In this case, we want to allow AWS IoT to
invoke a Lambda function, so we specify lambda:InvokeFunction.
For more information, see Lambda Permission Model.
When creating a rule with a lambda action, you must specify the Lambda function to invoke when the
rule is triggered.
The following JSON example shows a rule that calls a Lambda function:
{
"rule": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"actions": [{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-1:123456789012:func
tion:myLambdaFunction"
}
}]
}
}
For more information, see the AWS Lambda Developer Guide.
S3 Action
A s3 action writes the data from the MQTT message that triggered the rule to an Amazon S3 bucket.
When creating an AWS IoT rule with an s3 action, you must specify the following information:
bucket
The Amazon S3 bucket to which to write data.
key
The path to the file where the data is written. For example, if the value of this parameter is "${topic()}"
and the topic the message was sent to is "this/is/my/topic," the data will be written to a file called
"topic" in the "this/is/my" folder on Amazon S3.
roleArn
The IAM role that allows access to the Amazon S3 bucket.
51
AWS IoT Developer Guide
SNS Action
Note
Ensure the role associated with the rule has a policy granting the s3:PutObject permission.
The following JSON example shows how to define an s3 action in an AWS IoT rule:
{
"rule": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"actions": [{
"s3": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3",
"bucketName": "my-bucket",
"key": "${topic()}"
}
}]
}
}
For more information, see the Amazon S3 Developer Guide.
SNS Action
A sns action sends the data from the MQTT message that triggered the rule as an SNS push notification.
When creating a rule with an sns action, you must specify the following information:
targetArn
The SNS topic or individual device to which the push notification will be sent.
roleArn
The IAM role that allows access to SNS.
Note
Ensure that the policy associated with the rule has the sns:Publish permission.
The following JSON example shows how to define an sns action in an AWS IoT rule:
{
"rule": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"actions": [{
"sns": {
"targetArn": "arn:aws:sns:us-east-1:123456789012:my_sns_topic",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sns"
}
}]
}
}
For more information, see the Amazon SNS Developer Guide.
52
AWS IoT Developer Guide
Firehose Action
Firehose Action
A firehose action sends data from an MQTT message that triggered the rule to an Firehose stream.
When creating a rule with a firehose action, you must specify the following information:
deliveryStreamName
The Firehose stream to which to write the message data.
roleArn
The IAM role that allows access to Firehose.
Note
Ensure the role associated with the rule has a policy granting the firehose:PutRecord
permission.
The following JSON example shows how to create an AWS IoT rule with a firehose action:
{
"rule": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"actions": [{
"firehose": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_firehose",
"deliveryStreamName": "my_firehose_stream"
}
}]
}
}
For more information, see the Firehose Developer Guide.
SQS Action
A sqs action sends data from the MQTT message that triggered the rule to an SQS queue. When creating
a rule with an sqs action, you must specify the following information:
queueUrl
The URL of the SQS queue to which to write the data.
useBase64
Set to true if you want the MQTT message data to be Base64-encoded before writing to the SQS
queue; otherwise, set to false.
roleArn
The IAM role that allows access to the SQS queue.
Note
Ensure the role associated with the rule has a policy granting the sqs:SendMessage permission.
The following JSON example shows how to create an AWS IoT rule with an sqs action:
{
"rule": {
"sql": "SELECT * FROM 'some/topic'",
53
AWS IoT Developer Guide
Republish Action
"ruleDisabled": false,
"actions": [{
"sqs": {
"queueUrl": "https://sqs.us-east-1.amazon
aws.com/123456789012/my_sqs_queue",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sqs",
"useBase64": false
}
}]
}
}
For more information, see the Amazon SQS Developer Guide.
Republish Action
The republish action allows you to republish the message that triggered the role to another MQTT
topic. When creating a rule with a republish action, you must specify the following information:
topic
The MQTT topic to which to republish the message.
roleArn
The IAM role that allows publishing to the MQTT topic.
Note
Ensure the role associated with the rule has a policy granting the iot:Publish permission.
{
"rule": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"actions": [{
"republish": {
"topic": "another/topic",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish"
}
}]
}
}
AWS IoT SQL Reference
This reference focuses on the differences between ANSI SQL and AWS IoT SQL. If you are not familiar
with ANSI SQL, see the W3Schools SQL Tutorial.
All rules include a SQL statement that consists of a SELECT clause and an optional WHERE clause. The
SELECT clause allows you to extract one or more JSON objects or attributes from the MQTT message
payload. The WHERE clause allows you to filter the JSON objects or attributes extracted by the SELECT
clause.
All data processed by a SELECT query is assumed to be in JSON format. The JSON document may
contain either a single root object or a single root object with nested objects.
54
AWS IoT Developer Guide
Expressions
As with ANSI SQL, white space is insignificant and keywords are not case-sensitive. Strings and JSON
properties are case-sensitive. In our examples, all keywords are capitalized following common practice
for SQL.
Expressions
Select, FROM, and WHERE clauses are all composed of expressions. The following expressions are
allowed in AWS IoT.
Token
Meaning
Example
=
Equal, comparison color = 'red'
<>
Not equal, compar- color <> 'red'
ison
AND
Logical AND
color = 'red' AND siren = 'on'
OR
Logical OR
color = 'red' OR siren = 'on'
()
Parenthesis,
grouping
color = 'red' AND (siren = 'on' OR isTest)
$
Dollar sign, used in "$$aws/things/mything/shadow/update/accepted"
reserved topic
names. When specifying a reserved
topic name in a
substitution template, the '$' must
be escaped using
another '$'
+
Addition, arithmetic 4 + 5
-
Subtraction, arithmetic
/
Division, arithmetic 20 / 4
*
Multiplication,
arithmetic
5*4
%
Modulo division,
arithmetic
20 % 6
<
Less than, compar- 5 < 6
ison
<=
Less than or equal, 5 <= 6
comparison
>
Greater than, com- 6 > 5
parison
>=
Greater than or
6 >= 5
equal, comparison
Function call
A invocation of an
SQL function
5-4
clientId()
55
AWS IoT Developer Guide
SELECT Clause
Token
Meaning
Example
A JSON extension An expression that state.desired.color
expression
selects a specific
value in a JSON
document.
CASE ... WHEN ... Case statement
CASE location WHEN 'home'
THEN ... ELSE ...
THEN 'off' WHEN 'work'
END
THEN 'on' ELSE 'silent' END
IN
A binary operator
that determines if
an element exists
in an array.
'foo' IN array, or 'foo' IN (SELECT * FROM array AS a WHERE
a > 0)
EXISTS
A unary operator
that determines if
an attribute exists.
EXISTS (SELECT * FROM array AS a WHERE a > 0) returns
True if the array contains an element with a value greater
than zero.
EXISTS foo returns True if the attribute foo exists, even if it
has a NULL value.
VALUE
Used in a SELECT Given input: {“arr”:[{“a”:1},{“b”:2}]}
clause to select the
value of an attrib- SELECT VALUE (SELECT VALUE b FROM arr WHERE b =
2) FROM ‘a/b’ returns the value 2.
ute.
SELECT Clause
The AWS IoT SELECT clause is essentially the same as the ANSI SQL SELECT clause, with a few minor
differences. The "AS" keyword is required with AWS IoT SELECT clauses unless you are using JSON
extensions ('.' syntax), for example:
SELECT state.temperature FROM 'mydevices/device1'
For more information about JSON extensions, see JSON Extensions (p. 60).
Unlike querying relational databases, you can use SELECT * without the concern of retrieving too much
information. The information returned by the SELECT * AS some_name clause contains only the JSON
payload of the MQTT message. The message can be returned without parsing, which possibly improves
performance of the query. SELECT queries for a single object JSON document are of the form: SELECT
<object> AS <object-name>. The <object> can be any object or attribute name in the JSON document.
<object-name> provides a name for the result of the SELECT query. SELECT queries for JSON documents
with nested objects are of the form: SELECT <object> where <object> is the root object, any level of
nested objects, and an optional attribute. For example:
• object
• object.nestedObject
• object.nestedObject1.nestedObject2
• object.nestedObject1.nestedObject2.attribute
You can specify as many layers of nested objects as there are in the JSON document.
56
AWS IoT Developer Guide
FROM Clause
FROM Clause
In ANSI SQL, you select data from tables. In AWS IoT SQL, you select data from JSON properties in
MQTT messages.
The data source, which is the topic to which MQTT messages are sent, is specified using the MQTT()
function, as shown in this example:
SELECT * FROM mqtt('com.example/sensors/+')
However, the FROM clause assumes you are querying an MQTT message, so you can omit the call to
the mqtt() function and specify only the topic name, as shown in the following example:
SELECT * FROM 'com.example/sensors'
WHERE Clause
The WHERE clause filters the message data returned by the SELECT clause based on JSON attribute
values. For example, suppose you have a topic filter from an MQTT topic, iot/thing/#. The following
is an example JSON payload that could be published by a device:
{
"deviceid" : "iot123",
"temp" : 54.98,
"humidity" : 32.43,
"coords" : {
"latitude" : 47.615694,
"longitude" : -122.3359976
}
}
You could use the following SQL statement in your rule to query the iot/thing/# topic and extract the
sensor data when the temp field is above 50.
SELECT * FROM 'iot/thing/#' WHERE temp > 50
Functions
You can use the following built-in functions in the SELECT or WHERE clauses of your SQL expressions.
Function
Description
abs(number)
Returns the absolute value.
accountId()
Returns the account ID of the MQTT client sending
the message, or undefined if the message didn't
come through MQTT.
asin(number)
Returns the arcsine.
atan(number)
Returns the arctangent.
bitand(number1, number2)
Returns the result of a bitwise AND operation.
57
AWS IoT Developer Guide
Functions
Function
Description
cast(value as type)
Converts the value to the specified data type.
Supported data types are:
double
converts the value to a double.
float
converts the value to a double.
int
converts the value to an integer.
integer
converts the value to an integer.
ntext
converts the value to a string.
num
converts the value to a double.
number
converts the value to a double.
nvarchar
converts the value to a string.
string
converts the value to a string.
text
converts the value to a string.
varchar
converts the value to a string.
ceil(number)
Returns the result of rounding up to the nearest
integer.
chr(number)
Returns the ASCII character represented by number.
clientId()
Returns the client ID of the MQTT client sending
the message, or undefined if the message didn't
come through MQTT.
concat(string1, string2)
Returns the concatenation of two strings.
cos(number)
Returns the cosine.
cosh(number)
Returns the hyperbolic cosine.
endswith(input, suffix)
Returns true if input ends with suffix.
exp(number)
Returns e to the power of the specified number.
floor(number)
Returns the result of rounding down to the nearest
integer.
ln(number)
Returns the natural logarithm.
log(n, m)
Returns the logarithm of n base m.
58
AWS IoT Developer Guide
Functions
Function
Description
lower(string)
Returns the result of converting all characters to
lowercase.
lpad(string, n)
Adds n spaces to the left side of string.
ltrim(string)
Removes all white space from the left side of string.
md2(string)
Returns the MD2 hash value.
md5(string)
Returns the MD5 hash value.
mod(m, n)
Returns the remainder of m divided by n.
nanvl(value, default)
Returns value if it's non-null, and default otherwise.
payload(textEncoding)
Gets the payload of the MQTT message decoded
as the specified text encoding (defaults to UTF-8).
power(m, n)
Returns m raised to the nth power.
remainder(m, n)
Returns the remainder of m divided by n.
replace(source, substring, replacement)
Returns source with all occurrences of substring
replaced by replacement.
round(number, precision)
Returns the result of rounding number to precision
decimal places. If precision is 0, the function rounds
to the nearest whole number.
rpad(string, n)
Adds n spaces to the right side of string.
rtrim(string)
Removes all white space from the right side of
string.
sign(number)
Returns a value indicating the sign of a number. If
number < 0, then -1. Else, if number = 0, then 0.
Else, if number > 0, then 1.
sin(number)
Returns the sine.
sinh(number)
Returns the hyperbolic sine.
split(string, [sep = ','])
Splits a string using the specified separator. The
default separator is ','.
sqrt(number)
Returns the square root.
startswith(input, prefix)
Returns true if input starts with prefix.
tan(number)
Returns the tangent.
tanh(number)
Returns the hyperbolic tangent.
traceId()
Returns the trace ID of the MQTT message, or
undefined if the message didn't come through
MQTT.
topic(number)
Returns the specified topic segment. For example,
if the topic is foo/bar, topic() returns "foo/bar", topic(1) returns "foo" and topic(2) returns "bar".
59
AWS IoT Developer Guide
JSON Extensions
Function
Description
trunc(number, precision)
Returns the result of truncating number to precision
decimal places.
upper(string)
Returns the result of converting all characters to
uppercase.
sha1(string)
Returns the SHA-1 hash value.
sha224(string)
Returns the SHA-224 hash value.
sha256(string)
Returns the SHA-256 hash value.
sha512(string)
Returns the SHA-512 hash value.
rand()
Returns a random number between 0 and 1.
newuuid()
Returns a random 16-byte UUID.
timestamp()
Returns the current Unix timestamp, as observed
by the current server.
JSON Extensions
You can use the following extensions to ANSI SQL syntax to make it easier to work with nested JSON
objects.
"." Operator
This operator accesses members in embedded JSON objects and functions identically to ANSI SQL and
JavaScript.
"*" Operator
This functions exactly like the * wildcard in ANSI SQL. It's used in the SELECT clause only and creates
a new JSON object.
Applying a Function to an Attribute Value
The following is an example JSON payload that could be published by a device:
{
"deviceid" : "iot123",
"temp" : 54.98,
"humidity" : 32.43,
"coords" : {
"latitude" : 47.615694,
"longitude" : -122.3359976
}
}
The following example applies a function to an attribute value in a JSON payload:
SELECT temp, md5(deviceid) AS hashed_id FROM topic/#
The result of this query is the following JSON object:
60
AWS IoT Developer Guide
Substitution Templates
{
"temp": 54.98,
"hashed_id": "e37f81fb397e595c4aeb5645b8cbbbd1"
}
Substitution Templates
You can use a substitution template to augment the JSON data returned when a rule is triggered and
AWS IoT performs an action. The syntax for a substitution template is ${expression}, where expression
can be any expression supported by AWS IoT in SELECT or WHERE clauses. For more information
about supported expressions, see Expressions (p. 55).
Substitution templates appear in the SELECT clause within a rule, for example:
{
"sql": "SELECT *, topic() AS topic FROM 'my/iot/topic'",
"ruleDisabled": false,
"actions": [{
"republish": {
"topic": "${topic()}",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}]
}
If this rule is triggered by the following JSON:
{
"deviceid" : "iot123",
"temp" : 54.98,
"humidity" : 32.43,
"coords" : {
"latitude" : 47.615694,
"longitude" : -122.3359976
}
Here is the output of the rule:
{
"coords":{
"longitude":-122.3359976,
"latitude":47.615694
},
"humidity":32.43,
"temp":54.98,
"deviceid":"iot123",
"topic":"my/iot/topic"
}
61
AWS IoT Developer Guide
Device Shadows Data Flow
Device Shadows for AWS IoT
A thing shadow (sometimes referred to as a device shadow) is a JSON document that is used to store
and retrieve current state information for a thing (device, app, and so on). The Thing Shadows service
maintains a thing shadow for each thing you connect to AWS IoT. You can use thing shadows to get and
set the state of a thing over MQTT or HTTP, regardless of whether the thing is connected to the Internet.
Each thing shadow is uniquely identified by its name.
Contents
• Device Shadows Data Flow (p. 62)
• Device Shadows Documents (p. 67)
• Using Device Shadows (p. 70)
• Device Shadow RESTful API (p. 80)
• Device Shadow MQTT Pub/Sub Messages (p. 82)
• Device Shadow Document Syntax (p. 88)
• Device Shadow Error Messages (p. 90)
Device Shadows Data Flow
The Thing Shadows services acts as an intermediary, allowing devices and applications to retrieve and
update thing shadows.
To illustrate how devices and applications communicate with the Thing Shadows service, this section
walks you through the use of the MQTT.fx MQTT client and the AWS CLI to simulate communication
between an internet-connected light bulb, an application, and the Thing Shadows service. For more
information about how to use and configure MQTT.fx to work with AWS IoT, see Verify MQTT Subscribe
and Publish (p. 7).
The Thing Shadows service uses a number of MQTT topics to facilitate communication between
applications and devices. To see how this works, use MQTT.fx to subscribe to the following MQTT topics
with QoS 1:
$aws/things/myLightBulb/shadow/update/accepted
The Thing Shadows service sends messages to this topic when an update is successfully made to
a thing shadow.
62
AWS IoT Developer Guide
Device Shadows Data Flow
$aws/things/myLightBulb/shadow/update/rejected
The Thing Shadows service sends messages to this topic when an update to a thing shadow is
rejected.
$aws/things/myLightBulb/shadow/update/delta
The Thing Shadows service sends messages to this topic when a difference is detected between
the reported and desired sections of a thing shadow.
$aws/things/myLightBulb/shadow/get/accepted
The Thing Shadows service sends messages to this topic when a request for a thing shadow is made
successfully.
$aws/things/myLightBulb/shadow/get/rejected
The Thing Shadows service sends messages to this topic when a request for a thing shadow is
rejected.
To learn more about all of the MQTT topics used by the Thing Shadows service, see Device Shadow
MQTT Pub/Sub Messages (p. 82).
Note
We recommend you subscribe to the .../rejected topics to see any errors sent by the Thing
Shadows service.
When the light bulb comes online, it sends its current state to the Thing Shadows service by sending an
MQTT message to the $aws/things/myLightBulb/shadow/update topic.
To simulate this, use MQTT.fx to publish the following message to the
$aws/things/myLightbulb/shadow/update topic:
{
"state": {
"reported": {
"color": "red"
}
}
}
The Thing Shadows service responds by sending the following message to the
$aws/things/myLightBulb/shadow/update/accepted topic:
{
"state":{
"reported":{
"color":"red"
}
},
"metadata":{
"reported":{
"color":{
"timestamp":1447437304
}
}
},
"version":1,
"timestamp":1447437304
}
This message indicates the Thing Shadows service received the update request and updated the thing
shadow. If the thing shadow doesn't exist, it is created. Otherwise, the thing shadow is updated with the
63
AWS IoT Developer Guide
Device Shadows Data Flow
data in the message. If you don't see a message published to
$aws/things/myLightBulb/shadow/update/accepted, check the subscription to
$aws/things/myLightBulb/shadow/update/rejected to see any error messages.
An application that interacts with the light bulb comes online and requests the light bulb's current state.
The application sends an empty message to the $aws/things/myLightBulb/shadow/get topic. To
simulate this, use MQTT.fx to publish an empty message ("") to the
$aws/things/myLightBulb/shadow/get topic.
The Thing Shadows service responds by publishing the requested thing shadow to the
$aws/things/myLightBulb/shadow/get/accepted topic:
{
"state":{
"reported":{
"color":"red"
}
},
"metadata":{
"reported":{
"color":{
"timestamp":1447437304
}
}
},
"version":1,
"timestamp":1447437398
}
If you don't see a message on the $aws/things/myLightBulb/shadow/get/accepted topic, check
the $aws/things/myLightBulb/shadow/get/rejected topic for any error messages.
The application displays this information to the user, and the user requests a change to the light bulb's
color (from red to green). To do this, the application publishes a message on the
$aws/things/myLightBulb/shadow/update topic:
{
"state": {
"desired": {
"color": "green"
}
}
}
To simulate this, use MQTT.fx to publish the preceding message to the
$aws/things/myLightBulb/shadow/update topic.
The Thing Shadows service responds by sending a message to the
$aws/things/myLightBulb/shadow/update/accepted topic:
{
"state":{
"desired":{
"color":"green"
}
},
64
AWS IoT Developer Guide
Device Shadows Data Flow
"metadata":{
"desired":{
"color":{
"timestamp":1447437647
}
}
},
"version":2, "timestamp":1447437647 }
and to the $aws/things/myLightBulb/shadow/update/delta topic:
{
"version":2,
"timestamp":1447437647,
"state":{
"color":"green"
},
"metadata":{
"color":{
"timestamp":1447437647
}
}
}
The light bulb is subscribed to the $aws/things/myLightBulb/shadow/update/delta topic, so it
receives the message, changes its color, and publishes its new state. To simulate this, use MQTT.fx
publish the following message to update the shadow state:
{
"state":{
"reported":{
"color":"green"
},
"desired":null}
}
}
In response, the Thing Shadows service sends a message to the
$aws/things/myLightBulb/shadow/update/accepted topic:
{
"state":{
"reported":{
"color":"green"
}
},
"metadata":{
"reported":{
"color":{
"timestamp":1447437894
}
}
},
"version":3, "timestamp":1447437894 }
65
AWS IoT Developer Guide
Device Shadows Data Flow
The app requests the current state from the Thing Shadows service and displays the most recent state
data. To simulate this, run the following command:
aws iot-data get-thing-shadow --thing-name "myLightBulb" "output.txt" && cat
"output.txt"
The Thing Shadows service returns the thing shadow document:
{
"state":{
"reported":{
"color":"green"
}
},
"metadata":{
"reported":{
"color":{
"timestamp":1447437894
}
}
},
"version":3,
"timestamp":1447438044
}
If you want to determine if a device is currently connected, include a connected setting in the thing shadow
and use an MQTT Last Will and Testament (LWT) message that will set the connected setting to false
if a device is disconnected due to error.
Note
Currently, LWT messages sent to AWS IoT reserved topics (topics that begin with $) are ignored.
To work around this issue, register an LWT message to a non-reserved topic and create a rule
that republishes the message on the reserved topic. The following example shows how to create
a republish rule that listens for a messages from the my/things/myLightBulb/update topic
and republishes it to $aws/things/myLightBulb/shadow/update.
{
"rule": {
"ruleDisabled": false,
"sql": "SELECT * FROM 'my/things/myLightBulb/update'",
"description": "Turn my/things/ into $aws/things/",
"actions": [{
"republish": {
"topic": "$$aws/things/myLightBulb/shadow/update",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish"
}
}]
}
}
When a device connects, it registers an LWT that sets the connected setting to false:
{
"reported":
66
AWS IoT Developer Guide
Device Shadows Documents
{
"connected":"false"
}
}
It also publishes a message on its update topic ($aws/things/myLightBulb/shadow/update), setting
its connected state to true:
{
"reported":
{
"connected":"true"
}
}
When the device disconnects gracefully, it publishes a message on its update topic and sets its connected
state to true:
{
"reported":
{
"connected":"false"
}
}
If the device disconnects due to an error, its LWT message is posted automatically to the update topic.
Device Shadows Documents
The Thing Shadows service respects all rules of the JSON specification. Values, objects, and arrays are
stored in the thing shadow document.
Contents
• Document Properties (p. 67)
• Versioning of a Thing Shadow (p. 68)
• Client Token (p. 68)
• Example Document (p. 68)
• Empty Sections (p. 69)
• Arrays (p. 70)
Document Properties
A thing shadow document has the following properties:
state
desired
The desired state of the thing. Applications can write to this portion of the document to update
the state of a thing without having to directly connect to a thing.
67
AWS IoT Developer Guide
Versioning of a Thing Shadow
reported
The reported state of the thing. Things write to this portion of the document to report their new
state. Applications read this portion of the document to determine the state of a thing.
metadata
Information about the data stored in the state section of the document. This includes timestamps,
in Epoch time, for each attribute in the state section, which enables you to determine when they
were updated.
timestamp
Indicates when the message was transmitted by AWS IoT. By using the timestamp in the message
and the timestamps for individual attributes in the desired or reported section, a thing can determine
how old an updated item is, even if it doesn't feature an internal clock.
clientToken
A string unique to the device that enables you to associate responses with requests in an MQTT
environment.
version
The document version. Every time the document is updated, this version number is incremented.
Used to ensure the version of the document being updated is the most recent.
For more information, see Device Shadow Document Syntax (p. 88).
Versioning of a Thing Shadow
The Thing Shadows service supports versioning on every update message (both request and response),
which means that with every update of a thing shadow, the version of the JSON document is incremented.
This ensures two things:
• A client can receive an error if it attempts to overwrite a shadow using an older version number. The
client is informed it needs to resync before it can update a thing shadow.
• A client can decide not to act on a received message if the message has a lower version than the
version stored by the client.
In some cases, a client might bypass version matching by not submitting a version.
Client Token
You can use a client token with MQTT-based messaging to verify a request and request response contain
the same client token. This ensures the response and request are associated.
Example Document
Here is an example thing shadow document:
{
"state" : {
"desired" : {
"color" : "RED",
"sequence" : [ "RED", "GREEN", "BLUE" ]
},
"reported" : {
"color" : "GREEN"
}
},
68
AWS IoT Developer Guide
Empty Sections
"metadata" : {
"desired" : {
"color" : {
"timestamp" : 12345
},
"sequence" : {
"timestamp" : 12345
}
},
"reported" : {
"color" : {
"timestamp" : 12345
}
}
},
"version" : 10,
"clientToken" : "UniqueClientToken",
"timestamp": 123456789
}
Empty Sections
A thing shadow document contains a desired section only if it has a desired state. For example, the
following is a valid state document with no desired section:
{
"reported" : { "temp": 55 }
}
The reported section can also be empty:
{
"desired" : { "color" : "RED" }
}
If an update causes the desired or reported sections to become null, the section is removed from the
document. To remove the desired section from a document (in response, for example, to a device updating
its state), set the desired section to null:
{
"state": {
"reported": {
"color": "red"
},
"desired": null
}
}
It is also possible a thing shadow document will not contain desired or reported sections. In that case,
the shadow document is empty. For example, this is a valid document:
{
}
69
AWS IoT Developer Guide
Arrays
Arrays
Thing shadows support arrays, but treat them as normal values in that an update to an array replaces
the whole array. It is not possible to update part of an array.
Initial state:
{
"desired" : { "colors" : ["RED", "GREEN", "BLUE" ] }
}
Update:
{
"desired" : { "colors" : ["RED"] }
}
Final state:
{
"desired" : { "colors" : ["RED"] }
}
Arrays can't have null values. For example, the following array is not valid and will be rejected.
{
"desired" : {
"colors" : [ null, "RED", "GREEN" ]
}
}
Using Device Shadows
AWS IoT provides three methods for working with thing shadows:
UPDATE
Creates a thing shadow if it doesn't exist, or updates the content of a thing shadow with the data
provided in the request. The data is stored with timestamp information to indicate when it was last
updated. Messages are sent to all subscribers with the difference between reported and desired
state (delta). Things or apps that receive a message can perform an action based on the difference
between reported and desired states. For example, a device can update its state to the desired state,
or an app can update its UI to show the change in the device's state.
GET
Retrieves the latest state stored in the thing shadow (for example, during startup of a device to retrieve
configuration and the last state of operation). This method returns the full JSON document, including
metadata.
DELETE
Deletes a thing shadow, including all of its content. This removes the JSON document from the data
store. You can't restore a thing shadow you deleted, but you can create a new thing shadow with the
same name.
70
AWS IoT Developer Guide
Protocol Support
Protocol Support
These methods are supported through both MQTT and a RESTful API over HTTPS. Because MQTT is
a pub/sub communication model, AWS IoT implements a set of reserved topics. Things or applications
subscribe to these topics before publishing on a request topic in order to implement a request–response
behavior. For more information, see Device Shadow MQTT Pub/Sub Messages (p. 82) and Device
Shadow RESTful API (p. 80).
Updating a Thing Shadow
You can update a thing shadow by using the UpdateThingShadow (p. 81) RESTful API or by publishing
to the /update (p. 83) topic. Updates affect only the fields specified in the request.
Initial state:
{
"state": {
"reported" : {
"color" : { "r" :255, "g": 255, "b": 0 }
}
}
}
An update message is sent:
{
"state": {
"desired" : {
"color" : { "r" : 10 },
"engine" : "ON"
}
}
}
The device receives the desired state on the /update/delta topic that is triggered by the previous /update
message and then executes the desired changes. When finished, the device should confirm its updated
state through the reported section in the thing shadow JSON document.
Final state:
{
"state": {
"reported" : {
"color" : { "r" : 10, "g" : 255, "b": 0 },
"engine" : "ON"
}
}
}
Retrieving a Thing Shadow Document
You can retrieve a thing shadow by using the GetThingShadow (p. 80) RESTful API or by subscribing
and publishing to the /get (p. 85) topic. This retrieves the entire document plus the delta between the
desired and reported states.
71
AWS IoT Developer Guide
Retrieving a Thing Shadow Document
Example document:
{
"state": {
"desired": {
"lights": {
"color": "RED"
},
"engine": "ON"
},
"reported": {
"lights": {
"color": "GREEN"
},
"engine": "ON"
}
},
"metadata": {
"desired": {
"lights": {
"color": {
"timestamp": 123456
},
"engine": {
"timestamp": 123456
}
},
"reported": {
"lights": {
"color": {
"timestamp": 789012
}
},
"engine": {
"timestamp": 789012
}
}
},
"version": 10,
"timestamp": 123456789
}
}
Response:
{
"state": {
"desired": {
"lights": {
"color": "RED"
},
"engine": "ON"
},
"reported": {
"lights": {
"color": "GREEN"
},
72
AWS IoT Developer Guide
Retrieving a Thing Shadow Document
"engine": "ON"
},
"delta": {
"lights": {
"color": "RED"
}
}
},
"metadata": {
"desired": {
"lights": {
"color": {
"timestamp": 123456
},
"engine": {
"timestamp": 123456
}
},
"reported": {
"lights": {
"color": {
"timestamp": 789012
}
},
"engine": {
"timestamp": 789012
}
},
"delta": {
"lights": {
"color": {
"timestamp": 123456
}
}
}
},
"version": 10,
"timestamp": 123456789
}
}
Optimistic Locking
You can use the state document version to ensure you are updating the most recent version of a thing
shadow document. When you supply a version with an update request, the service rejects the request
with a HTTP 409 conflict response code if the current version of the state document does not match the
version supplied.
For example:
Initial document:
{
"state" : {
"desired" : { "colors" : ["RED", "GREEN", "BLUE" ] }
},
73
AWS IoT Developer Guide
Deleting Data
"version" : 10
}
Update: (version doesn't match; request will be rejected)
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 9
}
Result:
409 Conflict
Update: (version matches; this request will be accepted)
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 10
}
Final state
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 11
}
Deleting Data
You can delete data from a thing shadow by publishing to the /update (p. 83) topic, setting the fields to
be deleted to null. Any field with a value of null is removed from the document.
Initial state:
74
AWS IoT Developer Guide
Deleting a Thing Shadow
{
"state": {
"desired" : {
"lights": { "color": "RED" },
"engine" : "ON"
},
"reported" : {
"lights" : { "color": "GREEN"
"engine" : "OFF"
}
}
},
}
An update message is sent:
{
"state": {
"desired": null,
"reported": {
"engine": null
}
}
}
Final state:
{
"state": {
"reported" : {
"lights" : { "color" : "GREEN" }
}
}
}
You can delete all data from a thing shadow by setting its state to null. For example, sending the following
message will delete all of the state data but the thing shadow will remain.
{
"state": null
}
The thing shadow still exists even though its state is null. The version of the thing shadow will be
incremented when the next update occurs.
Deleting a Thing Shadow
You can delete a thing shadow document by using the DeleteThingShadow (p. 81) RESTful API or by
publishing to the /delete (p. 86) topic.
Initial state:
{
"state": {
75
AWS IoT Developer Guide
Delta State
"desired" : {
"lights": { "color": "RED" },
"engine" : "ON"
},
"reported" : {
"lights" : { "color": "GREEN"
"engine" : "OFF"
}
},
}
}
A message is sent to the /delete topic.
Final state:
HTTP 404 - resource not found
Delta State
Delta state is a virtual type of state that contains the difference between the desired and reported states.
Fields in the desired section that are not in the reported section are included in the delta. Fields that are
in the reported section and not in the desired section are not included in the delta. The delta contains
metadata, and its values are equal to the metadata in the desired field. For example:
{
"state": {
"desired": {
"color": "RED",
"state": "STOP"
},
"reported": {
"color": "GREEN",
"engine": "ON"
},
"delta": {
"color": "RED",
"state": "STOP"
}
},
"metadata": {
"desired": {
"color": {
"timestamp": 12345
},
"state": {
"timestamp": 12345
},
"reported": {
"color": {
"timestamp": 12345
},
"engine": {
"timestamp": 12345
}
},
76
AWS IoT Developer Guide
Delta State
"delta": {
"color": {
"timestamp": 12345
},
"state": {
"timestamp": 12345
}
}
},
"version": 17,
"timestamp": 123456789
}
}
When nested objects differ, the delta contains the path all the way to the root.
{
"state": {
"desired": {
"lights": {
"color": {
"r": 255,
"g": 255,
"b": 255
}
}
},
"reported": {
"lights": {
"color": {
"r": 255,
"g": 0,
"b": 255
}
}
},
"delta": {
"lights": {
"color": {
"g": 255
}
}
}
},
"version": 18,
"timestamp": 123456789
}
The Thing Shadows service calculates the delta by iterating through each field in the desired state and
comparing it to the reported state.
Arrays are treated like values. If an array in the desired section doesn't match the array in the reported
section, then the entire desired array is copied into the delta.
77
AWS IoT Developer Guide
Observing State Changes
Observing State Changes
When a thing shadow is updated, messages are published on two MQTT topics:
• $aws/things/thing-name/shadow/update/accepted
• $aws/things/thing-name/shadow/update/delta
The message sent to the /update/delta topic is intended for the thing whose state is being updated. This
message contains only the difference between the desired and reported sections of the thing shadow
document. Upon receiving this message, the thing decides whether to make the requested change. If the
thing's state is changed, it publishes its new current state to the $aws/things/thing-name/shadow/update
topic.
Devices and applications can subscribe to either of these topics to be notified when the state of the
document has changed.
Here is an example of that flow:
1. Device reports state.
2. The system updates the state document in its persistent data store.
3. The system publishes a delta message, which contains only the delta and is targeted at the subscribed
devices. Devices should subscribe to this topic to receive updates.
4. The thing shadow publishes an accepted message, which contains the entire received document,
including metadata. Applications should subscribe to this topic to receive updates.
Message Order
There is no guarantee that messages from the AWS IoT service will arrive at the device in any specific
order.
Initial state document:
{
"state" : {
"reported" : { "color" : "blue" }
},
"version" : 10,
"timestamp": 123456777
}
Update 1:
{
"state": { "desired" : { "color" : "RED" } },
"version": 10,
"timestamp": 123456777
}
Update 2:
{
"state": { "desired" : { "color" : "GREEN" } },
78
AWS IoT Developer Guide
Trim Device Shadow Messages
"version": 11 ,
"timestamp": 123456778
}
Final state document:
{
"state": {
"reported": { "color" : "GREEN" }
},
"version": 12,
"timestamp": 123456779
}
This results in two delta messages:
{
"state": {
"color": "RED"
},
"version": 11,
"timestamp": 123456778
}
{
"state": { "color" : "GREEN" },
"version": 12,
"timestamp": 123456779
}
The device may receive these messages out of order. Because the state in these messages is cumulative,
a device can safely discard any messages that contain a version number older than the one it is tracking.
If the device receives the delta for version 12 before version 11, it can safely discard the version 11
message.
Trim Device Shadow Messages
To reduce the size of thing shadow messages sent to your device, define a rule that selects only the fields
your device needs and republishes the message on an MQTT topic to which your device is listening.
The rule is specified in JSON and should look like the following:
{
"sql": "SELECT state, version FROM '$aws/things/+/shadow/update/delta'",
"ruleDisabled": false,
"actions": [{
"republish": {
"topic": "${topic(2)}/delta",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}]
}
79
AWS IoT Developer Guide
RESTful API
The select statement determines which fields from the message will be republished to the specified topic.
A "+" wildcard is used to match all thing shadow names. The rule specifies that all matching messages
should be republished to the specified topic. In this case, the "topic()" function is used to specify the topic
on which to republish. topic(2) evaluates to the thing name in the original topic. For more information
about creating rules, see Rules.
Device Shadow RESTful API
A thing shadow exposes the following URI for updating state information:
https://endpoint/things/thingName/shadow
The endpoint is specific to your AWS account. To retrieve your endpoint, use the describe-endpoint
command. The format of the endpoint is as follows:
identifier.iot.region.amazonaws.com
API Actions
• GetThingShadow (p. 80)
• UpdateThingShadow (p. 81)
• DeleteThingShadow (p. 81)
GetThingShadow
Gets the thing shadow for the specified thing.
The response state document includes the delta between the desired and reported states.
Request
The request includes the standard HTTP headers plus the following URI:
HTTP GET https://endpoint/things/thingName/shadow
Response
Upon success, the response includes the standard HTTP headers plus the following code and body:
HTTP 200
BODY: response state document
For more information, see Example Response State Document (p. 89).
Authorization
Retrieving a thing shadow requires a policy that allows the caller to perform the iot:GetThingShadow
action. The Thing Shadows service accepts two forms of authentication: signature version 4 with IAM
credentials or TLS mutual authentication with a client certificate.
The following is an example policy that allows a caller to retrieve a thing shadow:
80
AWS IoT Developer Guide
UpdateThingShadow
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "iot:GetThingShadow",
"Resource": ["arn:aws:iot:region:account:thing/thing"]
}]
}
UpdateThingShadow
Updates the thing shadow for the specified thing.
Updates affect only the fields specified in the request state document. Any field with a value of null is
removed from the thing shadow.
Request
The request includes the standard HTTP headers plus the following URI and body:
HTTP POST https://endpoint/things/thingName/shadow
BODY: request state document
For more information, see Example Request State Document (p. 88).
Response
Upon success, the response includes the standard HTTP headers plus the following code and body:
HTTP 200
BODY: response state document
For more information, see Example Response State Document (p. 89).
Authorization
Updating a thing shadow requires a policy that allows the caller to perform the iot:UpdateThingShadow
action. The Thing Shadows service accepts two forms of authentication: signature version 4 with IAM
credentials or TLS mutual authentication with a client certificate.
The following is an example policy that allows a caller to update a thing shadow:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "iot:UpdateThingShadow",
"Resource": ["arn:aws:iot:region:account:thing/thing"]
}]
}
DeleteThingShadow
Deletes the thing shadow for the specified thing.
81
AWS IoT Developer Guide
MQTT Pub/Sub Messages
Request
The request includes the standard HTTP headers plus the following URI:
HTTP DELETE https://endpoint/things/thingName/shadow
Response
Upon success, the response includes the standard HTTP headers plus the following code and body:
HTTP 200
BODY: Empty response state document
Authorization
Deleting a thing shadow requires a policy that allows the caller to perform the iot:DeleteThingShadow
action. The Thing Shadows service accepts two forms of authentication: signature version 4 with IAM
credentials or TLS mutual authentication with a client certificate.
The following is an example policy that allows a caller to delete a thing shadow:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "iot:DeleteThingShadow",
"Resource": ["arn:aws:iot:region:account:thing/thing"]
}]
}
Device Shadow MQTT Pub/Sub Messages
The Thing Shadows service uses reserved MQTT topics to enable applications and things to get, update,
or delete the state information for a thing (thing shadow). The names of these topics start with
$aws/things/thingName/shadow. Publishing and subscribing on thing shadow topics requires topic-based
authorization.
The following are the pub/sub messages used with MQTT for interacting with thing shadows.
Messages
• /update (p. 83)
• /update/accepted (p. 83)
• /update/rejected (p. 83)
• /update/delta (p. 84)
• /get (p. 85)
• /get/accepted (p. 85)
• /get/rejected (p. 86)
• /delete (p. 86)
• /delete/accepted (p. 87)
• /delete/rejected (p. 87)
82
AWS IoT Developer Guide
/update
/update
A thing publishes a request state document to this topic to update the thing shadow:
$aws/things/thingName/shadow/update
AWS IoT responds by publishing to either /update/accepted (p. 83) or /update/rejected (p. 83).
For more information, see Request State Documents (p. 88).
Example Policy
The following is an example policy:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["iot:Publish"],
"Resource": ["arn:aws:iot:region:account:topic/$aws/things/thingName/shad
ow/update"]
}]
}
/update/accepted
AWS IoT publishes a response state document to this topic when it accepts a change for the thing shadow:
$aws/things/thingName/shadow/update/accepted
For more information, see Response State Documents (p. 89).
Example Policy
The following is an example of the required policy:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"iot:Subscribe",
"iot:Receive"
],
"Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thing
Name/shadow/update/accepted"]
}]
}
/update/rejected
AWS IoT publishes an error response document to this topic when it rejects a change for the thing shadow:
83
AWS IoT Developer Guide
/update/delta
$aws/things/thingName/shadow/update/rejected
For more information, see Error Response Documents (p. 90).
Example Policy
The following is an example of the required policy:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"iot:Subscribe",
"iot:Receive"
],
"Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thing
Name/shadow/update/rejected"]
}]
}
/update/delta
AWS IoT publishes a response state document to this topic when it accepts a change for the thing shadow
and the request state document contains different values for desired and reported states:
$aws/things/thingName/shadow/update/delta
For more information, see Response State Documents (p. 89).
Publishing Details
• A message published on update/delta includes only the desired attributes that differ between the
reported and desired sections. It contains all of these attributes, regardless of whether these attributes
were contained in the current update message or were already stored in AWS IoT. Attributes that do
not differ between the reported and desired sections are not included.
• If an attribute is in the reported section but has no equivalent in the desired section, it is not included.
• If an attribute is in the desired section but has no equivalent in the reported section, it is not included.
• If an attribute is deleted from the reported section but still exists in the desired section, it is included.
Example Policy
The following is an example of the required policy:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"iot:Subscribe",
"iot:Receive"
84
AWS IoT Developer Guide
/get
],
"Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thing
Name/shadow/update/delta"]
}]
}
/get
A thing publishes to this topic to get the thing shadow:
$aws/things/thingName/shadow/get
AWS IoT responds by publishing to either /get/accepted (p. 85) or /get/rejected (p. 86).
Example Policy
The following is an example of the required policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:region:account:topic/$aws/things/thingName/shad
ow/get"
]
}
]
}
/get/accepted
AWS IoT publishes a response state document to this topic when returning the thing shadow:
$aws/things/thingName/shadow/get/accepted
For more information, see Response State Documents (p. 89).
Example Policy
The following is an example of the required policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
85
AWS IoT Developer Guide
/get/rejected
"iot:Subscribe",
"iot:Receive"
],
"Resource": [
"arn:aws:iot:region:account:topicfilter/$aws/things/thing
Name/shadow/get/accepted"
]
}
]
}
/get/rejected
AWS IoT publishes an error response document to this topic when it can't return the thing shadow:
$aws/things/thingName/shadow/get/rejected
For more information, see Error Response Documents (p. 90).
Example Policy
The following is an example of the required policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"iot:Subscribe",
"iot:Receive"
],
"Resource": [
"arn:aws:iot:region:account:topicfilter/$aws/things/thing
Name/shadow/get/rejected"
]
}
]
}
/delete
A thing publishes a document to this topic to delete a thing shadow:
$aws/things/thingName/shadow/delete
To delete a thing shadow, send a message to the delete topic. The content of the message is ignored.
AWS IoT responds by publishing to either /delete/accepted (p. 87) or /delete/rejected (p. 87).
Example Policy
The following is an example policy:
86
AWS IoT Developer Guide
/delete/accepted
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"iot:Subscribe",
"iot:Receive"
],
"Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thing
Name/shadow/delete"]
}]
}
/delete/accepted
AWS IoT publishes a message to this topic when deleting a thing shadow:
$aws/things/thingName/shadow/delete/accepted
Example Policy
The following is an example of the required policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe",
"iot:Receive"
],
"Resource": [
"arn:aws:iot:region:account:topicfilter/$aws/things/thing
Name/shadow/delete/accepted"
]
}
]
}
/delete/rejected
AWS IoT publishes an error response document to this topic when it can't delete the thing shadow:
$aws/things/thingName/shadow/delete/rejected
For more information, see Error Response Documents (p. 90).
Example Policy
The following is an example of the required policy:
87
AWS IoT Developer Guide
Document Syntax
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe",
"iot:Receive"
],
"Resource": [
"arn:aws:iot:region:account:topicfilter/$aws/things/thing
Name/shadow/delete/rejected"
]
}
]
}
Device Shadow Document Syntax
The Thing Shadows service uses the following documents in UPDATE, GET, and DELETE operations,
using the RESTful API (p. 80) or MQTT Pub/Sub Messages (p. 82). For more information, see Device
Shadows Documents (p. 67).
Examples
• Request State Documents (p. 88)
• Response State Documents (p. 89)
• Error Response Documents (p. 90)
Request State Documents
Request state documents have the following format:
{
"state": {
"desired": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"reported": {
"attribute1": integer1,
"attribute2": "string1",
...
"attributeN": boolean1
}
}
"clientToken": "token",
"version": version
}
• state — Updates affect only the fields specified.
88
AWS IoT Developer Guide
Response State Documents
• clientToken — If used, you can verify that the request and response contain the same client token.
• version — If used, the Thing Shadows service processes the update only if the specified version
matches the latest version it has.
Response State Documents
Response state documents have the following format:
{
"state": {
"desired": {
"attribute1": integer2,
"attribute2": "string2",
...
"attributeN": boolean2
},
"reported": {
"attribute1": integer1,
"attribute2": "string1",
...
"attributeN": boolean1
},
"delta": {
"attribute3": integerX,
"attribute5": "stringY"
}
},
"metadata": {
"desired": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
},
"reported": {
"attribute1": {
"timestamp": timestamp
},
"attribute2": {
"timestamp": timestamp
},
...
"attributeN": {
"timestamp": timestamp
}
}
},
"timestamp": timestamp,
"clientToken": "token",
89
AWS IoT Developer Guide
Error Response Documents
"version": version
}
• state
• reported — Only present if a thing reported any data in the reported section and contains only
fields that were in the request state document.
• desired — Only present if a thing reported any data in the desired section and contains only fields
that were in the request state document.
• metadata — Contains the timestamps for each attribute in the desired and reported sections so
that you can determine when the state was updated.
• timestamp — The Epoch date and time the response was generated by AWS IoT.
• clientToken — Present only if a client token was used when publishing valid JSON to the /update
topic.
• version — The current version of the document for the thing shadow shared in AWS IoT. It is increased
by one over the previous version of the document.
Error Response Documents
Error response documents have the following format:
{
"code": error-code,
"message": "error-message",
"timestamp": timestamp,
"clientToken": "token"
}
• code — An HTTP response code that indicates the type of error.
• message — A text message that provides additional information.
• timestamp — The date and time the response was generated by AWS IoT.
• clientToken — Present only if a client token was used when publishing valid JSON to the /update
topic.
For more information, see Device Shadow Error Messages (p. 90).
Device Shadow Error Messages
The Thing Shadows service publishes a message on the error topic (over MQTT) when an attempt to
change the state document fails. This message is only emitted as a response to a publish on one of the
reserved $aws topics. If the client updates the document using the REST API, then it receives the HTTP
error code as part of its response, and no MQTT error messages are emitted.
90
AWS IoT Developer Guide
Error Messages
HTTP Error Code
Error Messages
400 (Bad Request)
• Invalid JSON
• Missing required node: state
• State node must be an object
• Desired node must be an object
• Reported node must be an object
• Invalid version
• Invalid clientToken
• JSON contains too many levels of nesting; maximum is 6
• State contains an invalid node
401 (Unauthorized)
• Unauthorized
403 (Forbidden)
• Forbidden
404 (Not Found)
• Thing not found
409 (Conflict)
• Version conflict
413 (Payload Too Large)
• The payload exceeds the maximum size allowed
415 (Unsupported Media Type)
• Unsupported documented encoding; supported encoding
is UTF-8
429 (Too Many Requests)
• The Thing Shadow service will generate this error message
when there are more than 10 in-flight requests.
500 (Internal Server Error)
• Internal service failure
91
AWS IoT Developer Guide
Device SDK
AWS IoT SDKs
Contents
• AWS IoT Device SDK (p. 92)
• Getting Started with AWS IoT on the Raspberry Pi and the AWS IoT Device SDK for C (p. 94)
• Getting Started with AWS IoT on Raspberry Pi and the AWS IoT Device SDK for Node.js (p. 106)
AWS IoT provides a number of ways to interact with the service platform, using the MQTT and HTTP
RESTful protocols, and across different language frameworks. Depending on your application use cases,
you may find one or more SDKs to use.
• AWS SDKs for configuration: All configuration APIs are available as part of the standard AWS SDKs
in all supported AWS SDK languages, under the iot package namespace. There are functions to
create and manage:
• Identities and authorization (including certificates and policies).
• Rules and actions in the rules engine, endpoints, logging roles and levels.
• Names and attributes for devices in the Thing Registry.
• AWS SDKs to publish messages and work with thing shadows: AWS IoT provides support for:
• Applications using IAM users/roles (either directly or through Amazon Cognito).
• The HTTP protocol to publish messages directly to the message broker using HTTP POST.
• The ability to get, update, and delete states for device shadows.
These APIs are available in all languages supported by the AWS SDKs, under the iot-data package
namespace.
• Device SDKs: AWS IoT provides support for devices and applications that use certificate-based
authentication and the MQTT protocol (typically, memory-constrained devices) to perform message
publish and subscribe to the message broker. The C SDK can be compiled on Linux distributions using
OpenSSL or mbed TLS libraries and the included MQTT library. Customers can also port this SDK to
additional embedded platforms and incorporate custom TLS and MQTT libraries, if needed. A special
version of the C SDK is provided for Arduino Yún. The Device SDK is available for JavaScript in the
Node.js package ecosystem.
AWS IoT Device SDK
The AWS IoT Device SDK is a C language SDK developed for constrained devices or system on a chip
(SoC) with 256 KB or more of available memory. The Device SDK simplifies the process of connecting
92
AWS IoT Developer Guide
Device SDK Feature Set
embedded devices to the AWS IoT platform by implementing the security requirements to connect to the
broker of the AWS IoT service and providing basic pub/sub functionality as well as access to device
shadows over MQTT. This eliminates the need to implement support for an HTTP RESTful API. The
Device SDK was designed and tested to work with embedded Linux and a variety of industry-standard,
real-time operating systems as well as third-party TLS 1.2 and cryptographic library implementations to
support the high security standards of the broker of the AWS IoT platform.
Device SDK Feature Set
The Device SDK provides this functionality across platforms:
• Configuration of security credentials and artifacts for TLS 1.2 mutual authentication communication
with the AWS IoT message broker in the supported regions.
• Establishes and manages connection with the AWS IoT message broker (over MQTT) including timeout
configuration.
• Provides a wrapper for common MQTT client implementations to publish data and subscribe to topics
over MQTT.
• Provides support for updating, retrieving, and deleting device shadows, including support for the
versioning of device shadows.
Platform Support
The Device SDK is available for starter kits for rapid prototyping and for major semiconductor
manufacturers’ evaluation kits for product development. These are the currently supported platforms:
• Arduino Yún
The Arduino Yún features a powerful communication processor that allows you to use TLS 1.2 and
client certificates to connect the Arduino Yún board to AWS IoT.The SDK includes installation instructions
and scripts that prepare your Arduino Yún board for connection to AWS IoT. You can now do even
more with your Arduino sketch by having access to the cloud features of AWS through AWS IoT.
For more information, see:
Developer Guide and API reference
Source Code
Download the AWS IoT SDK for Arduino
• C SDK for embedded platforms (Linux, real-time OS)
The C SDK was developed following the C99 language standard.The SDK provides sample applications
and getting started instructions to improve the onboarding experience and quickly connect your device
to AWS IoT.The C SDK also includes a porting guide that helps you modify the SDK’s wrapper functions
to support your platform-specific data types, operating system timers, and embedded TLS
implementation, so that your application code can remain unchanged when you move from a rapid
prototyping environment in Linux to a more constrained and cost-efficient microcontroller.
For more information, see:
Download the Device SDK built for OpenSSL Package
Download the Device SDK built for mbedTLS package
Developer Guide
Porting Guide
93
AWS IoT Developer Guide
AWS IoT Device SDK for C
AWS IoT API Reference
Source Code
• Node.js JavaScript runtime package
The Node.js SDK was developed for rapid prototyping on more powerful embedded platforms that
support the Node.js package ecosystem. You can use the NPM packager manager to install the AWS
IoT package for Node.js. The example application and instructions will demonstrate which additional
packages are needed to run your Node.js application and connect it to AWS IoT quickly.
For more information, see:
Download the AWS IoT SDK for Node.js
AWS IoT SDK for Node.js Source
Developer Guide and API Reference
Getting Started with AWS IoT on the Raspberry
Pi and the AWS IoT Device SDK for C
This guide provides step-by-step instructions for connecting your Raspberry Pi to the AWS IoT platform
and setting it up for use with the AWS IoT Device SDK for C. After following the steps in this guide, you
will be able to get connected to the AWS IoT platform and run sample apps included with the AWS IoT
Device SDK for C.
Prerequisites
• A fully set up Raspberry Pi board with Internet access
For information about setting up your Raspberry Pi, see Raspberry Pi Quickstart Guide.
• Chrome or Firefox (Iceweasel) browser
For information about installing Iceweasel, see the instructions on the Embedded Linux Wiki.
In this guide, the following hardware and software are used:
• Raspberry Pi 2 Model B
• Raspbian Wheezy
• Iceweasel browser
Connecting Your Raspberry Pi
Sign in to the AWS IoT Console
Turn on your Raspberry Pi and confirm you have an Internet connection.
Sign in to the AWS Management Console and open the AWS IoT console at https://aws.amazon.com/
iot. On the Welcome page, choose Get started with AWS IoT.
94
AWS IoT Developer Guide
Connecting Your Raspberry Pi
If this is your first time using the AWS IoT console, you will see two buttons: Get Started and Start
interactive tutorial:
95
AWS IoT Developer Guide
Connecting Your Raspberry Pi
Choose Get Started. The following page should appear.
If you don't see blue banner with Create a thing, Create a rule, Create a certificate, and Create a policy
buttons, choose the Create a resource button:
96
AWS IoT Developer Guide
Connecting Your Raspberry Pi
Create and Attach a Thing (Device)
A thing represents a device whose status or data is stored in the AWS IoT cloud. The Thing Shadow
service maintains a thing shadow for each device connected to AWS IoT. Thing shadows allow you to
access and modify thing state data.
Choose Create a thing, type a name for the thing, and then choose Create:
97
AWS IoT Developer Guide
Connecting Your Raspberry Pi
In addition to a confirmation message, the View thing button will be displayed:
98
AWS IoT Developer Guide
Connecting Your Raspberry Pi
Choose View thing to display information about your thing:
99
AWS IoT Developer Guide
Connecting Your Raspberry Pi
Choose the Connect a device button to download a key pair and a certificate generated by AWS IoT:
100
AWS IoT Developer Guide
Connecting Your Raspberry Pi
On the Connect a device page, select the SDK to use, and then choose Generate certificate and policy:
101
AWS IoT Developer Guide
Connecting Your Raspberry Pi
This will generate an X.509 certificate and key pair; activate the X.509 certificate; and create an AWS
IoT policy and attach it to the certificate.
The following page will be displayed:
Create a working directory called deviceSDK where your files will be stored. Choose the links to download
your public and private keys and certificate and save them in the deviceSDK directory.
Choose Confirm & start connecting. The following page will be displayed:
102
AWS IoT Developer Guide
Connecting Your Raspberry Pi
There are two versions of the AWS IoT Device SDK for C: OpenSSL and mbed TLS. Choose the OpenSSL
link. This will download the AWS IoT AWS IoT Device SDK for C in a tarball
(linux_mqtt_openssl-latest.tar). Save it in your deviceSDK directory. In a terminal window, type
the following command to extract the tarball into your deviceSDK directory:
`tar -xvf linux_mqtt_openssl-latest.tar`
Set Up the AWS IoT Device SDK for C Runtime Environment
Before you can use the AWS IoT AWS IoT Device SDK for C, you must install the OpenSSL library on
Raspberry Pi. . In a terminal window, run sudo apt-get install libssl-dev.
103
AWS IoT Developer Guide
Connecting Your Raspberry Pi
Sample App Configuration
The AWS IoT AWS IoT Device SDK for C includes sample apps for you to try. For simplicity, we are going
to run subscribe_publish_sample. Copy your certificate and private key into the deviceSDK/certs
directory. Download a root CA certificate here. Copy the root CA text from the browser, paste it into a file,
and then copy it into the deviceSDK/certs directory.
Navigate to the deviceSDK/sample_apps/subscribe_publish_sample directory. You will need to
configure your personal endpoint, private key, and certificate. If you have access to a machine with the
AWS CLI installed, you can use the aws iot describe-endpoint command to find your personal
endpoint URL. Otherwise, go to the AWS IoT console, double-click MyNewThing, and look for REST
API endpoint. Copy everything after "https://" including ".com":
Open the aws_iot_config.h file and update the values for the following:
AWS_IOT_MQTT_HOST
Your personal endpoint.
AWS_IOT_MY_THING_NAME
Your thing name.
AWS_IOT_ROOT_CA_FILENAME
Your root CA certificate.
AWS_IOT_CERTIFICATE_FILENAME
Your certificate.
AWS_IOT_PRIVATE_KEY_FILENAME
Your private key.
Run Sample Applications
Compile the subscribe_publish_sample_app using the included makefile.
make -f Makefile
This will generate an executable file.
104
AWS IoT Developer Guide
Connecting Your Raspberry Pi
Now run the subscribe_publish_sample_app. You should see output similar to the following:
Your Raspberry Pi is now connected to AWS IoT using the AWS IoT Device SDK for C.
105
AWS IoT Developer Guide
AWS IoT Device SDK for Node.js
Getting Started with AWS IoT on Raspberry Pi
and the AWS IoT Device SDK for Node.js
This guide provides step-by-step instructions for connecting your Raspberry Pi to the AWS IoT platform
and setting it up for use with the AWS IoT Device SDK for Node.js. After following the steps in this guide,
you will be able to get connected to the AWS IoT platform and run sample apps included in the SDK.
Prerequisites
• A fully set up Raspberry Pi board with Internet access
For information about setting up your Raspberry Pi, see the Raspberry Pi Quickstart Guide.
• Chrome or Firefox (Iceweasel) browser
For information about installing Iceweasel, see the instructions on the Embedded Linux Wiki.
In this guide, the following hardware and software are used:
• Raspberry Pi 2 Model B
• Raspbian Jessie
• Iceweasel browser
Connecting Your Raspberry Pi
Sign in to the AWS IoT Console
Turn on your Raspberry Pi and confirm you have an Internet connection.
Sign in to the AWS Management Console and open the AWS IoT console at https://aws.amazon.com/
iot. On the Welcome page, choose Get started with AWS IoT:
106
AWS IoT Developer Guide
Connecting Your Raspberry Pi
If this is your first time using the AWS IoT console, you will see two buttons: Get Started and Start
Interactive Tutorial:
107
AWS IoT Developer Guide
Connecting Your Raspberry Pi
Choose Get Started. The following page should appear.
If you don't see blue banner with Create a thing, Create a rule, Create a certificate, and Create a policy
buttons, choose the Create a resource button:
108
AWS IoT Developer Guide
Connecting Your Raspberry Pi
Create and Attach a Thing (Device)
A thing represents a device whose status or data is stored in the AWS IoT cloud. The Thing Shadow
service maintains a thing shadow for each device connected to AWS IoT. Thing shadows allow you to
access and modify thing state data.
Choose Create a thing, type in a name for the thing, and then choose Create:
109
AWS IoT Developer Guide
Connecting Your Raspberry Pi
In addition to a confirmation message, the View thing button will be displayed:
110
AWS IoT Developer Guide
Connecting Your Raspberry Pi
Choose View thing to display information about your thing:
111
AWS IoT Developer Guide
Connecting Your Raspberry Pi
Choose the Connect a device button to download a key pair and a certificate generated by AWS IoT :
112
AWS IoT Developer Guide
Connecting Your Raspberry Pi
On the Connect a device page, select the SDK to use, and then chooseGenerate certificate and policy:
113
AWS IoT Developer Guide
Connecting Your Raspberry Pi
This will generate an X.509 certificate and key pair; activate the X.509 certificate; and create an AWS
IoT policy and attach it to the certificate.
The following page will be displayed:
Create a working directory called deviceSDK where your files will be stored. Choose the links to download
your public and private keys and certificate, and then save them in the deviceSDK directory.
Choose Confirm & start connecting. The following page will be displayed:
114
AWS IoT Developer Guide
Connecting Your Raspberry Pi
Set Up the AWS IoT Device SDK for Node.js Runtime
Environment
To use the AWS IoT Device SDK for Node.js, you need to install Node and the npm development tool on
your Raspberry Pi. These packages are not installed by default.
Note
Before you continue, you might want to configure the keyboard mapping for your Raspberry Pi.
For more information, see Configure Raspberry Pi Keyboard Mapping.
To add the Node repository, open a terminal and run the following command:
curl -sLS https://apt.adafruit.com/add | sudo bash
115
AWS IoT Developer Guide
Connecting Your Raspberry Pi
To install Node, run sudo apt-get install node. You should see output similar to the following:
To install npm, run sudo apt-get install npm. You should see output similar to the following:
116
AWS IoT Developer Guide
Connecting Your Raspberry Pi
To verify the installation of Node and npm, run node -v and npm -v. You should see output similar to
the following:
Install the AWS IoT Device SDK for Node.js
Now you will port the SDK to the Raspberry Pi. On the AWS IoT Device SDK page, choose the Get
source in Github link:
117
AWS IoT Developer Guide
Connecting Your Raspberry Pi
Open a console window. To keep things simple, we will use npm to install the SDK from the npm repository:
118
AWS IoT Developer Guide
Connecting Your Raspberry Pi
After the installation is complete, you should find the installed module in ~ directory (/home/pi is the
default):
Prepare to Run the Sample Applications
The AWS IoT Device SDK for Node.js includes sample apps for you to try.To run them, you must configure
your certificates and private key.
Type cd ~ to go to your home directory. Create a directory where your certificate, private key, and root
CA certificate will be stored. Name the directory certs.
Copy your certificate and private key into the directory. Download a root CA certificate from here. Copy
the text from the browser, paste it into a file, and then copy it into the certs directory.
You will need to configure your personal endpoint, private key, and certificate. If you have access to a
machine with the AWS CLI installed, you can use the aws iot describe-endpoint command to find
your personal endpoint URL. Otherwise, go to the AWS IoT console, double-click MyNewThing, and
look for REST API endpoint. Copy everything after "https://" including ".com":
119
AWS IoT Developer Guide
Connecting Your Raspberry Pi
By default, the files should be named as follows:
• your private key: private.pem.key
• your certificate: certificate.pem.crt
• the CA root certificate: root-CA.crt
You can edit the cmdline.js file to change the default names used by each sample.
default: {
region: 'us-east-1',
clientId: clientIdDefault,
privateKey: 'private.pem.key',
clientCert: 'certificate.pem.crt',
caCert: 'root-CA.cert,
testMode: 1,
reconnectPeriod: 3 * 1000, /* milliseconds */
delay: 4 * 1000
/* milliseconds */
};
Run the Sample Applications
Now you can run examples using node examples/<YourDesiredExample>.js -f <certs location> (assuming
you are under node_modules/aws-iot-device-sdk/). In this case, the certificates location should
be ~/certs/. You can specify the certificates location and your own host address using command line
options. For information, see Certificates.
Your Raspberry Pi is now connected to AWS IoT using the AWS IoT SDK for Node.js.
120
AWS IoT Developer Guide
Diagnosing Connectivity Issues
Troubleshooting AWS IoT
The following information might help you troubleshoot common issues in AWS IoT.
Tasks
• Diagnosing Connectivity Issues (p. 121)
• Setting Up CloudWatch Logs (p. 122)
• Diagnosing Rules Issues (p. 126)
• Diagnosing Problems with Thing Shadows (p. 127)
Diagnosing Connectivity Issues
Authentication
How do my devices authenticate AWS IoT endpoints?
Add the AWS IoT certification authority (CA) certificate to your client’s trust store. You can download
the CA certificate from here.
How can I validate a correctly configured certificate?
Use the OpenSSL s_client command to test a connection to the AWS IoT endpoint:
openssl s_client -connect iot.us-east-1.amazonaws.com:443 -CAfile CA.pem
-cert cert.pem -key privateKey.pem
Authorization
I received a PUBNACK or SUBNACK response from the broker. What do I do?
Make sure there is a policy attached to the certificate you are using to call AWS IoT. All
publish/subscribe operations are denied by default.
121
AWS IoT Developer Guide
Setting Up CloudWatch Logs
Setting Up CloudWatch Logs
As messages from your devices pass through the message broker and the rules engine, AWS IoT sends
progress events about each message. You can opt in to view these events in CloudWatch Logs. For
more information, see CloudWatch Logs.
Note
Before you enable AWS IoT logging, be sure you understand the access permissions to
CloudWatch Logs in your AWS account. Users with access to CloudWatch Logs will be able to
see debugging information from your devices.
Configuring an IAM Role for Logging
Use the IAM console to create a logging role.
Create an IAM Role for Logging
The following policy documents provide the role policy and trust policy that allow AWS IoT to submit logs
to CloudWatch on your behalf.
Role policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:PutMetricFilter",
"logs:PutRetentionPolicy"
],
"Resource": [
"*"
]
}
]
}
Trust policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
122
AWS IoT Developer Guide
CloudWatch Log Entry Format
]
}
Register the Logging Role with AWS IoT
Use the AWS IoT console or the following CLI command to register the logging role with AWS IoT.
aws iot set-logging-options --logging-options-payload
roleArn="arn:aws:iam::<your-aws-account-num>:role/IoTLoggingRole",logLevel="INFO"
The log level can be DEBUG, INFO, ERROR, or DISABLED:
• DEBUG provides the most detailed information of AWS IoT activity.
• INFO provides a summarized view of most actions. This is sufficient for most users.
• ERROR provides error cases only.
• DISABLED removes logging altogether, but keeps your logging role intact.
CloudWatch Log Entry Format
Each log entry has the following information:
Event
Describes the actions that take place in AWS IoT.
TimeStamp
The time the log was generated.
TraceId
An identifier generated randomly for an incoming request that can be used to filter all of the
corresponding logs to one incoming message.
PrincipalId
A certificate fingerprint or a thing name, depending on which endpoint (MQTT or HTTP) received the
request from a device.
LogLevel
The logging level. Can be DEBUG, INFO, ERROR, or WARN.
Topic Name
The MQTT topic name, which is added to an entry when an MQTT publish or subscribe message is
received.
ClientId
The ID of the client that sent an MQTT message.
ThingId
The thing identifier, which is added to an entry when a request is sent to an HTTP endpoint to update
or delete thing state.
RuleId
The rule identifier, which contains the ID of a rule when the rule is triggered.
Log Level
The log level specifies which types of logs will be generated.
DEBUG
Information that may be helpful when debugging a problem.
Logs will include DEBUG, INFO, ERROR, and WARN information.
123
AWS IoT Developer Guide
Logging Events and Error Codes
ERROR
Any error that causes an operation to fail.
Logs will include ERROR information only.
INFO
High-level information about the flow of things.
Logs will include INFO, ERROR, and WARN information.
WARN
Anything that can potentially cause inconsistencies in the system, but may not necessarily cause the
operation to fail.
Logs will include ERROR and WARN information.
Logging Events and Error Codes
This section lists the logging events and error codes sent by AWS IoT.
Identity and Security
Operation/Event Name
Description
Authentication Success
Successfully authenticated a certificate.
Authentication Failure
Failed to authenticate a certificate.
Identity and Security Error Codes
Error Code
Error Description
401
Unauthorized
Message Broker
Operation/Event Name
Description
MQTT Publish
MQTT Publish received.
MQTT Subscribe
MQTT Subscribe received.
MQTT Connect
MQTT Connect received.
MQTT Disconnect
MQTT Disconnect received.
HTTP/1.1 POST
MHTTP/1.1 POST received.
HTTP/1.1 GET
HTTP/1.1 GET received.
HTTP/1.1 Unsupported Method
Used when a message contains a syntax error or
the action (HTTP PUT/DELETE/) is forbidden.
Malformed HTTP Message
The connection was terminated because of a malformed HTTP message.
Malformed MQTT Message
The connection was terminated because of a malformed MQTT message.
124
AWS IoT Developer Guide
Logging Events and Error Codes
Operation/Event Name
Description
Authorization Failed
This client attempted to publish to or subscribe on
a topic for which it has no authorization.
Package Exceeds Maximum Payload Size
This client attempted to publish a payload that exceeds the message broker's upper limit.
Message Broker Error Codes
Error Code
Error Description
400
Bad Request
401
Unauthorized
403
Forbidden
503
Service Unavailable
Rues Engine Events
Operation/Event Name
Description
MessageReceived
Received a request for a topic.
DynamoActionSuccess
Successfully put DynamoDB record.
DynamoActionFailure
Failed to put DynamoDB record.
KinesisActionSuccess
Successfully published Amazon Kinesis message.
KinesisActionFailure
Failed to publish Amazon Kinesis message.
LambdaActionSuccess
Successfully invoked Lambda function.
LambdaActionFailure
Failed to invoke Lambda function.
RepublishActionSuccess
Successfully republished message.
MessageReceived
Received request for a topic.
RepublishActionFailure
Failed to republish message.
S3ActionSuccess
Successfully put Amazon S3 object.
S3ActionFailure
Failed to put Amazon S3 object.
SNSActionSuccess
Successfully published to Amazon SNS topic.
SNSActionFailure
Failed to publish to Amazon SNS topic.
SQSActionSuccess
Successfully sent message to Amazon SQS.
SQSActionFailure
Failed to send message to Amazon SQS.
125
AWS IoT Developer Guide
Diagnosing Rules Issues
Thing Shadow Events
Operation/Event Name
Description
UpdateThingState
A thing's state is updated over HTTP or MQTT.
DeleteThing
A thing is deleted.
Thing Shadow Error Codes
Error Code
Error Description
400
Bad request.
401
Unauthorized.
403
Forbidden.
404
Not found.
409
Conflict.
413
Request too large.
422
Failed to process request.
429
Too many requests.
500
Internal error.
503
Service unavailable.
Diagnosing Rules Issues
CloudWatch Logs is the best place to debug issues you may be having with rules. When you enable
CloudWatch Logs for AWS IoT, you get visibility into which rules are triggered and their success or failure.
You also get information about whether WHERE clause conditions match.
The most common issue is authorization. In this case, the logs will tell you your role is not authorized to
perform AssumeRole on the resource.
To view CloudWatch logs (console)
1. In the AWS Management Console, navigate to the CloudWatch console.
2. Choose Logs, and then choose the AWSIoTLogs log group from the list.
3. On the Streams for AWSIoTLogs page that appears, you will find a log stream for each of your
principal (X.509 certificate, IAM user, or Amazon Cognito identity) that called into AWS IoT under your
account.
For more information, see CloudWatch Logs.
External services are controlled by the end user. Before rule execution, make sure external services are
set up with enough throughput and capacity units.
126
AWS IoT Developer Guide
Diagnosing Problems with Thing Shadows
Diagnosing Problems with Thing Shadows
Diagnosing Thing Shadows
Issue
Troubleshooting Guidelines
A thing shadow document is rejected with "Invalid If you are unfamiliar with JSON, modify the exJSON document."
amples provided in this guide for your own use. For
more information, see Thing Shadow Document
Syntax.
I submitted correct JSON, but none or only parts
of it are stored in the thing shadow document.
Be sure you are following the JSON formatting
guidelines. Only JSON fields in the desired and
reported sections will be stored. JSON content
(even if formally correct) outside of those sections
will be ignored.
I received an error that the thing shadow exceeds The thing shadow supports 8 KB of data only. Try
the allowed size.
shortening field names inside of your JSON document or simply create additional thing shadows. A
device can have an unlimited number of thing
shadows. The only requirement is that the thing
name is unique in your account.
When I receive a thing shadow, it is larger than 8
KB. How can this happen?
Upon receipt, the AWS IoT service adds metadata
to the thing shadow. The service includes this data
in its response, but it does not count toward the
limit of 8 KB. Only the data for desired and reported
state inside the state document sent to the thing
shadow counts toward the limit.
My request has been rejected due to incorrect
version. What should I do?
Perform a GET operation to sync to the latest state
document version. When using MQTT, subscribe
to the ./update/accepted topic so you will be notified
about state changes and receive the latest version
of the JSON document.
The timestamp is off by several seconds.
The timestamp for individual fields and the whole
JSON document is updated when the document is
received by the AWS IoT service or when the state
document is published onto the ./update/accepted
and ./update/delta message. Messages can be
delayed over the network, which can cause the
timestamp to be off by a few seconds.
My device can publish and subscribe on the corresponding thing shadow topics, but when attempting
to update the thing shadow document over the
HTTP REST API, I get HTTP 403.
Be sure you have created policies in IAM to allow
access to these topics and for the corresponding
action (UPDATE/GET/DELETE) for the credentials
you are using. IAM policies and certificate policies
are independent.
Other issues.
The Thing Shadows service will log errors to
CloudWatch Logs. To identify device and configuration issues, enable CloudWatch Logs and view
the logs for debug information.
127
AWS IoT Developer Guide
AWS IoT Limits
The following limits apply to the message broker:
Topic length limit
The topic passed to the message broker when
publishing a message cannot exceed 256 bytes
encoded in UTF-8.
Restricted topic prefix
Topics beginning with '$' are considered reserved
and are not supported for publishing and subscribing except when working with the Thing Shadows
service.
Maximum number of slashes in topic and topic filter A topic provided while publishing a message or a
topic filter provided while subscribing can have no
more than eight forward slashes (/).
Client ID size limit
128 bytes encoded in UTF-8.
Restricted client ID prefix
'$' is reserved for internally generated client IDs.
Message size limit
The payload for every publish message is limited
to 128 KB. The AWS IoT service will reject messages larger than this size.
Throughput per connection
AWS IoT limits the ingress and egress rate on each
client connection to 512 KB/s. Data sent or received
at a higher rate will be throttled to this throughput.
Maximum subscriptions per subscribe call
A single subscribe call is limited to request a maximum of eight subscriptions.
Subscriptions per session
The message broker limits each client session to
subscribe to up to 50 subscriptions. A subscribe
request that pushes the total number of subscriptions past 50 will result in the connection being
disconnected.
128
AWS IoT Developer Guide
Connection inactivity (keep-alive) limits
By default, an MQTT client connection is disconnected after 30 minutes of inactivity. When the client
sends a PUBLISH, SUBSCRIBE, PING, or PUBACK message, the inactivity timer is reset.
A client can request a shorter keep-alive interval
by specifying a keep-alive value between 5-1,200
seconds in the MQTT CONNECT message sent
to the server. If a keep-alive value is specified, the
server will disconnect the client if it does not receive
a PUBLISH, SUBSCRIBE, PINGREQ, or PUBACK
message within a period 1.5 times the requested
interval. The keep-alive timer starts after the sender
sends a CONNACK.
If a client sends a keep-alive value of zero, the default keep-alive behavior will remain in place.
If a client request a keep-alive shorter than 5
seconds, the server will treat the client as though
it requested a keep-alive interval of 5 seconds.
Maximum inbound unacknowledged messages
The message broker allows 100 in-flight unacknowledged messages (limit is across all messages requiring ACK). When this limit is reached, no new
messages will be accepted until an ACK is returned
by the server.
Maximum outbound unacknowledged messages
The message broker only allows 100 in-flight unacknowledged messages (limit is across all messages
requiring ACK). When this limit is reached, no new
messages will be sent to the client until the client
acknowledges the in-flight messages.
Maximum retry interval for delivering QoS 1 messages
If a connected client is unable to receive an ACK
on a QoS 1 message for one hour, the message
broker will drop the message. The client may be
unable to receive the message if it has 100 in-flight
messages, it is being throttled due to large payloads, or other errors.
WebSocket connection duration
WebSocket connections are currently limited to 5
minutes. If the limit is exceeded, the WebSocket
connection will automatically be closed when an
attempt is made to send a message by the client
or server. If you need to maintain an active WebSocket connection for longer than 5 minutes, simply
close and re-open the WebSocket connection from
the client side before the 5 minutes elapses.
AWS IoT supports keep-alive values specified in MQTT CONNECT messages. When a client specifies
a keep-alive value, the client tells the server to disconnect the client and transmit any last-will message
associated with the MQTT session if the server does not receive a message (PUBLISH, SUBSCRIBE,
PUBACK, PINGREQ) within 1.5 times the keep-alive period. AWS IoT supports keep-alive values between
5 seconds and 20 minutes. If a client requests no keep-alive (that is, sets the field to 0 in the MQTT
CONNECT message), the server will set the keep-alive value to 20 minutes, which corresponds to the
maximum idle time supported by AWS IoT of 30 minutes. Most MQTT clients (including the AWS SDK
129
AWS IoT Developer Guide
Throttling Limits
clients) support keep-alive values by sending a PINGREQ if the keep-alive period expires without the
transmission of any other message by the client.
Note
The keep-alive timer begins immediately after the server returns a CONNACK to the client. There
may be a brief delay between the client's sending of a CONNECT message and the start of
keep-alive behavior.
The following limits apply to thing shadows:
• The maximum size of a state document in JSON cannot exceed 8 KB.
• You can store an unlimited number of JSON objects per account.
• A thing shadow is deleted by AWS IoT if it has not been updated or retrieved in more than 12 months.
• The Thing Shadows service supports up to 10 in-flight unacknowledged messages. When this limit is
reached, all new shadow requests will be rejected with a 429 error code.
The following limits apply to security and identity:
• You can attach up to 10 policies to an AWS IoT certificate.
• You can keep up to 5 versions of a named policy.
• Policy document size is limited to 2048 characters (excluding white space).
•
Throttling Limits
The following table lists the throttling limits for AWS IoT API:
API
Transaction per Second
AcceptCertificateTransfer
10
AttachThingPrincipal
15
CancelCertificateTransfer
10
CreateCertificateFromCsr
15
CreatePolicy
10
CreatePolicyVersion
10
CreateThing
15
DeleteCertificate
10
DeletePolicy
10
DeletePolicyVersion
10
DeleteThing
10
DescribeCertificate
10
DescribeThing
10
DetachThingPrincipal
10
130
AWS IoT Developer Guide
Throttling Limits
API
Transaction per Second
DetachPrincipalPolicy
15
GetPolicy
10
GetPolicyVersion
15
ListCertificates
10
ListPolicies
10
ListPolicyVersions
10
ListPrincipalPolicies
15
ListPrincipalThings
10
ListThings
10
ListThingPrincipals
10
RejectCertificateTransfer
10
SetDefaultPolicyVersion
10
TransferCertificate
10
UpdateCertificate
10
UpdateThing
10
131
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement