Application level OnOff server behavioral structures, functions, and callbacks. More...
Data Structures | |
| struct | app_onoff_state_t |
| Internal structure to hold state and timing information. More... | |
| struct | app_onoff_server_t |
| Application level structure holding the OnOff server model context and OnOff state representation. More... | |
Macros | |
| #define | APP_ONOFF_SERVER_DEF(_name, _force_segmented, _mic_size, _set_cb, _get_cb, _transition_cb) |
| Macro to create application level app_onoff_server_t context. More... | |
Typedefs | |
| typedef void(* | app_onoff_set_cb_t) (const app_onoff_server_t *p_app, bool onoff) |
| Application state set callback prototype. More... | |
| typedef void(* | app_onoff_get_cb_t) (const app_onoff_server_t *p_app, bool *p_present_onoff) |
| Application state read callback prototype. More... | |
| typedef void(* | app_onoff_transition_cb_t) (const app_onoff_server_t *p_app, uint32_t transition_time_ms, bool target_onoff) |
| Application transition time callback prototype. More... | |
Functions | |
| void | app_onoff_status_publish (app_onoff_server_t *p_app) |
| Initiates value fetch from the user application by calling a get callback, updates internal state, and publishes the Generic OnOff Status message. More... | |
| uint32_t | app_onoff_init (app_onoff_server_t *p_app, uint8_t element_index) |
| Initializes the behavioral module for the generic OnOff model. More... | |
| uint32_t | app_onoff_value_restore (app_onoff_server_t *p_app) |
| Restores the onoff value from persistent storage. More... | |
| uint32_t | app_onoff_scene_context_set (app_onoff_server_t *p_app, app_scene_setup_server_t *p_app_scene) |
| Sets the scene context. More... | |
Application level OnOff server behavioral structures, functions, and callbacks.
This module implements the behavioral requirements of the Generic OnOff 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/transiton_time 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 determins that it is time to inform the user application. It is possible that the client can send multiple overlapping set/transition 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_ONOFF_SERVER_DEF | ( | _name, | |
| _force_segmented, | |||
| _mic_size, | |||
| _set_cb, | |||
| _get_cb, | |||
| _transition_cb | |||
| ) |
Macro to create application level app_onoff_server_t context.
Individual timer instances are created for each model instance.
| [in] | _name | Name of the app_onoff_server_t instance |
| [in] | _force_segmented | If the Generic OnOff server shall use force segmentation of messages |
| [in] | _mic_size | MIC size to be used by Generic OnOff 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 98 of file app_onoff.h.
| typedef void(* app_onoff_set_cb_t) (const app_onoff_server_t *p_app, bool onoff) |
Application state set callback prototype.
This callback is called by the this module whenever application is required to be informed to reflect the desired OnOff value, as a result of the received SET message. Depending on the received Target OnOff value and timing parameters, this callback may be triggered after the delay+transition time is over or instantly after the delay if the Target OnOff value is 1, as required by Bluetooth Mesh Model Specification (MshMDLv1.0.1).
Note: Since the behavioral module encapsulates functionality required for the compliance with timing behaviour, it is not possible to infer number of Generic OnOff Set messages received by the node by counting the number of times this callback is triggered.
| [in] | p_app | Pointer to app_onoff_server_t context. |
| [in] | onoff | New onoff value to be used by the application |
Definition at line 142 of file app_onoff.h.
| typedef void(* app_onoff_get_cb_t) (const app_onoff_server_t *p_app, bool *p_present_onoff) |
Application state read callback prototype.
This callback is called by the app_model_behaviour.c whenever application onoff state is required to be read.
| [in] | p_app | Pointer to app_onoff_server_t context. |
| [out] | p_present_onoff | User application fills this value with the value retrived from the hardware interface. See model_callback_pointer_note. |
Definition at line 152 of file app_onoff.h.
| typedef void(* app_onoff_transition_cb_t) (const app_onoff_server_t *p_app, uint32_t transition_time_ms, bool target_onoff) |
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 onoff value and timing parameters.
| [in] | p_app | Pointer to app_onoff_server_t context. |
| [in] | transition_time_ms | Transition time (in milliseconds) to be used by the application. |
| [in] | target_onoff | Target onoff value to be used by the application. |
Definition at line 165 of file app_onoff.h.
| void app_onoff_status_publish | ( | app_onoff_server_t * | p_app | ) |
Initiates value fetch from the user application by calling a get callback, updates internal state, and publishes the Generic OnOff Status message.
This API must always be called by an application when user initiated action (e.g. button press) results in the local OnOff 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 error condition.
| [in] | p_app | Pointer to app_onoff_server_t context. |
| uint32_t app_onoff_init | ( | app_onoff_server_t * | p_app, |
| uint8_t | element_index | ||
| ) |
Initializes the behavioral module for the generic OnOff model.
| [in] | p_app | Pointer to app_onoff_server_t context. |
| [in] | element_index | Element index on which this server will be instantiated. |
| NRF_SUCCESS | If initialization is successful. |
| NRF_ERROR_NO_MEM | ACCESS_MODEL_COUNT number of models already allocated, or no more subscription lists available in memory pool. |
| NRF_ERROR_NULL | NULL pointer is supplied to the function or to the required member variable pointers. |
| NRF_ERROR_NOT_FOUND | Invalid access element index, or access handle invalid. |
| 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_INVALID_PARAM | Model not bound to appkey, publish address not set or wrong opcode format. The application timer module has not been initialized or timeout handler is not provided. |
| NRF_ERROR_INVALID_STATE | If the application timer is running. |
| uint32_t app_onoff_value_restore | ( | app_onoff_server_t * | p_app | ) |
Restores the onoff 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_onoff_server_t context. |
| NRF_SUCCESS | Value is restored successfully |
| NRF_ERROR_NULL | If NULL pointer is provided as input context |
| uint32_t app_onoff_scene_context_set | ( | app_onoff_server_t * | p_app, |
| app_scene_setup_server_t * | p_app_scene | ||
| ) |
Sets the scene context.
This is needed for app onoff to inform app scene when the state change occurs.
| [in] | p_app | Pointer to app_onoff_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 |