nRF5 SDK for Mesh v5.0.0
Data Structures | Macros | Typedefs | Functions
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, _transition_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_app, int16_t present_level)
 Application state set callback prototype. More...
 
typedef void(* app_level_get_cb_t) (const app_level_server_t *p_app, int16_t *p_present_level)
 Application state read callback prototype. More...
 
typedef void(* app_level_transition_cb_t) (const app_level_server_t *p_app, uint32_t transition_time_ms, uint16_t target_level, app_transition_type_t transition_type)
 Application transition time callback prototype. More...
 

Functions

uint32_t app_level_current_value_publish (app_level_server_t *p_app)
 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_app, uint8_t element_index)
 Initializes the behavioral module for the Generic Level model. More...
 
uint32_t app_level_value_restore (app_level_server_t *p_app)
 Restores the level value from persistent storage. More...
 
uint32_t app_level_scene_context_set (app_level_server_t *p_app, app_scene_setup_server_t *p_app_scene)
 Sets the scene context. 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 can happen through the following callbacks: get_cb, set_cb and/or transition_cb

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

Using set_cb: 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 callback 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.

Using transition_cb: If the underlaying hardware does not support setting of the instantaneous level value provided via set_cb, the transition_cb can be used to implement the transition effect according to provided transition parameters. This callback will be called when transition starts with the required transition time and target value. When the transition is complete this callback will be called again with transition time set to 0 and the desired target value.

Warning
To comply with the Bluetooth Mesh Model Specification (MshMDLv1.0.1) test cases, the application must adhere to the requirements defined in the following sections:
  • Bluetooth Mesh Model Specification (MshMDLv1.0.1) section 3.1.2 (Generic Level) and section 3.3.2.2 (Generic Level state behaviour).
  • Bluetooth Mesh Profile Specification (MshPRFv1.0.1) section 3.7.6.1 (Publish).

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,
  _transition_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, \
.state.transition.timer.p_timer_id = &_name ## _timer, \
.p_dtt_ms = _p_dtt, \
.level_set_cb = _set_cb, \
.level_get_cb = _get_cb, \
.level_transition_cb = _transition_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.
[in]_transition_cbCallback for setting the application transition time and state value to given values.

Definition at line 113 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_app, 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_appPointer to app_level_server_t context.
[in]present_levelInstantaneous new level value to be used by the application

Definition at line 183 of file app_level.h.

◆ app_level_get_cb_t

typedef void(* app_level_get_cb_t) (const app_level_server_t *p_app, 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_appPointer to app_level_server_t context.
[out]p_present_levelUser application fills this value with the value retrived from the hardware interface. See model_callback_pointer_note.

Definition at line 193 of file app_level.h.

◆ app_level_transition_cb_t

typedef void(* app_level_transition_cb_t) (const app_level_server_t *p_app, uint32_t transition_time_ms, uint16_t target_level, app_transition_type_t transition_type)

Application transition time callback prototype.

This callback is called by the this module whenever application is required to be informed to reflect the desired transition time, depending on the received target level/type and timing parameters.

Parameters
[in]p_appPointer to app_level_server_t context.
[in]transition_time_msTransition time (in milliseconds) to be used by the application.
[in]target_levelTarget level value to be used by the application

Definition at line 206 of file app_level.h.

Function Documentation

◆ app_level_current_value_publish()

uint32_t app_level_current_value_publish ( app_level_server_t *  p_app)

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. This API should never be called from transition callback. Bluetooth Mesh Profile Specification (MshPRFv1.0.1) 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_appPointer to app_level_server_t context.
Return values
NRF_SUCCESSIf status message is successfully published.
NRF_ERROR_NULLNULL pointer given to function.
NRF_ERROR_INVALID_PARAMThe model not bound to application key or publish address not set.
NRF_ERROR_INVALID_STATEThere's already a segmented packet that is being to sent to this destination. Wait for the transmission to finish before sending new segmented packets.
NRF_ERROR_NO_MEMNo memory available to send the message at this point.
NRF_ERROR_FORBIDDENFailed to allocate a sequence number from network.
NRF_ERROR_NOT_FOUNDThe model is not initialized.

◆ app_level_init()

uint32_t app_level_init ( app_level_server_t *  p_app,
uint8_t  element_index 
)

Initializes the behavioral module for the Generic Level model.

Parameters
[in]p_appPointer to app_level_server_t context.
[in]element_indexElement index on which this server will be instantiated.
Return values
NRF_SUCCESSIf initialization is successful
NRF_ERROR_NULLNULL pointer is supplied to the function or to the required member variable pointers.
NRF_ERROR_NO_MEMACCESS_MODEL_COUNT number of models already allocated or no more subscription lists available in memory pool (see ACCESS_SUBSCRIPTION_LIST_COUNT).
NRF_ERROR_FORBIDDENMultiple model instances per element are not allowed or changes to device composition are not allowed. Adding a new model after device is provisioned is not allowed.
NRF_ERROR_NOT_FOUNDInvalid access element index.
NRF_ERROR_INVALID_PARAMIf the application timer module has not been initialized.
NRF_ERROR_INVALID_STATEIf the application timer is running.

◆ app_level_value_restore()

uint32_t app_level_value_restore ( app_level_server_t *  p_app)

Restores the level value from persistent storage.

This is called by main.c when the mesh is initialized and stable. Note that this function must be called from the same IRQ level that mesh_init() is set at.

Parameters
[in]p_appPointer to app_level_server_t context.
Return values
NRF_SUCCESSValue is restored successfully
NRF_ERROR_NULLIf NULL pointer is provided as input context

◆ app_level_scene_context_set()

uint32_t app_level_scene_context_set ( app_level_server_t *  p_app,
app_scene_setup_server_t *  p_app_scene 
)

Sets the scene context.

This is needed for app level to inform app scene when the state change occurs.

Note
Available only if SCENE_SETUP_SERVER_INSTANCES_MAX is equal or larger than 1.
Parameters
[in]p_appPointer to app_level_server_t context.
[in]p_app_scenePointer to scene behavioral moduel context.
Return values
NRF_SUCCESSValue is restored successfully
NRF_ERROR_NULLIf NULL pointer is provided as input context

Documentation feedback | Developer Zone | Subscribe | Updated