Application Light CTL Setup Server behavioral structures, functions, and callbacks. More...

Data Structures
struct	app_light_ctl_temperature_duv_hw_state_t
	Light CTL hardware state format for transfer of temperature and delta UV between the mid app and top app (main.c) More...

struct	app_light_ctl_state_t
	Internal structure to hold state and timing information. More...

struct	app_light_ctl_setup_server_t
	Application level structure holding the Light CTL Setup Server model context, Light Lightness application structure (which contains the light_lightness_setup_server model context), and the Light CTL and Light Lightness state representation. More...

Macros
#define	APP_LIGHT_CTL_SETUP_SERVER_DEF(_name, _force_segmented, _mic_size, _light_ctl_set_cb, _light_ctl_get_cb, _light_ctl_transition_cb)
	Macro to create application level app_light_ctl_setup_server_t context. More...

Typedefs
typedef void(*	app_light_ctl_set_cb_t) (const app_light_ctl_setup_server_t p_app, app_light_ctl_temperature_duv_hw_state_t p_ctl_state)
	Application Light CTL (temperature/delta UV) state set callback prototype. More...

typedef void(*	app_light_ctl_get_cb_t) (const app_light_ctl_setup_server_t p_app, app_light_ctl_temperature_duv_hw_state_t p_present_ctl_state)
	Application Light CTL state read callback prototype. More...

typedef void(*	app_light_ctl_transition_cb_t) (const app_light_ctl_setup_server_t *p_app, uint32_t transition_time_ms, app_light_ctl_temperature_duv_hw_state_t target_ctl_state)
	Application Light CTL transition time callback prototype. More...

Functions
uint32_t	app_light_ctl_model_init (app_light_ctl_setup_server_t p_app, uint8_t element_index, app_light_lightness_setup_server_t p_app_ll)
	Initializes the behavioral module for the Light CTL and Light Lightness models. More...

uint32_t	app_light_ctl_binding_setup (app_light_ctl_setup_server_t *p_app)
	Informs the model that the system is ready to have the powerup onoff bindings. More...

uint32_t	app_light_ctl_current_value_publish (app_light_ctl_setup_server_t *p_app)
	Initiates value fetch from the user application by calling a get callback, updates internal state, and publishes the Light CTL Status messages. More...

uint32_t	app_light_ctl_scene_context_set (app_light_ctl_setup_server_t p_app, app_scene_setup_server_t p_app_scene)
	Sets the scene context. More...

Detailed Description

Application Light CTL Setup Server behavioral structures, functions, and callbacks.

This module implements the behavioral requirements of the Light CTL Setup Server model.

The CTL server requires a composite state for the hardware. This composite state has the lightness, temperature, and delta UV values. There are two independent callbacks that pass this information to the application, whenever these values need to be updated. One callback is provided to update the Delta UV (DUV) and Temperature value and another callback is provided to update the Lightness value. The two callbacks are provided as these states can change the values independently.

The application should use the set/transition callbacks provided by this module to set the hardware state. The hardware state could be changed by reflecting the value provided by the set/transition callbacks on GPIOs 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 values 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.3 (Ligth CTL state), section 6.3.2 (Light CTL Messages), and section 6.4.3-6.4.5.

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

Macro Definition Documentation

◆ APP_LIGHT_CTL_SETUP_SERVER_DEF

#define APP_LIGHT_CTL_SETUP_SERVER_DEF	(	_name,
		_force_segmented,
		_mic_size,
		_light_ctl_set_cb,
		_light_ctl_get_cb,
		_light_ctl_transition_cb
	)

Value:

APP_TIMER_DEF(_name ## _timer); \
 static app_light_ctl_setup_server_t _name = \
 { \
 .light_ctl_setup_srv.settings.force_segmented = _force_segmented, \
 .light_ctl_setup_srv.settings.transmic_size = _mic_size, \
 .state.transition.timer.p_timer_id = &_name ## _timer, \
 .app_light_ctl_set_cb = _light_ctl_set_cb, \
 .app_light_ctl_get_cb = _light_ctl_get_cb, \
 .app_light_ctl_transition_cb = _light_ctl_transition_cb, \
 };

Macro to create application level app_light_ctl_setup_server_t context.

Individual timer instances are created for each model instance. An app light lightness structure needs to be created separately for each model instance.

Parameters

[in]	_name	Name of the app_light_ctl_setup_server_t instance.
[in]	_force_segmented	If the Light CTL Setup Server shall use force segmentation of messages.
[in]	_mic_size	MIC size to be used by the Light CTL Setup Server.
[in]	_light_ctl_set_cb	Callback for setting the application state to given value.
[in]	_light_ctl_get_cb	Callback for reading the state from the application.
[in]	_light_ctl_transition_cb	Callback for setting the application transition time and state value to given values.

Definition at line 118 of file app_light_ctl.h.

Typedef Documentation

◆ app_light_ctl_set_cb_t

typedef void(* app_light_ctl_set_cb_t) (const app_light_ctl_setup_server_t *p_app, app_light_ctl_temperature_duv_hw_state_t *p_ctl_state)

Application Light CTL (temperature/delta UV) state set callback prototype.

This callback is called by this module whenever the application is required to be informed to reflect the desired Light CTL composite state (temperature, delta UV), as a result of the received messages (for Light CTL or extended models), depending on the received target state values 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_ctl_setup_server_t context.
[in]	p_ctl_state	Pointer to the composite Light CTL state to set. See app_light_ctl_temperature_duv_hw_state_t and model_callback_pointer_note.

Definition at line 188 of file app_light_ctl.h.

◆ app_light_ctl_get_cb_t

typedef void(* app_light_ctl_get_cb_t) (const app_light_ctl_setup_server_t *p_app, app_light_ctl_temperature_duv_hw_state_t *p_present_ctl_state)

Application Light CTL state read callback prototype.

This callback is called by the app_model_behaviour.c whenever application Light CTL state is required to be read.

Parameters

[in]	p_app	Pointer to app_light_ctl_setup_server_t context.
[out]	p_present_ctl_state	User application fills this value with the values retrieved from the hardware interface. See app_light_ctl_temperature_duv_hw_state_t and model_callback_pointer_note.

Definition at line 201 of file app_light_ctl.h.

◆ app_light_ctl_transition_cb_t

typedef void(* app_light_ctl_transition_cb_t) (const app_light_ctl_setup_server_t *p_app, uint32_t transition_time_ms, app_light_ctl_temperature_duv_hw_state_t target_ctl_state)

Application Light CTL 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 ctl or encapsulated models), depending on the received target ctl state and timing parameters.

Parameters

[in]	p_app	Pointer to app_light_ctl_setup_server_t context.
[in]	transition_time_ms	Transition time (in milliseconds) to be used by the application.
[in]	target_ctl_state	Target Light CTL state to be used by the application. See app_light_ctl_temperature_duv_hw_state_t.

Definition at line 214 of file app_light_ctl.h.

Function Documentation

◆ app_light_ctl_model_init()

uint32_t app_light_ctl_model_init	(	app_light_ctl_setup_server_t *	p_app,
		uint8_t	element_index,
		app_light_lightness_setup_server_t *	p_app_ll
	)

Initializes the behavioral module for the Light CTL and Light Lightness models.

Parameters

[in]	p_app	Pointer to app_light_ctl_setup_server_t context.
[in]	element_index	Element index on which the Light CTL Setup Server will be instantiated. This needs to be the same element index as the one Light Lightness was instantiated on.
[in]	p_app_ll	Pointer to app_light_lightness_setup_server_t context.

Return values

NRF_SUCCESS	If initialization is successful.
NRF_ERROR_NULL	If NULL pointer is provided as input context.
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_STATE	If module is unable to initialize the storage for Light CTL states.
NRF_ERROR_RESOURCES	No more instances can be created. In that case, increase value of LIGHT_CTL_SETUP_SERVER_INSTANCES_MAX.

◆ app_light_ctl_binding_setup()

uint32_t app_light_ctl_binding_setup ( app_light_ctl_setup_server_t * p_app )

Informs the model that the system is ready to have the powerup onoff bindings.

Note: This function must be called from the same IRQ level that is specified for the mesh stack (see mesh_stack_init() API).

Parameters

[in] p_app Pointer to app_light_ctl_setup_server_t context.

Return values

NRF_SUCCESS	Bindings are setup successfully.
NRF_ERROR_NULL	If NULL pointer is provided as input context.
NRF_ERROR_INVALID_DATA	If OnPowerUp state value (see generic_on_powerup_values_t) is not within range.

◆ app_light_ctl_current_value_publish()

uint32_t app_light_ctl_current_value_publish ( app_light_ctl_setup_server_t * p_app )

Initiates value fetch from the user application by calling a get callback, updates internal state, and publishes the Light CTL Status messages.

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.

Parameters

[in] p_app Pointer to app_light_ctl_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	Not enough memory available for message publication.
NRF_ERROR_NOT_FOUND	Invalid model handle or model not bound to element.
NRF_ERROR_INVALID_PARAM	Model not bound to appkey, publish address not set or wrong opcode format.
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 the publish address (if force segmentation is enabled). Wait for the transmission to finish.

◆ app_light_ctl_scene_context_set()

uint32_t app_light_ctl_scene_context_set	(	app_light_ctl_setup_server_t *	p_app,
		app_scene_setup_server_t *	p_app_scene
	)

Sets the scene context.

This is needed for app light ctl 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_ctl_setup_server_t](__app_light_ctl_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

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ APP_LIGHT_CTL_SETUP_SERVER_DEF

Typedef Documentation

◆ app_light_ctl_set_cb_t

◆ app_light_ctl_get_cb_t

◆ app_light_ctl_transition_cb_t

Function Documentation

◆ app_light_ctl_model_init()

◆ app_light_ctl_binding_setup()

◆ app_light_ctl_current_value_publish()

◆ app_light_ctl_scene_context_set()