AWS IoT Immersion Day

Using the AWS IoT Device Shadow

December, 2017

Table of Contents
AWS IoT Immersion Day
Table of Contents
Overview
Prerequisites
Lab Assumptions
Tips and Helpful Hints
Copying Commands from the PDF
Using the AWS IoT Device Shadow
Import Lab into Your Node-RED Environment
Publish Reported State to the AWS IoT Device Shadow
Subscribing to Additional Shadow Topics
Publishing Commands to the AWS IoT Shadow
Lab Summary
Lab Cleanup
Copyright 2017, Amazon Web Services, All Rights Reserved

Overview
This lab will walk you through using the AWS IoT Device Shadow. It will guide you through several
steps that show the syntax of a Device Shadow, how the Shadow communicates updates through
different MQTT topics, how to update the Device shadow, and how to enable version locking for an
individual Device Shadow. Once completed, you’ll have a better understanding of how the AWS IoT
Device Shadow can be used for creating a virtual representation of your device in AWS IoT.

Prerequisites
All IoT Immersion Day labs utilize an open source software package called, Node-RED, which will be
automatically installed through a CloudFormation template. For this lab, you must have
successfully completed the Getting Started with AWS IoT – Connecting a Device lab.
Completion of that lab will have created a working Node-RED environment and your device
(yourname_device1).

Lab Assumptions
In order to reduce overly descriptive text, the following assumptions are made:

All labs will be performed in a single region. For purposes of screenshots and commands, all
lab guides will use us-west-2 (Oregon). If you run the labs in a different region, replace
references to us-west-2 with your region.
Your unique device name will be referenced as yourname_device1. Where seen, replace with
the unique device name you created. This can be the device name itself or as part of a topic
structure.

Tips and Helpful Hints

As you go through the labs, these tips may help make the process more streamlined.

Copying Commands from the PDF

There will be several commands and code throughout labs that will look very similar to the below.
When snippets are presented that require copying and pasting, we will include a numerical number
for them, and include them in a text file for easier copying and pasting.

{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 9
}

Using the AWS IoT Device Shadow

Import Lab into Your Node-RED Environment
In the first lab, you configured Node-RED for testing device communication to your AWS IoT
endpoint. On completion of the first lab, you should have access to Node-RED’s user interface
which will be used as the starting point for this lab. You should also have completed getting your
first device connected to AWS IoT. If all steps were completed, your current work environment
should be similar to the below (the amount of tabs may differ if other labs were run before this
one):

For this lab, you’ll be creating a new flow in Node-RED. Flows in Node-RED are visually displayed as
individual tabs in the workstation. To start the lab, first download the starting configuration for this
lab:

AWS IoT Device Shadow Node-RED Configuration File

1. In Node-RED select the right menu icon to open the available options.

2. Hover over the Import dropdown option and select Clipboard. The Clipboard option supports
being able to include new workflows by copying and pasting a valid Node-RED JSON file.
3. On your desktop or downloads folder for your web browser, open the configuration file
named, hol\_iot\_shadow\_config.json . The contents of the file should contain valid JSON
that represents the baseline for this lab.

4. Copy and paste the contents of the JSON file into the text field in the Node-RED Import-
>Clipboard option. Then select the New Flow button on the Node-RED screen, and then
Import. Once import completes, click on the Using IoT Shadow tab, and verify you see the
following:
 5. In order to complete the set-up for the lab, Select Deploy in the Node-RED UI. This will apply
your changes. You will see an error message displayed, but you can ignore this error as it
indicates an incomplete Node-RED flow which you will complete by the end of the lab. Feel
free to select the checkbox labeled “do not warn about this again” to suppress this error as you
go through the lab:

The missing broker configuration errors are expected at this point, you will correct in later steps.

Publish Reported State to the AWS IoT Device

Shadow
The first part of the lab will focus on getting basic shadow publish to your IoT device for the
reported state of the shadow. For this lab we continue using the same thing that you created in the
first lab named yourname_device1. If you used a different name for your IoT device in the AWS IoT
Registry, you will need to update the steps below to use your device name in place of
yourname_device1.

1. Open your browser and go to the AWS console. Select the service AWS IoT. Then select
Manage->Things and the click on the device yourname_device1. This will display the base
details about the current IoT device.

2. Next select Interact from the left hand tabs. The Interact tab displays more detail about the
device communications that are supported to this specific device over its device shadow.
Browse this page and note the list of topics available and the topic patterns.

3. Copy the MQTT topic for the Update to this thing shadow from the Interact page to your
clipboard.

4. Navigate back to the AWS IoT console and select Test. Then select Subscribe to a topic link,
paste the topic you copied in step 3 and add /accepted to the end to create the topic. Your
topic should have the following syntax:

​ $aws/things/yourname_device1/shadow/update/accepted

Finally click the Subscribe to topic button. This will bring up a real time client monitoring the
IoT Shadow for accepted updates.
5. Open your second browser which is displaying Node-RED. Double click the mqtt topic node
related to the Update Shadow Workflow. Node-RED should display the settings for
communicating to AWS IoT over MQTT.

6. Paste the shadow topic for your device into the Topic section of the MQTT node. Then Select 0
from the QOS drop down, and finally enter a name for the node such as AWS IoT Shadow. Once
complete your screen should resemble the one below. Then select Done to close the current
node screen.

Note: Ensure that the retain flag is not selected or set in this command.

7. To view your changes, Select Deploy in the top right of the Node-RED screen. This will update
Node-RED to reflect all of your changes.
8. Now click the button for the Generate Timestamp to publish to the shadow for your device
to AWS IoT.
 9. You can verify the shadow was published successfully by navigating back to Test in AWS IoT.
You should see a message related to the IoT Shadow update. This message will include
metadata about the Shadow update such as timestamp and the version of the shadow.

Subscribing to Additional Shadow Topics

In the first part of this lab, you used the AWS IoT console to subscribe to only the accepted updates
for the AWS IoT Shadow. In this section you will use a wildcard topic in MQTT to subscribe to any
accepted or rejected messages sent by the AWS IoT Shadow.

1. From the Node-RED user interface, double-click the mqtt topic node for Shadow Response
Message. This MQTT configuration will be used to subscribe to your topics for Shadow
updates.

2. Paste the same shadow update topic that you copied from the Interact state into the field
Topic in your MQTT node. It should have a format similar to the below:

​ $aws/things/yourname_device1/shadow/update

2. In order to subscribe to both accepted and rejected topics you’ll need to append a /# to the
end of the topic. Your new format should mirror the below:

​ $aws/things/yourname_device1/shadow/update/#

3. Next, select 0 for the QOS level dropdown and enter Shadow Topics as the name of the Node.
Your configuration should be similar to the this:
 Select Done.

4. Now that you’ve configured a listener for both accepted and rejected states, you can test if this
is working successfully. Click the Deploy button in the top right corner to deploy your
changes. Click the button again for the Generate Timestamp in the Update Shadow Workflow
to publish to the shadow for your device to AWS IoT. You should see in the debug log a JSON
object that shows the MQTT topic for a success update and the full shadow update payload:
 5. In the next section you’ll now make use of this workflow to test rejected shadow messages as
well as monitoring the difference between the reported and desired state of the shadow.

Publishing Commands to the AWS IoT Shadow

In the first parts of this lab, you have primarily published messages that only updated the reported
state of the device. In this section you will work with sending commands to the shadow using the
desired section of the AWS IoT Shadow document.

1. Navigate to your Node-RED user interface and double-click the mqtt topic node for the Test
Shadow Update section. This MQTT configuration will be used to publish to your topics for
Shadow updates. Similar to the previous sections, paste your update shadow topic into the
Topic section and select 0 as your QOS and enter Test Shadow Command for the Name:

2. Next Double Click on the {"sample": "test"} node. This will open a screen that allows you to
configure custom input. Enter Command Topic for the name of the node. To modify the JSON
payload select the … next to the sample test input. This will launch a JSON editor.

❗ Ensure that the "retain" flag is not selected or set in this command.
3. Enter the following JSON payload into the text editor. This payload will update the Shadow
with two commands related to the color and brightness of the device. Click Done and then
Select Done to close the node.

{
"state": {
"desired": {
"color": "violet",
"brightness" : 25
}
}
}

4. Click Deploy in the top right corner to apply your updates. After this is complete, click the
button for inject which will publish the desired state to your device’s shadow. You should see
in the debug log a shadow success message.

5. Open a second browser window or tab and go to the AWS Console. Select the service AWS IoT.
Then select Manage->Things and the click on the device yourname_device1, then select the
Shadow tab. Here you will be able to see the current state of the AWS IoT Shadow for
yourname_device1. The current Shadow document should now contain not only reported fields
but also desired fields.
6. Now we will update the JSON input for our Test Shadow Update inject node such that the
desired and reported states are updated simultaneously. Double Click the Command Topic
node and then click the … to edit the JSON. Copy and paste the JSON below which will
simultaneously apply a matching reported and desired state, but will also pass null for a
desired field:

{
"state": {
"desired": {
"color": null,
"brightness": 25
},
"reported": {
"color": "violet"
}
}
}

7. Click Deploy in the top right corner to apply your updates. Click the button for *Test Shadow
Update * inject to publish your message. You will again see messages in your debug log in
Node-RED. Navigate back to your thing yourname_device1 in the AWS IoT Manage (or refresh
your browser if you still have your console open from step 5). You should now see one of the
desired fields has been removed from the current shadow document.

8. You will make one last update to the Test Shadow Update inject node to publish a message
using a version in the payload. As discussed during the presentation, the AWS IoT Device
Shadow supports versioning. " When you include a version in the payload, you are
requesting that AWS IoT check that the version in the message is equal to the latest version on
AWS IoT.

Double Click Command Topic to open the editor and select the … field next to the message to
open the JSON editor. Copy and paste the following message into the editor and click Done.
Then click Done to close the node editor.

{
"state": {
"reported": {
"brightness": 25
}
},
"version": 1
}
 9. Click Deploy in the top right corner to apply your update. Click the button for Command
Topic to publish your new message that now includes the version as part of the payload. You
should see in the debug log and message published on the shadow error topic with a
message of “Version Conflict”:

10. " This error occurs because we set our Shadow version to 1, but we have clearly updated our
shadow with reported and desired states—which has incremented the version number. In
order to fix this issue, you will need to retrieve the latest version from the IoT Shadow
document for yourname_device1. Open the browser for your AWS Console and select the
service AWS IoT. Then select Manage->Things and the click on the device
yourname_device1, then select the Shadow tab.

11. Look in the metadata section of the shadow document to find the current version of that
device shadow and copy this value (the one shown below is for reference only, you version will
be different):
12. Go back to the Node-RED console. Double-click the Command Topic inject node and then click
the … to edit the JSON. Replace the version number 1 with the version number that you
copied in the previous step. Your payload should look similar to the below where
CURRENT_VERSION_NUMBER is replaced by the current version of your shadow . Click Done
and then Done again to close the Command Topic node.

{
"state": {
"reported": {
"brightness": 25
}
},
"version": CURRENT_VERSION_NUMBER
}

13. Click Deploy in the top right corner to apply your updates. Now retest your shadow command
by clicking the button for inject to publish your new message that now includes the latest
version as part of the payload. You should see a success message displayed in your Node-RED
debug window.
 ❗ This step will only work once. After you have successfully updated the shadow, the version
number is again incremented and any updates will fail until you update the version in your
message again.

Lab Summary
In this lab, you accomplished the following tasks:

1. Used the AWS IoT Shadow to update the reported state of your device.
2. Used an MQTT wildcard topic to receive accepted and rejected updates to a specific device
shadow.
3. Used the desired state of the AWS IoT Shadow to send a command to the device.
4. Used the reported and desired state in one message to simultaneously remove acknowledge
commands and update the reported.
5. Used the version field of the AWS IoT Shadow to apply optimistic locking to the current version
of the shadow.

Lab Cleanup
This lab did not create any new resource except the shadow for your device. When all the labs are
done, deletion of the Thing will also delete the shadow document associated with it.

Copyright 2017, Amazon Web Services, All Rights

Reserved