Demo application for using the AT&T IoT Starter Kit Powered by AWS.
Dependencies: SDFileSystem
Fork of ATT_AWS_IoT_demo by
aws_iot_shadow_interface.h
00001 /* 00002 * Copyright 2010-2015 Amazon.com, Inc. or its affiliates. All Rights Reserved. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"). 00005 * You may not use this file except in compliance with the License. 00006 * A copy of the License is located at 00007 * 00008 * http://aws.amazon.com/apache2.0 00009 * 00010 * or in the "license" file accompanying this file. This file is distributed 00011 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either 00012 * express or implied. See the License for the specific language governing 00013 * permissions and limitations under the License. 00014 */ 00015 #ifndef AWS_IOT_SDK_SRC_IOT_SHADOW_H_ 00016 #define AWS_IOT_SDK_SRC_IOT_SHADOW_H_ 00017 00018 00019 /** 00020 * @file aws_iot_shadow_interface.h 00021 * @brief Interface for thing shadow 00022 * 00023 * These are the functions and structs to manage/interact the Thing Shadow(in the cloud). 00024 * This SDK will let you interact with your own thing shadow or any other shadow using its Thing Name. 00025 * There are totally 3 actions a device can perform on the shadow - Get, Update and Delete. 00026 * 00027 * Currently the device should use MQTT/S underneath. In the future this will also support other protocols. As it supports MQTT, the shadow needs to connect and disconnect. 00028 * It will also work on the pub/sub model. On performing any action, the acknowledgment will be received in either accepted or rejected. For Example: 00029 * If we want to perform a GET on the thing shadow the following messages will be sent and received: 00030 * 1. A MQTT Publish on the topic - $aws/things/{thingName}/shadow/get 00031 * 2. Subscribe to MQTT topics - $aws/things/{thingName}/shadow/get/accepted and $aws/things/{thingName}/shadow/get/rejected. 00032 * If the request was successful we will receive the things json document in the accepted topic. 00033 * 00034 * 00035 */ 00036 #include "aws_iot_mqtt_interface.h" 00037 #include "aws_iot_shadow_json_data.h" 00038 00039 /*! 00040 * @brief Shadow Connect parameters 00041 * 00042 * As the Shadow SDK uses MQTT underneath, it could be connected and disconnected on events to save some battery. 00043 * @note Always use the \c ShadowParametersDefault to initialize this struct 00044 * 00045 * 00046 * 00047 */ 00048 typedef struct { 00049 char *pMyThingName; ///< Every device has a Thing Shadow and this is the placeholder for name 00050 char *pMqttClientId; ///< Currently the Shadow uses MQTT to connect and it is important to ensure we have unique client id 00051 char *pHost; ///< This will be unique to a customer and can be retrieved from the console 00052 int port; ///< By default the port is 8883 00053 char *pRootCA; ///< Location with the Filename of the Root CA 00054 char *pClientCRT; ///< Location of Device certs signed by AWS IoT service 00055 char *pClientKey; ///< Location of Device private key 00056 } ShadowParameters_t; 00057 00058 /*! 00059 * @brief This is set to defaults from the configuration file 00060 * The certs are set to NULL because they need the path to the file. shadow_sample.c file demonstrates on how to get the relative path 00061 * 00062 * \relates ShadowParameters_t 00063 */ 00064 extern const ShadowParameters_t ShadowParametersDefault; 00065 00066 00067 /** 00068 * @brief Initialize the Thing Shadow before use 00069 * 00070 * This function takes care of initializing the internal book-keeping data structures 00071 * 00072 * @param pClient MQTT Client used as the protocol layer 00073 * @return An IoT Error Type defining successful/failed Initialization 00074 */ 00075 IoT_Error_t aws_iot_shadow_init(MQTTClient_t *pClient); 00076 /** 00077 * @brief Connect to the AWS IoT Thing Shadow service over MQTT 00078 * 00079 * This function does the TLSv1.2 handshake and establishes the MQTT connection 00080 * 00081 * @param pClient MQTT Client used as the protocol layer 00082 * @param pParams Shadow Conenction parameters like TLS cert location 00083 * @return An IoT Error Type defining successful/failed Connection 00084 */ 00085 IoT_Error_t aws_iot_shadow_connect(MQTTClient_t *pClient, ShadowParameters_t *pParams); 00086 /** 00087 * @brief Yield function to let the background tasks of MQTT and Shadow 00088 * 00089 * This function could be use in a separate thread waiting for the incoming messages, ensuring the connection is kept alive with the AWS Service. 00090 * It also ensures the expired requests of Shadow actions are cleared and Timeout callback is executed. 00091 * @note All callbacks ever used in the SDK will be executed in the context of this function. 00092 * 00093 * @param pClient MQTT Client used as the protocol layer 00094 * @param timeout in milliseconds, This is the maximum time the yield function will wait for a message and/or read the messages from the TLS buffer 00095 * @return An IoT Error Type defining successful/failed Yield 00096 */ 00097 IoT_Error_t aws_iot_shadow_yield(MQTTClient_t *pClient, int timeout); 00098 /** 00099 * @brief Disconnect from the AWS IoT Thing Shadow service over MQTT 00100 * 00101 * This will close the underlying TCP connection, MQTT connection will also be closed 00102 * 00103 * @param pClient MQTT Client used as the protocol layer 00104 * @return An IoT Error Type defining successful/failed disconnect status 00105 */ 00106 IoT_Error_t aws_iot_shadow_disconnect(MQTTClient_t *pClient); 00107 00108 /** 00109 * @brief Thing Shadow Acknowledgment enum 00110 * 00111 * This enum type is use in the callback for the action response 00112 * 00113 */ 00114 typedef enum { 00115 SHADOW_ACK_TIMEOUT, SHADOW_ACK_REJECTED, SHADOW_ACK_ACCEPTED 00116 } Shadow_Ack_Status_t; 00117 00118 /** 00119 * @brief Thing Shadow Action type enum 00120 * 00121 * This enum type is use in the callback for the action response 00122 * 00123 */ 00124 typedef enum { 00125 SHADOW_GET, SHADOW_UPDATE, SHADOW_DELETE 00126 } ShadowActions_t; 00127 00128 00129 /** 00130 * @brief Function Pointer typedef used as the callback for every action 00131 * 00132 * This function will be called from the context of \c aws_iot_shadow_yield() context 00133 * 00134 * @param pThingName Thing Name of the response received 00135 * @param action The response of the action 00136 * @param status Informs if the action was Accepted/Rejected or Timed out 00137 * @param pReceivedJsonDocument Received JSON document 00138 * @param pContextData the void* data passed in during the action call(update, get or delete) 00139 * 00140 */ 00141 typedef void (*fpActionCallback_t)(const char *pThingName, ShadowActions_t action, Shadow_Ack_Status_t status, 00142 const char *pReceivedJsonDocument, void *pContextData); 00143 00144 /** 00145 * @brief This function is the one used to perform an Update action to a Thing Name's Shadow. 00146 * 00147 * update is one of the most frequently used functionality by a device. In most cases the device may be just reporting few params to update the thing shadow in the cloud 00148 * Update Action if no callback or if the JSON document does not have a client token then will just publish the update and not track it. 00149 * 00150 * @note The update has to subscribe to two topics update/accepted and update/rejected. This function waits 2 seconds to ensure the subscriptions are registered before publishing the update message. 00151 * The following steps are performed on using this function: 00152 * 1. Subscribe to Shadow topics - $aws/things/{thingName}/shadow/update/accepted and $aws/things/{thingName}/shadow/update/rejected 00153 * 2. wait for 2 seconds for the subscription to take effect 00154 * 3. Publish on the update topic - $aws/things/{thingName}/shadow/update 00155 * 4. In the \c aws_iot_shadow_yield() function the response will be handled. In case of timeout or if the response is received, the subscription to shadow response topics are un-subscribed from. 00156 * On the contrary if the persistent subscription is set to true then the un-subscribe will not be done. The topics will always be listened to. 00157 * 00158 * @param pClient MQTT Client used as the protocol layer 00159 * @param pThingName Thing Name of the shadow that needs to be Updated 00160 * @param pJsonString The update action expects a JSON document to send. The JSO String should be a null terminated string. This JSON document should adhere to the AWS IoT Thing Shadow specification. To help in the process of creating this document- SDK provides apis in \c aws_iot_shadow_json_data.h 00161 * @param callback This is the callback that will be used to inform the caller of the response from the AWS IoT Shadow service.Callback could be set to NULL if response is not important 00162 * @param pContextData This is an extra parameter that could be passed along with the callback. It should be set to NULL if not used 00163 * @param timeout_seconds It is the time the SDK will wait for the response on either accepted/rejected before declaring timeout on the action 00164 * @param isPersistentSubscribe As mentioned above, every time if a device updates the same shadow then this should be set to true to avoid repeated subscription and unsubscription. If the Thing Name is one off update then this should be set to false 00165 * @return An IoT Error Type defining successful/failed update action 00166 */ 00167 IoT_Error_t aws_iot_shadow_update(MQTTClient_t *pClient, const char *pThingName, char *pJsonString, 00168 fpActionCallback_t callback, void *pContextData, uint8_t timeout_seconds, bool isPersistentSubscribe); 00169 00170 /** 00171 * @brief This function is the one used to perform an Get action to a Thing Name's Shadow. 00172 * 00173 * One use of this function is usually to get the config of a device at boot up. 00174 * It is similar to the Update function internally except it does not take a JSON document as the input. The entire JSON document will be sent over the accepted topic 00175 * 00176 * @param pClient MQTT Client used as the protocol layer 00177 * @param pThingName Thing Name of the JSON document that is needed 00178 * @param callback This is the callback that will be used to inform the caller of the response from the AWS IoT Shadow service.Callback could be set to NULL if response is not important 00179 * @param pContextData This is an extra parameter that could be passed along with the callback. It should be set to NULL if not used 00180 * @param timeout_seconds It is the time the SDK will wait for the response on either accepted/rejected before declaring timeout on the action 00181 * @param isPersistentSubscribe As mentioned above, every time if a device gets the same Sahdow (JSON document) then this should be set to true to avoid repeated subscription and un-subscription. If the Thing Name is one off get then this should be set to false 00182 * @return An IoT Error Type defining successful/failed get action 00183 */ 00184 IoT_Error_t aws_iot_shadow_get(MQTTClient_t *pClient, const char *pThingName, fpActionCallback_t callback, 00185 void *pContextData, uint8_t timeout_seconds, bool isPersistentSubscribe); 00186 /** 00187 * @brief This function is the one used to perform an Delete action to a Thing Name's Shadow. 00188 * 00189 * This is not a very common use case for device. It is generally the responsibility of the accompanying app to do the delete. 00190 * It is similar to the Update function internally except it does not take a JSON document as the input. The Thing Shadow referred by the ThingName will be deleted. 00191 * 00192 * @param pClient MQTT Client used as the protocol layer 00193 * @param pThingName Thing Name of the Shadow that should be deleted 00194 * @param callback This is the callback that will be used to inform the caller of the response from the AWS IoT Shadow service.Callback could be set to NULL if response is not important 00195 * @param pContextData This is an extra parameter that could be passed along with the callback. It should be set to NULL if not used 00196 * @param timeout_seconds It is the time the SDK will wait for the response on either accepted/rejected before declaring timeout on the action 00197 * @param isPersistentSubscribe As mentioned above, every time if a device deletes the same Sahdow (JSON document) then this should be set to true to avoid repeated subscription and un-subscription. If the Thing Name is one off delete then this should be set to false 00198 * @return An IoT Error Type defining successful/failed delete action 00199 */ 00200 IoT_Error_t aws_iot_shadow_delete(MQTTClient_t *pClient, const char *pThingName, fpActionCallback_t callback, 00201 void *pContextData, uint8_t timeout_seconds, bool isPersistentSubscriptions); 00202 00203 /** 00204 * @brief This function is used to listen on the delta topic of #AWS_IOT_MY_THING_NAME mentioned in the aws_iot_config.h file. 00205 * 00206 * Any time a delta is published the Json document will be delivered to the pStruct->cb. If you don't want the parsing done by the SDK then use the jsonStruct_t key set to "state". A good example of this is displayed in the sample_apps/shadow_console_echo.c 00207 * 00208 * @param pClient MQTT Client used as the protocol layer 00209 * @param pStruct The struct used to parse JSON value 00210 * @return An IoT Error Type defining successful/failed delta registering 00211 */ 00212 IoT_Error_t aws_iot_shadow_register_delta(MQTTClient_t *pClient, jsonStruct_t *pStruct); 00213 00214 /** 00215 * @brief Reset the last received version number to zero. 00216 * This will be useful if the Thing Shadow is deleted and would like to to reset the local version 00217 * @return no return values 00218 * 00219 */ 00220 void aws_iot_shadow_reset_last_received_version(void); 00221 /** 00222 * @brief Version of a document is received with every accepted/rejected and the SDK keeps track of the last received version of the JSON document of #AWS_IOT_MY_THING_NAME shadow 00223 * 00224 * One exception to this version tracking is that, the SDK will ignore the version from update/accepted topic. Rest of the responses will be scanned to update the version number. 00225 * Accepting version change for update/accepted may cause version conflicts for delta message if the update message is received before the delta. 00226 * 00227 * @return version number of the last received response 00228 * 00229 */ 00230 uint32_t aws_iot_shadow_get_last_received_version(void); 00231 /** 00232 * @brief Enable the ignoring of delta messages with old version number 00233 * 00234 * As we use MQTT underneath, there could be more than 1 of the same message if we use QoS 0. To avoid getting called for the same message, this functionality should be enabled. All the old message will be ignored 00235 */ 00236 void aws_iot_shadow_enable_discard_old_delta_msgs(void); 00237 /** 00238 * @brief Disable the ignoring of delta messages with old version number 00239 */ 00240 void aws_iot_shadow_disable_discard_old_delta_msgs(void); 00241 00242 #endif //AWS_IOT_SDK_SRC_IOT_SHADOW_H_ 00243
Generated on Tue Jul 12 2022 22:13:20 by 1.7.2