Demonstrates usage of the Thing Shadow library. More...

#include "iot_config.h"
#include <stdbool.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "iot_demo_logging.h"
#include "platform/iot_clock.h"
#include "platform/iot_threads.h"
#include "iot_mqtt.h"
#include "aws_iot_shadow.h"
#include "aws_iot_doc_parser.h"

Macros
#define	KEEP_ALIVE_SECONDS ( 60 )
	The keep-alive interval used for this demo. More...

#define	TIMEOUT_MS ( 5000 )
	The timeout for Shadow and MQTT operations in this demo.

#define	SHADOW_DESIRED_JSON
	Format string representing a Shadow document with a "desired" state. More...

#define	EXPECTED_DESIRED_JSON_SIZE ( sizeof( SHADOW_DESIRED_JSON ) - 3 )
	The expected size of SHADOW_DESIRED_JSON. More...

#define	SHADOW_REPORTED_JSON
	Format string representing a Shadow document with a "reported" state. More...

#define	EXPECTED_REPORTED_JSON_SIZE ( sizeof( SHADOW_REPORTED_JSON ) - 3 )
	The expected size of SHADOW_REPORTED_JSON. More...

Functions
int	RunShadowDemo (bool awsIotMqttMode, const char pIdentifier, void pNetworkServerInfo, void pNetworkCredentialInfo, const IotNetworkInterface_t pNetworkInterface)
	The function that runs the Shadow demo, called by the demo runner. More...

static bool	_getDelta (const char pDeltaDocument, size_t deltaDocumentLength, const char pDeltaKey, const char *pDelta, size_t pDeltaLength)
	Parses a key in the "state" section of a Shadow delta document. More...

static bool	_getUpdatedState (const char pUpdatedDocument, size_t updatedDocumentLength, const char pSectionKey, const char *pState, size_t pStateLength)
	Parses the "state" key from the "previous" or "current" sections of a Shadow updated document. More...

static void	_shadowDeltaCallback (void pCallbackContext, AwsIotShadowCallbackParam_t pCallbackParam)
	Shadow delta callback, invoked when the desired and updates Shadow states differ. More...

static void	_shadowUpdatedCallback (void pCallbackContext, AwsIotShadowCallbackParam_t pCallbackParam)
	Shadow updated callback, invoked when the Shadow document changes. More...

static int	_initializeDemo (void)
	Initialize the the MQTT library and the Shadow library. More...

static void	_cleanupDemo (void)
	Clean up the the MQTT library and the Shadow library.

static int	_establishMqttConnection (const char pIdentifier, void pNetworkServerInfo, void pNetworkCredentialInfo, const IotNetworkInterface_t pNetworkInterface, IotMqttConnection_t *pMqttConnection)
	Establish a new connection to the MQTT server for the Shadow demo. More...

static int	_setShadowCallbacks (IotSemaphore_t pDeltaSemaphore, IotMqttConnection_t mqttConnection, const char pThingName, size_t thingNameLength)
	Set the Shadow callback functions used in this demo. More...

static void	_clearShadowDocument (IotMqttConnection_t mqttConnection, const char *const pThingName, size_t thingNameLength)
	Try to delete any Shadow document in the cloud. More...

static int	_sendShadowUpdates (IotSemaphore_t pDeltaSemaphore, IotMqttConnection_t mqttConnection, const char const pThingName, size_t thingNameLength)
	Send the Shadow updates that will trigger the Shadow callbacks. More...

Detailed Description

Demonstrates usage of the Thing Shadow library.

This program demonstrates the using Shadow documents to toggle a state called "powerOn" in a remote device.

Macro Definition Documentation

◆ KEEP_ALIVE_SECONDS

#define KEEP_ALIVE_SECONDS ( 60 )

The keep-alive interval used for this demo.

An MQTT ping request will be sent periodically at this interval.

◆ SHADOW_DESIRED_JSON

#define SHADOW_DESIRED_JSON

Value:

"{"                         \
    "\"state\":{"               \
    "\"desired\":{"             \
    "\"powerOn\":%01d"          \
    "}"                         \
    "},"                        \
    "\"clientToken\":\"%06lu\"" \
    "}"

Format string representing a Shadow document with a "desired" state.

Note the client token, which is required for all Shadow updates. The client token must be unique at any given time, but may be reused once the update is completed. For this demo, a timestamp is used for a client token.

◆ EXPECTED_DESIRED_JSON_SIZE

#define EXPECTED_DESIRED_JSON_SIZE ( sizeof( SHADOW_DESIRED_JSON ) - 3 )

The expected size of SHADOW_DESIRED_JSON.

Because all the format specifiers in SHADOW_DESIRED_JSON include a length, its full size is known at compile-time.

◆ SHADOW_REPORTED_JSON

#define SHADOW_REPORTED_JSON

Value:

"{"                         \
    "\"state\":{"               \
    "\"reported\":{"            \
    "\"powerOn\":%01d"          \
    "}"                         \
    "},"                        \
    "\"clientToken\":\"%06lu\"" \
    "}"

Format string representing a Shadow document with a "reported" state.

Note the client token, which is required for all Shadow updates. The client token must be unique at any given time, but may be reused once the update is completed. For this demo, a timestamp is used for a client token.

◆ EXPECTED_REPORTED_JSON_SIZE

#define EXPECTED_REPORTED_JSON_SIZE ( sizeof( SHADOW_REPORTED_JSON ) - 3 )

The expected size of SHADOW_REPORTED_JSON.

Because all the format specifiers in SHADOW_REPORTED_JSON include a length, its full size is known at compile-time.

Function Documentation

◆ RunShadowDemo()

int RunShadowDemo	(	bool	awsIotMqttMode,
		const char *	pIdentifier,
		void *	pNetworkServerInfo,
		void *	pNetworkCredentialInfo,
		const IotNetworkInterface_t *	pNetworkInterface
	)

The function that runs the Shadow demo, called by the demo runner.

Parameters

[in]	awsIotMqttMode	Ignored for the Shadow demo.
[in]	pIdentifier	NULL-terminated Shadow Thing Name.
[in]	pNetworkServerInfo	Passed to the MQTT connect function when establishing the MQTT connection for Shadows.
[in]	pNetworkCredentialInfo	Passed to the MQTT connect function when establishing the MQTT connection for Shadows.
[in]	pNetworkInterface	The network interface to use for this demo.

Returns: EXIT_SUCCESS if the demo completes successfully; EXIT_FAILURE otherwise.

◆ _getDelta()

static bool _getDelta	(	const char *	pDeltaDocument,
		size_t	deltaDocumentLength,
		const char *	pDeltaKey,
		const char **	pDelta,
		size_t *	pDeltaLength
	)

static

Parses a key in the "state" section of a Shadow delta document.

Parameters

[in]	pDeltaDocument	The Shadow delta document to parse.
[in]	deltaDocumentLength	The length of `pDeltaDocument`.
[in]	pDeltaKey	The key in the delta document to find. Must be NULL-terminated.
[out]	pDelta	Set to the first character in the delta key.
[out]	pDeltaLength	The length of the delta key.

Returns: true if the given delta key is found; false otherwise.

◆ _getUpdatedState()

static bool _getUpdatedState	(	const char *	pUpdatedDocument,
		size_t	updatedDocumentLength,
		const char *	pSectionKey,
		const char **	pState,
		size_t *	pStateLength
	)

static

Parses the "state" key from the "previous" or "current" sections of a Shadow updated document.

Parameters

[in]	pUpdatedDocument	The Shadow updated document to parse.
[in]	updatedDocumentLength	The length of `pUpdatedDocument`.
[in]	pSectionKey	Either "previous" or "current". Must be NULL-terminated.
[out]	pState	Set to the first character in "state".
[out]	pStateLength	Length of the "state" section.

Returns: true if the "state" was found; false otherwise.

◆ _shadowDeltaCallback()

static void _shadowDeltaCallback	(	void *	pCallbackContext,
		AwsIotShadowCallbackParam_t *	pCallbackParam
	)

static

Shadow delta callback, invoked when the desired and updates Shadow states differ.

This function simulates a device updating its state in response to a Shadow.

Parameters

[in]	pCallbackContext	Not used.
[in]	pCallbackParam	The received Shadow delta document.

◆ _shadowUpdatedCallback()

static void _shadowUpdatedCallback	(	void *	pCallbackContext,
		AwsIotShadowCallbackParam_t *	pCallbackParam
	)

static

Shadow updated callback, invoked when the Shadow document changes.

This function reports when a Shadow has been updated.

Parameters

[in]	pCallbackContext	Not used.
[in]	pCallbackParam	The received Shadow updated document.

◆ _initializeDemo()

static int _initializeDemo ( void )

static

Initialize the the MQTT library and the Shadow library.

Returns: EXIT_SUCCESS if all libraries were successfully initialized; EXIT_FAILURE otherwise.

◆ _establishMqttConnection()

static int _establishMqttConnection	(	const char *	pIdentifier,
		void *	pNetworkServerInfo,
		void *	pNetworkCredentialInfo,
		const IotNetworkInterface_t *	pNetworkInterface,
		IotMqttConnection_t *	pMqttConnection
	)

static

Establish a new connection to the MQTT server for the Shadow demo.

Parameters

[in]	pIdentifier	NULL-terminated MQTT client identifier. The Shadow demo will use the Thing Name as the client identifier.
[in]	pNetworkServerInfo	Passed to the MQTT connect function when establishing the MQTT connection.
[in]	pNetworkCredentialInfo	Passed to the MQTT connect function when establishing the MQTT connection.
[in]	pNetworkInterface	The network interface to use for this demo.
[out]	pMqttConnection	Set to the handle to the new MQTT connection.

Returns: EXIT_SUCCESS if the connection is successfully established; EXIT_FAILURE otherwise.

◆ _setShadowCallbacks()

static int _setShadowCallbacks	(	IotSemaphore_t *	pDeltaSemaphore,
		IotMqttConnection_t	mqttConnection,
		const char *	pThingName,
		size_t	thingNameLength
	)

static

Set the Shadow callback functions used in this demo.

Parameters

[in]	pDeltaSemaphore	Used to synchronize Shadow updates with the delta callback.
[in]	mqttConnection	The MQTT connection used for Shadows.
[in]	pThingName	The Thing Name for Shadows in this demo.
[in]	thingNameLength	The length of `pThingName`.

Returns: EXIT_SUCCESS if all Shadow callbacks were set; EXIT_FAILURE otherwise.

◆ _clearShadowDocument()

static void _clearShadowDocument	(	IotMqttConnection_t	mqttConnection,
		const char *const	pThingName,
		size_t	thingNameLength
	)

static

Try to delete any Shadow document in the cloud.

Parameters

[in]	mqttConnection	The MQTT connection used for Shadows.
[in]	pThingName	The Shadow Thing Name to delete.
[in]	thingNameLength	The length of `pThingName`.

◆ _sendShadowUpdates()

static int _sendShadowUpdates	(	IotSemaphore_t *	pDeltaSemaphore,
		IotMqttConnection_t	mqttConnection,
		const char *const	pThingName,
		size_t	thingNameLength
	)

static

Send the Shadow updates that will trigger the Shadow callbacks.

Parameters

[in]	pDeltaSemaphore	Used to synchronize Shadow updates with the delta callback.
[in]	mqttConnection	The MQTT connection used for Shadows.
[in]	pThingName	The Thing Name for Shadows in this demo.
[in]	thingNameLength	The length of `pThingName`.

Returns: EXIT_SUCCESS if all Shadow updates were sent; EXIT_FAILURE otherwise.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ KEEP_ALIVE_SECONDS

◆ SHADOW_DESIRED_JSON

◆ EXPECTED_DESIRED_JSON_SIZE

◆ SHADOW_REPORTED_JSON

◆ EXPECTED_REPORTED_JSON_SIZE

Function Documentation

◆ RunShadowDemo()

◆ _getDelta()

◆ _getUpdatedState()

◆ _shadowDeltaCallback()

◆ _shadowUpdatedCallback()

◆ _initializeDemo()

◆ _establishMqttConnection()

◆ _setShadowCallbacks()

◆ _clearShadowDocument()

◆ _sendShadowUpdates()