Mesh Light HSL Server

The AIROC Mesh Hue Saturation Lightness (HSL) Server module provides a way for an application to implement a dimmable light device with hue/saturation support. More...

Macros
#define	WICED_BT_MESH_MODEL_LIGHT_HSL_SERVER
	Mesh Light HSL Server device definition. More...
#define	WICED_BT_MESH_MODEL_LIGHT_HSL_HUE_SERVER
#define	WICED_BT_MESH_MODEL_LIGHT_HSL_SATURATION_SERVER

Typedefs
typedef void(	wiced_bt_mesh_light_hsl_server_callback_t )(uint8_t element_idx, uint16_t event, void *p_data)
	Light HSL Server callback. More...

Functions
void	wiced_bt_mesh_model_light_hsl_server_init (uint8_t lightness_element_idx, wiced_bt_mesh_light_hsl_server_callback_t *p_callback, wiced_bool_t is_provisioned)
	Light HSL Server Module initialization. More...
void	wiced_bt_mesh_model_light_hsl_server_state_changed (uint8_t element_idx, wiced_bt_mesh_light_hsl_status_data_t *p_data)
	Light HSL state changed. More...
wiced_bool_t	wiced_bt_mesh_model_light_hsl_server_message_handler (wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
	Light HSL Server Message Handler. More...
wiced_bool_t	wiced_bt_mesh_model_light_hsl_setup_server_message_handler (wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
	Light HSL Setup Server Message Handler. More...
wiced_bool_t	wiced_bt_mesh_model_light_hsl_hue_server_message_handler (wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
	Light HSL Hue Server Message Handler. More...
wiced_bool_t	wiced_bt_mesh_model_light_hsl_saturation_server_message_handler (wiced_bt_mesh_event_t *p_event, uint8_t *p_data, uint16_t data_len)
	Light HSL Saturation Server Message Handler. More...
uint16_t	wiced_bt_mesh_model_light_hsl_server_scene_store_handler (uint8_t element_idx, uint8_t *p_buffer, uint16_t buffer_len)
	Light HSL Server Scene Store Handler. More...
uint16_t	wiced_bt_mesh_model_light_hsl_server_scene_recall_handler (uint8_t element_idx, uint8_t *p_buffer, uint16_t buffer_len, uint32_t transition_time, uint32_t delay)
	Light HSL Server Scene Recall Handler. More...
void	wiced_bt_mesh_model_light_hsl_server_set_startup_controller (uint8_t element_idx, wiced_bool_t startup_controller)
	Set Light HSL Model as a startup controller. More...

Detailed Description

The AIROC Mesh Hue Saturation Lightness (HSL) Server module provides a way for an application to implement a dimmable light device with hue/saturation support.

The device can be controlled by a device with rich UI which can control the brightness, hue and saturation, but also the device can be can be controlled using a Level sliders (Generic Level client) applied to the brightness, hue or saturation 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 HSL Server spans three elements. To include the Mesh Models support for the HSL Server module the application includes the WICED_BT_MESH_MODEL_LIGHT_HSL_SERVER, the WICED_BT_MESH_MODEL_LIGHT_HSL_HUE_SERVER, and the WICED_BT_MESH_MODEL_LIGHT_HSL_SATURATION_SERVER in three consecutive elements in the device definition. If the device supports several lights with HSL Server support, for example, a light fixture or a chandelier with several color lights, the triplet of WICED_BT_MESH_MODEL_LIGHT_HSL_SERVER, WICED_BT_MESH_MODEL_LIGHT_HSL_HUE_SERVER and WICED_BT_MESH_MODEL_LIGHT_HSL_SATURATION_SERVER shall be repeated for each physical device.

In addition to the definition, the application shall initialize the HSL Server module by calling wiced_bt_mesh_model_light_hsl_server_init function for each primary element where the HSL functionality is required providing the wiced_bt_mesh_light_hsl_server_callback_t callback that will be executed when the brightness level, the hue or the saturation of the device needs to be changed.

If device supports local control, for example, when the brightness of the device can be changed locally, the application should call the wiced_bt_mesh_model_light_hsl_status_changed function 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 HSL server device is implemented in the Mesh Models Library. The application only needs to set hardware appropriately on receiving WICED_BT_MESH_LIGHT_HSL_STATUS event. If a client requests to change the brightness or the color to the target values 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_HSL_HUE_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 }, \
    { MESH_COMPANY_ID_BT_SIG, WICED_BT_MESH_CORE_MODEL_ID_LIGHT_HSL_HUE_SRV, wiced_bt_mesh_model_light_hsl_hue_server_message_handler, NULL, NULL }

#define WICED_BT_MESH_MODEL_LIGHT_HSL_SATURATION_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 }, \
    { MESH_COMPANY_ID_BT_SIG, WICED_BT_MESH_CORE_MODEL_ID_LIGHT_HSL_SATURATION_SRV, wiced_bt_mesh_model_light_hsl_saturation_server_message_handler, NULL, NULL }

#define WICED_BT_MESH_MODEL_LIGHT_HSL_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_HSL_SRV, wiced_bt_mesh_model_light_hsl_server_message_handler, wiced_bt_mesh_model_light_hsl_server_scene_store_handler, wiced_bt_mesh_model_light_hsl_server_scene_recall_handler }, \
    { MESH_COMPANY_ID_BT_SIG, WICED_BT_MESH_CORE_MODEL_ID_LIGHT_HSL_SETUP_SRV, wiced_bt_mesh_model_light_hsl_setup_server_message_handler, NULL, NULL }

Mesh Light HSL Server device definition.

The Mesh Light HSL Server device implements all required models for the primary, hue and saturation elements of a color bulb that supports brightness, hue and saturation control. The WICED_BT_MESH_MODEL_LIGHT_HSL_HUE_SERVER and WICED_BT_MESH_MODEL_LIGHT_HSL_SATURATION_SERVER should be defined in the element with the higher index than one with WICED_BT_MESH_MODEL_LIGHT_HSL_SERVER, but before the next primary element of the device. For example, if application supports one HSL and one dimmable light, the consecutive elements should be WICED_BT_MESH_MODEL_LIGHT_HSL_SERVER, WICED_BT_MESH_MODEL_LIGHT_HSL_HUE_SERVER, WICED_BT_MESH_MODEL_LIGHT_HSL_SATURATION_SERVER, WICED_BT_MESH_MODEL_LIGHT_LIGHTNESS_SERVER. The time and scheduler models are optional and can be commented out to reduce memory footprint.

Typedef Documentation

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

Light HSL Server callback.

Light HSL 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, hue or saturation level over a period of time, the callback will be executed repeatedly. The Mesh Models Library calculates the present levels and submits to the application to setup the hardware.

The p_data parameter points to the wiced_bt_mesh_light_hsl_status_data_t structure. Typically the application will only need to use the value of the present lightness, hue and saturation 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 levels is in progress and the Mesh Models Library will execute the callback at least once more before the transition is completed.

Parameters

element_idx	Element index of the primary element
event	The only event that the application should process is WICED_BT_MESH_LIGHT_HSL_STATUS
p_data	Pointer to the wiced_bt_mesh_light_hsl_status_data_t structure

Returns

None

Function Documentation

wiced_bool_t wiced_bt_mesh_model_light_hsl_hue_server_message_handler	(	wiced_bt_mesh_event_t *	p_event,
		uint8_t *	p_data,
		uint16_t	data_len
	)

Light HSL Hue Server Message Handler.

The Light HSL Hue 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 returns WICED_TRUE if the message is destined for this specific model, and returns WICED_FALSE otherwise.

Parameters

p_event	Mesh event with information about received message.
p_data	Pointer to the data portion of the message
data_len	Length 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_hsl_saturation_server_message_handler	(	wiced_bt_mesh_event_t *	p_event,
		uint8_t *	p_data,
		uint16_t	data_len
	)

Light HSL Saturation Server Message Handler.

The Light HSL Saturation 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 returns WICED_TRUE if the message is destined for this specific model, and returns WICED_FALSE otherwise.

Parameters

p_event	Mesh event with information about received message.
p_data	Pointer to the data portion of the message
data_len	Length of the data in the message

Returns

WICED_TRUE if the message is for this company ID/Model/Element Index combination, WICED_FALSE otherwise.

void wiced_bt_mesh_model_light_hsl_server_init	(	uint8_t	lightness_element_idx,
		wiced_bt_mesh_light_hsl_server_callback_t *	p_callback,
		wiced_bool_t	is_provisioned
	)

Light HSL Server Module initialization.

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

Parameters

lightness_element_idx	Element index where lightness part of the HSL is located.
p_callback	Application callback that will be executed to set device hardware to required brightness, hue, saturation values.
is_provisioned	If 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_hsl_server_message_handler	(	wiced_bt_mesh_event_t *	p_event,
		uint8_t *	p_data,
		uint16_t	data_len
	)

Light HSL Server Message Handler.

The Light HSL 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_event	Mesh event with information about received message.
p_data	Pointer to the data portion of the message
data_len	Length 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_hsl_server_scene_recall_handler	(	uint8_t	element_idx,
		uint8_t *	p_buffer,
		uint16_t	buffer_len,
		uint32_t	transition_time,
		uint32_t	delay
	)

Light HSL Server Scene Recall Handler.

The Light HSL Server Recall 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_idx	Element index for which scene information is being recalled
p_buffer	Pointer to a buffer where model's data is located
buf_size	Maximum amount of data a model can get from the buffer
transition_time	Specified time in milliseconds to transition to the target state
delay	Specifies 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_hsl_server_scene_store_handler	(	uint8_t	element_idx,
		uint8_t *	p_buffer,
		uint16_t	buffer_len
	)

Light HSL Server Scene Store Handler.

The Light HSL Server Store 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_idx	Element index for which scene information is being stored
p_buffer	Pointer to a buffer where data should be stored
buf_size	Maximum amount of data a model can store

Returns

Number of bytes the model wrote into the provided buffer

void wiced_bt_mesh_model_light_hsl_server_set_startup_controller	(	uint8_t	element_idx,
		wiced_bool_t	startup_controller
	)

Set Light HSL Model as a startup controller.

This 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 the ones that support 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 lightness/hue/saturation based on the last state before the power off. If the model is not set as a controller, it will not execute on power up state.

Parameters

element_idx	The element index of the top level model
startup_controller	If set to WICED_TRUE, the model will execute on power up operation

Returns

None

void wiced_bt_mesh_model_light_hsl_server_state_changed	(	uint8_t	element_idx,
		wiced_bt_mesh_light_hsl_status_data_t *	p_data
	)

Light HSL state changed.

The application shall call the Light HSL state changed function to notify the Mesh Models library when values brightness, hue or saturation are changed internally.

Parameters

element_idx	Element index for the lightness part of the HSL device
p_data	Pointer to the wiced_bt_mesh_light_hsl_status_data_t status data

Returns

None

wiced_bool_t wiced_bt_mesh_model_light_hsl_setup_server_message_handler	(	wiced_bt_mesh_event_t *	p_event,
		uint8_t *	p_data,
		uint16_t	data_len
	)

Light HSL Setup Server Message Handler.

The Light HSL 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_event	Mesh event with information about received message.
p_data	Pointer to the data portion of the message
data_len	Length of the data in the message

Returns

WICED_TRUE if the message is for this company ID/Model/Element Index combination, WICED_FALSE otherwise.