Home

Awesome

<h1 align = "center">AWS IoT Arduino Yún SDK</h1>

What is AWS IoT Arduino Yún SDK

The AWS-IoT-Arduino-Yún-SDK allows developers to connect their Arduino Yún compatible Board to AWS IoT. By connecting the device to the AWS IoT, users can securely work with the message broker, rules and the Thing Shadow provided by AWS IoT and with other AWS services like AWS Lambda, Amazon Kinesis, Amazon S3, etc.

<a name="overview"></a>

Overview

This document provides step by step instructions to install the Arduino Yún SDK and connect your device to the AWS IoT.
The AWS-IoT-Arduino-Yún-SDK consists of two parts, which take use of the resources of the two chips on Arduino Yún, one for native Arduino IDE API access and the other for functionality and connections to the AWS IoT built on top of AWS IoT Device SDK for Python.

MQTT connection

The AWS-IoT-Arduino-Yún-SDK provides APIs to let users publish messages to AWS IoT and subscribe to MQTT topics to receive messages transmitted by other devices or coming from the broker. This allows to interact with the standard MQTT PubSub functionality of AWS IoT. More information on MQTT protocol is available here.

Thing shadow

The AWS-IoT-Arduino-Yún-SDK also provides APIs to provide access to thing shadows in AWS IoT. Using this SDK, users will be able to sync the data/status of their devices as JSON files to the cloud and respond to change of status requested by other applications. More information on Thing Shadow is available here.

<a name="credentials"></a>

Credentials

The SDK supports two types of credentials that correspond to the two connection types:

X.509 certificate

For the certificate-based mutual authentication connection type. Download the AWS IoT root CA. Use the AWS IoT console to create and download the certificate and private key. You must upload these credentials along with the Python runtime code base to AR9331 on Yún board and specify the location of these files in a configuration file aws_iot_config.h.

IAM credentials

For the Websocket with Signature Version 4 authentication type. You will need IAM credentials: an access key ID, a secret access key. You must also download and upload the AWS IoT root CA. A tooling script AWSIoTArduinoYunWebsocketCredentialConfig.sh is provided for Mac OS/Linux users to update the IAM credentials as environment variables on AR9331, Yún board.

<a name="installation"></a>

Installation

Download AWS-IoT-Arduino-Yún-SDK

Click here to download AWS-IoT-Arduino-Yún-SDK zip package and extract it to AWS-IoT-Arduino-Yun-SDK on your computer.

Set up your Arduino Yún Board

Please follow the instructions from official website: Arduino Yún Guide.

Installation on Mac OS/Linux

Before proceeding to the following steps, please make sure that you have expect installed on your computer and correctly installed the Arduino IDE.
To install expect:
For Ubuntu, simply run sudo apt-get install expect.
For Mac, expect is installed as default.
For Arduino IDE installation on Linux, please visit here.

  1. Setup the Arduino Yún board and connect it to WiFi. Obtain its IP address and password.
  2. Make sure your computer is connected to the same network (local IP address range).
  3. Download the AWS IoT CA file from here.
  4. Put your AWS IoT CA file, private key and certificate into AWS-IoT-Arduino-Yun-SDK/AWS-IoT-Python-Runtime/certs. If you are using MQTT over Websocket, you can put only your AWS IoT CA file into the directory. You should have a correctly configured AWS Identity and Access Management (IAM) role with a proper policy, and a pair of AWS Access Key and AWS Secret Access Key ID, which will be used in step 6. For more information about IAM, please visit AWS IAM home page.
  5. Open a terminal, cd to AWS-IoT-Arduino-Yun-SDK. Do chmod 755 AWSIoTArduinoYunInstallAll.sh and execute it as ./AWSIoTArduinoYunInstallAll.sh <Board IP> <UserName> <Board Password>. By default for Arduino Yún Board, your user name will be root and your password will be arduino.
    This script will upload the python runtime code base and credentials to openWRT running on the more powerful micro-controller on you Arduino Yún board.
    This script will also download and install libraries for openWRT to implement the necessary scripting environment as well as communication protocols.

Step 5 can take 10-15 minutes for the device to download and install the required packages (distribute, python-openssl, pip, AWSIoTPythonSDKv1.0.0).

NOTE: Do NOT close the terminal before the script finishes, otherwise you have to start over with step 5. Make sure you are in your local terminal before repeating step 5.

  1. Optional, only for Websocket. Open a terminal, cd to AWS-IoT-Arduino-Yun-SDK. Do chmod 755 AWSIoTArduinoYunWebsocketCredentialConfig.sh and execute it as ./AWSIoTArduinoYunWebsocketCredentialConfig.sh <Board iP> <UserName> <Board Password> <AWS_ACCESS_KEY_ID_STRING> <AWS_SECRET_ACCESS_KEY_STRING>.
    This script will add the given key ID and secret key onto the OpenWRT as environment variables $AWS_ACCESS_KEY_ID and $AWS_SECRET_ACCESS_KEY.

    NOTE1: You can always use this script to update your IAM credentials used on the board. The script will handle the update of the environment variables for you.

    NOTE2: Please follow the instructions on the screen after the script completes to power-cycle your board to enable all the environment changes on OpenWRT.

  2. Copy and paste AWS-IoT-Arduino-Yun-SDK/AWS-IoT-Arduino-Yun-Library folder into Arduino libraries that was installed with your Arduino SDK installation. For Mac OS default, it should be under Documents/Arduino/libraries.

  3. Restart the Arduino IDE if it was running during the installation. You should be able to see the AWS IoT examples in the Examples folder in your IDE.

There are the other two scripts: AWSIoTArduinoYunScp.sh and AWSIoTArduinoYunSetupEnvironment.sh, which are utilized in AWSIoTArduinoYunInstallAll.sh. You can always use AWSIoTArduinoYunScp.sh to upload your new credentials to your board. When you are in the directory AWS-IoT-Arduino-Yun-SDK/, the command should be something like this:

./AWSIoTArduinoYunScp.sh <Board IP> <UserName> <Board Password> <File> <Destination>


Installation on Windows

Before proceeding to the following steps, please make sure that you have Putty and WinSCP installed on your PC. If you prefer to use other tools for SSH-ing into your Arduino Yún board and transferring files, you will have to adjust the steps below according to your tools.
Putty can be downloaded from here.
WinSCP can be downloaded from here.

  1. Setup the Arduino Yún Cloud board and connect it to WiFi. Obtain its IP address and password.

  2. Make sure your PC is connected to the same network (local IP address range).

  3. Download the AWS IoT CA file from here.

  4. Put your AWS IoT CA file, private key and certificate into AWS-IoT-Arduino-Yun-SDK/AWS-IoT-Python-Runtime/certs. If you are using MQTT over Websocket, you can put only your AWS IoT CA file into the directory. You should have a correctly configured AWS Identity and Access Management (IAM) role with a proper policy, and a pair of AWS Access Key and AWS Secret Access Key ID, which will be used in step 7. For more information about IAM, please visit AWS IAM home page.

  5. Start WinSCP and upload AWS-IoT-Python-Runtime/ folder to /root on the board.

  6. Use Putty to ssh into OpenWRT on your board and execute the following commands to install the necessary libraries:

     opkg update
 opkg install distribute
 opkg install python-openssl
 easy_install pip
 pip install AWSIoTPythonSDK==1.0.0

It can take 10-15 minutes for the device to download and install the required packages.

  1. Optional, only for Websocket. Use Putty to ssh into OpenWRT on your board and modify /etc/profile to include your IAM credentials as environment variables:

     ...
 export AWS_ACCESS_KEY_ID=<AWS_ACCES_KEY_ID_STRING>
 export AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY_STRING>
 ...

After that, run source /etc/profile and power-cycle the board to enable the changes.

  1. Copy and paste AWS-IoT-Arduino-Yun-SDK/AWS-IoT-Arduino-Yun-Library folder into Arduino libraries that was installed with your Arduino SDK installation. For Windows default, it should be under Documents/Arduino/libraries.
  2. Restart the Arduino IDE if it was running during the installation. You should be able to see the AWS IoT examples in the Examples folder in your IDE.

<a name="api"></a>

API documentation

Class Name:

aws_iot_mqtt_client

API:

Message Callback:
void(*message_callback)(char*, unsigned int, Message_status_t)

<a name="setup"></a>

IoT_Error_t setup(const char* client_id, bool clean_session, MQTTv_t MQTT_version, bool useWebsocket)

Description
Start the Python runtime and set up connection for aws_iot_mqtt_client object. Must be called before any of aws_iot_mqtt_client API is called.

Syntax

object.setup("myClientID"); // setup a client with client_id set to "myClientID"
object.setup("myClientID", true, MQTTv31, true); // setup a client with client_id set to "myClientID", with clean_session set to true, using MQTT 3.1, over Websocket

Parameters
client_id - The client id for this connection.
clean_session - Clear the previous connection with this id or not. Default value is true.
MQTT_version - Version of MQTT protocol for this connection, either MQTTv31 (MQTT version 3.1) or MQTTv311 (MQTT version 3.1.1). Default value is MQTTv311.
useWebsocket - Enable the use of Websocket or not. Default value is false. IAM credentials must be included in the environment variables on OpenWRT to make a successful MQTT connection over Websocket.

Returns
NONE_ERROR if the setup on openWRT side and connection settings are correct.
NULL_VALUE_ERROR if input parameters have NULL value.
OVERFLOW_ERROR if input string exceeds the internal buffer size.
SET_UP_ERROR if the setup failed.
SERIAL1_COMMUNICATION_ERROR if there is an error in Serial1 communication between the two chips.
GENERIC_ERROR if an unknown error happens.

<a name="config"></a>

IoT_Error_t config(const char* host, unsigned int port, const char* cafile_path, const char* keyfile_path, const char* certfile_path)

Description
Configure host, port and certs location used to connect to AWS IoT. If the input strings for host, cafile_path, keyfile_path and certfile_path are set to NULL, the default value will be used to connect. Must be called to load user settings right after aws_iot_mqtt_client::setup and before connect.

Syntax

object.config("example.awsamazon.com", 1234, "./cafile", "./keyfile", "./certfile");

Parameters
host - The endpoint to connect to. Must be a NULL-terminated string.
port - The port number to connect to.
cafile_path - The path of CA file on OpenWRT. Must be a NULL-terminated string.
keyfile_path - The path of private key file on OpenWRT. Must be a NULL-terminated string.
certfile_path - The path of certificate file on OpenWRT. Must be a NULL-terminated string.

Returns
NONE_ERROR if the configuration is successful.
NO_SET_UP_ERROR if no setup is called before this call.
WRONG_PARAMETER_ERROR if there is an error for the Python Runtime to get enough input parameters for this command.
CONFIG_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="configWss"></a>

IoT_Error_t configWss(const char* host, unsigned int port, const char* cafile_path)

Description
Configure host, port and rootCA location used to connect to AWS IoT over Websocket. If the input strings for host and cafile_path are set to NULL, the default value will be used to connect. Must be called to load user settings right after aws_iot_mqtt_client::setup and before connect. The client must be configured in setup to use Websocket.

Syntax

object.configWss("example.awsamazon.com", 1234, "./cafile");

Parameters
host - The endpoint to connect to. Must be a NULL-terminated string.
port - The port number to connect to.
cafile_path - The path of CA file on OpenWRT. Must be a NULL-terminated string.

Returns
NONE_ERROR if the configuration is successful.
NO_SET_UP_ERROR if no setup is called before this call.
WRONG_PARAMETER_ERROR if there is an error for the Python Runtime to get enough input parameters for this command.
CONFIG_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="configBackoffTiming"></a>

IoT_Error_t configBackoffTiming(unsigned int baseReconnectQuietTimeSecond, unsigned int maxReconnectQuietTimeSecond, unsigned int stableConnectionTimeSecond)

Description
Configure the progressive back-off timing on reconnect. Time interval for reconnect attempt will increase/double from baseReconnectQuietTimeSecond to maxReconnectQuietTimeSecond. Once a connection is live for longer than stableConnectionTimeSecond, the time interval will be reset to baseReconnectQuietTimeSecond. Note that stableConnectionTimeSecond must be greater than baseReconnectQuietTimeSecond. More details about progressive back-off can be found here.

Note that if this API is not called, the following default values will be used to configure the back-off timing:

baseReconnectQuietTimeSecond = 1;
maxReconnectQuietTimeSecond = 128;
stableConnectionTimeSecond = 20;

Syntax

object.configBackoffTiming(1, 32, 20); // Configure baseReconnectQuietTimeSecond to be 1 second. Configure maxReconnectQuietTimeSecond to be 32 seconds. Configure stableConnectionTimeSecond to be 20 seconds.

Parameters
baseReconnectQuietTimeSecond - Number of seconds to start with for progressive back-off on reconnect.
maxReconnectQuietTimeSecond - Maximum number of seconds for progressive back-off on reconnect.
stableConnectionTimeSecond - Number of seconds for a valid connection to be considered stable.

<a name="configOfflinePublishQueue"></a>

IoT_Error_t configOfflinePublishQueue(unsigned int queueSize, DropBehavior_t behavior)

Description
Configure the internal queue size and its drop behavior once the queue is full in the Python runtime on the OpenWRT side. When the client is offline, publish requests will be queued up and get resent once the network connection is back. If the number of publish requests exceeds the maximum size of the queue configured, dropping will happen according the drop behavior configured by this API. More details about offline publish requests queuing can be found here.

Syntax

object.configOfflinePublishQueue(20, DROP_OLDEST); // Configure size of the offline publish requests queue to be 20. Configure the queue to drop the oldest requests once the queue is full.
object.configOfflinePublishQueue(20, DROP_NEWEST); // Configure size of the offline publish requests queue to be 20. Configure the queue to drop the newest requests once the queue is full.
object.configOfflinePublishQueue(0, DROP_OLDEST); // Configure size of the offline publish requests queue to be infinite. The queue-full drop behavior is ignored when the size if infinite.
object.configOfflinePublishQueue(-1, DROP_OLDEST); // Disable the offline publish requests queue. The queue-full drop behavior is ignored when the queue is disabled.

Parameters
queueSize - The size of the offline publish requests queue, determining how many publish requests can be queued up while the client it offline.
behavior - The drop behavior when the offline publish requests queue is full. Can be configured to drop the oldest requests or the newest requests in the queue.

Returns
NONE_ERROR if the configuration is successful.
NO_SET_UP_ERROR if no setup is called before this call.
WRONG_PARAMETER_ERROR if there is an error for the Python Runtime to get enough input parameters for this command.
CONFIG_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="configDrainingInterval"></a>

IoT_Error_t configDrainingInterval(float numberOfSeconds)

Description
Configure the draining interval for requests to be sent out when client is back online and gets connected. This will affect the outbound rate for republish and resubscribe requests. More details about draining can be found here.

Syntax

object.configDrainingInterval(0.5); // Configure the draining interval to be 0.5 seconds. In this way, resubscribe requests, if any, will be sent per 0.5 seconds. Offline publish requests, if any in the queue, will be sent per 0.5 seconds.

Parameters
numberOfSeconds - Number of seconds to wait between every resubscribe/republish request when the client is back online and connected.

Returns
NONE_ERROR if the configuration is successful.
NO_SET_UP_ERROR if no setup is called before this call.
WRONG_PARAMETER_ERROR if there is an error for the Python Runtime to get enough input parameters for this command.
CONFIG_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="connect"></a>

IoT_Error_t connect(unsigned int keepalive_interval)

Description
Connect to AWS IoT, using user-specific keepalive setting.

Syntax

object.connect(); // connect to AWS IoT with default keepalive set to 60 seconds
object.connect(55); // connect to AWS IoT with keepalive set to 55 seconds

Parameters
keepalive_interval - amount of time for MQTT ping request interval, in seconds. Default is set to 60 seconds.

Returns
NONE_ERROR if the connect is successful.
NO_SET_UP_ERROR if no setup is called before this call.
WRONG_PARAMETER_ERROR if there is an error for the Python Runtime to get enough input parameters for this command.
CONNECT_SSL_ERROR if the TLS handshake failed.
CONNECT_ERROR if the connection failed.
CONNECT_TIMEOUT if the connection gets timeout.
CONNECT_CREDENTIAL_NOT_FOUND if the specified credentials are not found on OpenWRT.
WEBSOCKET_CREDENTIAL_NOT_FOUND if the IAM credentials do not exist as environment variables on OpenWRT.
CONNECT_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="publish"></a>

IoT_Error_t publish(const char* topic, const char* payload, unsigned int payload_len, unsigned int qos, bool retain)

Description
Publish a new message to the desired topic with qos and retain flag settings using MQTT protocol

Syntax

object.publish("myTopic", "myMessage", strlen("myMessage"), 0, false); // publish "myMessage" to topic "myTopic" in QoS 0 with retain flag set to false

Parameters
topic - Topic name to publish to. Must be a NULL-terminated string.
payload - Payload to publish.
payload_len - Length of payload.
qos - Qualiy of service, could be 0 or 1.
retain - retain flag.

Returns
NONE_ERROR if the publish is successful.
NULL_VALUE_ERROR if input parameters have NULL value.
OVERFLOW_ERROR if topic/payload exceeds the internal buffer size.
NO_SET_UP_ERROR if no setup is called before this call.
WRONG_PARAMETER_ERROR if there is an error for the Python Runtime to get enough input parameters for this command.
PUBLISH_ERROR if the publish failed.
PUBLISH_TIMEOUT if the publish gets timeout.
PUBLISH_QUEUE_FULL if the internal offline publish requests queue is full.
PUBLISH_QUEUE_DISABLED if the internal offline publish requests queue is disabled.
PUBLISH_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="subscribe"></a>

IoT_Error_t subscribe(const char* topic, unsigned int qos, message_callback cb)

Description
Subscribe to the desired topic and register a callback for new messages from this topic.

Syntax

object.subscribe("myTopic", 0, myCallbackFunc); // subscribe to topic "myTopic" in QoS 0 and register its callback function as myCallbackFunc

Parameters
topic - The topic to subscribe to. Must be a NULL-terminated string.
qos - Quality of service, could be 0 or 1.
cb - Function pointer to user-specific callback function to call when a new message comes in for the subscribed topic. The callback function should have a parameter list of (char*, unsigned int, Message_status_t) to store the incoming message content and the length of the message.

Returns
NONE_ERROR if the subscribe is successful.
NULL_VALUE_ERROR if input parameters have NULL value.
OVERFLOW_ERROR if topic/payload exceeds the internal buffer size.
OUT_OF_SKETCH_SUBSCRIBE_MEMORY if the number of current subscribe exceeds the configured number in aws_iot_config_SDK.h.
NO_SET_UP_ERROR if no setup is called before this call.
WRONG_PARAMETER_ERROR if there is an error for the Python Runtime to get enough input parameters for this command.
SUBSCRIBE_ERROR if the subscribe failed.
SUBSCRIBE_TIMEOUT if the subscribe gets timeout.
SUBSCRIBE_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="unsubscribe"></a>

IoT_Error_t unsubscribe(const char* topic)

Description
Unsubscribe to the desired topic.

Syntax

object.unsubscribe("myTopic");

Parameters
topic - The topic to unsubscribe to. Must be a NULL-terminated string.

Returns
NONE_ERROR if the unsubscribe is successful.
NULL_VALUE_ERROR if input parameters have NULL value.
OVERFLOW_ERROR if topic exceeds the internal buffer size.
NO_SET_UP_ERROR if no setup is called before this call.
WRONG_PARAMETER_ERROR if there is an error for the Python Runtime to get enough input parameters for this command.
UNSUBSCRIBE_ERROR if the unsubscribe failed.
UNSUBSCRIBE_TIMEOUT if the unsubscribe gets timeout.
UNSUBSCRIBE_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="yield"></a>

IoT_Error_t yield()

Description
Called in the loop to check if there is a new message from all subscribed topics, as well as thing shadow topics. Registered callback functions will be called according to the sequence of messages if there is any. Specifically, unnecessary shadow thing topics (accepted/rejected) will be unsubscribed according to the incoming new messages to free subscribe slots. Users should call this function frequently to receive new messages and free subscribe slots for new subscribes, especially for shadow thing requests.

Syntax

object.yield();

Parameters
None

Returns
NONE_ERROR if the yield is successful, whether there is a new message or not.
OVERFLOW_ERROR if the new message exceeds the internal buffer size.
YIELD_ERROR if the yield failed.

<a name="disconnect"></a>

IoT_Error_t disconnect()

Description
Disconnect from AWS IoT.

Syntax

object.disconnect();

Parameters
None

Returns
NONE_ERROR if disconnect is successful.
NO_SET_UP_ERROR if no setup is called before this call.
DISCONNECT_ERROR if the disconnect failed.
DISCONNECT_TIMEOUT if the disconnect gets timeout.
DISCONNECT_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="shadow_init"></a>

IoT_Error_t shadow_init(const char* thingName)

Description
Initialize thing shadow configuration and a shadow instance with thingName. Should be called before any of the thing shadow API call for thingName shadow operations.

Syntax

object.shadow_init("NewThingName"); // Init thing shadow configuration and set thing name to "NewThingName"

Parameters
thingName - Thing name for the shadow instance to be created. Must be a NULL-terminated string.

Returns
NONE_ERROR if thing shadow is successfully initialized.
NULL_VALUE_ERROR if input parameters have NULL value.
OVERFLOW_ERROR if thing name exceeds the internal buffer size.
SHADOW_INIT_ERROR if thing shadow initialization failed.
GENERIC_ERROR if an unknown error happens.

<a name="shadow_update"></a>

IoT_Error_t shadow_update(const char* thingName, const char* payload, unsigned int payload_len, message_callback cb, unsigned int timeout)

Description
Update the thing shadow data in the cloud by publishing a new JSON file onto the corresponding thing shadow topic and subscribing accepted/rejected thing shadow topics to get feedback of whether it is a successful/failed request. Timeout can be set in seconds as the maximum waiting time for feedback. Once the request gets timeout, a timeout message will be received. The registered callback function will be called whenever there is an accepted/rejected/timeout feedback. Subscription to accepted/rejected topics will be processed in a persistent manner and will not be unsubscribed once this API is called for this shadow.

Syntax

object.shadow_update("UserThingName", JSON_FILE, strlen(JSON_FILE), UserCallbackFunction, 5); // update the data of "UserThingName" thing shadow in the cloud to JSON_FILE, with a timeout of 5 seconds and UserCallbackFunction as the callback function

Parameters
thingName - The name of the thing shadow in the cloud. Must be a NULL-terminated string.
payload - The data that needs to be updated into the cloud, in JSON file format.
payload_len - Length of payload
cb - Function pointer to user-specific callback function to call when a new message comes in for the subscribed topic. The callback function should have a parameter list of (char*, unsigned int, Message_status_t) to store the incoming message content and the length of the message.
timeout - The maximum time to wait for feedback.

Returns
NONE_ERROR if the shadow update request succeeds.
NULL_VALUE_ERROR if input parameters have NULL value.
OVERFLOW_ERROR if thing name/payload exceeds the internal buffer size.
OUT_OF_SKETCH_SUBSCRIBE_MEMORY if the number of current subscribe exceeds the configured number in aws_iot_config_SDK.h.
NO_SHADOW_INIT_ERROR if the shadow with thingName is initialized before this call.
WRONG_PARAMETER_ERROR if there is an error for the Python Runtime to get enough input parameters for this command.
SUBSCRIBE_ERROR if the subscribe (accepted/rejected) failed.
SUBSCRIBE_TIMEOUT if the subscribe gets timeout.
PUBLISH_ERROR if the publish (payload) failed.
PUBLISH_TIMEOUT if the publish (payload) gets timeout.
PUBLISH_QUEUE_FULL if the publish action failed because of a full internal offline publish requests queue.
PUBLISH_QUEUE_DISABLED if the publish action failed because of a disabled internal offline publish requests queue.
SHADOW_UPDATE_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="shadow_get"></a>

IoT_Error_t shadow_get(const char* thingName, message_callback cb, unsigned int timeout)

Description
Obtain the thing shadow data in the cloud by publishing an empty JSON file onto the corresponding thing shadow topic and subscribing accepted/rejected thing shadow topics to get feedback of whether it is a successful/failed request. Timeout can be set in seconds as the maximum waiting time for feedback. Once the request gets timeout, a timeout message will be received. The registered callback function will be called whenever there is an accepted/rejected/timeout feedback. Subscription to accepted/rejected topics will be processed in a persistent manner and will not be unsubscribed once this API is called for this shadow. Thing shadow data will be available as a JSON file in the callback.

Syntax

object.shadow_get("UserThingName", UserCallbackFunction, 5); // get the data of the thing shadow "UserThingName", with a timeout of 5 seconds and UserCallbackFunction as the callback function

Parameters
thingName - The name of the thing shadow in the cloud. Must be a NULL-terminated string.
cb - Function pointer to user-specific callback function to call when a new message comes in for the subscribed topic. The callback function should have a parameter list of (char*, unsigned int, Message_status_t) to store the incoming message content and the length of the message.
timeout - The maximum time to wait for feedback.

Returns
NONE_ERROR if the shadow get request succeeds.
NULL_VALUE_ERROR if input parameters have NULL value.
OVERFLOW_ERROR if thing name exceeds the internal buffer size.
OUT_OF_SKETCH_SUBSCRIBE_MEMORY if the number of current subscribe exceeds the configured number in aws_iot_config_SDK.h.
NO_SHADOW_INIT_ERROR if the shadow with thingName is initialized before this call.
WRONG_PARAMETER_ERROR if there is an error for the Python Runtime to get enough input parameters for this command.
SUBSCRIBE_ERROR if the subscribe (accepted/rejected) failed.
SUBSCRIBE_TIMEOUT if the subscribe gets timeout.
PUBLISH_ERROR if the publish (payload) failed.
PUBLISH_TIMEOUT if the publish (payload) gets timeout.
PUBLISH_QUEUE_FULL if the publish action failed because of a full internal offline publish requests queue.
PUBLISH_QUEUE_DISABLED if the publish action failed because of a disabled internal offline publish requests queue.
SHADOW_GET_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="shadow_delete"></a>

IoT_Error_t shadow_delete(const char* thingName, message_callback cb, unsigned int timeout)

Description
Delete the thing shadow data in the cloud by publishing an empty JSON file onto the corresponding thing shadow topic and subscribing accepted/rejected thing shadow topics to get feedback of whether it is a successful/failed request. Timeout can be set in seconds as the maximum waiting time for feedback. Once the request gets timeout, a timeout message will be received. The registered callback function will be called whenever there is an accepted/rejected/timeout feedback. After the feedback comes in, it will automatically unsubscribe accepted/rejected shadow topics.

Syntax

object.shadow_delete("UserThingName", UserCallbackFunction, 5); // delete the data of the thing shadow "UserThingName", with a timeout of 5 seconds and UserCallbackFunction as the callback function

Parameters
thingName - The name of the thing shadow in the cloud. Must be a NULL-terminated string.
cb - Function pointer to user-specific callback function to call when a new message comes in for the subscribed topic. The callback function should have a parameter list of (char*, unsigned int, Message_status_t) to store the incoming message content and the length of the message.
timeout - The maximum time to wait for feedback.

Returns
NONE_ERROR if the shadow delete request succeeds.
NULL_VALUE_ERROR if input parameters have NULL value.
OVERFLOW_ERROR if thing name exceeds the internal buffer size.
OUT_OF_SKETCH_SUBSCRIBE_MEMORY if the number of current subscribe exceeds the configured number in aws_iot_config_SDK.h.
NO_SHADOW_INIT_ERROR if the shadow with thingName is initialized before this call.
WRONG_PARAMETER_ERROR if there is an error for the Python Runtime to get enough input parameters for this command.
SUBSCRIBE_ERROR if the subscribe (accepted/rejected) failed.
SUBSCRIBE_TIMEOUT if the subscribe gets timeout.
PUBLISH_ERROR if the publish (payload) failed.
PUBLISH_TIMEOUT if the publish (payload) gets timeout.
PUBLISH_QUEUE_FULL if the publish action failed because of a full internal offline publish requests queue.
PUBLISH_QUEUE_DISABLED if the publish action failed because of a disabled internal offline publish requests queue.
SHADOW_DELETE_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="shadow_register_delta_func"></a>

IoT_Error_t shadow_register_delta_func(const char* thingName, message_callback cb)

Description
Subscribe to the delta topic of the corresponding thing shadow with the given name and register a callback. Whenever there is a difference between the desired and reported state data, the registered callback will be called and the feedback/message will be available in the callback.

Syntax

object.shadow_register_delta_func("UserThingName", UserCallBackFunction); // register UserCallbackFunction as the  delta callback function for the thing shadow "UserThingName"

Parameters
thingName - The name of the thing shadow in the cloud. Must be a NULL-terminated string.
cb - Function pointer to user-specific callback function to call when a new message comes in for the subscribed topic. The callback function should have a parameter list of (char*, unsigned int, Message_status_t) to store the incoming message content and the length of the message.

Return
NONE_ERROR if the shadow delta topic is successfully subscribed and the callback function is successfully registered.
NULL_VALUE_ERROR if input parameters have NULL value.
OVERFLOW_ERROR if thing name exceeds the internal buffer size.
OUT_OF_SKETCH_SUBSCRIBE_MEMORY if the number of current subscribe exceeds the configured number in aws_iot_config_SDK.h.
NO_SHADOW_INIT_ERROR if the shadow with thingName is initialized before this call.
WRONG_PARAMETER_ERROR if there is an error for the Python Runtime to get enough input parameters for this command.
SUBSCRIBE_ERROR if the subscribe (accepted/rejected) failed.
SUBSCRIBE_TIMEOUT if the subscribe gets timeout.
SHADOW_REGISTER_DELTA_CALLBACK_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="shadow_unregister_delta_func"></a>

IoT_Error_t shadow_unregister_delta_func(const char* thingName)

Description
Unsubscribe to the delta topic of the corresponding thing shadow with the given name and unregister the callback. There will be no message coming after this API call if another difference occurs between the desired and reported state data for this thing shadow.

Syntax

object.shadow_unregister_delta_func("UserThingName"); // unregister the delta topic of the thing shadow "UserThingName"

Parameters
thingName - The name of the thing shadow in the cloud. Must be a NULL-terminated string.

Returns
NONE_ERROR if the shadow delta topic is successfully unsubscribed and the callback function is successfully unregistered.
NULL_VALUE_ERROR if input parameters have NULL value.
OVERFLOW_ERROR if thing name exceeds the internal buffer size.
NO_SHADOW_INIT_ERROR if the shadow with thingName is initialized before this call.
WRONG_PARAMETER_ERROR if there is an error for the Python Runtime to get enough input parameters for this command.
UNSUBSCRIBE_ERROR if the subscribe (accepted/rejected) failed.
UNSUBSCRIBE_TIMEOUT if the subscribe gets timeout.
SHADOW_UNREGISTER_DELTA_CALLBACK_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="getDesiredValueByKey"></a>

IoT_Error_t getDesiredValueByKey(const char* JSONIdentifier, const char* key, char* externalJSONBuf, unsigned int bufSize)

Description
Get the value by key in the desired section in the shadow JSON document denoted by the provided identifier. The corresponding value will be stored as a string into a user-specified externalBuffer. Nested key-value access is available. More information can be found here.

Syntax

object.getDesiredValueByKey("JSON-0", "property1", someBuffer, someBufferSize); // Access JSONDocument["state"]["desired"]["property1"] denoted by JSONIdentifier "JSON-0" and store the value in someBuffer
object.getDesiredValueByKey("JSON-0", "property2\"subproperty", someBuffer, someBufferSize); // Access JSONDocument["state"]["desired"]["property2"]["subproperty"] denoted by JSONIdentifier "JSON-0" and store the value in someBuffer

Parameters
JSONIdentifier - The JSON Identifier string to access a certain JSON document stored in Python runtime on the OpenWRT side. This is obtained from the registered shadow callback as shadow responses.
key - The key for dereferencing out the value in the desired section of the JSON document. Nested key can be specified using " as the delimiter.
externalJSONBuf - Buffer specified by the user to store the incoming value, as string.
bufSize - Size of the buffer to store the incoming value, as string.

Returns
NONE_ERROR if the value is retrieved successfully.
NO_SET_UP_ERROR if no setup is called before this call.
OVERFLOW_ERROR if the length of the incoming value exceeds the size of the provided externalJSONBuf.
JSON_FILE_NOT_FOUND if the JSON document with the provided JSON identifier does not exist.
JSON_KEY_NOT_FOUND if the specified key does not exist in the JSON document denoted by the provided JSON identifier.
JSON_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="getReportedValueByKey"></a>

IoT_Error_t getReportedValueByKey(const char* JSONIdentifier, const char* key, char* externalJSONBuf, unsigned int bufSize)]

Description
Get the value by key in the reported section in the shadow JSON document denoted by the provided identifier. The corresponding value will be stored as a string into a user-specified externalBuffer. Nested key-value access is available. More information can be found here.

Syntax

object.getReportedValueByKey("JSON-0", "property1", someBuffer, someBufferSize); // Access JSONDocument["state"]["reported"]["property1"] denoted by JSONIdentifier "JSON-0" and store the value in someBuffer
object.getReportedValueByKey("JSON-0", "property2\"subproperty", someBuffer, someBufferSize); // Access JSONDocument["state"]["reported"]["property2"]["subproperty"] denoted by JSONIdentifier "JSON-0" and store the value in someBuffer

Parameters
JSONIdentifier - The JSON Identifier string to access a certain JSON document stored in Python runtime on the OpenWRT side. This is obtained from the registered shadow callback as shadow responses.
key - The key for dereferencing out the value in the reported section of the JSON document. Nested key can be specified using " as the delimiter.
externalJSONBuf - Buffer specified by the user to store the incoming value, as string.
bufSize - Size of the buffer to store the incoming value, as string.

Returns
NONE_ERROR if the value is retrieved successfully.
NO_SET_UP_ERROR if no setup is called before this call.
OVERFLOW_ERROR if the length of the incoming value exceeds the size of the provided externalJSONBuf.
JSON_FILE_NOT_FOUND if the JSON document with the provided JSON identifier does not exist.
JSON_KEY_NOT_FOUND if the spedified key does not exist in the JSON document denoted by the provided JSON identifier.
JSON_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="getDeltaValueByKey"></a>

IoT_Error_t getDeltaValueByKey(const char* JSONIdentifier, const char* key, char* externalJSONBuf, unsigned int bufSize)]

Description
Get the value by key in the state section in the shadow JSON document denoted by the provided identifier. The corresponding value will be stored as a string into a user-specified externalBuffer. Nested key-value access is available. More information can be found here.

Syntax

object.getDeltaValueByKey("JSON-0", "property1", someBuffer, someBufferSize); // Access JSONDocument["state"]["property1"] denoted by JSONIdentifier "JSON-0" and store the value in someBuffer
object.getDeltaValueByKey("JSON-0", "property2\"subproperty", someBuffer, someBufferSize); // Access JSONDocument["state"]["property2"]["subproperty"] denoted by JSONIdentifier "JSON-0" and store the value in someBuffer

Parameters
JSONIdentifier - The JSON Identifier string to access a certain JSON document stored in Python runtime on the OpenWRT side. This is obtained from the registered shadow callback as shadow responses.
key - The key for dereferencing out the value in the state section of the JSON document. Nested key can be specified using " as the delimiter.
externalJSONBuf - Buffer specified by the user to store the incoming value, as string.
bufSize - Size of the buffer to store the incoming value, as string.

Returns
NONE_ERROR if the value is retrieved successfully.
NO_SET_UP_ERROR if no setup is called before this call.
OVERFLOW_ERROR if the length of the incoming value exceeds the size of the provided externalJSONBuf.
JSON_FILE_NOT_FOUND if the JSON document with the provided JSON identifier does not exist.
JSON_KEY_NOT_FOUND if the specified key does not exist in the JSON document denoted by the provided JSON identifier.
JSON_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="getValueByKey"></a>

IoT_Error_t getValueByKey(const char* JSONIdentifier, const char* key, char* externalJSONBuf, unsigned int bufSize)]

Description
Get the value by key in the shadow JSON document denoted by the provided identifier. The corresponding value will be stored as a string into a user-specified externalBuffer. Nested key-value access is available. More information can be found here.

Syntax

object.getValueByKey("JSON-0", "property1", someBuffer, someBufferSize); // Access JSONDocument["property1"] denoted by JSONIdentifier "JSON-0" and store the value in someBuffer
object.getValueByKey("JSON-0", "property2\"subproperty", someBuffer, someBufferSize); // Access JSONDocument["property2"]["subproperty"] denoted by JSONIdentifier "JSON-0" and store the value in someBuffer

Parameters
JSONIdentifier - The JSON Identifier string to access a certain JSON document stored in Python runtime on the OpenWRT side. This is obtained from the registered shadow callback as shadow responses.
key - The key for dereferencing out the value in the JSON document. Nested key can be specified using " as the delimiter.
externalJSONBuf - Buffer specified by the user to store the incoming value, as string.
bufSize - Size of the buffer to store the incoming value, as string.

Returns
NONE_ERROR if the value is retrieved successfully.
NO_SET_UP_ERROR if no setup is called before this call.
OVERFLOW_ERROR if the length of the incoming value exceeds the size of the provided externalJSONBuf.
JSON_FILE_NOT_FOUND if the JSON document with the provided JSON identifier does not exist.
JSON_KEY_NOT_FOUND if the specified key does not exist in the JSON document denoted by the provided JSON identifier.
JSON_GENERIC_ERROR if there is an error in executing the command in Python Runtime.
GENERIC_ERROR if an unknown error happens.

<a name="message_callback"></a>

void(*message_callback)(char*, unsigned int, Message_status_t)]

Description
Callback function for received MQTT messages, used for plain MQTT communications as well as shadow communications.
For plain MQTT messages, message payload and size will be passed into the callback. Message_status_t will be STATUS_NORMAL. See Parameters below for more details.
For shadow messages, JSON identifier and its size will be passed into the callback. Message_status_t varies for shadow messages from different topics. For accept shadow responses, Message_status_t will be STATUS_SHADOW_ACCEPTED. For reject shadow responses, Message_status_t will be STATUS_SHADOW_REJECTED. For delta shadow responses, Message_status_t will be STATUS_NORMAL. See Parameters below for more details.

Syntax

void custom_message_callback(char* msg, unsigned int length, Message_status_t status) {
	// * Access the incoming message from msg, length
	// Message payload for plain MQTT messages
	// JSON identifer for shadow messages
	// * Access the message status from status
	// STATUS_NORMAL for plain MQTT/shadow delta messages
	// STATUS_SHADOW_ACCEPTED for shadow accept responses
	// STATUS_SHADOW_REJECTED for shadow reject responses
}

Parameters
char* - Incoming message. Message payload for plain MQTT messages and JSON identifier for shadow message/responses.
unsigned int - Length of bytes of the incoming message.
Message_status_t - Status of the incoming responses/messages. It has the following values:

typedef enum {
	STATUS_DEBUG = -1,
	STATUS_NORMAL = 0,
	STATUS_SHADOW_TIMEOUT = 1,
	STATUS_SHADOW_ACCEPTED = 2,
	STATUS_SHADOW_REJECTED = 3,
	STATUS_MESSAGE_OVERFLOW = 4
} Message_status_t;

STATUS_NORMAL indicates that a new plain MQTT message/shadow delta message has arrived.
STATUS_SHADOW_TIMEOUT indicates that the incoming message is a shadow response for an operation timeout. There was no response received for the corresponding shadow operation within the preconfigured timeout.
STATUS_SHADOW_ACCEPTED indicates that the incoming message is a shadow response for accept. The corresponding shadow operation was accepted by the AWS IoT service and has succeeded.
STATUS_SHADOW_REJECTED indicates that the incoming message is a shadow response for reject. The corresponding shadow operation was rejected by the AWS IoT service and has failed.
STATUS_MESSAGE_OVERFLOW indicates that the size of the incoming message has exceeded the size of the internal message buffer. Internal message buffer size, configured in aws_iot_config_SDK.h, needs to be increased to receive the complete incoming message.
STATUS_DEBUG is for SDK internal use.

Returns
No returns.

<a name="keyfeatures"></a>

Key features

<a name="individualKVAccess"></a>

Individual Key Value Access for Shadow

As for shadow operations (Get/Update/Delete) and shadow delta messages, instead of detailed the message content for shadow JSON document, a JSON identifier will be passed through into the registered callback so that it can be used for key/value pair access on demand through the individual key/value pair access APIs. A JSON identifier of a shadow JSON response received looks like this:

JSON-i

where i is an integer number.

Note that there is a limitation on the total number of history JSON documents that can be kept on the OpenWRT side for key/value pair retrieval. The limits are:

512 entries for shadow JSON accepted responses
512 entries for shadow JSON rejected responses
512 entries for shadow JSON delta messages

Once the limits are exceeded, new incoming shadow JSON documents will overwrite history entries starting from the beginning (JSON-0, JSON-1 and JSON-2).

The following APIs are provided for uses to access shadow JSON key value pair from Arduino sketch in an easier manner:
IoT_Error_t getDesiredValueByKey(const char* JSONIdentifier, const char* key, char* externalJSONBuf, unsigned int bufSize)
IoT_Error_t getReportedValueByKey(const char* JSONIdentifier, const char* key, char* externalJSONBuf, unsigned int bufSize)
IoT_Error_t getDeltaValueByKey(const char* JSONIdentifier, const char* key, char* externalJSONBuf, unsigned int bufSize)
IoT_Error_t getValueByKey(const char* JSONIdentifier, const char* key, char* externalJSONBuf, unsigned int bufSize)

For a typical shadow JSON document (responses for get/update/delete), it should look like this:

{
	"state": {
		"desired": {
			...
		},
		"reported": {
			...
		}
	},
	...
}

getDesiredValueByKey and getReportedValueByKey can be used to access the key value pair in the desired/reported section respectively.

For a typical shadow JSON document (messages for delta), it should look like this:

{
	"state": {
		...
	},
	...
}

getDeltaValueByKey can be used to access the key value pair in the delta shadow JSON messages.

More generally, getValueByKey can be used to access key value pair in a more generic way where users can specify their own key patterns. Nested JSON key is denoted using " as the delimiter.

For example, we have the following shadow JSON document with a JSON identifier JSON-0:

{
	"state": {
		"desired": {
			"property1": "value1",
			"property2": {
				"subproperty": "value2"
			}
		},
		"reported": {
			"property3": "value3"
		}
	},
	...
}

To access a series of key value pair, we can use the following function calls:

object.getDesiredValueByKey("JSON-0", "property1", buffer, bufferSize); // Access JSONDocument["state"]["desired"]["property1"]
object.getReportedValueByKey("JSON-0", "property3", buffer, bufferSize); // Access JSONDocument["state"]["reported"]["property3"]
object.getDesiredValueByKey("JSON-0", "property2\"subproperty", buffer, bufferSize); // Access JSONDocument["state"]["desired"]["property2"]["subproperty"]

Note that the following two function calls are equivalent. They both access the nested JSON key value pair JSONDocument["state"]["desired"]["property2"]["subproperty"]:

object.getDesiredValueByKey("JSON-0", "property2\"subproperty", buffer, bufferSize);
object.getValueByKey("JSON-0", "state\"desired\"property2\"subproperty", buffer, bufferSize);

See that getValueByKey is a more generic way for shadow JSON key value access.

For detailed use cases, please check out Examples.

<a name="progressiveBackoff"></a>

Progressive Reconnect Back-off

API is provided to configure the progressive back-off timing parameters:
IoT_Error_t configBackoffTiming(unsigned int baseReconnectQuietTimeSecond, unsigned int maxReconnectQuietTimeSecond, unsigned int stableConnectionTimeSecond)

The auto-reconnect happens with a progressive back-off, which follows the following mechanism for reconnect quiet time:

<h5 align="center">t<sup>current</sup> = min(2<sup>n</sup>t<sup>base</sup>, t<sup>max</sup>),</h5>

where t<sup>current</sup> is the current reconnect quiet time, t<sup>base</sup> is the base reconnect quiet time, t<sup>max</sup> is the maximum reconnect quiet time.

The reconnect quiet time will be doubled on disconnect and reconnect attempt until it reaches the preconfigured maximum reconnect quiet time. Once the connection is stable for over the stableConnectionTime, the reconnect quiet time will be reset to the baseReconnectQuietTime.

If no configBackoffTiming gets called, the following default configuration for back-off timing will be done on setup call:

baseReconnectQuietTimeSecond = 1;
maxReconnectQuietTimeSecond = 128;
stableConnectionTimeSecond = 20;

<a name="offlinePublishQueueDraining"></a>

Offline publish requests queuing with draining

APIs are provided to configure the offline publish requests queuing (size and drop behavior) as well as draining intervals:
IoT_Error_t configOfflinePublishQueue(unsigned int queueSize, DropBehavior_t behavior)
IoT_Error_t configDrainingInterval(float numberOfSeconds)

When the client is temporarily offline and gets disconnected due to some network failure, publish requests will be queued up into an internal queue in the Python runtime on the OpenWRT side until the number of queued-up requests reaches to the size limit of the queue. Once the queue is full, offline publish requests will be discarded or replaced according to different configuration of the drop behavior:

typedef enum {
	DROP_OLDEST = 0,
	DROP_NEWEST = 1
} DropBehavior_t;

Lets say we configure the size of offlinePublishQueue to be 5 and we have 7 offline publish requests coming in...

In a DROP_OLDEST configuration:

myClient.configOfflinePublishQueue(5, DROP_OLDEST);

The internal queue should be like this when the queue is just full:

HEAD ['pub_req0', 'pub_req1', 'pub_req2', 'pub_req3', 'pub_req4']

When the 6th and the 7th publish requests are made offline, the internal queue will be like this:

HEAD ['pub_req2', 'pub_req3', 'pub_req4', 'pub_req5', 'pub_req6']

Since the queue is already full, the oldest requests pub_req0 and pub_req1 are discarded.

In a DROP_NEWEST configuration:

myClient.configOfflinePublishQueue(5, DROP_NEWEST);

The internal queue should be like this when the queue is just full:

HEAD ['pub_req0', 'pub_req1', 'pub_req2', 'pub_req3', 'pub_req4']

When the 6th and the 7th publish requests are made offline, the internal queue will be like this:

HEAD ['pub_req0', 'pub_req1', 'pub_req2', 'pub_req3', 'pub_req4']

Since the queue is already full, the newest requests pub_req5 and pub_req6 are discarded.

When the client is back online, connected and resubscribed to all topics that it has previously subscribed to, the draining starts. All requests in the offline publish queue will be resent at the configured draining rate.

if no configOfflinePublishQueue or configDrainingInterval is called, the following default configuration for offline publish queuing and draining will be done on setup call:

offlinePublishQueueSize = 20
dropBehavior = DROP_NEWEST
drainingInterval = 0.5 sec

Note that before the draining process finishes, any new publish request within this time will be added to the queue. Therefore, draining rate should be higher than the normal publish rate to avoid an endless draining process after reconnect.

Also note that disconnect event is detected based on PINGRESP MQTT packet loss. Offline publish queuing will NOT be triggered until the disconnect event gets detected. Configuring a shorter keep-alive interval allows the client to detect disconnects more quickly. Any QoS0 publish requests issued after the network failure and before the detection of the PINGRESP loss will be lost.

<a name="usingthesdk"></a>

Using the SDK

Make sure you have properly installed the AWS-IoT-Arduino-Yún-SDK and setup the board.

<a name="slowstartup"></a> Make sure to start the sketch after openWRT is ready and gets connected to WiFi. It takes about 80-90 seconds for Arduino Yún board to start the openWRT and get connected to WiFi for each power cycle.

Make sure you have properly configured SDK settings in aws_iot_config.h inside each sketch directory:

//===============================================================
#define AWS_IOT_MQTT_HOST "<RANDOM_STRING>.iot.<REGION>.amazonaws.com" 	// your endpoint
#define AWS_IOT_MQTT_PORT 8883									// your port, use 443 for MQTT over Websocket
#define AWS_IOT_CLIENT_ID	"My_ClientID"						// your client ID
#define AWS_IOT_MY_THING_NAME "My_Board"						// your thing name
#define AWS_IOT_ROOT_CA_FILENAME "aws-iot-rootCA.crt"           // your root-CA filename
#define AWS_IOT_CERTIFICATE_FILENAME "cert.pem"                 // your certificate filename
#define AWS_IOT_PRIVATE_KEY_FILENAME "privkey.pem"              // your private key filename
//===============================================================

These settings can be downloaded from the AWS IoT console after you created a device and clicked on "Connect a device".

Make sure you have included the AWS-IoT-Arduino-Yún-SDK library:

#include <aws_iot_mqtt.h>

Make sure you have included your configuration header file:

#include "aws_iot_config.h"

Make sure you have enough memory for subscribe, messages and sketch runtime. Internal buffer size is defined in SDK library source directory libraries/AWS-IoT-Arduino-Yun-Library/aws_iot_config_SDK.h. The following are default settings:

#define MAX_BUF_SIZE 256										// maximum number of bytes to publish/receive
#define MAX_SUB 15 												// maximum number of subscribe
#define CMD_TIME_OUT 200										// maximum time to wait for feedback from AR9331, 200 = 10 sec

Make sure you setup the client, configure it using your configuration and connect it to AWS IoT first. Remember to use certs path macros for configuration:

aws_iot_mqtt_client myClient;
myClient.setup(AWS_IOT_CLIENT_ID);
// myClient.setup(AWS_IOT_CLIENT_ID, true, MQTTv31, true); // Use Websocket
myClient.config(AWS_IOT_MQTT_HOST, AWS_IOT_MQTT_PORT, AWS_IOT_ROOT_CA_PATH, AWS_IOT_PRIVATE_KEY_PATH, AWS_IOT_CERTIFICATE_PATH);
// myClient.configWss(AWS_IOT_MQTT_HOST, AWS_IOT_MQTT_PORT, AWS_IOT_ROOT_CA_PATH); // Use Websocket
myClient.connnect();

Remember to check incoming messages in a loop:

void loop() { 
  ...  
  myClient.yield();
  ...
}

When you are using thing shadow API for a specific device shadow name, make sure you initialize the shadow with your device shadow name first:

myClient.shadow_init(AWS_IOT_MY_THING_NAME); // For shadow of this device
myClient.shadow_init("AnotherDevice"); // For another shadow

When you are using thing shadow API, always make sure MAX_SUB is big enough for a thing shadow request in the loop:

...
myClient.shadow_get("myThingName", myCallback, 5); // need 2 in MAX_SUB
...
void loop() {
	...
	myClient.shadow_get("myThingName", myCallback, 5); // need 4 in MAX_SUB
	myClient.yield(); // unsubscribe thing shadow topics when necessary
	...
}

When you are using thing shadow API, make sure you set the timeout to a proper value and frequently call yield to free subscribe resources. Long timeout with low rate of yielding and high rate of shadow request will result in exhaustion of subscribe resources:

void loop() {
	...
	myClient.shadow_get("myThingName", myCallback, 5); // 5 sec timeout is fine for a request per 5 sec
	
	// myClient.shadow_get("myThingName", myCallback, 50);
	// 50 sec timeout is too long. When missing feedback happens frequently, with a rate of 1 request per 5 sec, subscribed topics will soon accumulate and exceed MAX_SUB before any of the previously-subscribed topic gets timeout and unsubscribed
	
	myClient.yield();
	
	delay(5000); // 5 sec delay
	...
}

Enjoy the Internet of Things!

<a name="example"></a>

Example

BasicPubSub

This example demonstrates a simple MQTT publish/subscribe using AWS IoT from Arduino Yún board. It first subscribes to a topic once and registers a callback to print out new messages to Serial monitor and then publishes to the topic in a loop. Whenever it receives a new message, it will be printed out to Serial monitor indicating the callback function has been called.

ThingShadowEcho sample app

This example demonstrates Arduino Yún board as a device communicating with AWS IoT, syncing data into the thing shadow in the cloud and receiving commands from an app. Whenever there is a new command from the app side to change the desired state of the device, the board will receive this request and apply the change by publishing it as the reported state. By registering a delta callback function, users will be able to see this incoming message and notice the syncing of the state.

Simple Thermostat Simulator

This example demonstrates Arduino Yún as a device accepting instructions and syncing reported state in shadow in AWS IoT, which simulates a thermostat to control the temperature of a room. With the provided example App script, users will be able to get real-time temperature data coming from the board and be able to remotely set the desired temperature. This example also demonstrates how to retrieve shadow JSON data received on Arduino Yún Board.
AWS IoT Device SDK for Python is used in App scripts for MQTT connections. Users can modify it to use other MQTT library according to their needs.

<a name="errorcode"></a>

Error code

The following error codes are defined in AWS-IoT-Arduino-Yun-Library/aws_iot_error.h:

typedef enum {
	NONE_ERROR = 0,
	GENERIC_ERROR = -1,
	NULL_VALUE_ERROR = -2,
	OVERFLOW_ERROR = -3,
	OUT_OF_SKETCH_SUBSCRIBE_MEMORY = -4,
	SERIAL1_COMMUNICATION_ERROR = -5,
	SET_UP_ERROR = -6,
	NO_SET_UP_ERROR = -7,
	WRONG_PARAMETER_ERROR = -8,
	CONFIG_GENERIC_ERROR = -9,
	CONNECT_SSL_ERROR = -10,
	CONNECT_ERROR = -11,
	CONNECT_TIMEOUT = -12,
	CONNECT_CREDENTIAL_NOT_FOUND = -13,
	CONNECT_GENERIC_ERROR = -14,
	PUBLISH_ERROR = -15,
	PUBLISH_TIMEOUT = -16,
	PUBLISH_GENERIC_ERROR = -17,
	SUBSCRIBE_ERROR = -18,
	SUBSCRIBE_TIMEOUT = -19,
	SUBSCRIBE_GENERIC_ERROR = -20,
	UNSUBSCRIBE_ERROR = -21,
	UNSUBSCRIBE_TIMEOUT = -22,
	UNSUBSCRIBE_GENERIC_ERROR = -23,
	DISCONNECT_ERROR = -24,
	DISCONNECT_TIMEOUT = -25,
	DISCONNECT_GENERIC_ERROR = -26,
	SHADOW_INIT_ERROR = -27,
	NO_SHADOW_INIT_ERROR = -28,
	SHADOW_GET_GENERIC_ERROR = -29,
	SHADOW_UPDATE_GENERIC_ERROR = -30,
	SHADOW_UPDATE_INVALID_JSON_ERROR = -31,
	SHADOW_DELETE_GENERIC_ERROR = -32,
	SHADOW_REGISTER_DELTA_CALLBACK_GENERIC_ERROR = -33,
	SHADOW_UNREGISTER_DELTA_CALLBACK_GENERIC_ERROR = -34,
	YIELD_ERROR = -35,
	WEBSOCKET_CREDENTIAL_NOT_FOUND = -36,
	JSON_FILE_NOT_FOUND = -37,
	JSON_KEY_NOT_FOUND = -38,
	JSON_GENERIC_ERROR = -39,
	PUBLISH_QUEUE_FULL = -40,
	PUBLISH_QUEUE_DISABLED = -41
} IoT_Error_t;

<a name="support"></a>

Support

If you have technical questions about AWS IoT Device SDK, please use AWS IoT forum.
For any other questions on AWS IoT, please contact AWS Support.