Light CTL Setup Server model interface

nRF5 SDK for Mesh v5.0.0
Data Structures | Macros | Typedefs | Functions

This model is defined as a top level model in the SDK to enable implementation of the tunable white light. More...

Data Structures

struct  light_ctl_setup_server_state_cbs_t
 Transaction callbacks for the Light CTL states. More...
 
struct  light_ctl_server_settings_t
 User provided settings and callbacks for the Light CTL server model instance. More...
 
struct  light_ctl_server_t
 Forward declaration for __light_ctl_server_t. More...
 
struct  light_ctl_temperature_server_settings_t
 User provided settings and callbacks for the CTL temperature model instance. More...
 
struct  light_ctl_temperature_server_t
 
struct  light_ctl_setup_server_callbacks_t
 Light CTL server callback list. More...
 
struct  light_ctl_setup_server_settings_t
 User provided settings and callbacks for the Light CTL Setup Server model instance. More...
 
struct  light_ctl_state_t
 Internal structure to hold state information. More...
 
struct  light_ctl_setup_server_t
 

Macros

#define LIGHT_CTL_SERVER_MODEL_ID   (0x1303)
 Server model ID.
 
#define LIGHT_CTL_SETUP_SERVER_MODEL_ID   (0x1304)
 Setup server model ID.
 
#define LIGHT_CTL_TEMPERATURE_SERVER_MODEL_ID   (0x1306)
 Temperature server model ID.
 

Typedefs

typedef void(* light_ctl_state_set_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, const light_ctl_set_params_t *p_in, const model_transition_t *p_in_transition, light_ctl_status_params_t *p_out)
 Callback type for the Light CTL Set/Set Unacknowledged message. More...
 
typedef void(* light_ctl_state_get_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, light_ctl_status_params_t *p_out)
 Callback type for the Light CTL Get message. More...
 
typedef void(* light_ctl_state_temperature32_set_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, const light_ctl_temperature_set_params_t *p_in, const model_transition_t *p_in_transition, light_ctl_temperature_status_params_t *p_out)
 Callback type for the Light CTL Temperature Set/Set Unacknowledged message. More...
 
typedef void(* light_ctl_state_temperature32_get_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, light_ctl_temperature_status_params_t *p_out)
 Callback type for Light CTL Temperature Get message. More...
 
typedef void(* light_ctl_state_temperature32_range_set_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, const light_ctl_temperature_range_set_params_t *p_in, light_ctl_temperature_range_status_params_t *p_out)
 Callback type for the Light CTL Temperature Range Set/Set Unacknowledged message. More...
 
typedef void(* light_ctl_state_temperature32_range_get_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, light_ctl_temperature_range_status_params_t *p_out)
 Callback type for the Light CTL Temperature Range Get message. More...
 
typedef void(* light_ctl_state_default_set_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, const light_ctl_default_set_params_t *p_in, light_ctl_default_status_params_t *p_out)
 Callback type for the Light CTL Default Set/Set Unacknowledged message. More...
 
typedef void(* light_ctl_state_default_get_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, light_ctl_default_status_params_t *p_out)
 Callback type for the Light CTL Default Get message. More...
 
typedef void(* light_ctl_state_move_set_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, const light_ctl_temperature_move_set_params_t *p_in, const model_transition_t *p_in_transition, light_ctl_temperature_status_params_t *p_out)
 Callback type for the Light CTL move Set/Set Unacknowledged "message". More...
 
typedef void(* light_ctl_state_delta_set_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, const light_ctl_temperature_delta_set_params_t *p_in, const model_transition_t *p_in_transition, light_ctl_temperature_status_params_t *p_out)
 Callback type for the Light CTL delta Set/Set Unacknowledged "message". More...
 

Functions

uint32_t light_ctl_server_status_publish (const light_ctl_server_t *p_server, const light_ctl_status_params_t *p_params)
 Publishes unsolicited Status message. More...
 
uint32_t light_ctl_server_temperature_status_publish (const light_ctl_temperature_server_t *p_server, const light_ctl_temperature_status_params_t *p_params)
 Publishes unsolicited Status message. More...
 
uint32_t light_ctl_server_temperature_range_status_publish (const light_ctl_server_t *p_server, const light_ctl_temperature_range_status_params_t *p_params)
 Publishes unsolicited Status message. More...
 
uint32_t light_ctl_server_default_status_publish (const light_ctl_server_t *p_server, const light_ctl_default_status_params_t *p_params)
 Publishes unsolicited Status message. More...
 
uint32_t light_ctl_setup_server_init (light_ctl_setup_server_t *p_s_server, light_lightness_setup_server_t *p_ll_s_server, uint8_t element_index)
 Initializes the Light CTL Setup server. More...
 
uint32_t light_ctl_ponoff_binding_setup (light_ctl_setup_server_t *p_s_server, light_ctl_saved_values_t *p_saved_values)
 Function to do the OnPowerup binding. More...
 

Detailed Description

This model is defined as a top level model in the SDK to enable implementation of the tunable white light.

This model implements Light CTL Server, Light CTL Temperature Server, and Generic Level Server models. This model requires an instance of Light Lightness Setup Server to be initialized seperately and provided as an input during initialization.

Typedef Documentation

◆ light_ctl_state_set_cb_t

typedef void(* light_ctl_state_set_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, const light_ctl_set_params_t *p_in, const model_transition_t *p_in_transition, light_ctl_status_params_t *p_out)

Callback type for the Light CTL Set/Set Unacknowledged message.

Parameters
[in]p_selfPointer to the model structure.
[in]p_metaAccess metadata for the received message.
[in]p_inPointer to the input parameters for the user application.
[in]p_in_transitionPointer to transition parameters, if present in the incoming message, otherwise set to null.
[out]p_outPointer to store the output parameters from the user application. If null, indicates that it is UNACKNOWLEDGED message and no output params are required.

Definition at line 95 of file light_ctl_setup_server.h.

◆ light_ctl_state_get_cb_t

typedef void(* light_ctl_state_get_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, light_ctl_status_params_t *p_out)

Callback type for the Light CTL Get message.

Parameters
[in]p_selfPointer to the model structure.
[in]p_metaAccess metadata for the received message.
[out]p_outPointer to store the output parameters from the user application.

Definition at line 108 of file light_ctl_setup_server.h.

◆ light_ctl_state_temperature32_set_cb_t

typedef void(* light_ctl_state_temperature32_set_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, const light_ctl_temperature_set_params_t *p_in, const model_transition_t *p_in_transition, light_ctl_temperature_status_params_t *p_out)

Callback type for the Light CTL Temperature Set/Set Unacknowledged message.

Parameters
[in]p_selfPointer to the model structure.
[in]p_metaAccess metadata for the received message.
[in]p_inPointer to the input parameters for the user application.
[in]p_in_transitionPointer to transition parameters, if present in the incoming message, otherwise set to null.
[out]p_outPointer to store the output parameters from the user application. If null, indicates that it is UNACKNOWLEDGED message and no output params are required.

Definition at line 124 of file light_ctl_setup_server.h.

◆ light_ctl_state_temperature32_get_cb_t

typedef void(* light_ctl_state_temperature32_get_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, light_ctl_temperature_status_params_t *p_out)

Callback type for Light CTL Temperature Get message.

Parameters
[in]p_selfPointer to the model structure.
[in]p_metaAccess metadata for the received message.
[out]p_outPointer to store the output parameters from the user application.

Definition at line 137 of file light_ctl_setup_server.h.

◆ light_ctl_state_temperature32_range_set_cb_t

typedef void(* light_ctl_state_temperature32_range_set_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, const light_ctl_temperature_range_set_params_t *p_in, light_ctl_temperature_range_status_params_t *p_out)

Callback type for the Light CTL Temperature Range Set/Set Unacknowledged message.

Parameters
[in]p_selfPointer to the model structure.
[in]p_metaAccess metadata for the received message.
[in]p_inPointer to the input parameters for the user application.
[out]p_outPointer to store the output parameters from the user application. If null, indicates that it is UNACKNOWLEDGED message and no output params are required.

Definition at line 151 of file light_ctl_setup_server.h.

◆ light_ctl_state_temperature32_range_get_cb_t

typedef void(* light_ctl_state_temperature32_range_get_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, light_ctl_temperature_range_status_params_t *p_out)

Callback type for the Light CTL Temperature Range Get message.

Parameters
[in]p_selfPointer to the model structure.
[in]p_metaAccess metadata for the received message.
[out]p_outPointer to store the output parameters from the user application.

Definition at line 163 of file light_ctl_setup_server.h.

◆ light_ctl_state_default_set_cb_t

typedef void(* light_ctl_state_default_set_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, const light_ctl_default_set_params_t *p_in, light_ctl_default_status_params_t *p_out)

Callback type for the Light CTL Default Set/Set Unacknowledged message.

Parameters
[in]p_selfPointer to the model structure.
[in]p_metaAccess metadata for the received message.
[in]p_inPointer to the input parameters for the user application.
[out]p_outPointer to store the output parameters from the user application. If null, indicates that it is UNACKNOWLEDGED message and no output params are required.

Definition at line 177 of file light_ctl_setup_server.h.

◆ light_ctl_state_default_get_cb_t

typedef void(* light_ctl_state_default_get_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, light_ctl_default_status_params_t *p_out)

Callback type for the Light CTL Default Get message.

Parameters
[in]p_selfPointer to the model structure.
[in]p_metaAccess metadata for the received message.
[out]p_outPointer to store the output parameters from the user application.

Definition at line 189 of file light_ctl_setup_server.h.

◆ light_ctl_state_move_set_cb_t

typedef void(* light_ctl_state_move_set_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, const light_ctl_temperature_move_set_params_t *p_in, const model_transition_t *p_in_transition, light_ctl_temperature_status_params_t *p_out)

Callback type for the Light CTL move Set/Set Unacknowledged "message".

This isn't a real message, but CTL converts a level move set to this to allow the app layer to properly handle level move functionality

Parameters
[in]p_selfPointer to the model structure.
[in]p_metaAccess metadata for the received message.
[in]p_inPointer to the input parameters for the user application.
[in]p_in_transitionPointer to transition parameters, if present in the incoming message, otherwise set to null.
[out]p_outPointer to store the output parameters from the user application. If null, indicates that it is UNACKNOWLEDGED message and no output params are required.

Definition at line 209 of file light_ctl_setup_server.h.

◆ light_ctl_state_delta_set_cb_t

typedef void(* light_ctl_state_delta_set_cb_t) (const light_ctl_setup_server_t *p_self, const access_message_rx_meta_t *p_meta, const light_ctl_temperature_delta_set_params_t *p_in, const model_transition_t *p_in_transition, light_ctl_temperature_status_params_t *p_out)

Callback type for the Light CTL delta Set/Set Unacknowledged "message".

This isn't a real message, but CTL converts a level delta set to this to allow the app layer to properly handle level delta functionality

Parameters
[in]p_selfPointer to the model structure.
[in]p_metaAccess metadata for the received message.
[in]p_inPointer to the input parameters for the user application.
[in]p_in_transitionPointer to transition parameters, if present in the incoming message, otherwise set to null.
[out]p_outPointer to store the output parameters from the user application. If null, indicates that it is UNACKNOWLEDGED message and no output params are required.

Definition at line 230 of file light_ctl_setup_server.h.

Function Documentation

◆ light_ctl_server_status_publish()

uint32_t light_ctl_server_status_publish ( const light_ctl_server_t *  p_server,
const light_ctl_status_params_t *  p_params 
)

Publishes unsolicited Status message.

This API can be used to send unsolicited messages to report updated state value as a result of local action.

Parameters
[in]p_serverStatus server context pointer.
[in]p_paramsMessage parameters.
Return values
NRF_SUCCESSIf the message is published successfully.
NRF_ERROR_NULLIf NULL pointer is provided as input context.
NRF_ERROR_NO_MEMNot enough memory available for message publication.
NRF_ERROR_NOT_FOUNDInvalid model handle or model not bound to element.
NRF_ERROR_INVALID_PARAMModel not bound to appkey, publish address not set or wrong opcode format.
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 the publish address (if force segmentation is enabled). Wait for the transmission to finish.

◆ light_ctl_server_temperature_status_publish()

uint32_t light_ctl_server_temperature_status_publish ( const light_ctl_temperature_server_t *  p_server,
const light_ctl_temperature_status_params_t *  p_params 
)

Publishes unsolicited Status message.

This API can be used to send unsolicited messages to report updated state value as a result of local action.

Parameters
[in]p_serverStatus server context pointer.
[in]p_paramsMessage parameters.
Return values
NRF_SUCCESSIf the message is published successfully.
NRF_ERROR_NULLIf NULL pointer is provided as input context.
NRF_ERROR_NO_MEMNot enough memory available for message publication.
NRF_ERROR_NOT_FOUNDInvalid model handle or model not bound to element.
NRF_ERROR_INVALID_PARAMModel not bound to appkey, publish address not set or wrong opcode format.
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 the publish address (if force segmentation is enabled). Wait for the transmission to finish.

◆ light_ctl_server_temperature_range_status_publish()

uint32_t light_ctl_server_temperature_range_status_publish ( const light_ctl_server_t *  p_server,
const light_ctl_temperature_range_status_params_t *  p_params 
)

Publishes unsolicited Status message.

This API can be used to send unsolicited messages to report updated state value as a result of local action.

Parameters
[in]p_serverStatus server context pointer.
[in]p_paramsMessage parameters.
Return values
NRF_SUCCESSIf the message is published successfully.
NRF_ERROR_NULLIf NULL pointer is provided as input context.
NRF_ERROR_NO_MEMNot enough memory available for message publication.
NRF_ERROR_NOT_FOUNDInvalid model handle or model not bound to element.
NRF_ERROR_INVALID_PARAMModel not bound to appkey, publish address not set or wrong opcode format.
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 the publish address (if force segmentation is enabled). Wait for the transmission to finish.

◆ light_ctl_server_default_status_publish()

uint32_t light_ctl_server_default_status_publish ( const light_ctl_server_t *  p_server,
const light_ctl_default_status_params_t *  p_params 
)

Publishes unsolicited Status message.

This API can be used to send unsolicited messages to report updated state value as a result of local action.

Parameters
[in]p_serverStatus server context pointer.
[in]p_paramsMessage parameters.
Return values
NRF_SUCCESSIf the message is published successfully.
NRF_ERROR_NULLIf NULL pointer is provided as input context.
NRF_ERROR_NO_MEMNot enough memory available for message publication.
NRF_ERROR_NOT_FOUNDInvalid model handle or model not bound to element.
NRF_ERROR_INVALID_PARAMModel not bound to appkey, publish address not set or wrong opcode format.
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 the publish address (if force segmentation is enabled). Wait for the transmission to finish.

◆ light_ctl_setup_server_init()

uint32_t light_ctl_setup_server_init ( light_ctl_setup_server_t *  p_s_server,
light_lightness_setup_server_t *  p_ll_s_server,
uint8_t  element_index 
)

Initializes the Light CTL Setup server.

Note
The server handles the model allocation and adding.
Parameters
[in]p_s_serverLight CTL server context pointer.
[in]p_ll_s_serverLight Lightness context pointer.
[in]element_indexElement index to add the ctl and ctl setup server models to.

The light lightness context pointer is used to obtain the model handles for all of the light lightness and extended models for subscription list sharing.

Note
This model spans two elements and the API will initialize use secondary element (Temperature element) as next higher element. This helps the third party provisioners to easily identify the Light CTL Setup Server model in its entirety.
Return values
NRF_SUCCESSIf the model is initialized successfully.
NRF_ERROR_NULLIf NULL pointer is provided as input context.
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) or no more CTL Setup Server instances can be initialized (see LIGHT_CTL_SETUP_SERVER_INSTANCES_MAX).
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_STATEIf module is unable to initialize the storage for CTL states.

◆ light_ctl_ponoff_binding_setup()

uint32_t light_ctl_ponoff_binding_setup ( light_ctl_setup_server_t *  p_s_server,
light_ctl_saved_values_t *  p_saved_values 
)

Function to do the OnPowerup binding.

The caller is responsible for reading the saved state values out of flash and pass those so this function can determine what the current lightness should be set to.

Parameters
[in]p_s_serverLight CTL server context pointer.
[in]p_saved_valuesPointer to the structure containing the restored flash value" of the CTL states.
Return values
NRF_SUCCESSIf binding operation is performed successfully.
NRF_ERROR_NULLIf NULL pointer is provided as input context.
NRF_ERROR_INVALID_DATAIf OnPowerUp state value (see generic_on_powerup_values_t) is not within range.