Updated Jul 2025
AWS IoT Device Shadow Operations Demo
Introduction
This demo shows how to use the AWS IoT Device Shadow library to connect to the AWS Device Shadow Service. It uses the coreMQTT library to establish an MQTT connection with TLS (Mutual Authentication) to the AWS IoT MQTT Broker and the coreJSON parser to parse shadow documents it receives from the AWS Shadow service. The demo showcases some basic shadow operations, such as how to update a shadow document and how to delete a shadow document. The demo also shows how to register a callback function with the MQTT library to handle messages like the shadow
/update
/update/delta
This demo is intended only as a learning exercise because the request to update the shadow document (state) and the update response are done by the same application. In a realistic production scenario, an external application (e.g. an application running on a user's phone) would request an update of the state of the device remotely, even if the device is not currently connected. The device will acknowledge the update request when it is connected.
This demo project uses
the FreeRTOS Windows port,
so you can build and evaluate it with
the free Community version of Visual Studio on
Windows without the need for any MCU hardware.
Source Code Organization
The demo project is called
shadow_device_operations_demo.sln
1FreeRTOS-Plus\Demo\AWS\Device_Shadow_Windows_Simulator\Device_Shadow_Demo
Configure the Demo Project
The demo uses the FreeRTOS-Plus-TCP TCP/IP stack, so follow the instructions provided for the TCP/IP starter project to:
-
Install the pre-requisite components (such as WinPCap).
-
Optionally set a static or dynamic IP address, gateway address and netmask.
-
Optionally set a MAC address.
-
Select an Ethernet network interface on your host machine.
-
(Important!) Test your network connection before you attempt to run the Shadow demo.
All of these settings should be set in the Shadow demo project.
Configure the AWS IoT MQTT Broker Connection
In this demo you use an MQTT connection to the AWS IoT MQTT broker. This connection is configured in the same way as the MQTT mutual authentication demo.
Build the Demo Project
The demo project uses the free community edition of Visual Studio.
To build the demo:
-
Open the Visual Studio solution file
from within the Visual Studio IDE.FreeRTOS-Plus\Demo\AWS\Device_Shadow_Windows_Simulator\Device_Shadow_Demo\shadow_main_demo.sln -
Select 'build solution' from the IDE's 'build' menu.
Functionality
The demo creates a single application task that loops through a set of examples that demonstrate shadow
/update
/update/delta
desired
reported
desired
/update
powerOn
democonfigSHADOW_NAME
The demo performs the following operations:
-
Establish a MQTT connection by using the helper functions in
.shadow_demo_helpers.c -
Assemble MQTT topic strings for IoT device shadow operations, using macros defined by the Device Shadow library.
-
Publish to the MQTT topic used for deleting a device shadow to delete any existing device shadow.
-
Subscribe to the MQTT topics for
,/update/deltaand/update/acceptedusing helper functions in/update/rejected.shadow_demo_helpers.c -
Publish a desired state of
using helper functions inpowerOn. This will cause anshadow_demo_helpers.cmessage to be sent to the device./update/delta -
Handle incoming MQTT messages in
, and determine whether the message is related to the device shadow by using a function defined by the Device Shadow library (prvEventCallback). If the message is a device shadowShadow_MatchTopicStringmessage, then the main demo function will publish a second message to update the reported state to/update/delta. If anpowerOnmessage is received, verify that it has the same clientToken as previously published in the update message. That will mark the end of the demo./update/accepted
The structure of the demo can be found
in ShadowDemoMainExample.c
on GitHub.
This screenshot shows the expected output when the demo executes correctly:
Connect to the AWS IoT MQTT Broker
To connect to the AWS IoT MQTT broker, we use the same method as
MQTTConnect()
Delete the Shadow Document
To delete the shadow document, call
xPublishToTopic
MQTT_Publish
/delete
prvShadowDemoTask
Subscribe to Shadow Topics
Subscribe to the Device Shadow topics to receive notifications from the AWS IoT broker about shadow changes. The Device Shadow topics are assembled by macros defined in the Device Shadow library. An example showing how this is done in the
prvShadowDemoTask
Send Shadow Updates
To send a shadow update, the demo calls
xPublishToTopic
MQTT_Publish
/delete
prvShadowDemoTask
Handle Shadow Delta Messages and Shadow Update Messages
The user callback function, that was registered to the coreMQTT Client library
using the function
on GitHub.
The callback function confirms the incoming packet is of type
MQTT_PACKET_TYPE_PUBLISH
Shadow_MatchTopic
If the incoming message is a shadow message with type
ShadowMessageTypeUpdateDelta
prvUpdateDeltaHandler
prvUpdateDeltaHandler
powerOn
powerOn
prvUpdateDeltaHandler
If the incoming message is a shadow message with type
ShadowMessageTypeUpdateAccepted
prvUpdateAcceptedHandler
prvUpdateAcceptedHandler
clientToken
prvUpdateAcceptedHandler