wms_sleep.h File Reference

Detailed Description

The Non-Router Long Sleep (NRLS) Library is used to sleep Wirepas Mesh stack for time periods. Once waking-up from the sleep, Wirepas Mesh stack wakes up from the sleep without system reset. During Wirepas Mesh stack sleep, Single-MCU application can be running using the libraries which does not have dependency to Wirepas Mesh stack functionalities. Before entering to NRLS sleep, Wirepas Mesh stack needs to be running.

Non-Router Long Sleep libraries can be used with Wirepas Mesh stack which is configured to be running as Non-Router mode without any role extensions (APP_LIB_SETTINGS_ROLE_SUBNODE in app_lib_settings_base_role_e and APP_LIB_SETTINGS_ROLE_FLAG_RESV in app_lib_settings_flag_role_e). Any other app_lib_settings_base_role_e and app_lib_settings_flag_role_e definitions do not allow to use NRLS functionality.

Library services are accessed via lib_sleep handle.

Definition in file wms_sleep.h.

Go to the source code of this file.

Typedefs
typedef app_res_e(*	app_lib_sleep_stack_for_time_f) (uint32_t seconds, uint32_t appconf_wait_s)
	Start stack sleeping period for a given time. More...
typedef app_res_e(*	app_lib_sleep_wakeup_stack_f) (void)
	Wakeup stack from sleep. More...
typedef app_lib_sleep_stack_state_e(*	app_lib_sleep_get_sleep_state_f) (void)
	Get sleep state of stack. More...
typedef uint32_t(*	app_lib_sleep_get_wakeup_f) (void)
	Returns remaining sleep time in seconds. More...
typedef void(*	applib_wakeup_callback_f) (void)
	Callback called before stack wakes up. More...
typedef void(*	app_lib_sleep_wakeup_callback_f) (applib_wakeup_callback_f callback)
	Set callback function to be called before stack wakes up. More...
typedef uint32_t(*	app_lib_sleep_get_gotosleep) (void)
	Get latest time used before stack enters to sleep after NRLS sleep request given. More...
typedef void(*	applib_on_sleep_callback_f) (void)
	Callback called when stack starts sleep. More...
typedef void(*	app_lib_sleep_on_sleep_callback_f) (applib_on_sleep_callback_f callback)
	Set callback function to be called when stack starts sleep. More...

Data Structures
struct	app_lib_sleep_t
	List of library functions. More...

Enumerations
enum	app_lib_sleep_stack_state_e { APP_LIB_SLEEP_STOPPED = 0, APP_LIB_SLEEP_STARTED, APP_LIB_SLEEP_PENDING }
	Stack state flags. More...

Macros
#define	APP_LIB_LONGSLEEP_NAME   0x02f20818
	Library symbolic name. More...
#define	APP_LIB_LONGSLEEP_VERSION   0x203
	Maximum supported library version. More...

Typedef Documentation

app_lib_sleep_get_gotosleep

typedef uint32_t(* app_lib_sleep_get_gotosleep) (void)

Get latest time used before stack enters to sleep after NRLS sleep request given.

Returns time in seconds which was used in previous NRLS sleep request starting from application request lib_sleep->sleepStackforTime() until stack enters to NRLS sleep (i.e. device has disconnected from the network). This value may be used to estimate needed parameter configuration for appconf_wait_s in lib_sleep->sleepStackforTime() function.

Returns

Total time used including application callback during that period in seconds

Definition at line 154 of file wms_sleep.h.

app_lib_sleep_get_sleep_state_f

typedef app_lib_sleep_stack_state_e(* app_lib_sleep_get_sleep_state_f) (void)

Get sleep state of stack.

Returns

State of the sleep operation

Definition at line 114 of file wms_sleep.h.

app_lib_sleep_get_wakeup_f

typedef uint32_t(* app_lib_sleep_get_wakeup_f) (void)

Returns remaining sleep time in seconds.

Returns

Remaining sleep time in seconds. 0 if no sleep ongoing.

Definition at line 121 of file wms_sleep.h.

app_lib_sleep_on_sleep_callback_f

typedef void(* app_lib_sleep_on_sleep_callback_f) (applib_on_sleep_callback_f callback)

Set callback function to be called when stack starts sleep.

Parameters

callback

The callback function to set

Definition at line 171 of file wms_sleep.h.

app_lib_sleep_stack_for_time_f

typedef app_res_e(* app_lib_sleep_stack_for_time_f) (uint32_t seconds, uint32_t appconf_wait_s)

Start stack sleeping period for a given time.

Parameters

seconds	Wake up time. Device will wake up after this many seconds. Sleep starts when node has disconnected from Mesh network. If set to 0 - there is APP_RES_INVALID_VALUE response and sleep is not started.
appconf_wait_s	Maximum wait time in seconds to wait for app config data from network before NRLS stack sleep. If device has already acquired app config, this argument has no impact. 0 = App config is not awaited before going to sleep. Other values = Time used to wait that app config data is received from network. Minimum allowed value is 4 seconds and maximum 600 seconds.

Returns

APP_RES_INVALID_CONFIGURATION if node role is not correctly configured. Returns APP_RES_INVALID_VALUE if seconds exceeds the maximum value or appconf_wait_s is illegal value. Returns APP_RES_INVALID_STACK_STATE if stack is not started and node role and seconds is correct. Otherwisereturns APP_RES_OK when sleep process is started.

Note

If the time when waking up from NRLS sleep and going back to NRLS sleep is very short and app config is used to signal to the network e.g. overhaul state, good practice is to have appconf_wait_s long enough (minimum 4 seconds) to make sure that app config data is received before going to NRLS sleep

Sleep starts when device has disconnected to network. In addition to appconfig wait (if desired by appconf_wait_s), there may be additional delay up to 40 seconds before sleep actually starts. If device has not yet connected to network, this is not happening.

Definition at line 89 of file wms_sleep.h.

app_lib_sleep_wakeup_callback_f

typedef void(* app_lib_sleep_wakeup_callback_f) (applib_wakeup_callback_f callback)

Set callback function to be called before stack wakes up.

Parameters

callback

The callback function to set

Definition at line 138 of file wms_sleep.h.

app_lib_sleep_wakeup_stack_f

typedef app_res_e(* app_lib_sleep_wakeup_stack_f) (void)

Wakeup stack from sleep.

Starts the stack from sleep if application wants to wake-up the stack from NRLS sleep before NRLS sleep time has elapsed.

Returns

APP_RES_OK when stack wakeup is started from sleep. Returns APP_RES_INVALID_STACK_STATE if wakeup called when stack is running.

Note

If sleep process has started but sleep is not yet started (i.e. service lib_sleep->sleepStackforTime() has called but device has not yet disconnected from the network, wakeup occurs immediately after disconnction of network has happened.

Definition at line 108 of file wms_sleep.h.

applib_on_sleep_callback_f

typedef void(* applib_on_sleep_callback_f) (void)

Callback called when stack starts sleep.

Used with lib_sleep->setOnsleepCb() service

Definition at line 162 of file wms_sleep.h.

applib_wakeup_callback_f

typedef void(* applib_wakeup_callback_f) (void)

Callback called before stack wakes up.

Used with lib_sleep->setOnWakeupCb() service

Definition at line 129 of file wms_sleep.h.

---

Data Structure Documentation

app_lib_sleep_t

struct app_lib_sleep_t

List of library functions.

Definition at line 178 of file wms_sleep.h.

Data Fields
app_lib_sleep_get_gotosleep	getSleepLatestGotosleep
app_lib_sleep_get_sleep_state_f	getSleepState
app_lib_sleep_get_wakeup_f	getStackWakeup
app_lib_sleep_on_sleep_callback_f	setOnSleepCb
app_lib_sleep_wakeup_callback_f	setOnWakeupCb
app_lib_sleep_stack_for_time_f	sleepStackforTime
app_lib_sleep_wakeup_stack_f	wakeupStack

Enumeration Type Documentation

app_lib_sleep_stack_state_e

enum app_lib_sleep_stack_state_e

Stack state flags.

Enumerator
APP_LIB_SLEEP_STOPPED
APP_LIB_SLEEP_STARTED
APP_LIB_SLEEP_PENDING

Definition at line 47 of file wms_sleep.h.

{
    // @brief No sleep ongoing
    APP_LIB_SLEEP_STOPPED = 0,
    // @brief Sleep is started
    APP_LIB_SLEEP_STARTED,
    // @brief Sleep is pending, i.e. requested but device has not yet
    // disconnected from the network
    APP_LIB_SLEEP_PENDING,
} app_lib_sleep_stack_state_e;

Macro Definition Documentation

APP_LIB_LONGSLEEP_NAME

#define APP_LIB_LONGSLEEP_NAME   0x02f20818

Library symbolic name.

"SLEEP"

Definition at line 39 of file wms_sleep.h.

APP_LIB_LONGSLEEP_VERSION

#define APP_LIB_LONGSLEEP_VERSION   0x203

Maximum supported library version.

Definition at line 42 of file wms_sleep.h.