Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Tutorial: Installing the Device SDK and running the sample application for Device Shadows

This section shows how you can install the required software and the Amazon IoT Device SDK for Python and run the shadow.py sample application to edit the Shadow document and control the shadow's state.

Before you run this tutorial:

You must have set up your Amazon Web Services account, configured your Raspberry Pi device, and created an Amazon IoT thing and policy that gives the device permissions to publish and subscribe to the MQTT reserved topics of the Device Shadow service. For more information, see Tutorial: Preparing your Raspberry Pi to run the shadow application.

You must have also installed Git, Python, and the Amazon IoT Device SDK for Python. This tutorial builds on the concepts presented in the tutorial Connect a Raspberry Pi or other device. If you haven't tried that tutorial, we recommend that you follow the steps described in that tutorial to install the certificate files and Device SDK and then come back to this tutorial to run the shadow.py sample app.

This tutorial takes about 20 minutes to complete.

Step 1: Run the shadow.py sample app

Before you run the shadow.py sample app, you'll need the following information in addition to the names and location of the certificate files that you installed.

Enter values and observe the updates in Shadow document

You can enter values in the terminal to specify the desired value, which also updates the reported value. Say you enter the color yellow in the terminal. The reported value is also updated to the color yellow. The following shows the messages displayed in the terminal:

Enter desired value:
yellow
Changed local shadow value to 'yellow'.
Updating reported shadow value to 'yellow'...
Update request published.
Finished updating reported shadow value to 'yellow'.

When you publish this update request, Amazon IoT creates a default, classic shadow for the thing resource. You can observe the update request that you published to the reported and desired values in the Amazon IoT console by looking at the Shadow document for the thing resource that you created (for example, My_light_bulb). To see the update in the Shadow document:

The Shadow document should look similar to the following, showing the reported and desired values set to the color yellow. You see these values in the Shadow state section of the document.

{
"desired": {
  "welcome": "aws-iot",
  "color": "yellow"
},
"reported": {
  "welcome": "aws-iot",
  "color": "yellow"
}
}

You also see a Metadata section that contains the timestamp information and version number of the request.

You can use the state document version to ensure you are updating the most recent version of a device's Shadow document. If you send another update request, the version number increments by 1. When you supply a version with an update request, the service rejects the request with an HTTP 409 conflict response code if the current version of the state document doesn't match the version supplied.

{
"metadata": {
  "desired": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620156893
    }
  },
  "reported": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620156893
    }
  }
},
"version": 10
}        

To learn more about the Shadow document and observe changes to the state information, proceed to the next tutorial Tutorial: Interacting with Device Shadow using the sample app and the MQTT test client as described in the Step 4: Review the results and next steps section of this tutorial. Optionally, you can also learn about the shadow.py sample code and how it uses the MQTT protocol in the following section.

Step 2: Review the shadow.py Device SDK sample app

This section reviews the shadow.py sample app from the Amazon IoT Device SDK v2 for Python used in this tutorial. Here, we'll review how it connects to Amazon IoT Core by using the MQTT and MQTT over WSS protocol. The Amazon common runtime (Amazon-CRT) library provides the low-level communication protocol support and is included with the Amazon IoT Device SDK v2 for Python.

While this tutorial uses MQTT and MQTT over WSS, Amazon IoT supports devices that publish HTTPS requests. For an example of a Python program that sends an HTTP message from a device, see the HTTPS code example using Python’s requests library.

For information about how you can make an informed decision about which protocol to use for your device communications, review the Choosing a protocol for your device communication.

MQTT

The shadow.py sample calls mtls_from_path (shown here) in the mqtt_connection_builder to establish a connection with Amazon IoT Core by using the MQTT protocol. mtls_from_path uses X.509 certificates and TLS v1.2 to authenticate the device. The Amazon-CRT library handles the lower-level details of that connection.

mqtt_connection = mqtt_connection_builder.mtls_from_path(
  endpoint=args.endpoint,
  cert_filepath=args.cert,
  pri_key_filepath=args.key,
  ca_filepath=args.ca_file,
  client_bootstrap=client_bootstrap,
  on_connection_interrupted=on_connection_interrupted,
  on_connection_resumed=on_connection_resumed,
  client_id=args.client_id,
  clean_session=False,
  keep_alive_secs=6
)

The shadow.py sample also calls websockets_with_default_aws_signing in the mqtt_connection_builder to establish a connection with Amazon IoT Core using MQTT protocol over WSS. MQTT over WSS also uses the same parameters as MQTT and takes these additional parameters:

Subscribe to Shadow topics and events

The shadow.py sample attempts to establish a connection and waits to be fully connected. If it's not connected, commands are queued up. Once connected, the sample subscribes to delta events and update and get messages, and publishes messages with a Quality of Service (QoS) level of 1 (mqtt.QoS.AT_LEAST_ONCE).

When a device subscribes to a message with QoS level 1, the message broker saves the messages that the device is subscribed to until they can be sent to the device. The message broker resends the messages until it receives a PUBACK response from the device.

For more information about the MQTT protocol, see Review the MQTT protocol and MQTT.

For more information about how MQTT, MQTT over WSS, persistent sessions, and QoS levels that are used in this tutorial, see Review the pubsub.py Device SDK sample app.

Step 3: Troubleshoot problems with the shadow.py sample app

When you run the shadow.py sample app, you should see some messages displayed in the terminal and a prompt to enter a desired value. If the program throws an error, then to debug the error, you can start by checking whether you ran the correct command for your system.

In some cases, the error message might indicate connection issues and look similar to: Host name was invalid for dns resolution or Connection was closed unexpectedly. In such cases, here are some things you can check:

Step 4: Review the results and next steps

Next steps

You can now run the shadow.py sample application and use Device Shadows to control the state. You can observe the updates to the Shadow document in the Amazon IoT Console and observe delta events that the sample app responds to. Using the MQTT test client, you can subscribe to the reserved shadow topics and observe messages received by the topics when running the sample program. For more information about how to run this tutorial, see Tutorial: Interacting with Device Shadow using the sample app and the MQTT test client.