End of support notice: On October 7th, 2026, AWS will discontinue support for AWS IoT Greengrass Version 1. After October 7th, 2026, you will no longer be able to access the AWS IoT Greengrass V1 resources. For more information, please visit [Migrate from AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html).
# Module 5: Interacting with device shadows
This advanced module shows you how client devices can interact with [AWS IoT device shadows](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html) in an AWS IoT Greengrass group. A *shadow* is a JSON document that is used to store current or desired state information for a thing. In this module, you discover how one client device (`GG_Switch`) can modify the state of another client device (`GG_TrafficLight`) and how these states can be synced to the AWS IoT Greengrass cloud:
![\[AWS IoT Greengrass core is connected to a traffic light device shadow and a light switch device.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-077.5.png)
Before you begin, run the [Greengrass device setup](quick-start.md) script, or make sure that you have completed [Module 1](module1.md) and [Module 2](module2.md). You should also understand how to connect client devices to an AWS IoT Greengrass core ([Module 4](module4.md)). You do not need other components or devices.
This module should take about 30 minutes to complete.
**Topics**
+ [Configure devices and subscriptions](config-dev-subs.md)
+ [Download required files](file-download.md)
+ [Test communications (device syncs disabled)](comms-disabled.md)
+ [Test communications (device syncs enabled)](comms-enabled.md)
# Configure devices and subscriptions
Shadows can be synced to AWS IoT when the AWS IoT Greengrass core is connected to the internet. In this module, you first use local shadows without syncing to the cloud. Then, you enable cloud syncing.
Each client device has its own shadow. For more information, see [Device shadow service for AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html) in the *AWS IoT Developer Guide*.
1. On the group configuration page, choose the **Client devices** tab.
1. From the **Client devices** tab, add two new client devices in your AWS IoT Greengrass group. For detailed steps of this process, see [Create client devices in an AWS IoT Greengrass group](device-group.md).
+ Name the client devices **GG\$1Switch** and **GG\$1TrafficLight**.
+ Generate and download the security resources for both client devices.
+ Make a note of the certificate ID in the file names of the security resources for the client devices. You use these values later.
1. Create a folder on your computer for these client devices' security credentials. Copy the certificates and keys into this folder.
1. Make sure that the client devices are set to use local shadows and not sync with the AWS Cloud. If not, select the client device, choose **Sync shadow**, and then choose **Disable shadow sync with cloud**.
1. Add the subscriptions in the following table to your group. For example, to create the first subscription:
1. On the group configuration page, choose the **Subscriptions** tab, and then choose **Add**.
1. For **Source type**, choose **Client device**, and then choose **GG\$1Switch**.
1. For **Target type**, choose **Service**, and then choose **Local Shadow Service**.
1. For **Topic filter**, enter **\$1aws/things/GG\$1TrafficLight/shadow/update**
1. Choose **Create subscription**.
The topics must be entered exactly as shown in the table. Although it's possible to use wildcards to consolidate some of the subscriptions, we don't recommend this practice. For more information, see [Shadow MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html) in the *AWS IoT Developer Guide*.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/config-dev-subs.html)
The new subscriptions are displayed on the **Subscriptions** tab.
**Note**
For information about the `$` character, see [Reserved topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html#reserved-topics).
1. Make sure that automatic detection is enabled so the Greengrass core can publish a list of its IP addresses. Client devices use this information to discover the core. Do the following:
1. On the group configuration page, choose the **Lambda functions** tab.
1. Under **System Lambda functions**, choose **IP detector**, and then choose **Edit**.
1. In the **Edit IP detector settings**, choose **Automatically detect and override MQTT broker endpoints**, and then choose **Save**.
1. Make sure that the Greengrass daemon is running, as described in [Deploy cloud configurations to a core device](configs-core.md).
1. On the group configuration page, choose **Deploy**.
# Download required files
1. If you haven't already done so, install the AWS IoT Device SDK for Python. For instructions, see step 1 in [Install the AWS IoT Device SDK for Python](IoT-SDK.md).
This SDK is used by client devices to communicate with AWS IoT and with AWS IoT Greengrass core devices.
1. From the [ TrafficLight](https://github.com/aws/aws-greengrass-core-sdk-python/tree/master/examples/TrafficLight) examples folder on GitHub, download the `lightController.py` and `trafficLight.py` files to your computer. Save them in the folder that contains the GG\$1Switch and GG\$1TrafficLight client device certificates and keys.
The `lightController.py` script corresponds to the GG\$1Switch client device, and the `trafficLight.py` script corresponds to the GG\$1TrafficLight client device.
![\[Screenshot of files including the two Python scripts and the device certificates and keys.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-082.png)
**Note**
The example Python files are stored in the AWS IoT Greengrass Core SDK for Python repository for convenience, but they don't use the AWS IoT Greengrass Core SDK.
# Test communications (device syncs disabled)
1. Make sure that your computer and the AWS IoT Greengrass core device are connected to the internet using the same network.
1. On the AWS IoT Greengrass core device, run the following command to find its IP address.
```
hostname -I
```
1. On your computer, run the following command using the IP address of the core. You can use Ctrl \$1 C to stop the **ping** command.
```
ping IP-address
```
Output similar to the following indicates successful communication between the computer and the AWS IoT Greengrass core device (0% packet loss):
![\[Successful ping command output.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-075.5.png)
**Note**
If you're unable to ping an EC2 instance that's running AWS IoT Greengrass, make sure that the inbound security group rules for the instance allow ICMP traffic for [Echo request](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-group-rules-reference.html#sg-rules-ping) messages. For more information, see [ Adding rules to a security group](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html#adding-security-group-rule) in the *Amazon EC2 User Guide*.
On Windows host computers, in the Windows Firewall with Advanced Security app, you might also need to enable an inbound rule that allows inbound echo requests (for example, **File and Printer Sharing (Echo Request - ICMPv4-In)**), or create one.
1. Get your AWS IoT endpoint.
1. From the [AWS IoT console](https://console.aws.amazon.com/iot/) navigation pane, choose **Settings**.
1. Under **Device data endpoint**, make a note of the value of **Endpoint**. You use this value to replace the *AWS\$1IOT\$1ENDPOINT* placeholder in the commands in the following steps.
**Note**
Make sure that your [endpoints correspond to your certificate type](gg-core.md#certificate-endpoints).
1. On your computer (not the AWS IoT Greengrass core device), open two [command-line](https://en.wikipedia.org/wiki/Command-line_interface) (terminal or command prompt) windows. One window represents the GG\$1Switch client device and the other represents the GG\$1TrafficLight client device.
1. From the GG\$1Switch client device window, run the following commands.
+ Replace *path-to-certs-folder* with the path to the folder that contains the certificates, keys, and Python files.
+ Replace *AWS\$1IOT\$1ENDPOINT* with your endpoint.
+ Replace the two *switchCertId* instances with the certificate ID in the file name for your GG\$1Switch client device.
```
cd path-to-certs-folder
python lightController.py --endpoint AWS_IOT_ENDPOINT --rootCA AmazonRootCA1.pem --cert switchCertId-certificate.pem.crt --key switchCertId-private.pem.key --thingName GG_TrafficLight --clientId GG_Switch
```
1. From the GG\$1TrafficLight client device window, run the following commands.
+ Replace *path-to-certs-folder* with the path to the folder that contains the certificates, keys, and Python files.
+ Replace *AWS\$1IOT\$1ENDPOINT* with your endpoint.
+ Replace the two *lightCertId* instances with the certificate ID in the file name for your GG\$1TrafficLight client device.
```
cd path-to-certs-folder
python trafficLight.py --endpoint AWS_IOT_ENDPOINT --rootCA AmazonRootCA1.pem --cert lightCertId-certificate.pem.crt --key lightCertId-private.pem.key --thingName GG_TrafficLight --clientId GG_TrafficLight
```
Every 20 seconds, the switch updates the shadow state to G, Y, and R, and the light displays its new state, as shown next.
GG\$1Switch output:
![\[Screenshot of the output associated with GG_Switch.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-083.png)
GG\$1TrafficLight output:
![\[Screenshot of the output associated with GG_TrafficLight.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-084.png)
When executed for the first time, each client device script runs the AWS IoT Greengrass discovery service to connect to the AWS IoT Greengrass core (through the internet). After a client device has discovered and successfully connected to the AWS IoT Greengrass core, future operations can be executed locally.
**Note**
The `lightController.py` and `trafficLight.py` scripts store connection information in the `groupCA` folder, which is created in the same folder as the scripts. If you receive connection errors, make sure that the IP address in the `ggc-host` file matches the IP address endpoint for your core.
1. In the AWS IoT console, choose your AWS IoT Greengrass group, choose the **Client devices** tab, and then choose **GG\$1TrafficLight** to open the client device's AWS IoT thing details page.
1. Choose the **Device Shadows** tab. After the GG\$1Switch changes states, there should not be any updates to this shadow. That's because the GG\$1TrafficLight is set to **Disable shadow sync with cloud**.
1. Press Ctrl \$1 C in the GG\$1Switch (`lightController.py`) client device window. You should see that the GG\$1TrafficLight (`trafficLight.py`) window stops receiving state change messages.
Keep these windows open so you can run the commands in the next section.
# Test communications (device syncs enabled)
For this test, you configure the GG\$1TrafficLight device shadow to sync to AWS IoT. You run the same commands as in the previous test, but this time the shadow state in the cloud is updated when GG\$1Switch sends an update request.
1. In the AWS IoT console, choose your AWS IoT Greengrass group, and then choose the **Client devices** tab.
1. Select the GG\$1TrafficLight device, choose **Sync shadow**, and then choose **Enable shadow sync with cloud**.
You should receive a notification that the device shadow sync status was updated.
1. On the group configuration page, choose **Deploy**.
1. In your two command-line windows, run the commands from the previous test for the [GG\$1Switch](comms-disabled.md#run-switch-device) and [GG\$1TrafficLight](comms-disabled.md#run-trafficlight-device) client devices.
1. Now, check the shadow state in the AWS IoT console. Choose your AWS IoT Greengrass group, choose the **Client devices** tab, choose **GG\$1TrafficLight**, choose the **Device Shadows** tab, and then choose **Classic Shadow**.
Because you enabled sync of the GG\$1TrafficLight shadow to AWS IoT, the shadow state in the cloud should be updated whenever GG\$1Switch sends an update. This functionality can be used to expose the state of a client device to AWS IoT.
**Note**
If necessary, you can troubleshoot issues by viewing the AWS IoT Greengrass core logs, particularly `runtime.log`:
```
cd /greengrass/ggc/var/log
sudo cat system/runtime.log | more
```
You can also view `GGShadowSyncManager.log` and `GGShadowService.log`. For more information, see [Troubleshooting AWS IoT Greengrass](gg-troubleshooting.md).
Keep the client devices and subscriptions set up. You use them in the next module. You also run the same commands.