Generic Level server behaviour

This module implements the behavioral requirements of the Generic Level server model. More...

Data Structures
struct	set_transition_t
	Internal structure for holding Set/Delta Set transition related variables. More...
struct	move_transition_t
	Internal structure for holding Move transition related variables. More...
struct	app_level_state_t
	Internal structure to hold state and timing information. More...
struct	app_level_server_t
	Application level structure holding the Level server model context and Level state representation. More...

Macros
#define	APP_LEVEL_SERVER_DEF(_name, _force_segmented, _mic_size, _p_dtt, _set_cb, _get_cb)
	Macro to create application level app_level_server_t context. More...

Typedefs
typedef void(*	app_level_set_cb_t) (const app_level_server_t *p_server, int16_t present_level)
	Application state set callback prototype. More...
typedef void(*	app_level_get_cb_t) (const app_level_server_t *p_server, int16_t *p_present_level)
	Application state read callback prototype. More...

Enumerations
enum	app_level_transition_type_t { TRANSITION_SET, TRANSITION_DELTA_SET, TRANSITION_MOVE_SET, TRANSITION_NONE }
	Transition types. More...

Functions
uint32_t	app_level_current_value_publish (app_level_server_t *p_server)
	Initiates value fetch from the user application by calling a get callback, updates internal state, and publishes the Generic Level Status message. More...
uint32_t	app_level_init (app_level_server_t *p_server, uint8_t element_index)
	Initializes the behavioral module for the Generic Level model. More...

Detailed Description

This module implements the behavioral requirements of the Generic Level server model.

You may customize this behaviour to fit your application requirements or hardware interfaces.

Note

This sample implementation manages the incremental changes in the level value and reports it to the example application to write to hardware interface (in this case, a PWM hardware).

This implementation assumes the application hardware can handle all range of level values. Necessary scaling required, if any, can be performed in the main application.

This implementation assumes the wrap around behavior for the level state.

Interaction with the user application happens through two callbacks: get_cb, set_cb

Additionally, user application must call app_level_current_value_publish() API whenever local action results in the change in present_level value.

The behavioral module will manage all the timing requirements internally (delay + transitions) and call the set_cb whenever it is time to change the level value. User application shall use the present_level value in the set cb to drive the necessary hardware. This behavioral interface will trigger large number of Set callbacks to report the changing present_level value, therefore user must not do time consuming operations inside the callback.

The smallest possible callback interval for a given transition time will be limited by MODEL_TIMER_TIMEOUT_MIN_TICKS.

This module will call the get_cb to fetch the present level value from the application.

Warning

To comply with the Mesh Model Specification test cases, the application must adhere to the requirements defined in the following sections:

• Section 3.1.2 (Generic Level) and Section 3.3.2.2 (Generic Level state behaviour) of Mesh Model Specification v1.0.
• Section 3.7.6.1 (Publish) of Mesh Profile Specification v1.0.

These requirements are documented at appropriate places in the module source code.

Macro Definition Documentation

APP_LEVEL_SERVER_DEF

#define APP_LEVEL_SERVER_DEF	(		_name,
			_force_segmented,
			_mic_size,
			_p_dtt,
			_set_cb,
			_get_cb
	)

Value:

APP_TIMER_DEF(_name ## _timer); \
 static app_level_server_t _name = \
 { \
 .server.settings.force_segmented = _force_segmented, \
 .server.settings.transmic_size = _mic_size, \
 .timer.p_timer_id = &_name ## _timer, \
 .p_dtt_ms = _p_dtt, \
 .level_set_cb = _set_cb, \
 .level_get_cb = _get_cb \
 };

Macro to create application level app_level_server_t context.

Individual timer instances are created for each model instance.

Parameters

[in]	_name	Name of the app_level_server_t instance
[in]	_force_segmented	If the Generic Level server shall use force segmentation of messages
[in]	_mic_size	MIC size to be used by Generic Level server
[in]	_p_dtt	Pointer to the default transition time state if present
[in]	_set_cb	Callback for setting the application state to given value.
[in]	_get_cb	Callback for reading the state from the application.

Definition at line 104 of file app_level.h.

Typedef Documentation

app_level_set_cb_t

typedef void(* app_level_set_cb_t) (const app_level_server_t *p_server, int16_t present_level)

Application state set callback prototype.

This callback is called by the this module whenever application is required to be informed to reflect the desired Level value, as a result of the received SET/DELTA SET/MOVE SET message, depending on the received Target Level value and timing parameters.

Note: Since the behavioral module encapsulates functionality required for the compliance with timing behaviour, it is not possible to infer number of Level messages received by the node by counting the number of times this callback is triggered. If such counting is required, it should be done in the app_level.c module.

Parameters

[in]	p_server	Pointer to __app_level_server_t [app_level_server_t] context
[in]	present_level	Instantaneous new level value to be used by the application

Definition at line 186 of file app_level.h.

app_level_get_cb_t

typedef void(* app_level_get_cb_t) (const app_level_server_t *p_server, int16_t *p_present_level)

Application state read callback prototype.

This callback is called by the app_level.c whenever application level state is required to be read.

Parameters

[in]	p_server	Pointer to __app_level_server_t [app_level_server_t] context
[out]	p_present_level	User application fills this value with the value retrived from the hardware interface.

Definition at line 196 of file app_level.h.

Enumeration Type Documentation

app_level_transition_type_t

enum app_level_transition_type_t

Transition types.

Enumerator
TRANSITION_SET	indicating SET message
TRANSITION_DELTA_SET	indicating DELTA SET message
TRANSITION_MOVE_SET	indicating MOVE SET message
TRANSITION_NONE	indicating no transition

Definition at line 117 of file app_level.h.

Function Documentation

app_level_current_value_publish()

uint32_t app_level_current_value_publish

(

app_level_server_t *

p_server

)

Initiates value fetch from the user application by calling a get callback, updates internal state, and publishes the Generic Level Status message.

This API must always be called by an application when user initiated action (e.g. button press) results in the local Level state change. Mesh Profile Specification v1.0 mandates that, every local state change must be published if model publication state is configured. If model publication is not configured this API call will not generate any assertion.

Parameters

[in]

p_server

Pointer to __app_level_server_t [app_level_server_t] context

Return values

NRF_SUCCESS

If status message is succesfully published.

Returns

Other return values returned by the lower layer APIs.

app_level_init()

uint32_t app_level_init	(	app_level_server_t *	p_server,
		uint8_t	element_index
	)

Initializes the behavioral module for the Generic Level model.

Parameters

[in]	p_server	Pointer to the application Level server struture array.
[in]	element_index	Element index on which this server will be instantiated.

Return values

NRF_ERROR_NULL	NULL pointer is supplied to the function or to the required member variable pointers.
NRF_ERROR_INVALID_PARAM	If value of the server_count is zero, or other parameters required by lower level APIs are not correct.

Returns

Other return values returned by the lower layer APIs.