diff --git a/codebuild/samples/pubsub-mqtt5-linux.sh b/codebuild/samples/pubsub-mqtt5-linux.sh index ee0e76b0..d37dacfc 100755 --- a/codebuild/samples/pubsub-mqtt5-linux.sh +++ b/codebuild/samples/pubsub-mqtt5-linux.sh @@ -12,4 +12,4 @@ ENDPOINT=$(aws secretsmanager get-secret-value --secret-id "ci/endpoint" --query echo "MQTT5 PubSub test" python3 mqtt5_pubsub.py --endpoint $ENDPOINT --key /tmp/privatekey.pem --cert /tmp/certificate.pem -popd \ No newline at end of file +popd diff --git a/documents/FAQ.md b/documents/FAQ.md index b981b292..28b2433a 100644 --- a/documents/FAQ.md +++ b/documents/FAQ.md @@ -40,7 +40,7 @@ Please note that on Mac, once a private key is used with a certificate, that cer static: certificate has an existing certificate-key pair that was previously imported into the Keychain. Using key from Keychain instead of the one provided. ``` -### How do debug in VSCode? +### How do debug in VSCode? Here is an example launch.json file to run the pubsub sample ``` json @@ -79,13 +79,13 @@ Here is an example launch.json file to run the pubsub sample * Device certificate * Intermediate device certificate that is used to generate the key below * When using samples it can look like this: `--cert abcde12345-certificate.pem.crt` - * Key files + * Key files * You should have generated/downloaded private and public keys that will be used to verify that communications are coming from you * When using samples you only need the private key and it will look like this: `--key abcde12345-private.pem.key` ### I still have more questions about the this sdk? * [Here](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) are the AWS IoT Core docs for more details about IoT Core -* [Here](https://docs.aws.amazon.com/greengrass/v2/developerguide/what-is-iot-greengrass.html) are the AWS IoT Greengrass v2 docs for more details about greengrass +* [Here](https://docs.aws.amazon.com/greengrass/v2/developerguide/what-is-iot-greengrass.html) are the AWS IoT Greengrass v2 docs for more details about greengrass * [Discussion](https://github.com/aws/aws-iot-device-sdk-python-v2/discussions) questions are also a great way to ask other questions about this sdk. -* [Open an issue](https://github.com/aws/aws-iot-device-sdk-python-v2/issues) if you find a bug or have a feature request \ No newline at end of file +* [Open an issue](https://github.com/aws/aws-iot-device-sdk-python-v2/issues) if you find a bug or have a feature request diff --git a/samples/README.md b/samples/README.md index 6344ee3c..4af8b24b 100644 --- a/samples/README.md +++ b/samples/README.md @@ -1,926 +1,50 @@ # Sample apps for the AWS IoT Device SDK v2 for Python -* [MQTT5 PubSub](#mqtt5-pubsub) -* [PubSub](#pubsub) -* [Basic Connect](#basic-connect) -* [Websocket Connect](#websocket-connect) -* [PKCS#11 Connect](#pkcs11-connect) -* [Windows Certificate Connect](#windows-certificate-connect) -* [Custom Authorizer Connect](#custom-authorizer-connect) -* [Cognito Connect](#cognito-connect) -* [Shadow](#shadow) -* [Jobs](#jobs) -* [Fleet Provisioning](#fleet-provisioning) -* [Greengrass Discovery](#greengrass-discovery) +* [MQTT5 PubSub](./mqtt5_pubsub.md) +* [PubSub](./pubsub.md) +* [Basic Connect](./basic_connect.md) +* [Websocket Connect](./websocket_connect.md) +* [MQTT5 PKCS#11 Connect](./mqtt5_pkcs11_connect.md) +* [PKCS#11 Connect](./pkcs11_connect.md) +* [Windows Certificate Connect](./windows_cert_connect/README.md) +* [MQTT5 Custom Authorizer Connect](./mqtt5_custom_authorizer_connect.md) +* [Custom Authorizer Connect](./custom_authorizer_connect.md) +* [Cognito Connect](./cognito_connect.md) +* [Shadow](./shadow.md) +* [Jobs](./jobs.md) +* [Fleet Provisioning](./fleetprovisioning.md) +* [Greengrass Discovery](./basic_discovery.md) +* [Greengrass IPC](./ipc_greengrass.md) -## Build instructions +### Build instructions -First, install the aws-iot-devices-sdk-python-v2 with following the instructions from [Installation](../README.md#Installation). +First, install the `aws-iot-devices-sdk-python-v2` with following the instructions from [Installation](../README.md#Installation). -Then change into the samples directory to run the Python commands to execute the samples. You can view the commands of a sample like this: +Then change into the `samples` folder/directory to run the Python commands to execute the samples. Each sample README has instructions on how to run each sample and each sample can be run from the `samples` folder. For example, to run the [PubSub](./pubsub/README.md) sample: ``` sh -# For Windows: replace 'python3' with 'python' -python3 pubsub.py --help -``` - -## MQTT5 PubSub -This sample uses the -[Message Broker](https://docs.aws.amazon.com/iot/latest/developerguide/iot-message-broker.html) -for AWS IoT to send and receive messages -through an MQTT5 connection. - -MQTT5 introduces additional features and enhancements that improve the development experience with MQTT. You can read more about MQTT5 in the Python V2 SDK by checking out the [MQTT5 user guide](../documents/MQTT5.md). - -Note: MQTT5 support is currently in **developer preview**. We encourage feedback at all times, but feedback during the preview window is especially valuable in shaping the final product. During the preview period we may make backwards-incompatible changes to the public API, but in general, this is something we will try our best to avoid. - -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/mqtt5_pubsub.py` - -Your Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect, subscribe, publish, and receive. Make sure your policy allows a client ID of `test-*` to connect or use `--client_id ` to send the client ID your policy supports. - -
-(see sample policy) -
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Publish",
-        "iot:Receive"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:topic/test/topic"
-      ]
-    },
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Subscribe"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:topicfilter/test/topic"
-      ]
-    },
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Connect"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:client/test-*"
-      ]
-    }
-  ]
-}
-
-
- -Run the sample like this: -``` sh -# For Windows: replace 'python3' with 'python' -python3 mqtt5_pubsub.py --endpoint --ca_file --cert --key -``` - -## PubSub - -This sample uses the -[Message Broker](https://docs.aws.amazon.com/iot/latest/developerguide/iot-message-broker.html) -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` - -Your Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect, subscribe, publish, and receive. Make sure your policy allows a client ID of `test-*` to connect or use `--client_id ` to send the client ID your policy supports. - -
-(see sample policy) -
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Publish",
-        "iot:Receive"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:topic/test/topic"
-      ]
-    },
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Subscribe"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:topicfilter/test/topic"
-      ]
-    },
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Connect"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:client/test-*"
-      ]
-    }
-  ]
-}
-
-
- -Run the sample like this: -``` sh -# For Windows: replace 'python3' with 'python' -python3 pubsub.py --endpoint --ca_file --cert --key -``` - -## Basic Connect - -This sample makes an MQTT connection using a certificate and key file. On startup, the device connects to the server using the certificate and key files, and then disconnects. -This sample is for reference on connecting via certificate and key files. - -Source: `samples/basic_connect.py` - -Your Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect. Make sure your policy allows a client ID of `test-*` to connect or use `--client_id ` to send the client ID your policy supports. - -
-(see sample policy) -
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Connect"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:client/test-*"
-      ]
-    }
-  ]
-}
-
-
- -Run the sample like this: -``` sh -# For Windows: replace 'python3' with 'python' -python3 basic_connect.py --endpoint --ca_file --cert --key -``` - -## Websocket Connect - -This sample makes an MQTT connection via websockets and then disconnects. On startup, the device connects to the server via websockets and then disconnects. -This sample is for reference on connecting via websockets. - -Source: `samples/websocket_connect.py` - -Your Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect. Make sure your policy allows a client ID of `test-*` to connect or use `--client_id ` to send the client ID your policy supports. - -
-(see sample policy) -
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Connect"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:client/test-*"
-      ]
-    }
-  ]
-}
-
-
- -Run the sample like this: -``` sh -# For Windows: replace 'python3' with 'python' -python3 websocket_connect.py --endpoint --ca_file --signing_region -``` - -Note that using Websockets will attempt to fetch the AWS credentials from your enviornment variables or local files. See the [authorizing direct AWS](https://docs.aws.amazon.com/iot/latest/developerguide/authorizing-direct-aws.html) page for documentation on how to get the AWS credentials, which then you can set to the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS`, and `AWS_SESSION_TOKEN` environment variables. - -## PKCS#11 Connect - -This sample is similar to the [Basic Connect](#basic-connect), -but the private key for mutual TLS is stored on a PKCS#11 compatible smart card or Hardware Security Module (HSM) - -WARNING: Unix only. Currently, TLS integration with PKCS#11 is only available on Unix devices. - -source: `samples/pkcs11_connect.py` - -Your Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect. Make sure your policy allows a client ID of `test-*` to connect or use `--client_id ` to send the client ID your policy supports. - -
-(see sample policy) -
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Connect"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:client/test-*"
-      ]
-    }
-  ]
-}
-
-
- -To run this sample using [SoftHSM2](https://www.opendnssec.org/softhsm/) as the PKCS#11 device: - -1) Create an IoT Thing with a certificate and key if you haven't already. - -2) Convert the private key into PKCS#8 format - ```sh - openssl pkcs8 -topk8 -in -out -nocrypt - ``` - -3) Install [SoftHSM2](https://www.opendnssec.org/softhsm/): - ```sh - sudo apt install softhsm - ``` - - Check that it's working: - ```sh - softhsm2-util --show-slots - ``` - - If this spits out an error message, create a config file: - * Default location: `~/.config/softhsm2/softhsm2.conf` - * This file must specify token dir, default value is: - ``` - directories.tokendir = /usr/local/var/lib/softhsm/tokens/ - ``` - -4) Create token and import private key. - - You can use any values for the labels, PINs, etc - ```sh - softhsm2-util --init-token --free --label --pin --so-pin - ``` - - Note which slot the token ended up in - - ```sh - softhsm2-util --import --slot --label --id --pin - ``` - -5) Now you can run the sample: - ```sh - # For Windows: replace 'python3' with 'python' - python3 pkcs11_connect.py --endpoint --ca_file --cert --pkcs11_lib --pin --token_label --key_label - ``` - -## Windows Certificate Connect - -WARNING: Windows only - -This sample is similar to the basic [Connect](#basic-connect), -but your certificate and private key are in a -[Windows certificate store](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/certificate-stores), -rather than simply being files on disk. - -To run this sample you need the path to your certificate in the store, -which will look something like: -"CurrentUser\My\A11F8A9B5DF5B98BA3508FBCA575D09570E0D2C6" -(where "CurrentUser\My" is the store and "A11F8A9B5DF5B98BA3508FBCA575D09570E0D2C6" is the certificate's thumbprint) - -If your certificate and private key are in a -[TPM](https://docs.microsoft.com/en-us/windows/security/information-protection/tpm/trusted-platform-module-overview),, -you would use them by passing their certificate store path. - -source: `samples/windows_cert_connect.py` - -Your Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect. Make sure your policy allows a client ID of `test-*` to connect or use `--client_id ` to send the client ID your policy supports. - -
-(see sample policy) -
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Connect"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:client/test-*"
-      ]
-    }
-  ]
-}
-
-
- -To run this sample with a basic certificate from AWS IoT Core: - -1) Create an IoT Thing with a certificate and key if you haven't already. - -2) Combine the certificate and private key into a single .pfx file. - - You will be prompted for a password while creating this file. Remember it for the next step. - - If you have OpenSSL installed: - ```powershell - openssl pkcs12 -in certificate.pem.crt -inkey private.pem.key -out certificate.pfx - ``` - - Otherwise use [CertUtil](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/certutil). - ```powershell - certutil -mergePFX certificate.pem.crt,private.pem.key certificate.pfx - ``` - -3) Add the .pfx file to a Windows certificate store using PowerShell's - [Import-PfxCertificate](https://docs.microsoft.com/en-us/powershell/module/pki/import-pfxcertificate) - - In this example we're adding it to "CurrentUser\My" - - ```powershell - $mypwd = Get-Credential -UserName 'Enter password below' -Message 'Enter password below' - Import-PfxCertificate -FilePath certificate.pfx -CertStoreLocation Cert:\CurrentUser\My -Password $mypwd.Password - ``` - - Note the certificate thumbprint that is printed out: - ``` - Thumbprint Subject - ---------- ------- - A11F8A9B5DF5B98BA3508FBCA575D09570E0D2C6 CN=AWS IoT Certificate - ``` - - So this certificate's path would be: "CurrentUser\My\A11F8A9B5DF5B98BA3508FBCA575D09570E0D2C6" - -4) Now you can run the sample: - - ```sh - # For Windows: replace 'python3' with 'python' - python3 windows_cert_connect.py --endpoint --ca_file --cert - ``` - -## Custom Authorizer Connect - -This sample makes an MQTT connection and connects through a [Custom Authorizer](https://docs.aws.amazon.com/iot/latest/developerguide/custom-authentication.html). On startup, the device connects to the server and then disconnects. This sample is for reference on connecting using a custom authorizer. - -Your Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect. Make sure your policy allows a client ID of `test-*` to connect or use `--client_id ` to send the client ID your policy supports. - -
-(see sample policy) -
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Connect"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:client/test-*"
-      ]
-    }
-  ]
-}
-
-
- -Run the sample like this: -``` sh -# For Windows: replace 'python3' with 'python' -python3 custom_authorizer_connect.py --endpoint --custom_auth_authorizer_name -``` - -You will need to setup your Custom Authorizer so that the lambda function returns a policy document. See [this page on the documentation](https://docs.aws.amazon.com/iot/latest/developerguide/config-custom-auth.html) for more details and example return result. - -## Cognito Connect - -This sample makes an MQTT websocket connection and connects through a [Cognito](https://aws.amazon.com/cognito/) identity. On startup, the device connects to the server and then disconnects. This sample is for reference on connecting using Cognito. - -To run this sample, you need to have a Cognito identifier ID. You can get a Cognito identifier ID by creating a Cognito identity pool. For creating Cognito identity pools, please see the following page on the AWS documentation: [Tutorial: Creating an identity pool](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-identity-pool.html) - -**Note:** This sample assumes using an identity pool with unauthenticated identity access for the sake of convenience. Please follow best practices in a real world application based on the needs of your application and the intended use case. - -Once you have a Cognito identity pool, you can run the following CLI command to get the Cognito identity pool ID: -```sh -aws cognito-identity get-id --identity-pool-id -# result from above command -{ - "IdentityId": "" -} -``` - -You can then use the returned ID in the `IdentityId` result as the input for the `--cognito_identity` argument. Please note that the Cognito identity pool ID is **not** the same as a Cognito identity ID and the sample will not work if you pass a Cognito pool id. - -Your IoT Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect. Make sure your policy allows a client ID of `test-*` to connect or use `--client_id ` to send the client ID your policy supports. - -
-(see sample policy) -
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Connect"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:client/test-*"
-      ]
-    }
-  ]
-}
-
-
- -Run the sample like this: -``` sh -# For Windows: replace 'python3' with 'python' -python3 cognito_connect.py --endpoint --signing_region --cognito_identity -``` - -## Shadow - -This sample uses the AWS IoT -[Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html) -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: -``` sh -# For Windows: replace 'python3' with 'python' -python3 shadow.py --endpoint --ca_file --cert --key --thing_name -``` - -Your Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect, subscribe, publish, and receive. Make sure your policy allows a client ID of `test-*` to connect or use `--client_id ` to send the client ID your policy supports. - -
-(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/test-*"
-    }
-  ]
-}
-
-
- -## Jobs - -This sample uses the AWS IoT -[Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) -Service to get a list of pending jobs and -then execution operations on these pending jobs until there are no more -remaining 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](https://docs.aws.amazon.com/iot/latest/developerguide/create-manage-jobs.html). - -On startup, the sample tries to get a list of all the in-progress and queued -jobs and display them in a list. Then it 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: -``` sh -# For Windows: replace 'python3' with 'python' -python3 jobs.py --endpoint --ca_file --cert --key --thing_name -``` - -Your Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect, subscribe, publish, and receive. Make sure your policy allows a client ID of `test-*` to connect or use `--client_id ` to send the client ID your policy supports. - -
-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",
-        "arn:aws:iot:region:account:topic/$aws/things/thingname/jobs/*/get",
-        "arn:aws:iot:region:account:topic/$aws/things/thingname/jobs/get"
-      ]
-    },
-    {
-      "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/*",
-        "arn:aws:iot:region:account:topic/$aws/things/thingname/jobs/*/update/*",
-        "arn:aws:iot:region:account:topic/$aws/things/thingname/jobs/get/*",
-        "arn:aws:iot:region:account:topic/$aws/things/thingname/jobs/*/get/*"
-      ]
-    },
-    {
-      "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/*",
-        "arn:aws:iot:region:account:topicfilter/$aws/things/thingname/jobs/*/update/*",
-        "arn:aws:iot:region:account:topicfilter/$aws/things/thingname/jobs/get/*",
-        "arn:aws:iot:region:account:topicfilter/$aws/things/thingname/jobs/*/get/*"
-      ]
-    },
-    {
-      "Effect": "Allow",
-      "Action": "iot:Connect",
-      "Resource": "arn:aws:iot:region:account:client/test-*"
-    }
-  ]
-}
-
-
- -## Fleet Provisioning - -This sample uses the AWS IoT -[Fleet provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) -to provision devices using either a CSR or Keys-And-Certificate 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: -``` sh -# For Windows: replace 'python3' with 'python' -python3 fleetprovisioning.py --endpoint --ca_file --cert --key --template_name --template_parameters -``` - -Run the sample using createCertificateFromCsr: -``` sh -# For Windows: replace 'python3' with 'python' -python3 fleetprovisioning.py --endpoint --ca_file --cert --key --template_name --template_parameters --csr -``` - -Your Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect, subscribe, publish, and receive. Make sure your policy allows a client ID of `test-*` to connect or use `--client_id ` to send the client ID your policy supports. - -
-(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"
-      ],
-      "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:Subscribe"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:topicfilter/$aws/certificates/create/json/accepted",
-        "arn:aws:iot:region:account:topicfilter/$aws/certificates/create/json/rejected",
-        "arn:aws:iot:region:account:topicfilter/$aws/certificates/create-from-csr/json/accepted",
-        "arn:aws:iot:region:account:topicfilter/$aws/certificates/create-from-csr/json/rejected",
-        "arn:aws:iot:region:account:topicfilter/$aws/provisioning-templates/templatename/provision/json/accepted",
-        "arn:aws:iot:region:account:topicfilter/$aws/provisioning-templates/templatename/provision/json/rejected"
-      ]
-    },
-    {
-      "Effect": "Allow",
-      "Action": "iot:Connect",
-      "Resource": "arn:aws:iot:region:account:client/test-*"
-    }
-  ]
-}
-
-
- -### Fleet Provisioning Detailed Instructions - -#### AWS Resource Setup - -Fleet provisioning requires some additional AWS resources be set up first. This section documents the steps you need to take to -get the sample up and running. These steps assume you have the AWS CLI installed and the default user/credentials has -sufficient permission to perform all of the listed operations. These steps are based on provisioning setup steps -that can be found at [Embedded C SDK Setup](https://docs.aws.amazon.com/freertos/latest/lib-ref/c-sdk/provisioning/provisioning_tests.html#provisioning_system_tests_setup). - -First, create the IAM role that will be needed by the fleet provisioning template. Replace `RoleName` with a name of the role you want to create. -``` sh -aws iam create-role \ - --role-name [RoleName] \ - --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Action":"sts:AssumeRole","Effect":"Allow","Principal":{"Service":"iot.amazonaws.com"}}]}' -``` -Next, attach a policy to the role created in the first step. Replace `RoleName` with the name of the role you created previously. -``` sh -aws iam attach-role-policy \ - --role-name [RoleName] \ - --policy-arn arn:aws:iam::aws:policy/service-role/AWSIoTThingsRegistration -``` -Finally, create the template resource which will be used for provisioning by the demo application. This needs to be done only -once. To create a template, the following AWS CLI command may be used. Replace `TemplateName` with the name of the fleet -provisioning template you want to create. Replace `RoleName` with the name of the role you created previously. Replace -`TemplateJSON` with the template body as a JSON string (containing escape characters). Replace `account` with your AWS -account number. -``` sh -aws iot create-provisioning-template \ - --template-name [TemplateName] \ - --provisioning-role-arn arn:aws:iam::[account]:role/[RoleName] \ - --template-body "[TemplateJSON]" \ - --enabled -``` -The rest of the instructions assume you have used the following for the template body: - -
-(see template body) -``` sh -{ - "Parameters": { - "DeviceLocation": { - "Type": "String" - }, - "AWS::IoT::Certificate::Id": { - "Type": "String" - }, - "SerialNumber": { - "Type": "String" - } - }, - "Mappings": { - "LocationTable": { - "Seattle": { - "LocationUrl": "https://example.aws" - } - } - }, - "Resources": { - "thing": { - "Type": "AWS::IoT::Thing", - "Properties": { - "ThingName": { - "Fn::Join": [ - "", - [ - "ThingPrefix_", - { - "Ref": "SerialNumber" - } - ] - ] - }, - "AttributePayload": { - "version": "v1", - "serialNumber": "serialNumber" - } - }, - "OverrideSettings": { - "AttributePayload": "MERGE", - "ThingTypeName": "REPLACE", - "ThingGroups": "DO_NOTHING" - } - }, - "certificate": { - "Type": "AWS::IoT::Certificate", - "Properties": { - "CertificateId": { - "Ref": "AWS::IoT::Certificate::Id" - }, - "Status": "Active" - }, - "OverrideSettings": { - "Status": "REPLACE" - } - }, - "policy": { - "Type": "AWS::IoT::Policy", - "Properties": { - "PolicyDocument": { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "iot:Connect", - "iot:Subscribe", - "iot:Publish", - "iot:Receive" - ], - "Resource": "*" - } - ] - } - } - } - }, - "DeviceConfiguration": { - "FallbackUrl": "https://www.example.com/test-site", - "LocationUrl": { - "Fn::FindInMap": [ - "LocationTable", - { - "Ref": "DeviceLocation" - }, - "LocationUrl" - ] - } - } -} +# For Windows: replace 'python3' with 'python' and '/' with '\' +python3 pubsub.py --endpoint --cert --key ``` -
-If you use a different body, you may need to pass in different template parameters. +### Sample Help -#### Running the sample and provisioning using a certificate-key set from a provisioning claim +All samples will show their options by passing in `--help`. For example: -To run the provisioning sample, you'll need a certificate and key set with sufficient permissions. Provisioning certificates are normally -created ahead of time and placed on your device, but for this sample, we will just create them on the fly. You can also -use any certificate set you've already created if it has sufficient IoT permissions and in doing so, you can skip the step -that calls `create-provisioning-claim`. - -We've included a script in the utils folder that creates certificate and key files from the response of calling -`create-provisioning-claim`. These dynamically sourced certificates are only valid for five minutes. When running the command, -you'll need to substitute the name of the template you previously created, and on Windows, replace the paths with something appropriate. - -(Optional) Create a temporary provisioning claim certificate set: -``` sh -aws iot create-provisioning-claim \ - --template-name [TemplateName] \ - | python3 ../utils/parse_cert_set_result.py \ - --path /tmp \ - --filename provision -``` - -The provisioning claim's cert and key set have been written to `/tmp/provision*`. Now you can use these temporary keys -to perform the actual provisioning. If you are not using the temporary provisioning certificate, replace the paths for `--cert` -and `--key` appropriately: - -``` sh -# For Windows: replace 'python3' with 'python' -python3 fleetprovisioning.py \ - --endpoint \ - --ca_file \ - --cert \ - --key \ - --template_name