nRF5 SDK for Mesh v3.2.0  08c60f6
Generic Level server behaviour

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]_nameName of the app_level_server_t instance
[in]_force_segmentedIf the Generic Level server shall use force segmentation of messages
[in]_mic_sizeMIC size to be used by Generic Level server
[in]_p_dttPointer to the default transition time state if present
[in]_set_cbCallback for setting the application state to given value.
[in]_get_cbCallback 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_serverPointer to __app_level_server_t [app_level_server_t] context
[in]present_levelInstantaneous 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_serverPointer to __app_level_server_t [app_level_server_t] context
[out]p_present_levelUser 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

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_serverPointer to __app_level_server_t [app_level_server_t] context
Return values
NRF_SUCCESSIf 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_serverPointer to the application Level server struture array.
[in]element_indexElement index on which this server will be instantiated.
Return values
NRF_ERROR_NULLNULL pointer is supplied to the function or to the required member variable pointers.
NRF_ERROR_INVALID_PARAMIf 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.