Next generation AWS IoT Client SDK for Python.
This project is in GENERAL AVAILABILITY. If you have any issues or feature requests, please file an issue or pull request.
This SDK is built on the AWS Common Runtime, a collection of libraries
(1,
2,
3,
4,
5,
6,
7,
8 ...) written in C to be
cross-platform, high-performance, secure, and reliable. The libraries are bound
to Python by the awscrt
package (PyPI) (Github).
Integration with AWS IoT Services such as Device Shadow and Jobs is provided by code that been generated from a model of the service.
- Python 3.5+ or Python 2.7+
pip install awsiotsdk
pip install ./aws-iot-device-sdk-python-v2
awsiotsdk
depends on awscrt, which makes use of C extensions. Precompiled wheels are downloaded when installing on major platforms (Mac, Windows, Linux, Raspbian (python3 only)). If wheels are unavailable for your platform (ex: Raspbian with python2.7), your machine must compile some C libraries. If you encounter issues, install the following and try again:
sudo apt-get update
sudo apt-get install cmake
sudo apt-get install libssl-dev
This sample uses the Message Broker for AWS IoT to send and receive messages through an MQTT connection. On startup, the device connects to the server, subscribes to a topic, and begins publishing messages to that topic. The device should receive those same messages back from the message broker, since it is subscribed to that same topic. Status updates are continually printed to the console.
Source: samples/pubsub.py
Run the sample like this:
python pubsub.py --endpoint <endpoint> --root-ca <file> --cert <file> --key <file>
Your Thing's Policy must provide privileges for this sample to connect, subscribe, publish, and receive.
(see sample policy)
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish", "iot:Receive" ], "Resource": [ "arn:aws:iot:region:account:topic/samples/test" ] }, { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:region:account:topicfilter/samples/test" ] }, { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": [ "arn:aws:iot:region:account:client/samples-client-id" ] } ] }
This sample uses the AWS IoT Device Shadow Service to keep a property in sync between device and server. Imagine a light whose color may be changed through an app, or set by a local user.
Once connected, type a value in the terminal and press Enter to update the property's "reported" value. The sample also responds when the "desired" value changes on the server. To observe this, edit the Shadow document in the AWS Console and set a new "desired" value.
On startup, the sample requests the shadow document to learn the property's initial state. The sample also subscribes to "delta" events from the server, which are sent when a property's "desired" value differs from its "reported" value. When the sample learns of a new desired value, that value is changed on the device and an update is sent to the server with the new "reported" value.
Source: samples/shadow.py
Run the sample like this:
python shadow.py --endpoint <endpoint> --root-ca <file> --cert <file> --key <file> --thing-name <name>
Your Thing's Policy must provide privileges for this sample to connect, subscribe, publish, and receive.
(see sample policy)
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/things/thingname/shadow/get", "arn:aws:iot:region:account:topic/$aws/things/thingname/shadow/update" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/things/thingname/shadow/get/accepted", "arn:aws:iot:region:account:topic/$aws/things/thingname/shadow/get/rejected", "arn:aws:iot:region:account:topic/$aws/things/thingname/shadow/update/accepted", "arn:aws:iot:region:account:topic/$aws/things/thingname/shadow/update/rejected", "arn:aws:iot:region:account:topic/$aws/things/thingname/shadow/update/delta" ] }, { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:region:account:topicfilter/$aws/things/thingname/shadow/get/accepted", "arn:aws:iot:region:account:topicfilter/$aws/things/thingname/shadow/get/rejected", "arn:aws:iot:region:account:topicfilter/$aws/things/thingname/shadow/update/accepted", "arn:aws:iot:region:account:topicfilter/$aws/things/thingname/shadow/update/rejected", "arn:aws:iot:region:account:topicfilter/$aws/things/thingname/shadow/update/delta" ] }, { "Effect": "Allow", "Action": "iot:Connect", "Resource": "arn:aws:iot:region:account:client/samples-client-id" } ] }
This sample uses the AWS IoT Jobs Service to receive and execute operations on the device. Imagine periodic software updates that must be sent to and executed on devices in the wild.
This sample requires you to create jobs for your device to execute. See instructions here.
On startup, the sample tries to start the next pending job execution. If such a job exists, the sample emulates "doing work" by spawning a thread that sleeps for several seconds before marking the job as SUCCEEDED. When no pending job executions exist, the sample sits in an idle state.
The sample also subscribes to receive "Next Job Execution Changed" events. If the sample is idle, this event wakes it to start the job. If the sample is already working on a job, it remembers to try for another when it's done. This event is sent by the service when the current job completes, so the sample will be continually prompted to try another job until none remain.
Source: samples/jobs.py
Run the sample like this:
python jobs.py --endpoint <endpoint> --root-ca <file> --cert <file> --key <file> --thing-name <name>
Your Thing's Policy must provide privileges for this sample to connect, subscribe, publish, and receive.
(see sample policy)
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/things/thingname/jobs/start-next", "arn:aws:iot:region:account:topic/$aws/things/thingname/jobs/*/update" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/things/thingname/jobs/notify-next", "arn:aws:iot:region:account:topic/$aws/things/thingname/jobs/start-next/accepted", "arn:aws:iot:region:account:topic/$aws/things/thingname/jobs/start-next/rejected", "arn:aws:iot:region:account:topic/$aws/things/thingname/jobs/*/update/accepted", "arn:aws:iot:region:account:topic/$aws/things/thingname/jobs/*/update/rejected" ] }, { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:region:account:topicfilter/$aws/things/thingname/jobs/notify-next", "arn:aws:iot:region:account:topicfilter/$aws/things/thingname/jobs/start-next/accepted", "arn:aws:iot:region:account:topicfilter/$aws/things/thingname/jobs/start-next/rejected", "arn:aws:iot:region:account:topicfilter/$aws/things/thingname/jobs/*/update/accepted", "arn:aws:iot:region:account:topicfilter/$aws/things/thingname/jobs/*/update/rejected" ] }, { "Effect": "Allow", "Action": "iot:Connect", "Resource": "arn:aws:iot:region:account:client/samples-client-id" } ] }
This sample uses the AWS IoT Fleet provisioning to provision devices using either a CSR or KeysAndcertificate and subsequently calls RegisterThing.
On startup, the script subscribes to topics based on the request type of either CSR or Keys topics, publishes the request to corresponding topic and calls RegisterThing.
Source: samples/fleetprovisioning.py
Run the sample using createKeysAndCertificate:
python fleetprovisioning.py --endpoint <endpoint> --root-ca <file> --cert <file> --key <file> --templateName <name> --templateParameters <parameters>
Run the sample using createCertificateFromCsr:
python fleetprovisioning.py --endpoint <endpoint> --root-ca <file> --cert <file> --key <file> --templateName <name> --templateParameters <parameters> --csr <csr file>
Your Thing's Policy must provide privileges for this sample to connect, subscribe, publish, and receive.
(see sample policy)
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/certificates/create/json", "arn:aws:iot:region:account:topic/$aws/certificates/create-from-csr/json", "arn:aws:iot:region:account:topic/$aws/provisioning-templates/templatename/provision/json" ] }, { "Effect": "Allow", "Action": [ "iot:Receive", "iot:Subscribe" ], "Resource": [ "arn:aws:iot:region:account:topic/$aws/certificates/create/json/accepted", "arn:aws:iot:region:account:topic/$aws/certificates/create/json/rejected", "arn:aws:iot:region:account:topic/$aws/certificates/create-from-csr/json/accepted", "arn:aws:iot:region:account:topic/$aws/certificates/create-from-csr/json/rejected", "arn:aws:iot:region:account:topic/$aws/provisioning-templates/templatename/provision/json/accepted", "arn:aws:iot:region:account:topic/$aws/provisioning-templates/templatename/provision/json/rejected" ] }, { "Effect": "Allow", "Action": "iot:Connect", "Resource": "arn:aws:iot:region:account:client/samples-client-id" } ] }
This sample intended for use directly with the Getting Started with AWS IoT Greengrass guide.
This library is licensed under the Apache 2.0 License.