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... | |
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.
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.
These requirements are documented at appropriate places in the module source code.
#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.
Individual timer instances are created for each model instance.
[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. |
[in] | _transition_cb | Callback for setting the application transition time and state value to given values. |
Definition at line 113 of file app_level.h.
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.
[in] | p_app | Pointer to app_level_server_t context. |
[in] | present_level | Instantaneous new level value to be used by the application |
Definition at line 183 of file app_level.h.
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.
[in] | p_app | Pointer to app_level_server_t context. |
[out] | p_present_level | User 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.
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.
[in] | p_app | Pointer to app_level_server_t context. |
[in] | transition_time_ms | Transition time (in milliseconds) to be used by the application. |
[in] | target_level | Target level value to be used by the application |
Definition at line 206 of file app_level.h.
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.
[in] | p_app | Pointer to app_level_server_t context. |
NRF_SUCCESS | If status message is successfully published. |
NRF_ERROR_NULL | NULL pointer given to function. |
NRF_ERROR_INVALID_PARAM | The model not bound to application key or publish address not set. |
NRF_ERROR_INVALID_STATE | There'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_MEM | No memory available to send the message at this point. |
NRF_ERROR_FORBIDDEN | Failed to allocate a sequence number from network. |
NRF_ERROR_NOT_FOUND | The model is not initialized. |
uint32_t app_level_init | ( | app_level_server_t * | p_app, |
uint8_t | element_index | ||
) |
Initializes the behavioral module for the Generic Level model.
[in] | p_app | Pointer to app_level_server_t context. |
[in] | element_index | Element index on which this server will be instantiated. |
NRF_SUCCESS | If initialization is successful |
NRF_ERROR_NULL | NULL pointer is supplied to the function or to the required member variable pointers. |
NRF_ERROR_NO_MEM | ACCESS_MODEL_COUNT number of models already allocated or no more subscription lists available in memory pool (see ACCESS_SUBSCRIPTION_LIST_COUNT). |
NRF_ERROR_FORBIDDEN | Multiple 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_FOUND | Invalid access element index. |
NRF_ERROR_INVALID_PARAM | If the application timer module has not been initialized. |
NRF_ERROR_INVALID_STATE | If the application timer is running. |
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.
[in] | p_app | Pointer to app_level_server_t context. |
NRF_SUCCESS | Value is restored successfully |
NRF_ERROR_NULL | If NULL pointer is provided as input context |
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.
[in] | p_app | Pointer to app_level_server_t context. |
[in] | p_app_scene | Pointer to scene behavioral moduel context. |
NRF_SUCCESS | Value is restored successfully |
NRF_ERROR_NULL | If NULL pointer is provided as input context |