DeviceGroupHelper Class Reference

Helper class to use device groups on a Particle device. More...

#include <DeviceGroupHelperRK.h>

Public Types
enum	RetrievalMode { RetrievalMode::MANUAL, RetrievalMode::AT_START, RetrievalMode::PERIODIC }
	How often to retrieve device groups. More...
enum	NotificationType { NotificationType::UPDATED, NotificationType::ADDED, NotificationType::REMOVED }
	Used for the notify callback to specify what is being notified of. More...

Public Member Functions
DeviceGroupHelper &	withEventName (const char *eventName)
	Specify the name of the event used to get the device group. Must match integration. More...
const char *	getEventName () const
	Gets the event name to use for the webhook.
DeviceGroupHelper &	withRetrievalModeManual ()
	Sets manual retrieval mode. This is the default mode. More...
DeviceGroupHelper &	withRetrievalModeAtStart ()
	Sets retrieve groups at start mode. This should be done before setup().
DeviceGroupHelper &	withRetrievalModePeriodic (unsigned long ms)
	Sets retrieve groups at start mode and periodically mode. This should be done before setup(). More...
DeviceGroupHelper &	withRetrievalModePeriodic (std::chrono::milliseconds chronoLiteral)
	Sets retrieve groups at start mode and periodically mode. This should be done before setup(). More...
DeviceGroupHelper &	withRetrievalMode (RetrievalMode retrievalMode)
	Sets the retrieve mode using RetrievalMode value.
RetrievalMode	getRetrievalMode () const
	Gets the current retrival mode (how often to fetch group membership)
DeviceGroupHelper &	withPeriodicTimeMs (unsigned long ms)
	Sets the periodic time to check when in RetrivalMode::PERIODIC. More...
unsigned long	getPeriodicTimeMs () const
	Gets the periodic time to check in milliseconds.
DeviceGroupHelper &	withNotifyCallback (std::function< void(NotificationType, const char *)> notifyCallback)
	Sets a function to be called when the group list is updated. More...
void	setup ()
	You must call setup() from global application setup()! More...
void	loop ()
	You must call loop() from global application loop()! More...
const std::unordered_set< std::string >	getGroups () const
	Gets the set of all groups the device current belongs to. More...
bool	retrievedGroups () const
	Returns true if the group list has been retrieved.
bool	isInGroup (const char *group) const
	Returns true if this device belongs to the specified group. More...
void	update ()
	Requests an update of the group list. More...

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

Protected Member Functions
	DeviceGroupHelper ()
	Constructor (protected) More...
virtual	~DeviceGroupHelper ()
	Destructor - never used. More...
	DeviceGroupHelper (const DeviceGroupHelper &)=delete
	This class is not copyable.
DeviceGroupHelper &	operator= (const DeviceGroupHelper &)=delete
	This class is not copyable.
void	stateWaitConnected ()
	State handler, waits for Particle.connected() then publishes the request event. More...
void	stateWaitResponse ()
	State handler, waits for the subscription handler to be called. More...
void	stateWaitPeriodic ()
	State handler to wait for the next periodic check, or go into idle state (0) More...
void	stateWaitRetry ()
	State handler for waiting to retry after the subscribe handler was not called. More...
void	subscriptionHandler (const char *event, const char *data)
	Subscription handler to receive webhook responses.

Protected Attributes
String	eventName = "G52ES20Q_DeviceGroup"
	Event name, set with withEventName(). This must match the webhook.
RetrievalMode	retrievalMode = RetrievalMode::MANUAL
	How often to retrieve the group membership data.
unsigned long	periodicTimeMs = 0
	When in RetrievalMode::PERIODIC, how often to check in milliseconds.
std::function< void(DeviceGroupHelper &)>	stateHandler = 0
	State handler function. Can be NULL.
unsigned long	stateTime = 0
	Millis value for timing in some states.
std::unordered_set< std::string >	groups
	Groups this device belongs to.
unsigned long	groupUpdateTime = 0
	Millis value when the group list was last updated, or 0 for not updated.
bool	isIdle = true
	stateHandler is idle and update() can push it into stateWaitConnected to update list
std::chrono::milliseconds	groupResponseTimeout = 30s
	How long to wait for the webhook response.
std::chrono::milliseconds	retryTimeout = 2min
	How long to wait to retry after a failed webhook response.
std::function< void(NotificationType, const char *)>	notifyCallback = 0
	Callback function for when group membership is updated.

Static Protected Attributes
static DeviceGroupHelper *	_instance = 0
	Singleton instance of this class.

Detailed Description

Helper class to use device groups on a Particle device.

This is useful when you have a product and are using the device groups feature. Normally, use this to group related devices and control firmware releases. However, you can use this technique to read the device groups on-device, which would allow you to make decisions in device firmware based on group membership.

You can choose when to update groups (manually, at startup, or periodically).

You can then either query whether the device is in a specific group using the previously cached group list. This is fast and does not require network access so you can use it in your code liberally.

Or, if you prefer, you can register a notification function that will call your function with an indication that the list was updated, and when individual groups are added or removed from the previous retrieval.

Member Enumeration Documentation

NotificationType

enum DeviceGroupHelper::NotificationType

strong

Used for the notify callback to specify what is being notified of.

Enumerator
UPDATED	The groups were updated. Use getGroups() to get a set of all group names.
ADDED	This group was added.
REMOVED	This group was removed.

RetrievalMode

enum DeviceGroupHelper::RetrievalMode

strong

How often to retrieve device groups.

Enumerator
MANUAL	Manually (default)
AT_START	At startup (once)
PERIODIC	At startup, then periodically thereafter.

Constructor & Destructor Documentation

DeviceGroupHelper()

DeviceGroupHelper::DeviceGroupHelper ( )

protected

Constructor (protected)

You never construct one of these - use the singleton instance using DeviceGroupHelper::instance().

~DeviceGroupHelper()

DeviceGroupHelper::~DeviceGroupHelper ( )

protectedvirtual

Destructor - never used.

The singleton cannot be deleted.

Member Function Documentation

getGroups()

const std::unordered_set<std::string> DeviceGroupHelper::getGroups ( ) const

inline

Gets the set of all groups the device current belongs to.

This uses the previously retrieved list. This is fast and does not use the network.

To iterate the group list, you can use something like this:

auto groups = DeviceGroupHelper::instance().getGroups();
for(auto it = groups.begin(); it != groups.end(); it++) {
    Log.info("group %s", (*it).c_str());
}

isInGroup()

bool DeviceGroupHelper::isInGroup ( const char *  group ) const

inline

Returns true if this device belongs to the specified group.

Parameters

group

The group name to check.

You can use the notifyCallback to be notified of group changes instead of polling for it using this function.

This uses the previously retrieved list. This is fast and does not use the network.

loop()

void DeviceGroupHelper::loop

(

)

You must call loop() from global application loop()!

It's normally done like:

DeviceGroupHelper::instance().loop();

Failure to call loop will prevent the library from doing anything.

setup()

void DeviceGroupHelper::setup

(

)

You must call setup() from global application setup()!

It's normally done like:

DeviceGroupHelper::instance().setup();

Failure to call setup will prevent the library from doing anything.

stateWaitConnected()

void DeviceGroupHelper::stateWaitConnected ( )

protected

State handler, waits for Particle.connected() then publishes the request event.

Previous state: 0, stateWaitRetry, stateWaitPeriodic Next state: stateWaitResponse

stateWaitPeriodic()

void DeviceGroupHelper::stateWaitPeriodic ( )

protected

State handler to wait for the next periodic check, or go into idle state (0)

Previous state: stateWaitResponse Next state: 0 or stateWaitConnected

stateWaitResponse()

void DeviceGroupHelper::stateWaitResponse ( )

protected

State handler, waits for the subscription handler to be called.

Previous state: stateWaitConnected Next state: stateWaitRetry, stateWaitPeriodic

stateWaitRetry()

void DeviceGroupHelper::stateWaitRetry ( )

protected

State handler for waiting to retry after the subscribe handler was not called.

Previous state: stateWaitResponse Next state: stateWaitConnected

update()

void DeviceGroupHelper::update

(

)

Requests an update of the group list.

If the retrieval mode is PERIODIC, then this retrieves now and shifts the next check to be periodicTimeMs from now instead of the originally scheduled time.

Updates usually only take a second or so, but if there is poor network connectivity it could take longer, up to 30 seconds. It could also fail.

retrievedGroups() will return false immediately after calling update() and then will become try again if the operation succeeds.

If the notification callback is used, that will notify of any changes in group membership.

withEventName()

DeviceGroupHelper& DeviceGroupHelper::withEventName ( const char *  eventName )

inline

Specify the name of the event used to get the device group. Must match integration.

Default is "G52ES20Q_DeviceGroup".

withNotifyCallback()

DeviceGroupHelper& DeviceGroupHelper::withNotifyCallback ( std::function< void(NotificationType, const char *)>  notifyCallback )

inline

Sets a function to be called when the group list is updated.

Parameters

notifyCallback

The function to call

You can only have one notifyCallback. To remove it, pass NULL.

The function has the prototype:

void callback(NotificationType notificationType, const char *group)

The notificationTypes is one of the constants:

• NotificationType::ADDED A group was added to this device
• NotificationType::REMOVED A group was removed from this device
• NotificationType::UPDATED The list was updated

The UPDATED notification is made after ADDED and REMOVED, and occurs even if no changes occurred. You can use getGroups or isInGroup() in the UPDATED callback. The group parameter is always NULL for the UPDATED notification.

The notifyCallback parameter is a std::function so it can also be a C++11 lambda instead of a plain function. This is an easy way to make the callback a member function of your class instead of a static member function.

withPeriodicTimeMs()

DeviceGroupHelper& DeviceGroupHelper::withPeriodicTimeMs ( unsigned long  ms )

inline

Sets the periodic time to check when in RetrivalMode::PERIODIC.

Parameters

ms	Check period in milliseconds

Using withRetrievalModePeriodic() may be more convenient than using withRetrievalMode(RetrivalMode::PERIODIC) and withPeriodicTimeMs().

withRetrievalModeManual()

DeviceGroupHelper& DeviceGroupHelper::withRetrievalModeManual ( )

inline

Sets manual retrieval mode. This is the default mode.

Normally called before setup() but you can change it later using this method for example if you want to stop periodically checking at runtime.

withRetrievalModePeriodic() [1/2]

DeviceGroupHelper& DeviceGroupHelper::withRetrievalModePeriodic ( std::chrono::milliseconds  chronoLiteral )

inline

Sets retrieve groups at start mode and periodically mode. This should be done before setup().

Parameters

chronoLiteral

Time between retrievals as a chrono literal, for example 15min or 24h.

You don't want to set this to be too short as each retrieve uses two data operations.

withRetrievalModePeriodic() [2/2]

DeviceGroupHelper& DeviceGroupHelper::withRetrievalModePeriodic ( unsigned long  ms )

inline

Sets retrieve groups at start mode and periodically mode. This should be done before setup().

Parameters

ms	The number of milliseconds between retrievals.

You don't want to set this to be too short as each retrieve uses two data operations.

---

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

• src/DeviceGroupHelperRK.h
• src/DeviceGroupHelperRK.cpp