Readme (#126)

standardized README format
moved examples to sample folder README

Author: jmklix

LICENSE

@@ -187,7 +187,8 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+   SPDX-License-Identifier: Apache-2.0
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,9 +1,7 @@
 # AWS IoT SDK for C++ v2
+This document provides information about the AWS IoT device SDK for C++ V2.
 
-Next generation AWS IoT Client SDK for C++.
-
-This project is in **GENERAL AVAILABILITY**. If you have any issues or feature
-requests, please file an issue or pull request.
+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
 ([aws-c-common](https://github.com/awslabs/aws-c-common),
@@ -16,20 +14,27 @@ This SDK is built on the AWS Common Runtime, a collection of libraries
 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
+*__Jump To:__*
+* [Installation](#Installation)
+* [Samples](samples)
+* [Getting Help](#Getting-Help)
+* [Giving Feedback and Contributions](#Giving-Feedback-and-Contributions)
+* [More Resources](#More-Resources)
+
+
+
+## Installation
+
+### Minimum Requirements
 *   C++ 11 or higher
 *   CMake 3.1+
 *   Clang 3.9+ or GCC 4.4+ or MSVC 2015+
 
-## Build from source
-### Automatically Build and Install AWS Dependencies
-```
+
+### Build from source
+#### Automatically Build and Install AWS Dependencies
+```sh
 mkdir sdk-cpp-workspace
 cd sdk-cpp-workspace
 git clone --recursive https://github.com/aws/aws-iot-device-sdk-cpp-v2.git
@@ -38,297 +43,64 @@ cd aws-iot-device-sdk-cpp-v2-build
 cmake -DCMAKE_INSTALL_PREFIX="<absolute path sdk-cpp-workspace dir>"  -DBUILD_DEPS=ON ../aws-iot-device-sdk-cpp-v2
 cmake --build . --target install
 ```
-### Using a Pre-Built aws-crt-cpp (Most useful for development of this package)
+#### Using a Pre-Built aws-crt-cpp (Most useful for development of this package)
 
-```
+```sh
 mkdir aws-iot-device-sdk-cpp-v2-build
 cd aws-iot-device-sdk-cpp-v2-build
 cmake -DCMAKE_INSTALL_PREFIX="<absolute path sdk-cpp-workspace dir>"  -DCMAKE_PREFIX_PATH="<absolute path sdk-cpp-workspace dir>" -DBUILD_DEPS=OFF ../aws-iot-device-sdk-cpp-v2
 cmake --build . --target install
 ```
 
-# Mac-Only TLS Behavior
+### Mac-Only TLS Behavior
 
 Please note that on Mac, once a private key is used with a certificate, that certificate-key pair is imported into the Mac Keychain.  All subsequent uses of that certificate will use the stored private key and ignore anything passed in programmatically.  Beginning in v1.7.3, when a stored private key from the Keychain is used, the following will be logged at the "info" log level:
 
 ```
 static: certificate has an existing certificate-key pair that was previously imported into the Keychain.  Using key from Keychain instead of the one provided.
 ```
 
-# Samples
+## Samples
 
-## fleet provisioning
+[Samples README](samples)
 
-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 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/fleet_provisioning`
+## Getting Help
 
-cd ~/aws-iot-device-sdk-cpp-v2-build/samples/identity/fleet_provisioning
+Use the following sources for information :
 
-Run the sample like this to provision using CreateKeysAndCertificate:
- 
-```
-./fleet-provisioning --endpoint <endpoint> --ca_file <path to root CA> 
---cert <path to the certificate> --key <path to the private key> 
---template_name <template name> --template_parameters <template parameters json>
-```
+*   Check api and developer guides.
+*   Check for similar issues already opened.
 
-Run the sample like this to provision using Csr:
- 
-```
-./fleet-provisioning --endpoint <endpoint> --ca_file <path to root CA> 
---cert <path to the certificate> --key <path to the private key> 
---template_name <template name> --template_parameters <template parameters json> --csr <path to the CSR in PEM format>
-```
+If you still can’t find a solution to your problem open an [issue](https://github.com/aws/aws-iot-device-sdk-cpp-v2/issues)
 
-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.
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Publish"
-      ],
-      "Resource": [
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create/json",
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create-from-csr/json",
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/provisioning-templates/<b>templatename<b>/provision/json"
-      ]
-    },
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Receive",
-        "iot:Subscribe"
-      ],
-      "Resource": [
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create/json/accepted",
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create/json/rejected",
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create-from-csr/json/accepted",
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create-from-csr/json/rejected",
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/provisioning-templates/<b>templatename<b>/provision/json/accepted",
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/provisioning-templates/<b>templatename<b>/provision/json/rejected"
-      ]
-    },
-    {
-      "Effect": "Allow",
-      "Action": "iot:Connect",
-      "Resource": "arn:aws:iot:<b>region</b>:<b>account</b>:client/samples-client-id"
-    }
-  ]
-}
-```
 
-## Basic MQTT Pub-Sub
-
-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 and subscribes to a topic.
-
-The terminal prompts the user for input. Type something and press enter to publish a message to the topic.
-Since the sample is subscribed to the same topic, it will also receive the message back from the server.
-Type `quit` and press enter to end the sample.
-
-Source: `samples/mqtt/basic_pub_sub`
-
-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.
-
-```json
-{
-    "Effect": "Allow",
-    "Action": [
-        "iot:Receive",
-        "iot:Publish"
-    ],
-    "Resource": [
-        "arn:aws:iot:<your-region>:<your-id>:topic/a/b"
-    ],
-},
-{
-    "Effect": "Allow",
-    "Action": [
-        "iot:Subscribe"
-    ],
-    "Resource": [
-        "arn:aws:iot:<your-region>:<your-id>:topicfilter/a/b"
-    ]
-}
-```
 
-## Raw MQTT Pub-Sub
-This sample is similar to the Basic Pub-Sub, but the connection setup is more manual.
-This is a starting point for using custom
-[Configurable Endpoints](https://docs.aws.amazon.com/iot/latest/developerguide/iot-custom-endpoints-configurable.html).
+## Giving Feedback and Contributions
+
+We need your help in making this SDK great. Please participate in the community and contribute to this effort by submitting issues, participating in discussion forums and submitting pull requests through the following channels.
+
+*   [Contributions Guidelines](CONTRIBUTING.md)
+*   Articulate your feature request or upvote existing ones on our [Issues](https://github.com/aws/aws-iot-device-sdk-cpp-v2/issues?q=is%3Aissue+is%3Aopen+label%3Afeature-request) page.
+*   Submit [Issues](https://github.com/aws/aws-iot-device-sdk-cpp-v2/issues)
+
 
-source: `samples/mqtt/raw_pub_sub`
 
+## More Resources
 
-## Shadow
+*   [AWS IoT Core Documentation](https://docs.aws.amazon.com/iot/)
+*   [Developer Guide](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) ([source](https://github.com/awsdocs/aws-iot-docs))
+*   [Issues](https://github.com/aws/aws-iot-device-sdk-cpp-v2/issues)
+*   [Dev Blog](https://aws.amazon.com/blogs/?awsf.blog-master-iot=category-internet-of-things%23amazon-freertos%7Ccategory-internet-of-things%23aws-greengrass%7Ccategory-internet-of-things%23aws-iot-analytics%7Ccategory-internet-of-things%23aws-iot-button%7Ccategory-internet-of-things%23aws-iot-device-defender%7Ccategory-internet-of-things%23aws-iot-device-management%7Ccategory-internet-of-things%23aws-iot-platform)
 
-This sample uses the AWS IoT
+Integration with AWS IoT Services such as
 [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>
-
-## Greengrass Discovery
-This sample is intended for direct usage with the Greengrass tutorial found [here](https://docs.aws.amazon.com/greengrass/latest/developerguide/gg-gs.html).
-
-# License
-
-This library is licensed under the Apache 2.0 License.
+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.
+
+
+
+## License
+
+This library is licensed under the [Apache 2.0 License](LICENSE).