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

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

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

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

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

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

Return values

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.

◆ 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_app Pointer to [app_light_lightness_setup_server_t](__app_light_lightness_setup_server_t) context.

Return values

NRF_SUCCESS	Bindings are setup successfully
NRF_ERROR_NULL	If 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_app Pointer to [app_light_lightness_setup_server_t](__app_light_lightness_setup_server_t) context.

Return values

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.

◆ 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_app	Pointer to [app_light_lightness_setup_server_t](__app_light_lightness_setup_server_t) context.
[in]	lightness_value	Actual lightness value to set

Return values

NRF_SUCCESS	Bindings are setup successfully
NRF_ERROR_NULL	If 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_app	Pointer to app_light_lightness_setup_server_t context.
[in]	p_app_scene	Pointer to scene behavioral moduel context.

Return values

NRF_SUCCESS	Value is restored successfully
NRF_ERROR_NULL	If NULL pointer is provided as input context

Light Lightness Setup Server behaviour

nRF5 SDK for Mesh v5.0.0

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ APP_LIGHT_LIGHTNESS_SETUP_SERVER_DEF

Typedef Documentation

◆ app_light_lightness_set_cb_t

◆ app_light_lightness_get_cb_t

◆ app_light_lightness_transition_cb_t

◆ app_additional_publish_cb_t

◆ app_notify_set_cb_t

Function Documentation

◆ app_light_lightness_model_init()

◆ app_light_lightness_binding_setup()

◆ app_light_lightness_current_value_publish()

◆ app_light_lightness_direct_actual_set()

◆ app_light_lightness_scene_context_set()