Readme updates for dev-preview (#2)

README file

Author: JonathanHenson

README.md

@@ -1,7 +1,198 @@
-## AWS IoT SDK for C++ v2
+# AWS IoT SDK for C++ v2
 
-Next generation AWS IoT Client SDK for C++ using the AWS Common Runtime
+Next generation AWS IoT Client SDK for C++.
 
-## License
+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 library is licensed under the Apache 2.0 License. 
+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>
+{
+  "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.