Readme updates for dev-preview #2
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,198 @@ | ||
| # AWS IoT SDK for C++ v2 | ||
|
|
||
| Next generation AWS IoT Client SDK for C++. | ||
|
|
||
| This project is in **DEVELOPER PREVIEW** while we gather feedback on | ||
| interfaces and use cases. Please file issues and feature requests. | ||
| Expect breaking API changes as we incorporate feedback. | ||
| Until this project is promoted to General Availability, we advise you use the | ||
| [previous SDK](https://github.com/aws/aws-iot-device-sdk-cpp) | ||
| for a stable development environment. | ||
|
|
||
| This SDK is built on the AWS Common Runtime, a collection of libraries | ||
| ([1](https://github.com/awslabs/aws-c-common), | ||
| [2](https://github.com/awslabs/aws-c-io), | ||
| [3](https://github.com/awslabs/aws-c-mqtt), ...) written in C to be | ||
| cross-platform, high-performance, secure, and reliable. The libraries are bound | ||
| to C++ by the [aws-crt-cpp](https://github.com/awslabs/aws-crt-cpp) package. | ||
|
|
||
| Integration with AWS IoT Services such as | ||
| [Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html) | ||
| and [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) | ||
| is provided by code that been generated from a model of the service. | ||
|
|
||
| # Installation | ||
| ## Minimum Requirements | ||
| * C++ 11 or higher | ||
| * CMake 3.1+ | ||
| * Clang 3.9+ or GCC 4.4+ or MSVC 2015+ | ||
|
|
||
| ## Build from source | ||
| ``` | ||
| git clone --branch v0.1.0 https://github.com/awslabs/aws-crt-cpp.git | ||
| git clone https://github.com/awslabs/aws-iot-device-sdk-cpp-v2.git | ||
| mkdir aws-crt-cpp-build | ||
| cd aws-crt-cpp-build | ||
| cmake -DCMAKE_INSTALL_PREFIX="<path to where you install>" -DCMAKE_PREFIX_PATH="<path to where you install>" -DBUILD_SHARED_LIBS=ON -DBUILD_DEPS=ON ../aws-crt-cpp | ||
| <invoke build command make, msbuild, ninja etc....> install | ||
| cd .. | ||
| mkdir aws-iot-device-sdk-cpp-v2 | ||
| cd aws-iot-device-sdk-cpp-v2 | ||
| cmake -DCMAKE_INSTALL_PREFIX="<path to where you install>" -DCMAKE_PREFIX_PATH="<path to where you install>" -DBUILD_SHARED_LIBS=ON ../aws-iot-device-sdk-cpp-v2 | ||
| <invoke build command make, msbuild, ninja etc....> install | ||
|
|
||
| ``` | ||
|
|
||
| # Samples | ||
|
|
||
| ## 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/shadow_sync` | ||
|
|
||
| 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. | ||
|
|
||
| <details> | ||
| <summary>(see sample policy)</summary> | ||
| <pre> | ||
| { | ||
| "Version": "2012-10-17", | ||
| "Statement": [ | ||
| { | ||
| "Effect": "Allow", | ||
| "Action": [ | ||
| "iot:Publish" | ||
| ], | ||
| "Resource": [ | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/shadow/get", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/shadow/update" | ||
| ] | ||
| }, | ||
| { | ||
| "Effect": "Allow", | ||
| "Action": [ | ||
| "iot:Receive" | ||
| ], | ||
| "Resource": [ | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/shadow/get/accepted", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/shadow/get/rejected", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/shadow/update/accepted", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/shadow/update/rejected", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/shadow/update/delta" | ||
| ] | ||
| }, | ||
| { | ||
| "Effect": "Allow", | ||
| "Action": [ | ||
| "iot:Subscribe" | ||
| ], | ||
| "Resource": [ | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/shadow/get/accepted", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/shadow/get/rejected", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/shadow/update/accepted", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/shadow/update/rejected", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/shadow/update/delta" | ||
| ] | ||
| }, | ||
| { | ||
| "Effect": "Allow", | ||
| "Action": "iot:Connect", | ||
| "Resource": "arn:aws:iot:<b>region</b>:<b>account</b>:client/samples-client-id" | ||
| } | ||
| ] | ||
| } | ||
| </pre> | ||
| </details> | ||
|
|
||
| ## Jobs | ||
|
|
||
| This sample uses the AWS IoT | ||
| [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) | ||
| Service to describe jobs to execute. | ||
|
|
||
| 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 describes a job that is pending execution. | ||
|
|
||
| Source: `samples/jobs/describe_job_execution` | ||
|
|
||
| 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. | ||
| <details> | ||
| <summary>(see sample policy)</summary> | ||
| <pre> | ||
|
There was a problem hiding this comment. Instead of <pre> , you can fence the code with ``` (use ```json at the top for the best highlighting). |
||
| { | ||
| "Version": "2012-10-17", | ||
| "Statement": [ | ||
| { | ||
| "Effect": "Allow", | ||
| "Action": [ | ||
| "iot:Publish" | ||
| ], | ||
| "Resource": [ | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/start-next", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/*/update" | ||
| ] | ||
| }, | ||
| { | ||
| "Effect": "Allow", | ||
| "Action": [ | ||
| "iot:Receive" | ||
| ], | ||
| "Resource": [ | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/notify-next", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/start-next/accepted", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/start-next/rejected", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/*/update/accepted", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/*/update/rejected" | ||
| ] | ||
| }, | ||
| { | ||
| "Effect": "Allow", | ||
| "Action": [ | ||
| "iot:Subscribe" | ||
| ], | ||
| "Resource": [ | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/jobs/notify-next", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/jobs/start-next/accepted", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/jobs/start-next/rejected", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/jobs/*/update/accepted", | ||
| "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/jobs/*/update/rejected" | ||
| ] | ||
| }, | ||
| { | ||
| "Effect": "Allow", | ||
| "Action": "iot:Connect", | ||
| "Resource": "arn:aws:iot:<b>region</b>:<b>account</b>:client/samples-client-id" | ||
| } | ||
| ] | ||
| } | ||
| </pre> | ||
| </details> | ||
|
|
||
| # License | ||
|
|
||
| This library is licensed under the Apache 2.0 License. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
same