3. Choose Settings.
4. For Local connection detection, choose Manually manage connection information, and then choose View Cores for specific endpoint information.
5. Choose your core, and then choose Connectivity.
6. Choose Edit and make sure that you have only one endpoint value. This value must be the IP address endpoint for port 8883 of your AWS IoT Greengrass core device (for example, 192.168.1.4).
7. Choose Update.
Module 5: Interacting with device shadows
This advanced module shows you how AWS IoT Greengrass devices can interact with AWS IoT device shadows 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 AWS IoT Greengrass device (GG_Switch) can modify the state of another AWS IoT Greengrass device (GG_TrafficLight) and how these states can be synced to the AWS IoT Greengrass cloud:
Before you begin, run the Greengrass device setup (p. 108) script, or make sure that you have completed Module 1 (p. 118) and Module 2 (p. 131). You should also understand how to connect devices to an AWS IoT Greengrass core (Module 4 (p. 166)). You do not need other components or devices.
This module should take about 30 minutes to complete.
Configure devices and subscriptions
Topics
• Configure devices and subscriptions (p. 179)
• Download required files (p. 182)
• Test communications (device syncs disabled) (p. 182)
• Test communications (device syncs enabled) (p. 185)
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 device has its own shadow. For more information, see Device shadow service for AWS IoT in the AWS IoT Developer Guide.
1. From the Devices page, add two new devices in your AWS IoT Greengrass group. For detailed steps of this process, see the section called “Create AWS IoT devices in an AWS IoT Greengrass group” (p. 167).
• Name the devices GG_Switch and GG_TrafficLight.
• Generate and download the 1-Click default security resources for both devices.
• Make a note of the hash component in the file names of the security resources for the devices. You use these values later.
2. Decompress the downloaded certificates and keys for both devices into a single folder on your computer. For example, run the following command for each .tar.gz file.
tar -xzf hash-setup.tar.gz
NoteOn Windows, you can decompress .tar.gz files using a tool such as 7-Zip or WinZip.
3. Copy the root-ca-cert.pem file that you downloaded in the previous module (p. 169) to this folder.
4. Make sure that the devices are set to use local shadows. If not, choose the ellipsis (…), and then choose Make local only.
Configure devices and subscriptions
5. Add the subscriptions in the following table to your group. For example, to create the first subscription:
a. On the group configuration page, choose Subscriptions, and then choose Add subscription.
b. Under Select a source, choose Devices, and then choose GG_Switch.
c. Under Select a target, choose Services, and then choose Local Shadow Service.
d. Choose Next.
e. For Topic filter, enter $aws/things/GG_TrafficLight/shadow/update f. Choose Next, and then choose Finish.
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 in the AWS IoT Developer Guide.
Source Target Topic Notes
GG_Switch Local Shadow Service $aws/things/
GG_TrafficLight/
shadow/update
The GG_Switch sends an update request to update topic.
Local Shadow Service GG_Switch $aws/things/
GG_TrafficLight/
shadow/update/
accepted
The GG_Switch needs to know whether the update request was accepted.
Local Shadow Service GG_Switch $aws/things/
GG_TrafficLight/
shadow/update/
rejected
The GG_Switch needs to know whether the update request was rejected.
GG_TrafficLight Local Shadow Service $aws/things/
GG_TrafficLight/
shadow/update
The GG_TrafficLight sends an update of its state to the update topic.
Local Shadow Service GG_TrafficLight $aws/things/
GG_TrafficLight/
Configure devices and subscriptions
Source Target Topic Notes
Local Shadow Service GG_TrafficLight $aws/things/
GG_TrafficLight/
shadow/update/
accepted
The GG_TrafficLight needs to know whether its state update was accepted.
Local Shadow Service GG_TrafficLight $aws/things/
GG_TrafficLight/
shadow/update/
rejected
The GG_TrafficLight needs to know whether its state update was rejected.
The new subscriptions are displayed on the Subscriptions page. To see the full topic path of a subscription, hover your mouse over the Topic column.
NoteFor information about the $ character, see Reserved topics.
6. Make sure that automatic detection is enabled so the Greengrass core can publish a list of its IP addresses. Devices use this information to discover the core.
a. On the group configuration page, choose Settings.
b. Under Core connectivity information, for Local connection detection, choose Automatically detect and override connection information.
7. Make sure that the Greengrass daemon is running, as described in Deploy cloud configurations to a core device (p. 149).
8. On the group configuration page, from Actions, choose Deploy.
Download required files
This deploys the group configuration to your AWS IoT Greengrass core device. For troubleshooting help, see Troubleshooting (p. 860).
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 the section called “Install the AWS IoT Device SDK for Python” (p. 170).
This SDK is used by AWS IoT devices to communicate with AWS IoT and with AWS IoT Greengrass core devices.
2. From the 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_Switch and GG_TrafficLight device certificates and keys.
The lightController.py script corresponds to the GG_Switch device, and the trafficLight.py script corresponds to the GG_TrafficLight device.
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.
a. On the AWS IoT Greengrass core device, run the following command to find its IP address.
hostname -I
b. On your computer, run the following command using the IP address of the core. You can use Ctrl + C to stop the ping command.
Test communications (device syncs disabled)
ping IP-address
Output similar to the following indicates successful communication between the computer and the AWS IoT Greengrass core device (0% packet loss):
NoteIf 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 messages. For more information, see Adding rules to a security group in the Amazon EC2 User Guide for Linux Instances.
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.
2. Get your AWS IoT endpoint.
a. In the AWS IoT console, in the navigation pane, choose Settings.
b. Under Settings, make a note of the value of Endpoint. You use this value to replace the AWS_IOT_ENDPOINT placeholder in the commands in the following steps.
NoteMake sure that your endpoints correspond to your certificate type (p. 76).
3. On your computer (not the AWS IoT Greengrass core device), open two command-line (terminal or command prompt) windows. One window represents the GG_Switch device and the other represents the GG_TrafficLight device.
a. From the GG_Switch device window, run the following commands.
Test communications (device syncs disabled)
• Replace path-to-certs-folder with the path to the folder that contains the certificates, keys, and Python files.
• Replace AWS_IOT_ENDPOINT with your endpoint.
• Replace the two switch instances with the hash in the file name for your GG_Switch device.
cd path-to-certs-folder
python lightController.py --endpoint AWS_IOT_ENDPOINT --rootCA root-ca-cert.pem cert switch.cert.pem key switch.private.key thingName GG_TrafficLight --clientId GG_Switch
b. From the GG_TrafficLight 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_IOT_ENDPOINT with your endpoint.
• Replace the two light instances with the hash in the file name for your GG_TrafficLight device.
cd path-to-certs-folder
python trafficLight.py endpoint AWS_IOT_ENDPOINT rootCA root-ca-cert.pem --cert light.--cert.pem --key light.private.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_Switch output:
GG_TrafficLight output:
When executed for the first time, each device script runs the AWS IoT Greengrass discovery service to connect to the AWS IoT Greengrass core (through the internet). After a device has discovered and successfully connected to the AWS IoT Greengrass core, future operations can be executed locally.
NoteThe 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
Test communications (device syncs enabled)
connection errors, make sure that the IP address in the ggc-host file matches the IP address endpoint for your core.
4. In the AWS IoT console, choose your AWS IoT Greengrass group, choose Devices, and then choose GG_TrafficLight.
5. Choose Shadow. After the GG_Switch changes states, there should not be any updates to this shadow topic in Shadow State. That's because the GG_TrafficLight is set to LOCAL SHADOW ONLY as opposed to SHADOW SYNCING TO CLOUD.
6. Press Ctrl + C in the GG_Switch (lightController.py) device window. You should see that the GG_TrafficLight (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_TrafficLight 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_Switch sends an update request.
1. In the AWS IoT console, choose your AWS IoT Greengrass group, and then choose Devices.
2. For the GG_TrafficLight device, choose the ellipsis (…), and then choose Sync to the Cloud.
You should receive a notification that the device shadow was updated.
Test communications (device syncs enabled)
3. On the group configuration page, from Actions, choose Deploy.
This deploys the group configuration to your AWS IoT Greengrass core device. For troubleshooting help, see Troubleshooting (p. 860).
4. In your two command-line windows, run the commands from the previous test for the GG_Switch (p. 183) and GG_TrafficLight (p. 184) devices.
5. Now, check the shadow state in the AWS IoT console. Choose your AWS IoT Greengrass group, choose Devices, choose GG_TrafficLight, and then choose Shadow.
Because you enabled sync of the GG_TrafficLight shadow to AWS IoT, the shadow state in the cloud should be updated whenever GG_Switch sends an update. This functionality can be used to expose the state of a Greengrass device to AWS IoT.
NoteIf necessary, you can troubleshoot issues by viewing the AWS IoT Greengrass core logs, particularly runtime.log:
cd /greengrass/ggc/var/log