Pierre-Marie Ancèle / Mbed OS AWS-test

test

aws-iot/README.md@1:3f75eb8d46f4, 2017-04-12 (annotated)

Committer:
peyo
Date:
Wed Apr 12 14:09:46 2017 +0200
Revision:
1:3f75eb8d46f4
Parent:
0:cd5404401c2f 
add main

Who changed what in which revision?

UserRevisionLine numberNew contents of line
peyo 0:cd5404401c2f 1 ##Overview
peyo 0:cd5404401c2f 2
peyo 0:cd5404401c2f 3 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/).
peyo 0:cd5404401c2f 4
peyo 0:cd5404401c2f 5 ##Features
peyo 0:cd5404401c2f 6 The Device SDK simplifies access to the Pub/Sub functionality of the AWS IoT broker via MQTT and provide APIs to interact with Thing Shadows. The SDK has been tested to work with the AWS IoT platform to ensure best interoperability of a device with the AWS IoT platform.
peyo 0:cd5404401c2f 7
peyo 0:cd5404401c2f 8 ###MQTT Connection
peyo 0:cd5404401c2f 9 The Device SDK provides functionality to create and maintain a mutually authenticated TLS connection over which it runs MQTT. This connection is used for any further publish operations and allow for subscribing to MQTT topics which will call a configurable callback function when these topics are received.
peyo 0:cd5404401c2f 10
peyo 0:cd5404401c2f 11 ###Thing Shadow
peyo 0:cd5404401c2f 12 The Device SDK implements the specific protocol for Thing Shadows to retrieve, update and delete Thing Shadows adhering to the protocol that is implemented to ensure correct versioning and support for client tokens. It abstracts the necessary MQTT topic subscriptions by automatically subscribing to and unsubscribing from the reserved topics as needed for each API call. Inbound state change requests are automatically signalled via a configurable callback.
peyo 0:cd5404401c2f 13
peyo 0:cd5404401c2f 14 ## Design Goals of this SDK
peyo 0:cd5404401c2f 15 The embedded C SDK was specifically designed for resource constrained devices (running on micro-controllers and RTOS).
peyo 0:cd5404401c2f 16
peyo 0:cd5404401c2f 17 Primary aspects are:
peyo 0:cd5404401c2f 18 * Flexibility in picking and choosing functionality (reduce memory footprint)
peyo 0:cd5404401c2f 19 * Static memory only (no malloc’s)
peyo 0:cd5404401c2f 20 * Configurable resource usage(JSON tokens, MQTT subscription handlers, etc…)
peyo 0:cd5404401c2f 21 * Can be ported to a different RTOS, uses wrappers for OS specific functions
peyo 0:cd5404401c2f 22
peyo 0:cd5404401c2f 23 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)
peyo 0:cd5404401c2f 24
peyo 0:cd5404401c2f 25 ##How to get started ?
peyo 0:cd5404401c2f 26 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).
peyo 0:cd5404401c2f 27
peyo 0:cd5404401c2f 28 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:
peyo 0:cd5404401c2f 29
peyo 0:cd5404401c2f 30 * [mbedTLS from ARM](https://s3.amazonaws.com/aws-iot-device-sdk-embedded-c/linux_mqtt_mbedtls-2.1.1.tar)
peyo 0:cd5404401c2f 31
peyo 0:cd5404401c2f 32 ##Installation
peyo 0:cd5404401c2f 33 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.
peyo 0:cd5404401c2f 34
peyo 0:cd5404401c2f 35 Steps:
peyo 0:cd5404401c2f 36
peyo 0:cd5404401c2f 37 * Create a directory to hold your application e.g. (/home/<user>/aws_iot/my_app)
peyo 0:cd5404401c2f 38 * Change directory to this new directory
peyo 0:cd5404401c2f 39 * Download the SDK to device and place in the newly created directory
peyo 0:cd5404401c2f 40 * Expand the tarball (tar -xf <tarball.tar>). This will create the below directories:
peyo 0:cd5404401c2f 41 * `certs` - TLS certificates directory
peyo 0:cd5404401c2f 42 * `docs` - SDK API and file documentation. This folder is not present on GitHub. You can access the documentation [here](http://aws-iot-device-sdk-embedded-c-docs.s3-website-us-east-1.amazonaws.com/index.html)
peyo 0:cd5404401c2f 43 * `external_libs` - The mbedTLS and jsmn source files
peyo 0:cd5404401c2f 44 * `include` - The AWS IoT SDK header files
peyo 0:cd5404401c2f 45 * `platform` - Platform specific files for timer, TLS and threading layers
peyo 0:cd5404401c2f 46 * `samples` - The sample applications
peyo 0:cd5404401c2f 47 * `src` - The AWS IoT SDK source files
peyo 0:cd5404401c2f 48 * `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)
peyo 0:cd5404401c2f 49 * 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)
peyo 0:cd5404401c2f 50
peyo 0:cd5404401c2f 51 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).
peyo 0:cd5404401c2f 52
peyo 0:cd5404401c2f 53 ## Porting to different platforms
peyo 0:cd5404401c2f 54 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).
peyo 0:cd5404401c2f 55
peyo 0:cd5404401c2f 56 ## Migrating from 1.x to 2.x
peyo 0:cd5404401c2f 57 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.
peyo 0:cd5404401c2f 58
peyo 0:cd5404401c2f 59 * 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
peyo 0:cd5404401c2f 60 * All the SDK headers are in the `include` folder. These need to be added to the makefile as include directories
peyo 0:cd5404401c2f 61 * The source files are in the `src` folder. These need to be added to the makefile as one of the source directories
peyo 0:cd5404401c2f 62 * 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
peyo 0:cd5404401c2f 63 * The `platform/threading` folder only needs to be added if multi-threading is required, and the `_ENABLE_THREAD_SUPPORT_` macro is defined in config
peyo 0:cd5404401c2f 64 * The list below provides a mapping for migrating from the major APIs used in 1.x to the new APIs:
peyo 0:cd5404401c2f 65
peyo 0:cd5404401c2f 66 | Description | 1.x | 2.x |
peyo 0:cd5404401c2f 67 | :---------- | :-- | :-- |
peyo 0:cd5404401c2f 68 | 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);``` |
peyo 0:cd5404401c2f 69 | 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);``` |
peyo 0:cd5404401c2f 70 | 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);``` |
peyo 0:cd5404401c2f 71 | 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);``` |
peyo 0:cd5404401c2f 72 | 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);``` |
peyo 0:cd5404401c2f 73 | 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);``` |
peyo 0:cd5404401c2f 74 | Disconnect | ```IoT_Error_t aws_iot_mqtt_disconnect(void);``` | ```IoT_Error_t aws_iot_mqtt_disconnect(AWS_IoT_Client *pClient);``` |
peyo 0:cd5404401c2f 75
peyo 0:cd5404401c2f 76 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)
peyo 0:cd5404401c2f 77
peyo 0:cd5404401c2f 78 ## Resources
peyo 0:cd5404401c2f 79 [API Documentation](http://aws-iot-device-sdk-embedded-c-docs.s3-website-us-east-1.amazonaws.com/index.html)
peyo 0:cd5404401c2f 80
peyo 0:cd5404401c2f 81 [MQTT 3.1.1 Spec](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/csprd02/mqtt-v3.1.1-csprd02.html)
peyo 0:cd5404401c2f 82
peyo 0:cd5404401c2f 83 ## Support
peyo 0:cd5404401c2f 84 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).
peyo 0:cd5404401c2f 85 For any other questions on AWS IoT, contact [AWS Support](https://aws.amazon.com/contact-us/).
peyo 0:cd5404401c2f 86
peyo 0:cd5404401c2f 87 ## Sample APIs
peyo 0:cd5404401c2f 88 Connecting to the AWS IoT MQTT platform
peyo 0:cd5404401c2f 89
peyo 0:cd5404401c2f 90 ```
peyo 0:cd5404401c2f 91 AWS_IoT_Client client;
peyo 0:cd5404401c2f 92 rc = aws_iot_mqtt_init(&client, &iotInitParams);
peyo 0:cd5404401c2f 93 rc = aws_iot_mqtt_connect(&client, &iotConnectParams);
peyo 0:cd5404401c2f 94 ```
peyo 0:cd5404401c2f 95
peyo 0:cd5404401c2f 96
peyo 0:cd5404401c2f 97 Subscribe to a topic
peyo 0:cd5404401c2f 98
peyo 0:cd5404401c2f 99 ```
peyo 0:cd5404401c2f 100 AWS_IoT_Client client;
peyo 0:cd5404401c2f 101 rc = aws_iot_mqtt_subscribe(&client, "sdkTest/sub", 11, QOS0, iot_subscribe_callback_handler, NULL);
peyo 0:cd5404401c2f 102 ```
peyo 0:cd5404401c2f 103
peyo 0:cd5404401c2f 104
peyo 0:cd5404401c2f 105 Update Thing Shadow from a device
peyo 0:cd5404401c2f 106
peyo 0:cd5404401c2f 107 ```
peyo 0:cd5404401c2f 108 rc = aws_iot_shadow_update(&mqttClient, AWS_IOT_MY_THING_NAME, pJsonDocumentBuffer, ShadowUpdateStatusCallback,
peyo 0:cd5404401c2f 109 pCallbackContext, TIMEOUT_4SEC, persistenSubscription);
peyo 0:cd5404401c2f 110 ```