Application Light Lightness server behavioral structures, functions, and callbacks. More...
Data Structures | |
struct | app_light_lightness_state_t |
Internal structure to hold state and timing information. More... | |
struct | app_additional_light_lightness_notify_t |
Structure for holding publish and notification callbacks for other states bound to Light Lightness state. More... | |
struct | app_light_lightness_setup_server_t |
Application level structure holding the Light Lightness Setup server model context and Light Lightness state representation. More... | |
Macros | |
#define | APP_LIGHT_LIGHTNESS_SETUP_SERVER_DEF(_name, _force_segmented, _mic_size, _set_cb, _get_cb, _transition_cb) |
Macro to create application level app_light_lightness_setup_server_t context. More... | |
Typedefs | |
typedef void(* | app_light_lightness_set_cb_t) (const app_light_lightness_setup_server_t *p_app, uint16_t lightness) |
Application Light Lightness state set callback prototype. More... | |
typedef void(* | app_light_lightness_get_cb_t) (const app_light_lightness_setup_server_t *p_app, uint16_t *p_present_lightness) |
Application Light Lightness state read callback prototype. More... | |
typedef void(* | app_light_lightness_transition_cb_t) (const app_light_lightness_setup_server_t *p_app, uint32_t transition_time_ms, uint16_t target_lightness) |
Application Light Lightness transition time callback prototype. More... | |
typedef void(* | app_additional_publish_cb_t) (const void *p_app_v, light_lightness_status_params_t *p_pub_data) |
Application publish callback prototype. More... | |
typedef void(* | app_notify_set_cb_t) (const void *p_app_v, uint16_t lightness) |
Application notify callback prototype. More... | |
Functions | |
uint32_t | app_light_lightness_model_init (app_light_lightness_setup_server_t *p_app, uint8_t element_index) |
Initializes the behavioral module for the generic Light Lightness model. More... | |
uint32_t | app_light_lightness_binding_setup (app_light_lightness_setup_server_t *p_app) |
Informs the model that the system is ready to have the powerup onoff bindings. More... | |
uint32_t | app_light_lightness_current_value_publish (app_light_lightness_setup_server_t *p_app) |
Initiates value fetch from the user application by calling a get callback, updates internal state, and publishes the Lightness Actual status message. More... | |
uint32_t | app_light_lightness_direct_actual_set (app_light_lightness_setup_server_t *p_app, uint16_t lightness_value) |
Function to set the lightness value (sending to the hardware) and writing the flash state values. More... | |
uint32_t | app_light_lightness_scene_context_set (app_light_lightness_setup_server_t *p_app, app_scene_setup_server_t *p_app_scene) |
Sets the scene context. More... | |
Application Light Lightness server behavioral structures, functions, and callbacks.
This module implements the behavioral requirements of the Light Lightness server model.
The application should use the set/transition callback provided by this module to set the hardware state. The hardware state could be changed by reflecting the value provided by the set/transition callback on the GPIO or by sending this value to the connected lighting peripheral using some other interface (e.g. serial interface). Similarly, the application should use the get callback provided by this module to read the hardware state.
This module triggers the set/transition callback only when it determines that it is time to inform the user application. It is possible that the client can send multiple overlapping set commands. In such case any transition in progress will be abandoned and fresh transition will be started if required.
Using transition_cb: If the underlaying hardware does not support setting of the instantaneous 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 start 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_LIGHT_LIGHTNESS_SETUP_SERVER_DEF | ( | _name, | |
_force_segmented, | |||
_mic_size, | |||
_set_cb, | |||
_get_cb, | |||
_transition_cb | |||
) |
Macro to create application level app_light_lightness_setup_server_t context.
Individual timer instances are created for each model instance.
[in] | _name | Name of the app_light_lightness_setup_server_t instance |
[in] | _force_segmented | If the light lightness server shall use force segmentation of messages |
[in] | _mic_size | MIC size to be used by Light Lightness server |
[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 97 of file app_light_lightness.h.
typedef void(* app_light_lightness_set_cb_t) (const app_light_lightness_setup_server_t *p_app, uint16_t lightness) |
Application Light Lightness 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 messages (for light lightness or encapsulated models), depending on the received target lightness 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 Set messages received by the node by counting the number of times this callback is triggered.
[in] | p_app | Pointer to app_light_lightness_setup_server_t context. |
[in] | lightness | Lightness value to set |
Definition at line 156 of file app_light_lightness.h.
typedef void(* app_light_lightness_get_cb_t) (const app_light_lightness_setup_server_t *p_app, uint16_t *p_present_lightness) |
Application Light Lightness state read callback prototype.
This callback is called by the app_model_behaviour.c whenever application light_lightness state is required to be read.
[in] | p_app | Pointer to app_light_lightness_setup_server_t context. |
[out] | p_present_lightness | User application fills this value with the value retrieved from the hardware interface. See model_callback_pointer_note. |
Definition at line 168 of file app_light_lightness.h.
typedef void(* app_light_lightness_transition_cb_t) (const app_light_lightness_setup_server_t *p_app, uint32_t transition_time_ms, uint16_t target_lightness) |
Application Light Lightness 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, as a result of the received messages (for light lightness or encapsulated models), depending on the received target lightness value and timing parameters.
[in] | p_app | Pointer to app_light_lightness_setup_server_t context. |
[in] | transition_time_ms | Transition time (in milliseconds) to be used by the application. |
[in] | target_lightness | Target Lightness value to be used by the application. |
Definition at line 181 of file app_light_lightness.h.
typedef void(* app_additional_publish_cb_t) (const void *p_app_v, light_lightness_status_params_t *p_pub_data) |
Application publish callback prototype.
This callback is called by the light lightness mid app whenever it publishes. This will inform the mid app that instantiated it that a lightness publish has occurred. If the mid app needs to publish an additional message, it can do so.
Since the light lightness mid app doesn't know who the instantiator is, the p_app is sent as a void pointer.
[in] | p_app_v | Pointer to the app context stored in the structure. |
[in] | p_pub_data | Pointer to the lightness data structure containing data to publish. See model_callback_pointer_note. |
Definition at line 196 of file app_light_lightness.h.
typedef void(* app_notify_set_cb_t) (const void *p_app_v, uint16_t lightness) |
Application notify callback prototype.
This callback is called by the light lightness mid app whenever it sets the lightness. This will inform the mid app that instantiated it that the lightness has been set. The mid app can take whatever action is needed.
Since the light lightness mid app doesn't know who the instantiator is, the p_app_v is sent as a void pointer.
[in] | p_app_v | Pointer to the app context stored in the structure. |
[in] | lightness | The lightness value to publish. |
Definition at line 211 of file app_light_lightness.h.
uint32_t app_light_lightness_model_init | ( | app_light_lightness_setup_server_t * | p_app, |
uint8_t | element_index | ||
) |
Initializes the behavioral module for the generic Light Lightness model.
[in] | p_app | Pointer to [app_light_lightness_setup_server_t](__app_light_lightness_setup_server_t) context. |
[in] | element_index | Element index on which this server will be instantiated. |
NRF_SUCCESS | If initialization is successful. |
NRF_ERROR_NULL | If NULL pointer is provided as input context |
NRF_ERROR_RESOURCES | No more instances can be created. In that case, increase value of LIGHT_LIGHTNESS_SETUP_SERVER_INSTANCES_MAX. |
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_light_lightness_binding_setup | ( | app_light_lightness_setup_server_t * | p_app | ) |
Informs the model that the system is ready to have the powerup onoff bindings.
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_light_lightness_setup_server_t](__app_light_lightness_setup_server_t) context. |
NRF_SUCCESS | Bindings are setup successfully |
NRF_ERROR_NULL | If NULL pointer is provided as input context |
uint32_t app_light_lightness_current_value_publish | ( | app_light_lightness_setup_server_t * | p_app | ) |
Initiates value fetch from the user application by calling a get callback, updates internal state, and publishes the Lightness Actual status message.
This API must always be called by an application when user initiated action (e.g. button press) results in the local lightness 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_light_lightness_setup_server_t](__app_light_lightness_setup_server_t) context. |
NRF_SUCCESS | If status message is successfully published. |
NRF_ERROR_NULL | If NULL pointer is provided as input context |
NRF_ERROR_NO_MEM | No memory available to send the message at this point. |
NRF_ERROR_NOT_FOUND | The model is not initialized. |
NRF_ERROR_INVALID_PARAM | The model not bound to application key or publish address not set. |
NRF_ERROR_FORBIDDEN | Failed to allocate a sequence number from network. |
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. |
uint32_t app_light_lightness_direct_actual_set | ( | app_light_lightness_setup_server_t * | p_app, |
uint16_t | lightness_value | ||
) |
Function to set the lightness value (sending to the hardware) and writing the flash state values.
This API is for extending models to call to set the light lightness value when a state publish is not desired (e.g. LC server will be changing the lightness on a continual basis with light harvesting, so a publish is not desired). This function also writes the flash state values for last and actual.
[in] | p_app | Pointer to [app_light_lightness_setup_server_t](__app_light_lightness_setup_server_t) context. |
[in] | lightness_value | Actual lightness value to set |
NRF_SUCCESS | Bindings are setup successfully |
NRF_ERROR_NULL | If NULL pointer is provided as input context |
uint32_t app_light_lightness_scene_context_set | ( | app_light_lightness_setup_server_t * | p_app, |
app_scene_setup_server_t * | p_app_scene | ||
) |
Sets the scene context.
This is needed for app light lightness to inform app scene when the state change occurs.
[in] | p_app | Pointer to app_light_lightness_setup_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 |