Release of version 2.0.0

Author: chaurah

CHANGELOG.md

@@ -1,31 +1,58 @@
 #Change Log
-## [1.1.2](https://github.com/aws/aws-iot-device-sdk-embedded-C/releases/tag/v1.1.2) (April 22,2016)
+## [2.0.0](https://github.com/aws/aws-iot-device-sdk-embedded-C/releases/tag/v2.0.0) (April 28, 2016)
+
+New features:
+
+  - Refactored API to make it instance specific. This is a breaking change in the API from 1.x releases because a Client Instance parameter had to be added to all APIs
+  - Added Threading library porting layer wrapper
+  - Added support for multiple connections from one application
+  - Shadows and connections de-linked, connection needs to be set up separately, can be used independently of shadow
+  - Added integration tests for testing SDK functionality
 
 Bugfixes/Improvements:
+
+  - Yield cannot be called again while waiting for application callback to return
+  - Fixed issue with TLS layer handles not being cleaned up properly on connection failure reported [here](https://github.com/aws/aws-iot-device-sdk-embedded-C/issues/16)
+  - Renamed timer_linux.h to timer_platform.h as requested [here](https://github.com/aws/aws-iot-device-sdk-embedded-C/issues/5)
+  - Adds support for disconnect handler to shadow. A similar pull request can be found [here](https://github.com/aws/aws-iot-device-sdk-embedded-C/pull/9)
+  - New SDK folder structure, cleaned and simplified code structure
+  - Removed Paho Wrapper, Merge MQTT into SDK code, added specific error codes
+  - Refactored Network and Timer layer wrappers, added specific error codes
+  - Refactored samples and makefiles
+  
+## [1.1.2](https://github.com/aws/aws-iot-device-sdk-embedded-C/releases/tag/v1.1.2) (April 22,  2016)
+
+Bugfixes/Improvements:
+
   - Signature mismatch in MQTT library file fixed
   - Makefiles have a protective target on the top to prevent accidental execution
 
-## [1.1.1](https://github.com/aws/aws-iot-device-sdk-embedded-C/releases/tag/v1.1.1) (April  1,2016)
+## [1.1.1](https://github.com/aws/aws-iot-device-sdk-embedded-C/releases/tag/v1.1.1) (April 1, 2016)
 
 Bugfixes/Improvements:
+
   - Removing the Executable bit from all the files in the repository. Fixing [this](https://github.com/aws/aws-iot-device-sdk-embedded-C/issues/14) issue
   - Refactoring MQTT client to remove declaration after statement warnings
   - Fixing [this](https://forums.aws.amazon.com/thread.jspa?threadID=222467&tstart=0) bug
 
 
-## [1.1.0](https://github.com/aws/aws-iot-device-sdk-embedded-C/releases/tag/v1.1.0) (February  10,2016)
+## [1.1.0](https://github.com/aws/aws-iot-device-sdk-embedded-C/releases/tag/v1.1.0) (February 10, 2016)
 Features:
+
   - Auto Reconnect and Resubscribe
+  
 Bugfixes/Improvements:
+
   - MQTT buffer handling incase of bigger message
   - Large timeout values converted to seconds and milliseconds
   - Dynamic loading of Shadow parameters. Client ID and Thing Name are not hard-coded
   - MQTT Library refactored
 
 
-## [1.0.1](https://github.com/aws/aws-iot-device-sdk-embedded-C/releases/tag/v1.0.1) (October 21,2015)
+## [1.0.1](https://github.com/aws/aws-iot-device-sdk-embedded-C/releases/tag/v1.0.1) (October 21, 2015)
 
 Bugfixes/Improvements:
+
   - Paho name changed to Eclipse Paho
   - Renamed the Makefiles in the samples directory 
   - Device Shadow - Delete functionality macro fixed
@@ -34,6 +61,7 @@ Bugfixes/Improvements:
 ## [1.0.0](https://github.com/aws/aws-iot-device-sdk-embedded-C/releases/tag/v1.0.0) (October 8, 2015)
 
 Features:
+
   - Release to github
   - SDK tarballs made available for public download
 

NOTICE.txt

@@ -7,11 +7,10 @@ Amazon Inc (http://www.amazon.com/).
 **********************
 THIRD PARTY COMPONENTS
 **********************
-This software includes third party software subject to the following copyrights:
+This software includes third party software subject to the following licensing:
 - Embedded C MQTT Client - From the Eclipse Paho Project - EPL v1.0
-- mbedTLS
-- jsmn (JSON Parsing)
-- cURL (hostname verification)
-- SSL Conservatory (hostname verification)
+- mbedTLS (external library, included in tarball or downloaded separately)  - Apache 2.0
+- jsmn (JSON Parsing) - MIT
+- cURL (hostname verification) - MIT
 
 The licenses for these third party components are included in LICENSE.txt

PortingGuide.md

@@ -1,8 +1,3 @@
-##Note: Upgrade
-
-Makefiles in the samples folder had the executable bit set and could  potentially delete all files of the host machine if executed as a bash script. 
-More details could be found [here](https://github.com/aws/aws-iot-device-sdk-embedded-C/issues/14). Please upgrade to the latest version of the SDK. 
-
 ##Overview
 
 The AWS IoT device SDK for embedded C is a collection of C source files which can be used in embedded applications to securely connect to the [AWS IoT platform](http://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html). It includes transport clients **MQTT**, **TLS** implementations and examples for their use. It also supports AWS IoT specific features such as **Thing Shadow**. It is distributed in source form and intended to be built into customer firmware along with application code, other libraries and RTOS. For additional information about porting the Device SDK for embedded C onto additional platforms please refer to the [PortingGuide](https://github.com/aws/aws-iot-device-sdk-embedded-c/blob/master/PortingGuide.md/).
@@ -20,20 +15,19 @@ The Device SDK implements the specific protocol for Thing Shadows to retrieve, u
 The embedded C SDK was specifically designed for resource constrained devices (running on micro-controllers and RTOS).
 
 Primary aspects are:
- * Flexibility in picking and choosing functionalities (reduce memory footprint)
+ * Flexibility in picking and choosing functionality (reduce memory footprint)
  * Static memory only (no malloc’s)
  * Configurable resource usage(JSON tokens, MQTT subscription handlers, etc…)
- * Portability across RTOS due to use of wrapper functionality
+ * Can be ported to a different RTOS, uses wrappers for OS specific functions
 
 For more information on the Architecture of the SDK refer [here](http://aws-iot-device-sdk-embedded-c-docs.s3-website-us-east-1.amazonaws.com/index.html)
 
 ##How to get started ?
 Ensure you understand the AWS IoT platform and create the necessary certificates and policies. For more information on the AWS IoT platform please visit the [AWS IoT developer guide](http://docs.aws.amazon.com/iot/latest/developerguide/iot-security-identity.html).
 
-In order to quickly get started with the AWS IoT platform, we have ported the SDK for POSIX type Operating Systems like Ubuntu, OS X and RHEL. The porting of the SDK happens at the TLS layer, and for the MQTT protocol. The SDK is configured for two TLS libraries and can be built out of the box with *GCC* using *make utility*. The tarballs can be downloaded from the below links.
+In order to quickly get started with the AWS IoT platform, we have ported the SDK for POSIX type Operating Systems like Ubuntu, OS X and RHEL. The SDK is configured for the mbedTLS library and can be built out of the box with *GCC* using *make utility*. The tarball can be downloaded from the below link:
 
-* [OpenSSL](https://s3.amazonaws.com/aws-iot-device-sdk-embedded-c/linux_mqtt_openssl-1.1.2.tar)
-* [mbedTLS from ARM](https://s3.amazonaws.com/aws-iot-device-sdk-embedded-c/linux_mqtt_mbedtls-1.1.2.tar)
+* [mbedTLS from ARM](https://s3.amazonaws.com/aws-iot-device-sdk-embedded-c/linux_mqtt_mbedtls-2.0.0.tar)
 
 ##Installation
 This section explains the individual steps to retrieve the necessary files and be able to build your first application using the AWS IoT device SDK for embedded C.
@@ -43,64 +37,74 @@ Steps:
  * Create a directory to hold your application e.g. (/home/<user>/aws_iot/my_app)
  * Change directory to this new directory
  * Download the SDK to device and place in the newly created directory
- * Expand the tarball (tar -xf <tarball.tar>).  This will create 4 directories:
- 	* `aws_iot_src` - the AWS IoT SDK source files
- 	* `sample_apps` - the sample applications
- 	* `aws_mqtt_embedded_client_lib` - the aws MQTT client derived from [Eclipse Paho](http://www.eclipse.org/paho/clients/c/embedded/) Embedded C client
- 	* `certs` - TLS certificates directory
- * Change directory to sample_apps.  The following sample applications are included:
- 	* `subscribe_publish_sample` - a simple pub/sub MQTT example
- 	* `shadow_sample` - a simple device shadow example using a connected window example
- 	* `shadow_sample_console_echo` - a sample to work with the AWS IoT Console interactive guide
- * For each sample:
- 	* Explore the example.  It connects to AWS IoT platform using MQTT and demonstrates few actions that can be performed by the SDK
- 	* Build the example using make.  (''make'')
- 	* Place device identity cert and private key in locations referenced in the example (certs/).  Alternatively, you can run the sample application with the ''-c'' flag to point to a specific certificate directory.
- 	* Download certificate authority CA file from [Symantec](https://www.symantec.com/content/en/us/enterprise/verisign/roots/VeriSign-Class%203-Public-Primary-Certification-Authority-G5.pem) and place in location referenced in the example (certs/). Ensure the names of the cert files are the same as in the `aws_iot_config.h` file
- 	* Run sample application (./subscribe_publish_sample or ./shadow_sample).  The sample will print status messages to stdout.
- 	* More information on the examples could be found in the sample source file
+ * Expand the tarball (tar -xf <tarball.tar>).  This will create the below directories:
+    * `certs` - TLS certificates directory
+    * `docs` - SDK API and file documentation
+    * `external_libs` - The mbedTLS and jsmn source files
+    * `include` - The AWS IoT SDK header files
+    * `platform` - Platform specific files for timer, TLS and threading layers
+    * `samples` - The sample applications
+    * `src` - The AWS IoT SDK source files
+    * `tests` - Contains tests for verifying that the SDK is functioning as expected. More information can be found [here](https://github.com/aws/aws-iot-device-sdk-embedded-c/blob/master/tests/README.md)
+ * View further information on how to use the SDK in the Readme file for samples that can be found [here](https://github.com/aws/aws-iot-device-sdk-embedded-c/blob/master/samples/README.md)
 
 Also, for a guided example on getting started with the Thing Shadow, visit the AWS IoT Console's [Interactive Guide](https://console.aws.amazon.com/iot).
 
-##Porting to different platforms
-As Embedded devices run on different Real Time Operating Systems and TCP/IP stacks, it is one of the important design goals for the Device SDK to keep it portable. Please refer to the [porting guide](https://github.com/aws/aws-iot-device-sdk-embedded-C/blob/master/PortingGuide.md/) to get more information on how to make this SDK run on your devices (i.e. micro-controllers).
+## Porting to different platforms
+As Embedded devices run on different Real Time Operating Systems and TCP/IP stacks, it is one of the important design goals for the Device SDK to keep it portable. Please refer to the [porting guide](https://github.com/aws/aws-iot-device-sdk-embedded-C/blob/master/PortingGuide.md) to get more information on how to make this SDK run on your devices (i.e. micro-controllers).
+
+## Migrating from 1.x to 2.x
+The 2.x branch makes several changes to the SDK. This section provides information on what changes will be required in the client application for migrating from v1.x to 2.x.
+
+ * The first change is in the folder structure. Client applications using the SDK now need to keep only the certs, external_libs, include, src and platform folder in their application. The folder descriptions can be found above
+ * All the SDK headers are in the `include` folder. These need to be added to the makefile as include directories
+ * The source files are in the `src` folder. These need to be added to the makefile as one of the source directories
+ * Similar to 1.x, the platform folder contains the platform specific headers and source files. These need to be added to the makefile as well
+ * The `platform/threading` folder only needs to be added if multi-threading is required, and the `_ENABLE_THREAD_SUPPORT_` macro is defined in config 
+ * The list below provides a mapping for migrating from the major APIs used in 1.x to the new APIs:
 
-##Resources
+    | Description | 1.x | 2.x |
+    | :---------- | :-- | :-- |
+    | Initializing the client | ```void aws_iot_mqtt_init(MQTTClient_t *pClient);``` | ```IoT_Error_t aws_iot_mqtt_init(AWS_IoT_Client *pClient, IoT_Client_Init_Params *pInitParams);``` |
+    | Connect | ```IoT_Error_t aws_iot_mqtt_connect(MQTTConnectParams *pParams);``` | ```IoT_Error_t aws_iot_mqtt_connect(AWS_IoT_Client *pClient, IoT_Client_Connect_Params *pConnectParams);``` |
+    | Subscribe | ```IoT_Error_t aws_iot_mqtt_subscribe(MQTTSubscribeParams *pParams);``` | ```IoT_Error_t aws_iot_mqtt_subscribe(AWS_IoT_Client *pClient, const char *pTopicName, uint16_t topicNameLen, QoS qos, pApplicationHandler_t pApplicationHandler, void *pApplicationHandlerData);``` |
+    | Unsubscribe | ```IoT_Error_t aws_iot_mqtt_unsubscribe(char *pTopic);``` | ```IoT_Error_t aws_iot_mqtt_unsubscribe(AWS_IoT_Client *pClient, const char *pTopicFilter, uint16_t topicFilterLen);``` |
+    | Yield | ```IoT_Error_t aws_iot_mqtt_yield(int timeout);``` | ```IoT_Error_t aws_iot_mqtt_yield(AWS_IoT_Client *pClient, uint32_t timeout_ms);``` |
+    | Publish | ```IoT_Error_t aws_iot_mqtt_publish(MQTTPublishParams *pParams);``` | ```IoT_Error_t aws_iot_mqtt_publish(AWS_IoT_Client *pClient, const char *pTopicName, uint16_t topicNameLen, IoT_Publish_Message_Params *pParams);``` |
+    | Disconnect | ```IoT_Error_t aws_iot_mqtt_disconnect(void);``` | ```IoT_Error_t aws_iot_mqtt_disconnect(AWS_IoT_Client *pClient);``` |
+
+You can find more information on how to use the new APIs in the Readme file for samples that can be found [here](https://github.com/aws/aws-iot-device-sdk-embedded-c/blob/master/samples/README.md)
+
+## Resources
 [API Documentation](http://aws-iot-device-sdk-embedded-c-docs.s3-website-us-east-1.amazonaws.com/index.html)
 
 [MQTT 3.1.1 Spec](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/csprd02/mqtt-v3.1.1-csprd02.html)
 
-##Support
+## Support
 If you have any technical questions about AWS IoT Device SDK, use the [AWS IoT forum](https://forums.aws.amazon.com/forum.jspa?forumID=210).
 For any other questions on AWS IoT, contact [AWS Support](https://aws.amazon.com/contact-us/).
 
-##Sample APIs
+## Sample APIs
 Connecting to the AWS IoT MQTT platform
 
 ```
-rc = aws_iot_mqtt_connect( &connectParams ) ;
+AWS_IoT_Client client;
+rc = aws_iot_mqtt_init(&client, &iotInitParams);
+rc = aws_iot_mqtt_connect(&client, &iotConnectParams);
 ```
 
 
 Subscribe to a topic
 
 ```
-MQTTSubscribeParams subParams = MQTTSubscribeParamsDefault; 
-subParams.mHandler = MQTTcallbackHandler;
-subParams.qos = QOS_0;
-subParams.pTopic = "sdkTest/sub";
-rc = aws_iot_mqtt_subscribe( &subParams ) ;
+AWS_IoT_Client client;
+rc = aws_iot_mqtt_subscribe(&client, "sdkTest/sub", 11, QOS0, iot_subscribe_callback_handler, NULL);
 ```
 
 
 Update Thing Shadow from a device
 
 ``` 
-rc = aws_iot_shadow_update(&mqttClient,
-AWS_IOT_MY_THING_NAME, 
-pJsonDocumentBuffer, 
-ShadowUpdateStatusCallback,
-pCallbackContext, 
-TIMEOUT_4SEC, 
-persistenSubscription);
-```
+rc = aws_iot_shadow_update(&mqttClient, AWS_IOT_MY_THING_NAME, pJsonDocumentBuffer, ShadowUpdateStatusCallback,
+                            pCallbackContext, TIMEOUT_4SEC, persistenSubscription);
+```