Infineon Logo AIROC BTSDK v4.1 - Documentation
 
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Mesh Light CTL Server

The AIROC Mesh Color Temperature Lightness (CTL) Server module provides a way for an application to implement a dimmable light device with color temperature support. More...

Macros

#define WICED_BT_MESH_MODEL_LIGHT_CTL_SERVER
 Mesh Light CTL Server Device. More...
 
#define WICED_BT_MESH_MODEL_LIGHT_CTL_TEMPERATURE_SERVER
 

Typedefs

typedef void( wiced_bt_mesh_light_ctl_server_callback_t )(uint8_t element_idx, uint16_t event, void *p_data)
 Light CTL Server callback. More...
 

Functions

void wiced_bt_mesh_model_light_ctl_server_init (uint8_t lightness_element_idx, wiced_bt_mesh_light_ctl_server_callback_t *p_callback, wiced_bool_t is_provisioned)
 Light CTL Server Module initialization. More...
 
void wiced_bt_mesh_model_light_ctl_server_state_changed (uint8_t element_idx, wiced_bt_mesh_light_ctl_status_data_t *p_data)
 Light CTL state changed. More...
 
wiced_bool_t wiced_bt_mesh_model_light_ctl_server_message_handler (wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
 Light CTL Server Message Handler. More...
 
wiced_bool_t wiced_bt_mesh_model_light_ctl_setup_server_message_handler (wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
 Light CTL Setup Server Message Handler. More...
 
wiced_bool_t wiced_bt_mesh_model_light_ctl_temperature_server_message_handler (wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
 Light CTL Temperature Server Message Handler. More...
 
uint16_t wiced_bt_mesh_model_light_ctl_server_scene_store_handler (uint8_t element_idx, uint8_t *p_buffer, uint16_t buffer_len)
 Light CTL Server Scene Store Handler. More...
 
uint16_t wiced_bt_mesh_model_light_ctl_temperature_server_scene_store_handler (uint8_t element_idx, uint8_t *p_buffer, uint16_t buffer_len)
 Light CTL Temperature Server Scene Store Handler. More...
 
uint16_t wiced_bt_mesh_model_light_ctl_server_scene_recall_handler (uint8_t element_idx, uint8_t *p_buffer, uint16_t buffer_len, uint32_t transition_time, uint32_t delay)
 Light CTL Server Scene Restore Handler. More...
 
uint16_t wiced_bt_mesh_model_light_ctl_temperature_server_scene_recall_handler (uint8_t element_idx, uint8_t *p_buffer, uint16_t buffer_len, uint32_t transition_time, uint32_t delay)
 Light Temperature Server Scene Restore Handler. More...
 
void wiced_bt_mesh_model_light_ctl_server_set_startup_controller (uint8_t element_idx, wiced_bool_t startup_controller)
 Set Light CTL Model as a startup controller. More...
 

Detailed Description

The AIROC Mesh Color Temperature Lightness (CTL) Server module provides a way for an application to implement a dimmable light device with color temperature support.

The device can be controlled by setting the brightness, color temperature and delta UV, but also can be can be controlled using a Level slider (Generic Level client) applied to the brightness or color temperature and by a On/Off switch (Generic On/Off client). The device also supports a default transition time server functionality and the application can specify on power up behavior.

The definition of the CTL Server spans two elements. To include the Mesh Models support for the CTL Server model the application includes WICED_BT_MESH_MODEL_LIGHT_CTL_SERVER and WICED_BT_MESH_MODEL_LIGHT_CTL_TEMPERATURE_SERVER in two consecutive elements in the device definition. If the device supports several lights with CTL Server, for example, a light fixture or a chandelier with several color lights, the pair of WICED_BT_MESH_MODEL_LIGHT_CTL_SERVER and WICED_BT_MESH_MODEL_LIGHT_CTL_TEMPERATURE_SERVER shall be repeated for each physical device.

In addition to the definition, the application shall initialize the CTL Server module by calling wiced_bt_mesh_model_light_ctl_server_init function for each primary element where the CTL functionality is required providing the wiced_bt_mesh_light_ctl_server_callback_t callback that will be executed when the brightness level or the color temperature of the device needs to be changed.

If the brightness or color temperature of the device is changed locally the application should call the wiced_bt_mesh_model_light_ctl_status_changed so that the library can maintain correct state and send an appropriate status message if it is configured to do so.

Most of the functionality of the Light CTL server device is implemented in the Mesh Models Library. The application only needs to set hardware appropriately on receiving WICED_BT_MESH_LIGHT_CTL_STATUS event. If client requests to change the brightness or the color temperature to the target value over a period of time, the library will maintain the timer and will periodically call the application with appropriate values.

The default transition time is managed by the Mesh Models library. The application provides factory default in the default_transition_time element of the wiced_bt_mesh_core_config_t configuration structure. The default value is used unless overwritten by the default transition time client.

The on power up behavior is managed by the Mesh Models library. The application provides factory default in the onpowerup_state element of the wiced_bt_mesh_core_config_t configuration structure. The default value is used unless overwritten by the default transition time client.

Macro Definition Documentation

#define WICED_BT_MESH_MODEL_LIGHT_CTL_SERVER
Value:
{ MESH_COMPANY_ID_BT_SIG, WICED_BT_MESH_CORE_MODEL_ID_GENERIC_DEFTT_SRV, wiced_bt_mesh_model_default_transition_time_server_message_handler, NULL, NULL }, \
{ MESH_COMPANY_ID_BT_SIG, WICED_BT_MESH_CORE_MODEL_ID_SCENE_SRV, wiced_bt_mesh_model_scene_server_message_handler, NULL, NULL }, \
{ MESH_COMPANY_ID_BT_SIG, WICED_BT_MESH_CORE_MODEL_ID_SCENE_SETUP_SRV, wiced_bt_mesh_model_scene_setup_server_message_handler, NULL, NULL }, \
{ MESH_COMPANY_ID_BT_SIG, WICED_BT_MESH_CORE_MODEL_ID_GENERIC_ONOFF_SRV, wiced_bt_mesh_model_onoff_server_message_handler, NULL, NULL }, \
{ MESH_COMPANY_ID_BT_SIG, WICED_BT_MESH_CORE_MODEL_ID_GENERIC_POWER_ONOFF_SRV, wiced_bt_mesh_model_power_onoff_server_message_handler, NULL, NULL }, \
{ MESH_COMPANY_ID_BT_SIG, WICED_BT_MESH_CORE_MODEL_ID_GENERIC_POWER_ONOFF_SETUP_SRV, wiced_bt_mesh_model_power_onoff_setup_server_message_handler, NULL, NULL }, \
{ MESH_COMPANY_ID_BT_SIG, WICED_BT_MESH_CORE_MODEL_ID_GENERIC_LEVEL_SRV, wiced_bt_mesh_model_level_server_message_handler, NULL, NULL }, \
{ MESH_COMPANY_ID_BT_SIG, WICED_BT_MESH_CORE_MODEL_ID_LIGHT_LIGHTNESS_SRV, wiced_bt_mesh_model_light_lightness_server_message_handler, NULL, NULL }, \
{ MESH_COMPANY_ID_BT_SIG, WICED_BT_MESH_CORE_MODEL_ID_LIGHT_LIGHTNESS_SETUP_SRV, wiced_bt_mesh_model_light_lightness_setup_server_message_handler, NULL, NULL }, \
{ MESH_COMPANY_ID_BT_SIG, WICED_BT_MESH_CORE_MODEL_ID_LIGHT_CTL_SETUP_SRV, wiced_bt_mesh_model_light_ctl_setup_server_message_handler, NULL, NULL }
wiced_bool_t wiced_bt_mesh_model_power_onoff_setup_server_message_handler(wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
Power On/Off Setup Server Message Handler.
wiced_bool_t wiced_bt_mesh_model_light_lightness_server_message_handler(wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
Light Lightness Server Message Handler.
wiced_bool_t wiced_bt_mesh_model_default_transition_time_server_message_handler(wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
Default Transition Time Server Message Handler.
wiced_bool_t wiced_bt_mesh_model_light_lightness_setup_server_message_handler(wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
Light Lightness Setup Server Message Handler.
wiced_bool_t wiced_bt_mesh_model_scene_setup_server_message_handler(wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
Scene Setup Server Message Handler.
wiced_bool_t wiced_bt_mesh_model_light_ctl_setup_server_message_handler(wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
Light CTL Setup Server Message Handler.
wiced_bool_t wiced_bt_mesh_model_onoff_server_message_handler(wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
On/Off Server Message Handler.
wiced_bool_t wiced_bt_mesh_model_light_ctl_server_message_handler(wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
Light CTL Server Message Handler.
uint16_t wiced_bt_mesh_model_light_ctl_server_scene_recall_handler(uint8_t element_idx, uint8_t *p_buffer, uint16_t buffer_len, uint32_t transition_time, uint32_t delay)
Light CTL Server Scene Restore Handler.
wiced_bool_t wiced_bt_mesh_model_scene_server_message_handler(wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
Scene Server Message Handler.
wiced_bool_t wiced_bt_mesh_model_level_server_message_handler(wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
Level Server Message Handler.
wiced_bool_t wiced_bt_mesh_model_power_onoff_server_message_handler(wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
Power On/Off Server Message Handler.
uint16_t wiced_bt_mesh_model_light_ctl_server_scene_store_handler(uint8_t element_idx, uint8_t *p_buffer, uint16_t buffer_len)
Light CTL Server Scene Store Handler.

Mesh Light CTL Server Device.

The device implements all required models for the two elements of a color bulb that supports brightness and color temperature control. The WICED_BT_MESH_MODEL_LIGHT_CTL_TEMPERATURE_SERVER should be defined in the element with the higher index than one with WICED_BT_MESH_MODEL_LIGHT_CTL_SERVER, but before the next primary element of the device. For example, if application supports two CTL lights, the consecutive elements should be WICED_BT_MESH_MODEL_LIGHT_CTL_SERVER, WICED_BT_MESH_MODEL_LIGHT_CTL_SERVER, WICED_BT_MESH_MODEL_LIGHT_CTL_SERVER, WICED_BT_MESH_MODEL_LIGHT_CTL_SERVER. The time and scheduler models are optional and can be commented out to reduce memory footprint.

#define WICED_BT_MESH_MODEL_LIGHT_CTL_TEMPERATURE_SERVER
Value:
{ MESH_COMPANY_ID_BT_SIG, WICED_BT_MESH_CORE_MODEL_ID_GENERIC_LEVEL_SRV, wiced_bt_mesh_model_level_server_message_handler, NULL, NULL }, \
wiced_bool_t wiced_bt_mesh_model_light_ctl_temperature_server_message_handler(wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
Light CTL Temperature Server Message Handler.
uint16_t wiced_bt_mesh_model_light_ctl_temperature_server_scene_store_handler(uint8_t element_idx, uint8_t *p_buffer, uint16_t buffer_len)
Light CTL Temperature Server Scene Store Handler.
uint16_t wiced_bt_mesh_model_light_ctl_temperature_server_scene_recall_handler(uint8_t element_idx, uint8_t *p_buffer, uint16_t buffer_len, uint32_t transition_time, uint32_t delay)
Light Temperature Server Scene Restore Handler.
wiced_bool_t wiced_bt_mesh_model_level_server_message_handler(wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
Level Server Message Handler.

Typedef Documentation

typedef void( wiced_bt_mesh_light_ctl_server_callback_t)(uint8_t element_idx, uint16_t event, void *p_data)

Light CTL Server callback.

Light CTL Server callback is executed by the Mesh Models library when the application is required to adjust the amount of light emitted by the device or its color. The application is responsible for setting the hardware (for example, by controlling PWM) to comply with the values requested by the library.

If peer device requested to transition to the new brightness level over a period of time, the callback will be executed repeatedly. The Mesh Models Library calculates the present lightness level, color temperature and delta UV and submits to the application to setup the hardware.

The p_data parameter points to the wiced_bt_mesh_light_ctl_status_data_t structure. Typically the application will only need to use the value of the present lightness, temperature and delta_uv fields which specify the target values that the device shall be set at present time. If the remaining_time field is not zero, the transition to the new target level is in progress and the Mesh Models Library will execute the callback at least once more before the transition is completed.

Parameters
element_idxElement Index of the model
eventThe only event that the application should process is WICED_BT_MESH_LIGHT_CTL_STATUS
p_dataPointer to the wiced_bt_mesh_light_ctl_status_data_t structure
Returns
None

Function Documentation

void wiced_bt_mesh_model_light_ctl_server_init ( uint8_t  lightness_element_idx,
wiced_bt_mesh_light_ctl_server_callback_t p_callback,
wiced_bool_t  is_provisioned 
)

Light CTL Server Module initialization.

A Mesh application which contains Light CTL Server (for example, a dimmable bulb with color temperature control) should call this function during application initialization. The CTL functionality is split into two elements, the lightness and the color temperature. The initialization function should use the index of the primary - lightness element. If the application needs to support multiple CTL lights (for example, a light fixture or a chandelier), the function shall be called multiple times, once per each primary element.

Parameters
lightness_element_idxElement index where lightness part of the CTL is located
p_callbackApplication callback that will be executed to set device hardware to required brightness, color temperature, delta UV values.
is_provisionedIf TRUE, the application is being restarted after being provisioned or after a power loss. If FALSE the model cleans up NVRAM on startup.
Returns
WICED_TRUE if initialization was successful
wiced_bool_t wiced_bt_mesh_model_light_ctl_server_message_handler ( wiced_bt_mesh_event_t p_event,
uint8_t *  p_data,
uint16_t  data_len 
)

Light CTL Server Message Handler.

The Light CTL Server Message Handler is an internal Mesh Models library function and does not need to be implemented or called by the application, unless application wants to replace the library functionality. The Mesh Core library calls this function for each message received. The function shall return WICED_TRUE if the message is destined for this specific model and successfully processed, and returns WICED_FALSE otherwise.

Parameters
p_eventMesh event with information about received message.
p_dataPointer to the data portion of the message
data_lenLength of the data in the message
Returns
WICED_TRUE if the message is for this company ID/Model/Element Index combination, WICED_FALSE otherwise.
uint16_t wiced_bt_mesh_model_light_ctl_server_scene_recall_handler ( uint8_t  element_idx,
uint8_t *  p_buffer,
uint16_t  buffer_len,
uint32_t  transition_time,
uint32_t  delay 
)

Light CTL Server Scene Restore Handler.

The Light CTL Scene Restore Server Message Handler is an internal Mesh Models library function and does not need to be implemented or called by the application, unless application wants to replace the library functionality. When Scene Server receives Scene Recall message it calls this function with data previously stored in the NVRAM.

Parameters
element_idxElement index for which scene information is being recalled
p_bufferPointer to a buffer where model's data is located
buf_sizeMaximum amount of data a model can get from the buffer
transition_timeSpecified time in milliseconds to transition to the target state
delaySpecifies time in milliseconds before starting to transition to the target state
Returns
Number of bytes the model read from the provided buffer
uint16_t wiced_bt_mesh_model_light_ctl_server_scene_store_handler ( uint8_t  element_idx,
uint8_t *  p_buffer,
uint16_t  buffer_len 
)

Light CTL Server Scene Store Handler.

The Light CTL Scene Store Server Message Handler is an internal Mesh Models library function and does not need to be implemented or called by the application, unless application wants to replace the library functionality. The mesh Scene Server calls this function so that the module can store required data for the scene.

Parameters
element_idxElement index for which scene information is being stored
p_bufferPointer to a buffer where data should be stored
buf_sizeMaximum amount of data a model can store
Returns
Number of bytes the model wrote into the provided buffer
void wiced_bt_mesh_model_light_ctl_server_set_startup_controller ( uint8_t  element_idx,
wiced_bool_t  startup_controller 
)

Set Light CTL Model as a startup controller.

The Light CTL Scene Restore Server Message Handler is an internal Mesh Models library function and does not need to be implemented or called by the application, unless application wants to replace the library functionality. For multi-model applications, for example, when application supports both HSL and CTL controls, only one can be setup as a startup controller. If the controller mode is set, the library will execute the power on requirements, for example it can set the temperature, lightness based on the last set state. If the model is not set as a controller, it will not execute on power up state.

Parameters
element_idxThe element index of the top level model
startup_controllerIf set to WICED_TRUE, the model will execute On Power Up operation
Returns
None
void wiced_bt_mesh_model_light_ctl_server_state_changed ( uint8_t  element_idx,
wiced_bt_mesh_light_ctl_status_data_t p_data 
)

Light CTL state changed.

The application shall call the Light CTL state changed function to notify the Mesh Models library when values brightness, color temperature or delta UV are changed internally.

Parameters
element_idxElement index for which scene information is being recalled
p_dataPointer to the wiced_bt_mesh_light_ctl_status_data_t status data
Returns
None
wiced_bool_t wiced_bt_mesh_model_light_ctl_setup_server_message_handler ( wiced_bt_mesh_event_t p_event,
uint8_t *  p_data,
uint16_t  data_len 
)

Light CTL Setup Server Message Handler.

The Light CTL Server Message Handler is an internal Mesh Models library function and does not need to be implemented or called by the application, unless application wants to replace the library functionality. The Mesh Core library calls this function for each message received. The function shall return WICED_TRUE if the message is destined for this specific model and successfully processed, and returns WICED_FALSE otherwise.

Parameters
p_eventMesh event with information about received message.
p_dataPointer to the data portion of the message
data_lenLength of the data in the message
Returns
WICED_TRUE if the message is for this company ID/Model/Element Index combination, WICED_FALSE otherwise.
wiced_bool_t wiced_bt_mesh_model_light_ctl_temperature_server_message_handler ( wiced_bt_mesh_event_t p_event,
uint8_t *  p_data,
uint16_t  data_len 
)

Light CTL Temperature Server Message Handler.

The Light CTL Temperature Server Message Handler is an internal Mesh Models library function and does not need to be implemented or called by the application, unless application wants to replace the library functionality. The Mesh Core library calls this function for each message received. The function shall return WICED_TRUE if the message is destined for this specific model and successfully processed, and returns WICED_FALSE otherwise.

Parameters
p_eventMesh event with information about received message.
p_dataPointer to the data portion of the message
data_lenLength of the data in the message
Returns
WICED_TRUE if the message is for this company ID/Model/Element Index combination, WICED_FALSE otherwise.
uint16_t wiced_bt_mesh_model_light_ctl_temperature_server_scene_recall_handler ( uint8_t  element_idx,
uint8_t *  p_buffer,
uint16_t  buffer_len,
uint32_t  transition_time,
uint32_t  delay 
)

Light Temperature Server Scene Restore Handler.

The Light Temperature Scene Restore Server Message Handler is an internal Mesh Models library function and does not need to be implemented or called by the application, unless application wants to replace the library functionality. When Scene Server receives Scene Recall message it calls this function with data previously stored in the NVRAM. Note that if SCENE_SERVER is not implemented on the Light Temperature element, this function will be call internally by the parent Light Ctl Server

Parameters
element_idxElement index for which scene information is being recalled
p_bufferPointer to a buffer where model's data is located
buf_sizeMaximum amount of data a model can get from the buffer
transition_timeSpecified time in milliseconds to transition to the target state
delaySpecifies time in milliseconds before starting to transition to the target state
Returns
Number of bytes the model read from the provided buffer
uint16_t wiced_bt_mesh_model_light_ctl_temperature_server_scene_store_handler ( uint8_t  element_idx,
uint8_t *  p_buffer,
uint16_t  buffer_len 
)

Light CTL Temperature Server Scene Store Handler.

The Light CTL Scene Store Server Message Handler is an internal Mesh Models library function and does not need to be implemented or called by the application, unless application wants to replace the library functionality. The mesh Scene Server calls this function so that the module can store required data for the scene. Note that if Scene Server is not present on CTL Temperature Server, this function will be called by the internally by the CTL Server

Parameters
element_idxElement index for which scene information is being stored
p_bufferPointer to a buffer where data should be stored
buf_sizeMaximum amount of data a model can store
Returns
Number of bytes the model wrote into the provided buffer