AWS IoT Embedded C Device SDK
Thing Shadow

Thing Shadow module implements the JSON based protocol of the AWS IoT Thing Shadow. The SDK currently supports only one Thing Name for a device. Though the device can update any "Thing" using the Thing Name. A Device can perform update, get and delete action on its own or any Thing Shadow. There are totally 3 Key value pair a device needs to concerned about.

The device will always receive a delta message if there is any difference between the desired and the reported section of the device. Unless there is no call made to the aws_iot_shadow_register_delta(), The SDK will not subscribe to the delta topic.

Shadow Acknowledgments

If we want to perform an Update to a thing shadow and get the acknowledgment of the action. One of two things can happen, The update action could be accepted by the Thing Shadow and the version of the JSON document will be updated. The update request could also be rejected.

To know one way or the other, we need to subscribe to the 2 topics: $aws/things/{thingName}/shadow/update/accepted and $aws/things/{thingName}/shadow/update/rejected . One issue with this approach is that, There could be multiple devices trying to update the same shadow. Then it becomes impossible to know if was our update or the other apps. To avoid this we include a client token string to the request. It is of the form: "clientToken": "UniqueClientID+Seq". We use the MQTT client ID #AWS_IOT_MQTT_CLIENT_ID (as it has to be unique for one AWS account) with a sequence number to differentiate between our previous update requests.

This is taken care for you by the APIs in aws_iot_shadow_json_data.h file. In particular the aws_iot_finalize_json_document() adds the client token to the JSON request

Shadow JSON construction

There are APIs to help you in constructing a JSON update request in the aws_iot_shadow_json_data.h file. More about the usage could be found in the shadow_sample.c file. The update request construction should happen in this order.

  1. aws_iot_shadow_init_json_document()
  2. aws_iot_shadow_add_reported()
    Note
    desired and reported section are not mandatory. Most devices might just use the reported section
  3. aws_iot_shadow_add_desired()
  4. aws_iot_finalize_json_document()
    Note
    These APIs are there for the convenience and needs to be used with care. In the future revisions ideally this will be replaced with Auto code generation capabilities as most of the devices dont need dynamic configuration of the JSON document.

JSON Library

The JSON library used for this SDK is JSMN . This library is not using any dynamic memory allocation.

Configuration

#SHADOW_MAX_SIZE_OF_RX_BUFFER

#MAX_SIZE_OF_UNIQUE_CLIENT_ID_BYTES

#MAX_SIZE_CLIENT_ID_WITH_SEQUENCE

#MAX_SIZE_CLIENT_TOKEN_CLIENT_SEQUENCE

#MAX_ACKS_TO_COMEIN_AT_ANY_GIVEN_TIME

#MAX_THINGNAME_HANDLED_AT_ANY_GIVEN_TIME

#MAX_JSON_TOKEN_EXPECTED

#MAX_SHADOW_TOPIC_LENGTH_WITHOUT_THINGNAME

#MAX_SIZE_OF_THING_NAME

#MAX_SHADOW_TOPIC_LENGTH_BYTES

Known Issues