SleepHelper
Functions
Callback functions you can register

Functions

SleepHelperSleepHelper::withSleepConfigurationFunction (std::function< bool(SystemSleepConfiguration &, SleepConfigurationParameters &)> fn)
 Register a function to be called to configure sleep. More...
 
SleepHelperSleepHelper::withWakeFunction (std::function< bool(const SystemSleepResult &)> fn)
 Register a function to be called on wake from sleep. More...
 
SleepHelperSleepHelper::withSetupFunction (std::function< bool()> fn)
 Adds a function to be called during setup() More...
 
SleepHelperSleepHelper::withLoopFunction (std::function< bool()> fn)
 Adds a function to be called on every call to loop() More...
 
SleepHelperSleepHelper::withDataCaptureFunction (std::function< bool(AppCallbackState &state)> fn)
 The data capture function is called on a schedule to capture data. More...
 
SleepHelperSleepHelper::withSleepReadyFunction (std::function< bool(AppCallbackState &, system_tick_t)> fn)
 Determine if it's OK to sleep now, when in connected state. More...
 
SleepHelperSleepHelper::withShouldConnectFunction (std::function< bool(int &connectConviction, int &noConnectConviction)> fn)
 Function to call to determine if a full wake should be done. More...
 
SleepHelperSleepHelper::withWakeOrBootFunction (std::function< bool(int)> fn)
 Called during setup, after sleep, or an aborted sleep because duration was too short. More...
 
SleepHelperSleepHelper::withSleepOrResetFunction (std::function< bool(bool)> fn)
 Adds a function to be called right before sleep or reset. More...
 
SleepHelperSleepHelper::withMaximumTimeToConnectFunction (std::function< bool(system_tick_t ms)> fn)
 Adds a function to be called while connecting. More...
 
SleepHelperSleepHelper::withNoConnectionFunction (std::function< bool(AppCallbackState &state)> fn)
 Register a callback for when in the no connection state. More...
 

Detailed Description

Function Documentation

◆ withDataCaptureFunction()

SleepHelper & SleepHelper::withDataCaptureFunction ( std::function< bool(AppCallbackState &state)>  fn)
inline

The data capture function is called on a schedule to capture data.

Parameters
fnCallback function or C++11 lambda to call.
Returns
SleepHelper&

The callback has this prototype

bool callback()

Return true if you need to be called back to finish capturing data

Return false if you are done capturing data.

This callback is called for quick wake, full wake, and while connected. It runs in a parallel state machine to the connection state machine.

◆ withLoopFunction()

SleepHelper & SleepHelper::withLoopFunction ( std::function< bool()>  fn)
inline

Adds a function to be called on every call to loop()

Parameters
fnCallback function or C++11 lambda to call.
Returns
SleepHelper&

You will normally register a more specific function, such as a data capture function, no connect function, etc. but this function is provided just in case.

◆ withMaximumTimeToConnectFunction()

SleepHelper & SleepHelper::withMaximumTimeToConnectFunction ( std::function< bool(system_tick_t ms)>  fn)
inline

Adds a function to be called while connecting.

Parameters
fn
Returns
SleepHelper&

Function or lambda prototype:

bool callback(system_tick_t ms)

Return true to continue attempting to connect. Return false to stop trying to connect and go to sleep.

All maximum time to connect functions are called on every loop call during the connecting phase, until one return false. This provides a way to be called periodically during connection.

◆ withNoConnectionFunction()

SleepHelper & SleepHelper::withNoConnectionFunction ( std::function< bool(AppCallbackState &state)>  fn)
inline

Register a callback for when in the no connection state.

If the should connect handlers indicate that a cloud connection should not be attempted, for example if we're in a situation we wake briefly to sample a sensor but want to aggregate values before connecting to the cloud to avoid connecting too frequently, then the no connect handler provides time for your application to do thing before going to sleep. If you return true from your callback, then the device will continue to stay awake.

If you want to be called while connected, see the sleepReady function which does double duty as the whileConnected function.

Parameters
fn
Returns
SleepHelper&

◆ withSetupFunction()

SleepHelper & SleepHelper::withSetupFunction ( std::function< bool()>  fn)
inline

Adds a function to be called during setup()

Parameters
fnCallback function or C++11 lambda to call.
Returns
SleepHelper&

You must register this callback before actually calling setup() for obvious reasons. You will probably never need to use this, but it exists just in case.

◆ withShouldConnectFunction()

SleepHelper & SleepHelper::withShouldConnectFunction ( std::function< bool(int &connectConviction, int &noConnectConviction)>  fn)
inline

Function to call to determine if a full wake should be done.

Parameters
fnCallback function or C++11 lambda to call.
Returns
SleepHelper&

The callback has the prototype:

bool callback(int &connectConviction, int &noConnectConviction)

If the callback believes a connection should be made, the connectConviction should be set to a value from 1 to 100. A typical value would be 60. This would encourage connection but still could be overridden for other reasons, such as insufficient battery power.

If the callback believes a connection should not be made, it sets noConnectConviction to a value from 1 to 100, 100 being definitely do not connect.

If the highest connection conviction is greater than the highest no connection conviction, then a connection will be attempted.

Your function should return true in all cases.

◆ withSleepConfigurationFunction()

SleepHelper & SleepHelper::withSleepConfigurationFunction ( std::function< bool(SystemSleepConfiguration &, SleepConfigurationParameters &)>  fn)
inline

Register a function to be called to configure sleep.

Parameters
fnCallback function or C++11 lambda to call.
Returns
SleepHelper&

The callback function has the prototype:

bool callback(SystemSleepConfiguration &sleepConfiguration, SleepConfigurationParameters &sleepParameters)

  • sleepConfiguration is the object that is passed to System.sleep() you can refer to this or modify it, however some parameters like duration should be set via the sleepParameters.
  • sleepParameters include both informational fields (like whether you're currently connected to cellular) as well as fields you can change to modify the sleep behavior.

◆ withSleepOrResetFunction()

SleepHelper & SleepHelper::withSleepOrResetFunction ( std::function< bool(bool)>  fn)
inline

Adds a function to be called right before sleep or reset.

Parameters
fnA function or lambda to call. The bool result is ignored.
Returns
SleepHelper&

It's common to put code to power down peripherals and stop an external hardware watchdog. This should only be used for quick operations. You will already be disconnected from the cloud and network when this function is called. You cannot stop the reset or sleep process from this callback.

The order of callbacks is sleepOrReset, sleepConfiguration, then the device goes to sleep. When the device wakes, the wake callback is called.

◆ withSleepReadyFunction()

SleepHelper & SleepHelper::withSleepReadyFunction ( std::function< bool(AppCallbackState &, system_tick_t)>  fn)
inline

Determine if it's OK to sleep now, when in connected state.

Parameters
fnCallback function or C++11 lambda to call.
Returns
SleepHelper&

The sleep ready function prototype is:

bool callback(AppCallbackState &state, system_tick_t connecteTimeMs)

Return false if your situation is OK to sleep now. This does not guaranteed that sleep will actually occur, because there can be many sleep ready functions and other calculations. Once you return false your callback will no longe be called until the next wake cycle.

Return true if you still have things to do before it's OK to sleep. You callback will continue to be called until it returns false.

◆ withWakeFunction()

SleepHelper & SleepHelper::withWakeFunction ( std::function< bool(const SystemSleepResult &)>  fn)
inline

Register a function to be called on wake from sleep.

Parameters
fnCallback function or C++11 lambda to call.
Returns
SleepHelper&

The wake function has the prototype:

bool callback(const SystemSleepResult &sleepResult);

  • sleepResult is a const reference to the SystemSleepResult that was obtained right after wake.

You should return true in all cases from your callback.

◆ withWakeOrBootFunction()

SleepHelper & SleepHelper::withWakeOrBootFunction ( std::function< bool(int)>  fn)
inline

Called during setup, after sleep, or an aborted sleep because duration was too short.

Parameters
fn
Returns
SleepHelper&
  • WAKEUP_REASON_SETUP Called from setup after cold boot or reset
  • WAKEUP_REASON_NO_SLEEP Called after sleep aborted as it was too short
  • Any result code from for SystemSleepWakeupReason, such as:
    • SystemSleepWakeupReason::BY_GPIO
    • SystemSleepWakeupReason::BY_ADC
    • SystemSleepWakeupReason::BY_RTC
    • SystemSleepWakeupReason::BY_BLE
    • SystemSleepWakeupReason::BY_NETWORK