Application level Scene server behavioral structures, functions, and callbacks. More...

Data Structures
struct	app_scene_state_t
	Internal structure to hold state. More...

struct	app_scene_callbacks_t

struct	app_scene_model_interface_t

struct	app_scene_setup_server_t
	Application level structure holding the Scene server model context and sensor state representation. More...

Macros
#define	APP_SCENE_SETUP_SERVER_DEF(_name, _force_segmented, _mic_size, _transition_cb, _p_dtt_server)
	Macro to create application level app_scene_setup_server_t context. More...

#define	APP_SCENE_MODEL_COUNT (1)
	Number of Scene Models to support storage.

Typedefs
typedef void(*	app_scene_transition_cb_t) (const app_scene_setup_server_t *p_app, uint32_t transition_time_ms, uint16_t target_scene)
	Application transition time callback prototype. More...

typedef void(*	app_scene_store_cb_t) (const app_scene_model_interface_t *p_app_model_if, uint8_t scene_index)
	Application Scene state store callback prototype. More...

typedef void(*	app_scene_recall_cb_t) (const app_scene_model_interface_t *p_app_model_if, uint8_t scene_index, uint32_t delay_ms, uint32_t transition_time_ms)
	Application Scene state recall callback prototype. More...

typedef void(*	app_scene_delete_cb_t) (const app_scene_model_interface_t *p_app_model_if, uint8_t scene_index)
	Application Scene state delete callback prototype. More...

Functions
uint32_t	app_scene_model_init (app_scene_setup_server_t *p_app, uint8_t element_index)
	Initializes the behavioral module for the Scene model. More...

uint32_t	app_scene_model_add (app_scene_setup_server_t p_app, app_scene_model_interface_t p_app_scene_model_interface)
	The API is to be called by application to register a model which is to be stored with scene. More...

void	app_scene_model_scene_changed (app_scene_setup_server_t *p_app)
	This API is called by the behavioral modules of other models to inform that the current state of the device has been changed. More...

Detailed Description

Application level Scene server behavioral structures, functions, and callbacks.

This module implements the behavioral requirements of the Scene Setup Server model.

The Scene server requires a composite state for the Scene Register state, the Current Scene state, and the Target Scene state. The application should use the store/delete callback provided by this module to store/delete scenes states. The Scene is determined by the model associated with the scene. The values of the states that are stored as a scene and can be recalled later.

This module triggers the recall callback only when it determines that it is time to inform the user application about a model transition. The Scenes state change may start numerous parallel model transitions. Each model handles the transition internally. The scene transions is in progress when at least one transition from the group of individual model transitions is in progress

These callbacks should be implemented by those models that should be stored with scenes (see "Stored with Scene" column in Bluetooth Mesh Model Specification (MshMDLv1.0.1) for each model).

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 5.1.3 (Scenes) and section 5.2.2 (Scene messages).

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

Macro Definition Documentation

◆ APP_SCENE_SETUP_SERVER_DEF

#define APP_SCENE_SETUP_SERVER_DEF	(	_name,
		_force_segmented,
		_mic_size,
		_transition_cb,
		_p_dtt_server
	)

Value:

; \
 APP_TIMER_DEF(_name ## _timer); \
 static app_scene_setup_server_t _name = \
 { \
 .scene_setup_server.settings.force_segmented = _force_segmented, \
 .scene_setup_server.settings.transmic_size = _mic_size, \
 .state.transition.timer.p_timer_id = &_name ## _timer, \
 .app_scene_transition_cb = _transition_cb, \
 .scene_setup_server.p_gen_dtt_server = _p_dtt_server \
 };

Macro to create application level app_scene_setup_server_t context.

Individual timer instances are created for each model instance.

Parameters

[in]	_name	Name of the app_scene_server_t instance
[in]	_force_segmented	If the Scene server shall use force segmentation of messages
[in]	_mic_size	MIC size to be used by Scene server
[in]	_transition_cb	Callback for setting the application transition time and state value to given values.
[in]	_p_dtt_server	Pointer to default transition time server instance.

Definition at line 89 of file app_scene.h.

Typedef Documentation

◆ app_scene_transition_cb_t

typedef void(* app_scene_transition_cb_t) (const app_scene_setup_server_t *p_app, uint32_t transition_time_ms, uint16_t target_scene)

Application 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, depending on the received target onoff value and timing parameters.

Parameters

[in]	p_app	Pointer to [app_scene_setup_server_t](__app_scene_setup_server_t) context.
[in]	transition_time_ms	Transition time (in milliseconds) to be used by the application.
[in]	target_scene	Target scene number value to be used by the application.

Definition at line 138 of file app_scene.h.

◆ app_scene_store_cb_t

typedef void(* app_scene_store_cb_t) (const app_scene_model_interface_t *p_app_model_if, uint8_t scene_index)

Application Scene state store callback prototype.

This callback is called by this module whenever the application is required to be informed to reflect the desired scene number to be stored. All the register applications models will also store the state values for this scene number.

Parameters

[in]	p_app_model_if	Pointer to [app_scene_model_interface_t] (__app_scene_model_interface_t) context.
[in]	scene_index	Scene index extraced from storage based on scene number to be stored.

Definition at line 153 of file app_scene.h.

◆ app_scene_recall_cb_t

typedef void(* app_scene_recall_cb_t) (const app_scene_model_interface_t *p_app_model_if, uint8_t scene_index, uint32_t delay_ms, uint32_t transition_time_ms)

Application Scene state recall callback prototype.

This callback is called by this module whenever the application is required to be informed to reflect the desired scene number to be recalled. All the register applications models will also recall the state values for this scene number.

Parameters

[in]	p_app_model_if	Pointer to [app_scene_model_interface_t] (__app_scene_model_interface_t) context.
[in]	scene_index	Scene index extraced from storage based on scene number to be recalled.
[in]	delay_ms	Delay in milliseconds.
[in]	transition_time_ms	Transition time in milliseconds.

Definition at line 171 of file app_scene.h.

◆ app_scene_delete_cb_t

typedef void(* app_scene_delete_cb_t) (const app_scene_model_interface_t *p_app_model_if, uint8_t scene_index)

Application Scene state delete callback prototype.

This callback is called by this module whenever the application is required to be informed to reflect the desired scene number to be deleted. All the register applications models will also delete the state values for this scene number.

Parameters

[in]	p_app_model_if	Pointer to [app_scene_model_interface_t] (__app_scene_model_interface_t) context.
[in]	scene_index	Scene index extraced from storage based on scene number to be deleted.

Definition at line 187 of file app_scene.h.

Function Documentation

◆ app_scene_model_init()

uint32_t app_scene_model_init	(	app_scene_setup_server_t *	p_app,
		uint8_t	element_index
	)

Initializes the behavioral module for the Scene model.

Parameters

[in]	p_app	Pointer to [app_scene_setup_server_t](__app_scene_setup_server_t) context.
[in]	element_index	Element index on which this server will be instantiated.

Return values

NRF_SUCCESS	The model is initialized successfully.
NRF_ERROR_NULL	NULL pointer is supplied to the function or to the required member variable pointers.
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.

◆ app_scene_model_add()

uint32_t app_scene_model_add	(	app_scene_setup_server_t *	p_app,
		app_scene_model_interface_t *	p_app_scene_model_interface
	)

The API is to be called by application to register a model which is to be stored with scene.

Parameters

[in]	p_app	Pointer to [app_scene_setup_server_t](__app_scene_setup_server_t) context.
[in]	p_app_scene_model_interface	Pointer to model that should be registered with scene storage.

Return values

NRF_SUCCESS	The model is initialized successfully.
NRF_ERROR_NULL	NULL pointer is supplied to the function or to the required member variable pointers.
NRF_ERROR_NO_MEM	The (/APP_SCENE_MODEL_COUNT) number of models already added.

◆ app_scene_model_scene_changed()

void app_scene_model_scene_changed ( app_scene_setup_server_t * p_app )

This API is called by the behavioral modules of other models to inform that the current state of the device has been changed.

To comply with Bluetooth Mesh Model Specification (MshMDLv1.0.1) section 5.1.3.2.1, when any of the model states that are marked as "stored with scene" change as a result of the operation other than the Scene Recall operation (for example pressing of a button or receiving a SET message), this API must be called by associated modules to inform Scene behavioral module to reset the current scene.

Parameters

[in] p_app Pointer to [app_scene_setup_server_t](__app_scene_setup_server_t) context.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ APP_SCENE_SETUP_SERVER_DEF

Typedef Documentation

◆ app_scene_transition_cb_t

◆ app_scene_store_cb_t

◆ app_scene_recall_cb_t

◆ app_scene_delete_cb_t

Function Documentation

◆ app_scene_model_init()

◆ app_scene_model_add()

◆ app_scene_model_scene_changed()