shared_offline.h File Reference

Detailed Description

This library allows multiple application modules to control the NRLS feature of the stack at the same time without conflicts. Ie, when the stack can freely disconnect from the network and enter offline mode. The purpose of this mode is to save energy.

Note

Switching too often between online and offline mode may have the opposite desired effect. In fact, each time a node will be back in online mode, it will trigger a scan and consume additional power.

This library can only be used if node role is non-router. Otherwise it will have no effect.

Definition in file shared_offline.h.

Go to the source code of this file.

Typedefs
typedef void(*	offline_cb_f) (uint32_t delay_s)
	Offline callback called when the node enter offline state It means that all the module are ready to enter offline mode. More...
typedef void(*	online_cb_f) (uint32_t delay_from_deadline_s)
	Online callback called when the node enter online state. More...

Functions
shared_offline_res_e	Shared_Offline_init (void)
	Initialize shared offline module. More...
shared_offline_res_e	Shared_Offline_register (uint8_t *id_p, offline_setting_conf_t cbs)
	Register to offline share lib It is required to take part of the offline arbitration. More...
shared_offline_res_e	Shared_Offline_unregister (uint8_t id_p)
	Unregister from offline share lib Once done, you will not be notified anymore for online/offline event. More...
shared_offline_res_e	Shared_Offline_enter_offline_state (uint8_t id, uint32_t delay_s)
	Call to asynchronously enter in offline state. More...
shared_offline_res_e	Shared_Offline_enter_online_state (uint8_t id)
	Call to asynchronously enter in online state. More...
shared_offline_status_e	Shared_Offline_get_status (uint32_t *elapsed_s_p, uint32_t *remaining_s_p)
	Get the current status. More...

Data Structures
struct	offline_setting_conf_t

Enumerations
enum	shared_offline_res_e {   SHARED_OFFLINE_RES_OK = 0, SHARED_OFFLINE_RES_NO_MORE_ROOM = 1, SHARED_OFFLINE_RES_WRONG_ID = 2, SHARED_OFFLINE_RES_UNINITIALIZED = 3,   SHARED_OFFLINE_RES_ALREADY_ONLINE = 4, SHARED_OFFLINE_RES_WRONG_ROLE = 5 }
	List of return code. More...
enum	shared_offline_status_e { SHARED_OFFLINE_STATUS_OFFLINE = 0, SHARED_OFFLINE_STATUS_ONLINE = 1, SHARED_OFFLINE_STATUS_UNINITIALIZED = 3 }
	Offline state. More...

Macros
#define	SHARED_OFFLINE_INFINITE_DELAY   (uint32_t)(-1)

Typedef Documentation

offline_cb_f

typedef void(* offline_cb_f) (uint32_t delay_s)

Offline callback called when the node enter offline state It means that all the module are ready to enter offline mode.

Parameters

delay_s

Delay the node will stay offline if none of the registered module ask to enter online state asynchronously

Definition at line 70 of file shared_offline.h.

online_cb_f

typedef void(* online_cb_f) (uint32_t delay_from_deadline_s)

Online callback called when the node enter online state.

Parameters

delay_from_deadline_s

Delay in second per module relative to the initially requested time. If two registered modules M1 and M2 ask at the same time to stay offline for 3600 and 4000 seconds respectively, this variable will be set at 0 for M1 and 400 for M2. In fact online event happens 400s before initial M2 online request time.

Note

It is the responsibility of each registered module to ask for entering in offline state again by calling Shared_Offline_enter_offline_state. The call can be made directly from this callback.

For power consumption optimization, each module should try (if possible) to move forward their network activity (like sending a status) if their deadline is close, instead of asking to go offline for very short period.

on_online_event will be called at the latest when the deadline of the module to be online is reached. It can be called earlier if someone else has requested the online state earlier but it will never be called later.

Definition at line 93 of file shared_offline.h.

Function Documentation

Shared_Offline_enter_offline_state()

shared_offline_res_e Shared_Offline_enter_offline_state	(	uint8_t	id,
		uint32_t	delay_s
	)

Call to asynchronously enter in offline state.

Parameters

id	Id of the module asking for offline state
delay_s	Maximum delay in s to stay offline

Returns

Return code of the operation

Shared_Offline_enter_online_state()

shared_offline_res_e Shared_Offline_enter_online_state

(

uint8_t

id

)

Call to asynchronously enter in online state.

Parameters

id	Id of the module asking for online state

Returns

Return code of the operation

Shared_Offline_get_status()

shared_offline_status_e Shared_Offline_get_status	(	uint32_t *	elapsed_s_p,
		uint32_t *	remaining_s_p
	)

Get the current status.

Parameters

elapsed_s_p	Pointer to get the time in s already elapsed in the current state Can be NULL if caller is not interested by the info.
remaining_s_p	Pointer to get the time in s remaining in this state if no other event happens. Can be NULL if caller is not interested by the info.

Returns

Return code of the operation

Shared_Offline_init()

shared_offline_res_e Shared_Offline_init

(

void

)

Initialize shared offline module.

Note

If this library is used in application, the nrls stack library MUST NOT be used outside of this module

Shared_Offline_register()

shared_offline_res_e Shared_Offline_register	(	uint8_t *	id_p,
		offline_setting_conf_t	cbs
	)

Register to offline share lib It is required to take part of the offline arbitration.

Parameters

id_p	Pointer to store the id assigned to the module
cbs	Callbacks for module event

Returns

Return code of the operation

Shared_Offline_unregister()

shared_offline_res_e Shared_Offline_unregister

(

uint8_t

id_p

)

Unregister from offline share lib Once done, you will not be notified anymore for online/offline event.

Parameters

id_p	Pointer to store the id assigned to the module

Returns

Return code of the operation

---

Data Structure Documentation

offline_setting_conf_t

struct offline_setting_conf_t

Definition at line 95 of file shared_offline.h.

Data Fields
offline_cb_f	on_offline_event
online_cb_f	on_online_event

Enumeration Type Documentation

shared_offline_res_e

enum shared_offline_res_e

List of return code.

Enumerator
SHARED_OFFLINE_RES_OK	Operation is successful
SHARED_OFFLINE_RES_NO_MORE_ROOM	No more tasks available
SHARED_OFFLINE_RES_WRONG_ID	Wrong id
SHARED_OFFLINE_RES_UNINITIALIZED
SHARED_OFFLINE_RES_ALREADY_ONLINE
SHARED_OFFLINE_RES_WRONG_ROLE

Definition at line 32 of file shared_offline.h.

{
    SHARED_OFFLINE_RES_OK = 0,
    SHARED_OFFLINE_RES_NO_MORE_ROOM = 1,
    SHARED_OFFLINE_RES_WRONG_ID = 2,
    /* Module is not initialized */
    SHARED_OFFLINE_RES_UNINITIALIZED = 3,
    /* Stack is already online */
    SHARED_OFFLINE_RES_ALREADY_ONLINE = 4,
    /* Role is wrong to enter offline */
    SHARED_OFFLINE_RES_WRONG_ROLE = 5
} shared_offline_res_e;

shared_offline_status_e

enum shared_offline_status_e

Offline state.

Enumerator
SHARED_OFFLINE_STATUS_OFFLINE	Operation is successful
SHARED_OFFLINE_STATUS_ONLINE	No more tasks available
SHARED_OFFLINE_STATUS_UNINITIALIZED

Definition at line 51 of file shared_offline.h.

{
    SHARED_OFFLINE_STATUS_OFFLINE = 0,
    SHARED_OFFLINE_STATUS_ONLINE = 1,
    /* Module is not initialized */
    SHARED_OFFLINE_STATUS_UNINITIALIZED = 3,
} shared_offline_status_e;

Macro Definition Documentation

SHARED_OFFLINE_INFINITE_DELAY

#define SHARED_OFFLINE_INFINITE_DELAY   (uint32_t)(-1)

Definition at line 61 of file shared_offline.h.