Additional sample apps not described below:
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
To Run:
> mvn exec:java -pl samples/Shadow -Dexec.mainClass=shadow.ShadowSample -Dexec.args='--endpoint <endpoint> --rootca /path/to/AmazonRootCA1.pem --cert <cert path> --key <key path> --thingName <thing name>'Your Thing's Policy must provide privileges for this sample to connect, subscribe, publish, and receive.
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-*"
}
]
}
This sample uses the AWS IoT Jobs Service to describe jobs to execute.
This sample requires you to create jobs for your device to execute. See instructions here.
On startup, the sample describes a job that is pending execution.
Source: samples/Jobs
To Run:
> mvn exec:java -pl samples/Jobs -Dexec.mainClass=jobs.JobsSample -Dexec.args='--endpoint <endpoint> --rootca /path/to/AmazonRootCA1.pem --cert <cert path> --key <key path> --thingName <thing name>'Your Thing's Policy must provide privileges for this sample to connect, subscribe, publish, and receive.
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/test-*"
}
]
}
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/Identity
cd ~/samples/Identity
Run the sample using CreateKeysAndCertificate:
mvn exec:java -Dexec.mainClass="identity.FleetProvisioningSample" -Dexec.args="--endpoint <endpoint> --rootca <root ca path>
--cert <cert path> --key <private key path> --templateName <templatename> --templateParameters <templateParams>"Run the sample using CreateCertificateFromCsr:
mvn exec:java -Dexec.mainClass="identity.FleetProvisioningSample" -Dexec.args="--endpoint <endpoint> --rootca <root ca path>
--cert <cert path> --key <private key path> --templateName <templatename> --templateParameters <templateParams> --csr <csr path>"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/test-*"
}
]
}
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. You will also need python3 to be able to run parse_cert_set_result.py. These steps are based on provisioning setup steps that can be found at Embedded C SDK 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.
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.
aws iam attach-role-policy \
--role-name [RoleName] \
--policy-arn arn:aws:iam::aws:policy/service-role/AWSIoTThingsRegistrationFinally, 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.
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:
{\"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\"]}}}If you use a different body, you may need to pass in different template parameters.
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. This command is executed in the debug folder(aws-iot-device-sdk-java-v2-build\samples\identity\fleet_provisioning\Debug):
aws iot create-provisioning-claim \
--template-name [TemplateName] \
| python3 ../../../../../aws-iot-device-sdk-java-v2/utils/parse_cert_set_result.py \
--path /tmp \
--filename provisionThe 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:
mvn exec:java -Dexec.mainClass="identity.FleetProvisioningSample" -Dexec.args="--endpoint [your endpoint]-ats.iot.[region].amazonaws.com --rootca [pathToRootCA]
--cert /tmp/provision.cert.pem --key /tmp/provision.private.key --templateName [TemplateName] --templateParameters {\"SerialNumber\":\"1\",\"DeviceLocation\":\"Seattle\"}"Notice that we provided substitution values for the two parameters in the template body, DeviceLocation and SerialNumber.
To run the sample with this workflow, you'll need to create a certificate signing request.
First create a certificate-key pair:
openssl genrsa -out /tmp/deviceCert.key 2048Next create a certificate signing request from it:
openssl req -new -key /tmp/deviceCert.key -out /tmp/deviceCert.csr(Optional) As with the previous workflow, we'll create a temporary certificate set from a provisioning claim. This step can
be skipped if you're using a certificate set capable of provisioning the device. This command is executed in the debug folder(aws-iot-device-sdk-java-v2-build\samples\identity\fleet_provisioning\Debug):
aws iot create-provisioning-claim \
--template-name [TemplateName] \
| python3 ../../../../../aws-iot-device-sdk-java-v2/utils/parse_cert_set_result.py \
--path /tmp \
--filename provisionFinally, supply the certificate signing request while invoking the provisioning sample. As with the previous workflow, if
using a permanent certificate set, replace the paths specified in the --cert and --key arguments:
mvn exec:java -Dexec.mainClass="identity.FleetProvisioningSample" -Dexec.args="--endpoint [your endpoint]-ats.iot.[region].amazonaws.com --rootca [pathToRootCA]
--cert /tmp/provision.cert.pem --key /tmp/provision.private.key --templateName [TemplateName] --templateParameters {\"SerialNumber\":\"1\",\"DeviceLocation\":\"Seattle\"} --csr /tmp/deviceCert.csr"This sample is intended for use with the following tutorials in the AWS IoT Greengrass documentation:
- Connect and test client devices (Greengrass V2)
- Test client device communications (Greengrass V2)
- Getting Started with AWS IoT Greengrass (Greengrass V1)