Singleton class for managing cloud-based configuration. More...

#include <CloudConfigRK.h>

Public Types
enum	UpdateDataStatus { UpdateDataStatus::IDLE, UpdateDataStatus::IN_PROGRESS, UpdateDataStatus::SUCCESS, UpdateDataStatus::FAILURE, UpdateDataStatus::TIMEOUT }
	Enumeration used for the status of updateData. More...

Public Member Functions
CloudConfig &	withStorageMethod (CloudConfigStorage *storageMethod)
	Sets the storage method class, required before setup() is called. More...

CloudConfig &	withUpdateMethod (CloudConfigUpdate *updateMethod)
	Sets the update method class, not required, but if used, call before setup() is called. More...

CloudConfig &	withUpdateFrequency (long updateFrequency)
	Sets the update frequency in seconds. More...

CloudConfig &	withUpdateFrequency (std::chrono::seconds chronoLiteral)
	Sets the update frequency as a chrono literal. More...

CloudConfig &	withUpdateFrequencyOnce ()
	Sets the update frequency only if there is no saved value. More...

CloudConfig &	withUpdateFrequencyAtRestart ()
	Sets the update frequency to update once after cloud connecting after restart. More...

CloudConfig &	withDataCallback (std::function< void(void)> dataCallback)
	Adds a callback to be called after data is loaded or updated. More...

void	setup ()
	You must call setup() from your app's global setup after configuring it using the withXXX() methods.

void	loop ()
	You must call this from loop on every call to loop()

JSONValue	getJSONValue ()
	Gets the top level (outer) JSONValue object. More...

JSONValue	getJSONValueForKey (const char *key)
	Gets the value for a given key in the top-level outer JSON object. More...

JSONValue	getJSONValueForKey (JSONValue parentObj, const char *key)
	Gets the value for a given key in the a JSON object. More...

JSONValue	getJSONValueAtIndex (size_t index)
	Gets the value for a given index in the a JSON array in the top-level outer JSON array. More...

JSONValue	getJSONValueAtIndex (JSONValue parentObj, size_t index)
	Gets the value for a given index in the a JSON array. More...

int	getInt (const char *key)
	Convenience method for getting a top level JSON integer value by its key name. More...

bool	getBool (const char *key)
	Convenience method for getting a top level JSON integer value by its key name. More...

double	getDouble (const char *key)
	Convenience method for getting a top level JSON integer value by its key name. More...

const char *	getString (const char *key)
	Convenience method for getting a top level JSON integer value by its key name. More...

virtual bool	updateData (const char *json)
	Update methods call this when they have JSON configuration data. More...

void	updateDataFailed ()
	Update methods call this if they tried but failed to get configuration data. More...

Static Public Member Functions
static CloudConfig &	instance ()
	Get the singleton instance of this class. More...

Static Public Attributes
static const uint32_t	DATA_MAGIC = 0x7251dd53
	Magic bytes used to detect if EEPROM or retained memory has been initialized.

static const long	UPDATE_ONCE = 0
	Value used for updateFrequency to only request configuration data if it has never been saved.

static const long	UPDATE_AT_RESTART = -1
	Value used for updateFrequency to request configuration data on every restart. More...

Protected Member Functions
	CloudConfig ()
	Constructor - You never instantiate this class directly. More...

virtual	~CloudConfig ()
	This class is a singleton and never deleted.

	CloudConfig (const CloudConfig &)=delete
	This class is not copyable.

CloudConfig &	operator= (const CloudConfig &)=delete
	This class is not copyable.

void	stateStart ()
	State handler this is the first state entered. More...

void	stateWaitCloudConnected ()
	State handler to wait for cloud connnected. More...

void	stateWaitAfterCloudConnected ()
	State handler for the waiting time after cloud connected. More...

void	stateWaitToUpdate ()
	State handler for waiting to update. More...

void	stateStartUpdate ()
	State handler to have the update method actually update settings. More...

void	stateWaitUpdateComplete ()
	Waits for updateData or updateDataFailed to be called. More...

Protected Attributes
CloudConfigStorage *	storageMethod = 0
	Storage object - used to store data in retained memory, EEPROM, or flash file system file.

CloudConfigUpdate *	updateMethod = 0
	Update object - used to request data from the cloud.

std::function< void(void)>	dataCallback = 0
	Callback to call when there is data. More...

long	updateFrequency = 0
	How often to update the data from the cloud. More...

UpdateDataStatus	updateDataStatus = UpdateDataStatus::IDLE
	Status of updateData. Used when in stateWaitUpdateComplete. More...

std::function< void(CloudConfig &)>	stateHandler = 0
	State handler for the main state machine.

unsigned long	stateTime = 0
	Time value (millis) used in some states.

Static Protected Attributes
static CloudConfig *	_instance
	Singleton instance of this class.

Detailed Description

Singleton class for managing cloud-based configuration.

Member Enumeration Documentation

◆ UpdateDataStatus

enum CloudConfig::UpdateDataStatus

strong

Enumeration used for the status of updateData.

Enumerator
IDLE	updateData is not in progress
IN_PROGRESS	updateData is in progress (startData called, but updateData or updateDataFailed not called yet, and not at timeout)
SUCCESS	After startData(), updateData() was called so the data was successfully retrieved.
FAILURE	After startData(), updateDataFailed() was called so the data was not retrieved.
TIMEOUT	After startData(), neither updateData() nor updateDataFailed() were called by the timeout value.

Constructor & Destructor Documentation

◆ CloudConfig()

CloudConfig::CloudConfig ( )

protected

Constructor - You never instantiate this class directly.

Instead, get a singleton instance of a subclass by using CloudConfig::instance().

Member Function Documentation

◆ getBool()

bool CloudConfig::getBool ( const char * key )

inline

Convenience method for getting a top level JSON integer value by its key name.

Parameters

key	The JSON key to retrieve

If the key does not exist, false is returned.

◆ getDouble()

double CloudConfig::getDouble ( const char * key )

inline

Convenience method for getting a top level JSON integer value by its key name.

Parameters

key	The JSON key to retrieve

If the key does not exist, 0 is returned.

◆ getInt()

int CloudConfig::getInt ( const char * key )

inline

Convenience method for getting a top level JSON integer value by its key name.

Parameters

key	The JSON key to retrieve

If the key does not exist, 0 is returned.

◆ getJSONValue()

JSONValue CloudConfig::getJSONValue ( )

inline

Gets the top level (outer) JSONValue object.

This is typically an object, but could be an array.

◆ getJSONValueAtIndex() [1/2]

JSONValue CloudConfig::getJSONValueAtIndex	(	JSONValue	parentObj,
		size_t	index
	)

inline

Gets the value for a given index in the a JSON array.

Parameters

parentObj	A JSONValue for a JSON object to look in
index	0 = first entry, 1 = second entry, ...

Returns: A JSONValue object for that key. If the key does not exist in that object, an empty JSONValue object that returns false for isValid() is returned.

There is no call to determine the length of the array; iterate until an invalid object is returned.

◆ getJSONValueAtIndex() [2/2]

JSONValue CloudConfig::getJSONValueAtIndex ( size_t index )

inline

Gets the value for a given index in the a JSON array in the top-level outer JSON array.

Parameters

index 0 = first entry, 1 = second entry, ...

Returns: A JSONValue object for that key. If the key does not exist in that object, an empty JSONValue object that returns false for isValid() is returned.

This method is not commonly used because the top-level object is usually a JSON object (surrounded by { }) not a JSON array (surrounded by [ ]).

There is no call to determine the length of the array; iterate until an invalid object is returned.

◆ getJSONValueForKey() [1/2]

JSONValue CloudConfig::getJSONValueForKey ( const char * key )

inline

Gets the value for a given key in the top-level outer JSON object.

Parameters

key	The name of the key-value pair

Returns: A JSONValue object for that key. If the key does not exist in that object, an empty JSONValue object that returns false for isValid() is returned.

The getInt(), getBool(), getString() are convenience methods for getJSONValueForKey(key).toInt(), etc.

◆ getJSONValueForKey() [2/2]

JSONValue CloudConfig::getJSONValueForKey	(	JSONValue	parentObj,
		const char *	key
	)

inline

Gets the value for a given key in the a JSON object.

Parameters

parentObj	A JSONValue for a JSON object to look in
key	The name of the key-value pair

Returns: A JSONValue object for that key. If the key does not exist in that object, an empty JSONValue object that returns false for isValid() is returned.

◆ getString()

const char* CloudConfig::getString ( const char * key )

inline

Convenience method for getting a top level JSON integer value by its key name.

Parameters

key	The JSON key to retrieve

If the key does not exist, an empty string is returned.

◆ instance()

CloudConfig & CloudConfig::instance ( )

static

Get the singleton instance of this class.

You always use CloudConfig::instance() to get a reference to the singleton instance of this class. You cannot construct one of these as a global or on the stack. The singleton instance will never be deleted.

◆ stateStart()

void CloudConfig::stateStart ( )

protected

State handler this is the first state entered.

May call dataCallback if there is valid saved data

Next state: stateWaitCloudConnected

◆ stateStartUpdate()

void CloudConfig::stateStartUpdate ( )

protected

State handler to have the update method actually update settings.

The startUpdate method of the update method is called in this state.

Previous state: stateWaitAfterCloudConnected or stateWaitToUpdate Next state: stateWaitUpdateComplete

◆ stateWaitAfterCloudConnected()

void CloudConfig::stateWaitAfterCloudConnected ( )

protected

State handler for the waiting time after cloud connected.

This waits waitAfterCloudConnectedMs, which is configurable within the update method. Default is 2 seconds.

Previous state: stateWaitCloudConnected Next state: stateStartUpdate if we need to retrieve settings or stateWaitToUpdate if there is no update required (not time yet)

◆ stateWaitCloudConnected()

void CloudConfig::stateWaitCloudConnected ( )

protected

State handler to wait for cloud connnected.

Waits until Particle.connected() is true and also Time.isValid(). The latter is necessary because the store a timestamp of when we last checked the cloud settings.

Previous state: stateStart Next state: stateWaitAfterCloudConnected

◆ stateWaitToUpdate()

void CloudConfig::stateWaitToUpdate ( )

protected

State handler for waiting to update.

If updateFrequency is set to a periodic value greater than zero, this state waits until the time has expired.

Previous state: stateWaitAfterCloudConnected Next state: stateStartUpdate

◆ stateWaitUpdateComplete()

void CloudConfig::stateWaitUpdateComplete ( )

protected

Waits for updateData or updateDataFailed to be called.

The update method starts the update process when startUpdate() is called. Then they either call CloudConfig::instance().updateData() or updateDataFailed().

If neither is called before updateTimeoutMs expires (default: 60 seconds) an error is assume to have occurred and is treated as if the updateDataFailed.

Previous state: stateStartUpdate Next state: stateWaitToUpdate

◆ updateData()

bool CloudConfig::updateData ( const char * json )

virtual

Update methods call this when they have JSON configuration data.

The maximum size of the data is dependent on the storage method and how it was configured.

◆ updateDataFailed()

void CloudConfig::updateDataFailed ( )

Update methods call this if they tried but failed to get configuration data.

If you don't call updateData() or updateDataFailed() from the update method, then eventually it will time out, which will be treated as a failure.

◆ withDataCallback()

CloudConfig& CloudConfig::withDataCallback ( std::function< void(void)> dataCallback )

inline

Adds a callback to be called after data is loaded or updated.

Parameters

dataCallback the callback function to call

Returns: Returns *this so you can chain together the withXXX() methods, fluent-style.

Must be called before setup().

The method should have this prototype:

void callback(void);

The callback can also be a C++11 lambda, which you can use to call a C++ member function, if desired.

◆ withStorageMethod()

CloudConfig& CloudConfig::withStorageMethod ( CloudConfigStorage * storageMethod )

inline

Sets the storage method class, required before setup() is called.

Parameters

storageMethod The CloudConfigStorage subclass instance to use to store and retrieve the data

Returns: Returns *this so you can chain together the withXXX() methods, fluent-style.

There can only be one storage method, and once set, cannot be changed or removed.

◆ withUpdateFrequency() [1/2]

CloudConfig& CloudConfig::withUpdateFrequency ( long updateFrequency )

inline

Sets the update frequency in seconds.

Parameters

updateFrequency update frequency in seconds

Returns: Returns *this so you can chain together the withXXX() methods, fluent-style.

See also the overload that takes a chrono literal, as well as withUpdateFrequencyOnce() and withUpdateFrequencyAtRestart().

Can be called after setup to change the update frequency.

◆ withUpdateFrequency() [2/2]

CloudConfig& CloudConfig::withUpdateFrequency ( std::chrono::seconds chronoLiteral )

inline

Sets the update frequency as a chrono literal.

Parameters

chronoLiteral update frequency as a chrono literal. For example: 15min (15 minutes) or 24h (24 hours).

Returns: Returns *this so you can chain together the withXXX() methods, fluent-style.

Can be called after setup to change the update frequency.

◆ withUpdateFrequencyAtRestart()

CloudConfig& CloudConfig::withUpdateFrequencyAtRestart ( )

inline

Sets the update frequency to update once after cloud connecting after restart.

Returns: Returns *this so you can chain together the withXXX() methods, fluent-style.

This is anything that calls setup() so includes device reset and wake from HIBERNATE sleep mode.

Should be done before setup() to make sure it takes effect in time.

◆ withUpdateFrequencyOnce()

CloudConfig& CloudConfig::withUpdateFrequencyOnce ( )

inline

Sets the update frequency only if there is no saved value.

Returns: Returns *this so you can chain together the withXXX() methods, fluent-style.

If there is no saved value, then the update occurs after connecting to the cloud.

Should be done before setup() to make sure it takes effect in time.

◆ withUpdateMethod()

CloudConfig& CloudConfig::withUpdateMethod ( CloudConfigUpdate * updateMethod )

inline

Sets the update method class, not required, but if used, call before setup() is called.

Parameters

updateMethod The CloudConfigUpdate subclass instance to use to get data from the cloud

Returns: Returns *this so you can chain together the withXXX() methods, fluent-style.

There can only be one update method, and once set, cannot be changed or removed.

Field Documentation

◆ dataCallback

std::function<void(void)> CloudConfig::dataCallback = 0

protected

Callback to call when there is data.

This is called either at startup, if data is located from the storage method and is valid, or after data is updated from the cloud. For some storage methods like function or subscription, this can also be called spontaneously when the cloud-side sends new configuration data.

◆ UPDATE_AT_RESTART

const long CloudConfig::UPDATE_AT_RESTART = -1

static

Value used for updateFrequency to request configuration data on every restart.

Note that this also means after every HIBERNATE sleep wake!

◆ updateDataStatus

UpdateDataStatus CloudConfig::updateDataStatus = UpdateDataStatus::IDLE

protected

Status of updateData. Used when in stateWaitUpdateComplete.

The updateData() and updateDataFailed() methods change this value.

◆ updateFrequency

long CloudConfig::updateFrequency = 0

protected

How often to update the data from the cloud.

Values > 0 are in seconds. There are also two special values: UPDATE_ONCE (0) and UPDATE_AT_RESTART (-1);

Normally you use the withUpdateFrequency() methods to set this.

The documentation for this class was generated from the following files:

src/CloudConfigRK.h
src/CloudConfigRK.cpp

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ UpdateDataStatus

Constructor & Destructor Documentation

◆ CloudConfig()

Member Function Documentation

◆ getBool()

◆ getDouble()

◆ getInt()

◆ getJSONValue()

◆ getJSONValueAtIndex() [1/2]

◆ getJSONValueAtIndex() [2/2]

◆ getJSONValueForKey() [1/2]

◆ getJSONValueForKey() [2/2]

◆ getString()

◆ instance()

◆ stateStart()

◆ stateStartUpdate()

◆ stateWaitAfterCloudConnected()

◆ stateWaitCloudConnected()

◆ stateWaitToUpdate()

◆ stateWaitUpdateComplete()

◆ updateData()

◆ updateDataFailed()

◆ withDataCallback()

◆ withStorageMethod()

◆ withUpdateFrequency() [1/2]

◆ withUpdateFrequency() [2/2]

◆ withUpdateFrequencyAtRestart()

◆ withUpdateFrequencyOnce()

◆ withUpdateMethod()

Field Documentation

◆ dataCallback

◆ UPDATE_AT_RESTART

◆ updateDataStatus

◆ updateFrequency