nRF5 SDK for Mesh v5.0.0
Data Structures | Macros | Typedefs | Functions
Light Lightness Setup Server behaviour

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...
 

Detailed Description

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.

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 6.1.1 (Light Lightness) and section 6.4.1.2 (Light Lightness state behaviour).

These requirements are documented at appropriate places in the module source code.

Macro Definition Documentation

◆ APP_LIGHT_LIGHTNESS_SETUP_SERVER_DEF

#define APP_LIGHT_LIGHTNESS_SETUP_SERVER_DEF (   _name,
  _force_segmented,
  _mic_size,
  _set_cb,
  _get_cb,
  _transition_cb 
)
Value:
APP_TIMER_DEF(_name ## _timer); \
static app_light_lightness_setup_server_t _name = \
{ \
.light_lightness_setup_server.settings.force_segmented = _force_segmented, \
.light_lightness_setup_server.settings.transmic_size = _mic_size, \
.app_add_notify.app_add_publish_cb = NULL, \
.app_add_notify.app_notify_set_cb = NULL, \
.state.transition.timer.p_timer_id = &_name ## _timer, \
.app_light_lightness_set_cb = _set_cb, \
.app_light_lightness_get_cb = _get_cb, \
.app_light_lightness_transition_cb = _transition_cb \
};

Macro to create application level app_light_lightness_setup_server_t context.

Individual timer instances are created for each model instance.

Parameters
[in]_nameName of the app_light_lightness_setup_server_t instance
[in]_force_segmentedIf the light lightness server shall use force segmentation of messages
[in]_mic_sizeMIC size to be used by Light Lightness server
[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 97 of file app_light_lightness.h.

Typedef Documentation

◆ app_light_lightness_set_cb_t

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.

Parameters
[in]p_appPointer to app_light_lightness_setup_server_t context.
[in]lightnessLightness value to set

Definition at line 156 of file app_light_lightness.h.

◆ app_light_lightness_get_cb_t

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.

Parameters
[in]p_appPointer to app_light_lightness_setup_server_t context.
[out]p_present_lightnessUser 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.

◆ app_light_lightness_transition_cb_t

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.

Parameters
[in]p_appPointer to app_light_lightness_setup_server_t context.
[in]transition_time_msTransition time (in milliseconds) to be used by the application.
[in]target_lightnessTarget Lightness value to be used by the application.

Definition at line 181 of file app_light_lightness.h.

◆ app_additional_publish_cb_t

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.

Parameters
[in]p_app_vPointer to the app context stored in the structure.
[in]p_pub_dataPointer to the lightness data structure containing data to publish. See model_callback_pointer_note.

Definition at line 196 of file app_light_lightness.h.

◆ app_notify_set_cb_t

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.

Parameters
[in]p_app_vPointer to the app context stored in the structure.
[in]lightnessThe lightness value to publish.

Definition at line 211 of file app_light_lightness.h.

Function Documentation

◆ app_light_lightness_model_init()

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.

Parameters
[in]p_appPointer to [app_light_lightness_setup_server_t](__app_light_lightness_setup_server_t) context.
[in]element_indexElement index on which this server will be instantiated.
Return values
NRF_SUCCESSIf initialization is successful.
NRF_ERROR_NULLIf NULL pointer is provided as input context
NRF_ERROR_RESOURCESNo more instances can be created. In that case, increase value of LIGHT_LIGHTNESS_SETUP_SERVER_INSTANCES_MAX.
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_light_lightness_binding_setup()

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.

Parameters
[in]p_appPointer to [app_light_lightness_setup_server_t](__app_light_lightness_setup_server_t) context.
Return values
NRF_SUCCESSBindings are setup successfully
NRF_ERROR_NULLIf NULL pointer is provided as input context

◆ app_light_lightness_current_value_publish()

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.

Parameters
[in]p_appPointer to [app_light_lightness_setup_server_t](__app_light_lightness_setup_server_t) context.
Return values
NRF_SUCCESSIf status message is successfully published.
NRF_ERROR_NULLIf NULL pointer is provided as input context
NRF_ERROR_NO_MEMNo memory available to send the message at this point.
NRF_ERROR_NOT_FOUNDThe model is not initialized.
NRF_ERROR_INVALID_PARAMThe model not bound to application key or publish address not set.
NRF_ERROR_FORBIDDENFailed to allocate a sequence number from network.
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.

◆ app_light_lightness_direct_actual_set()

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.

Warning
This API must never be called from model transition callback.
Parameters
[in]p_appPointer to [app_light_lightness_setup_server_t](__app_light_lightness_setup_server_t) context.
[in]lightness_valueActual lightness value to set
Return values
NRF_SUCCESSBindings are setup successfully
NRF_ERROR_NULLIf NULL pointer is provided as input context

◆ app_light_lightness_scene_context_set()

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.

Note
Available only if SCENE_SETUP_SERVER_INSTANCES_MAX is equal or larger than 1.
Parameters
[in]p_appPointer to app_light_lightness_setup_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