README updates for 202009.00 release (#1270)

* README updates for 202009.00 release

Co-authored-by: leegeth <[email protected]>

Author: Archit Aggarwal

README.md

@@ -1,12 +1,55 @@
 
-# AWS IoT Device SDK C
+# AWS IoT Device SDK for Embedded C
 
 
-## Branches
+**[API documentation](https://docs.aws.amazon.com/freertos/latest/lib-ref/embedded-csdk/202009.00/lib-ref/index.html)**    
+
+We have released version 202009.00 of the AWS IoT Device SDK for Embedded-C (C-SDK). This release includes refactored MQTT, JSON Parser, and AWS IoT Device Shadow libraries for optimized memory usage and modularity, and includes dependent libraries via GitHub submoduling. These libraries have gone through code quality checks including verification that no function has a [GNU Complexity](https://www.gnu.org/software/complexity/manual/complexity.html) score over 8, and checks against deviations from mandatory rules in the [MISRA coding standard](https://www.misra.org.uk/MISRAHome/MISRAC2012/tabid/196/Default.aspx). They have also undergone both static analysis from [Coverity static analysis](https://scan.coverity.com/) and validation of memory safety and functional correctness proof through the [CBMC automated reasoning tool](https://www.youtube.com/watch?v=YwQHAPRhQkI&feature=youtu.be&t=1721).  
+
+If you are upgrading from v3.x of the C-SDK to the 202009.00 release, please follow the [migration guide](https://docs.aws.amazon.com/freertos/latest/lib-ref/embedded-csdk/202009.00/lib-ref/index.html). If you are using the C-SDK v4_beta_deprecated branch, note that we will continue to maintain this branch for critical bug fixes and security patches but will not add new features to it. See the C-SDK v4_beta_deprecated branch [README](https://github.com/aws/aws-iot-device-sdk-embedded-C/blob/v4_beta_deprecated/README.md) for additional details. 
+
+## Overview
+
+The AWS IoT Device SDK for Embedded C (C-SDK) is a collection of C source files under the [MIT open source license](LICENSE) that can be used in embedded applications to securely connect IoT devices to [AWS IoT Core](http://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html). It includes a MQTT, JSON Parser, and AWS IoT Device Shadow library. It is distributed in source form and intended to be built into customer firmware along with application code, other libraries and RTOS. 
+
+## Features
+
+The C-SDK simplifies access to the Pub/Sub functionality of the AWS IoT broker via MQTT and provides APIs to interact with Device Shadow. The SDK has been tested to work with the AWS IoT Core and an open source MQTT broker to ensure best interoperability of a device with the AWS IoT platform. The C-SDK contains the following libraries:
+
+### MQTT 
+The C-SDK provides the ability to establish an MQTT connection with a broker over a customer-implemented transport layer, which can either be a secure channel like a TLS session (mutually authenticated or server-only authentication) or a non-secure channel like a plaintext TCP connection. This MQTT connection can be used for performing publish operations to MQTT topics and subscribing to MQTT topics. The SDK provides a mechanism to register customer-defined callbacks for receiving incoming PUBLISH, acknowledgement and keep-alive response events from the broker.  The [coreMQTT](https://github.com/FreeRTOS/coreMQTT) library has been refactored for memory optimization and is fully compliant with the [MQTT 3.1.1](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html) standard.  It has no dependencies on any additional libraries other than the standard C library, a customer-implemented network transport interface, and *optionally* a customer-implemented platform time function.  The refactored design embraces different use-cases, ranging from resource-constrained platforms using only QoS 0 MQTT PUBLISH messages to resource-rich platforms using QoS 2 MQTT PUBLISH over TLS connections.  
+
+### AWS IoT Device Shadow
+[AWS IoT Device Shadow](https://github.com/aws/device-shadow-for-aws-iot-embedded-sdk) enables you to store and retrieve the current state (the “shadow”) of every registered device. The device’s shadow is a persistent, virtual representation of your device that you can interact with from AWS IoT Core even if the device is offline. The device state captured as its “shadow” is itself a [JSON](https://www.json.org/) document. The device can send commands over MQTT or HTTP to update its latest state. Each device’s shadow is uniquely identified by the name of the corresponding “thing”, a representation of a specific device or logical entity on the AWS Cloud. See [Managing Devices with AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-thing-management.html) for more information. More details about shadows can be found in [AWS IoT documentation](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html). 
+
+### JSON Parser
+The coreJSON library is a JSON parser that strictly enforces the [ECMA-404 JSON standard](https://www.json.org/json-en.html).
+
+## Metrics
 
+Within the MQTT Demo, users have the ability to report operating System, hardware platform and MQTT Client information to AWS IoT by sending a specially formatted string in the username field of the MQTT CONNECT packet.  
+
+### Format
+
+The format of the username string with metrics is:
+```
+<Actual_Username>?SDK=<OS_Name>&Version=<OS_Version>&Platform=<Hardware_Platform>&MQTTLib=<MQTT_Library_name>@<MQTT_Library_version>
+```
+where
+
+* **Actual_Username** is the actual username used for authentication (if a username/password is used for authentication).
+* **OS_Name** is the Operating System the application is running on.
+* **OS_Version** is the version number of the Operating System.
+* **Hardware_Platform** is the Hardware Platform the application is running on.
+* **MQTT_Library_name** is the MQTT Client library being used.
+* **MQTT_Library_version** is the version of the MQTT Client library being used.
+
+
+
+## Branches
 
 ### master branch
-The [master](https://github.com/aws/aws-iot-device-sdk-embedded-C/tree/master) branch hosts the continuous development of the AWS IoT Embedded C SDK libraries. Please be aware that the libraries in master branch may have bugs and performance issues. Consider using the released versions of the AWS IoT Embedded C SDK for production ready software.
+The [master](https://github.com/aws/aws-iot-device-sdk-embedded-C/tree/master) branch hosts the continuous development of the AWS IoT Embedded C SDK libraries. Please be aware that the development at the tip of the master branch is continuously in progress and may have bugs. Consider using the tagged releases of the AWS IoT Embedded C SDK for production ready software.
 
 ### v4_beta_deprecated branch (Formerly named v4_beta)
 The [v4_beta_deprecated](https://github.com/aws/aws-iot-device-sdk-embedded-C/tree/v4_beta_deprecated) branch contains a beta version of the AWS IoT Embedded C SDK libraries, which is now deprecated. This branch was earlier named as *v4_beta*, and was renamed to *v4_beta_deprecated*. The libraries in this branch will not be released. However, critical bugs will be fixed and tested. No new features will be added to this branch.
@@ -16,22 +59,56 @@ The [v4_beta_deprecated](https://github.com/aws/aws-iot-device-sdk-embedded-C/tr
 
 All of the released versions of the AWS IoT Embedded C SDK libraries are available as git tags. For example, the last release of the v3 SDK version is available at [tag 3.0.1](https://github.com/aws/aws-iot-device-sdk-embedded-C/tree/v3.0.1).
 
+## Versioning
+
+C-SDK releases will now follow a date based versioning scheme with the format YYYYMM.NN_major, where: 
+
+* Y represents the year.
+* M represents the month.
+* N represents the release order within the designated month (00 being the first release).
+* A "major" denotation indicates the addition of new features or significant updates to multiple libraries. 
+
+For example, a second release in June 2021 would be 202106.01. Although the SDK releases have moved to date-based versioning, each library within the SDK will still retain semantic versioning. In semantic versioning, the version number itself (X.Y.Z) indicates whether the release is a major, minor, or point release. You can use the semantic version of a library to assess the scope and impact of a new release on your application. 
+
+## Cloning
+This repo uses [Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to bring in dependent components.
+
+Note: If you download the ZIP file provided by GitHub UI, you will not get the contents of the submodules (The ZIP file is also not a valid git repository).  If you download from the [202009.00 Release Page](https://github.com/aws/aws-iot-device-sdk-embedded-C/releases/tag/202009.00) page, you will get the entire repository (including the submodules) in the ZIP file, aws-iot-device-sdk-embedded-c-202009.00.zip.  
+
+
+To clone using HTTPS:
+```
+git clone https://github.com/aws/aws-iot-device-sdk-embedded-C.git --recurse-submodules
+```
+Using SSH:
+```
+git clone [email protected]:aws/aws-iot-device-sdk-embedded-C.git --recurse-submodules
+```
+
+If you have downloaded the repo without using the `--recurse-submodules` argument, you need to run:
+```
+git submodule update --init --recursive
+```
+
+
 ## Building and Running Demos
 
 
+The libraries in this SDK are not dependent on any operating system. However, the demos for the libraries in this SDK are built and tested on a Linux platform. This SDK builds with [CMake](https://cmake.org/), a cross-platform build tool.
 
-The libraries in this SDK are not dependent on any operating systems. However, the demos for the libraries in this SDK are built and tested on a Linux platform. This SDK builds with [CMake](https://cmake.org/), a cross-platform build tool.
 
+### Prerequisites
 
+- CMake 3.13.0 or later 
 
-### Prerequisites
+- C90 compiler
 
-- CMake 3.13.0 or later and a C90 compiler.
+- Although not a part of the C90 standard, `stdint.h` is required for fixed-width integer types (e.g int32_t).
 
 - A supported operating system. The ports provided with this repo are expected to work with all recent versions of the following operating systems, although we cannot guarantee the behavior on all systems.
     - Linux system with POSIX sockets and timer APIs. (CI tests on Ubuntu 18.04).
         - On Linux systems, installation of OpenSSL development libraries and header files, *version 1.1.0 or later*, are required. The OpenSSL development libraries are usually called something like `libssl-dev` or `openssl-devel` when installed through a package manager.
-        - Although not a part of the C90 standard, `stdint.h` is required for fixed-width integer types (e.g int32_t).
+        
 
 
 
@@ -41,14 +118,15 @@ It is required to setup an AWS account and access the AWS IoT Console for runnin
 
 -  [Setup an AWS account](https://docs.aws.amazon.com/iot/latest/developerguide/iot-console-signin.html).
 
--  [Sign-in to the AWS IoT Console](https://docs.aws.amazon.com/iot/latest/developerguide/iot-console-signin.html) after setting up the AWS account.
+-  [Sign-in to the AWS IoT Console](https://aws.amazon.com/console/) after setting up the AWS account.
 
 
 
 *Note: If using the Provisioning library, a fleet provisioning template, a provisioning claim, IoT policies and IAM policies need to be setup for the AWS account. Complete the steps to setup your device and AWS IoT account outlined [here](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html#use-claim).*
 
 
 
+
 ### Configuring the MQTT mutual auth demo
 
 - You can pass the following configuration settings as command line options in order to run the mutual auth demo:
@@ -152,7 +230,11 @@ this script.
 
 ```shell
 cd <CSDK_ROOT>
-python3 docs/doxygen/generate_docs.py --root .
+python3 tools/doxygen/generate_docs.py --root .
 ```
 
-The generated documentation landing page is located at **docs/doxygen/output/html/index.html**.
+The generated documentation landing page is located at **docs/doxygen/output/html/index.html**
+
+## License
+
+The C-SDK libraries are licensed under the [MIT License](LICENSE).