BT Mesh Configuration Job#

BT Mesh Configuration Job aggregates group of configuration tasks which targets the same configuration server model on a remote node.

Modules#

btmesh_conf_job_t

Enumerations#

enum

btmesh_conf_job_result_t {

BTMESH_CONF_JOB_RESULT_SUCCESS

BTMESH_CONF_JOB_RESULT_FAIL

BTMESH_CONF_JOB_RESULT_CRITICAL_ERROR

BTMESH_CONF_JOB_RESULT_CANCEL

BTMESH_CONF_JOB_RESULT_UNKNOWN

}

Result of BT Mesh Configuration job.

Typedefs#

typedef enum btmesh_conf_job_result_t

btmesh_conf_job_result_t

Result of BT Mesh Configuration job.

typedef struct btmesh_conf_job_t

btmesh_conf_job_t

Type definition of struct btmesh_conf_job_t.

typedef void(*

btmesh_conf_on_job_notification_t)(const btmesh_conf_job_t *job)

Functions#

btmesh_conf_job_t *

btmesh_conf_job_create_default(uint16_t enc_netkey_index, uint16_t server_address, btmesh_conf_task_t *task_tree, btmesh_conf_on_job_notification_t on_job_notification)

btmesh_conf_job_t *

btmesh_conf_job_create(uint16_t enc_netkey_index, uint16_t server_address, btmesh_conf_task_t *task_tree, btmesh_conf_on_job_notification_t on_job_notification, btmesh_conf_varg_t job_status_param, bool auto_destroy, uint32_t *const job_id)

void

btmesh_conf_job_destroy(btmesh_conf_job_t *const self)

uint32_t

btmesh_conf_job_id_generator(void)

sl_status_t

btmesh_conf_job_set_next_task(btmesh_conf_job_t *const self)

Enumeration Documentation#

btmesh_conf_job_result_t#

btmesh_conf_job_result_t

Result of BT Mesh Configuration job.

Enumerator
BTMESH_CONF_JOB_RESULT_SUCCESS	Every executed task of configuration job is successful.
BTMESH_CONF_JOB_RESULT_FAIL	At least one executed task is failed during configuration job execution.
BTMESH_CONF_JOB_RESULT_CRITICAL_ERROR	Internal error occurred during configuration job execution.
BTMESH_CONF_JOB_RESULT_CANCEL	The configuration job is canceled because the configurator is deinitialized.
BTMESH_CONF_JOB_RESULT_UNKNOWN	The result of configuration job is not known yet.

Typedef Documentation#

btmesh_conf_job_result_t#

typedef enum btmesh_conf_job_result_t btmesh_conf_job_result_t

Result of BT Mesh Configuration job.

btmesh_conf_job_t#

typedef struct btmesh_conf_job_t btmesh_conf_job_t

Type definition of struct btmesh_conf_job_t.

btmesh_conf_on_job_notification_t#

typedef void(* btmesh_conf_on_job_notification_t) (const btmesh_conf_job_t *job) )(const btmesh_conf_job_t *job)

Parameters

Type	Direction	Argument Name	Description
	[in]	job	Configuration job with changed status

Type of BT Mesh Configuration Job status notification callback

If task execution path ends in the configuration job then the job ends as well and job status notification callback is called with the result.

Function Documentation#

btmesh_conf_job_create_default#

btmesh_conf_job_t * btmesh_conf_job_create_default (uint16_t enc_netkey_index, uint16_t server_address, btmesh_conf_task_t * task_tree, btmesh_conf_on_job_notification_t on_job_notification)

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	enc_netkey_index	Network key used to encrypt the config requests
uint16_t	[in]	server_address	Destination node primary element address
btmesh_conf_task_t *	[in]	task_tree	Config tasks which shall be executed in specified order
btmesh_conf_on_job_notification_t	[in]	on_job_notification	Configuration job status notification callback which is called when the status of the job changes at the end of the job

Create BT Mesh Configuration Job with default parameters

Returns

Created configuration job.

Return values

NULL: If the configuration job creation fails.

This function calls btmesh_conf_job_create with the following parameters:

job_status_param:BTMESH_CONF_VARG_NULL
auto_destroy: SL_BTMESH_CONF_JOB_AUTO_DESTROY_CFG_VAL
job_id: NULL

btmesh_conf_job_create#

btmesh_conf_job_t * btmesh_conf_job_create (uint16_t enc_netkey_index, uint16_t server_address, btmesh_conf_task_t * task_tree, btmesh_conf_on_job_notification_t on_job_notification, btmesh_conf_varg_t job_status_param, bool auto_destroy, uint32_t *const job_id)

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	enc_netkey_index	Network key used to encrypt the config requests
uint16_t	[in]	server_address	Destination node primary element address
btmesh_conf_task_t *	[in]	task_tree	Config tasks which shall be executed in specified order
btmesh_conf_on_job_notification_t	[in]	on_job_notification	Configuration job status notification callback which is called when the status of the job changes at the end of the job
btmesh_conf_varg_t	[in]	job_status_param	Job status param can be set by the application to differentiate config jobs if the same jobs status notification callback function is used in multiple jobs
bool	[in]	auto_destroy	Auto destroy deallocates the configuration job and its tasks automatically after the job status notification callback returns. If btmesh_conf_submit_job operation fails and the definition SL_BTMESH_CONF_JOB_AUTO_DESTROY_ON_SUBMIT_FAILURE_CFG_VAL is turned on then the job is deallocated automatically on submit failure.
uint32_t *const	[out]	job_id	Unique job ID generated by btmesh_conf_job_id_generator

Create BT Mesh Configuration Job with given tasks

Returns

Created configuration job.

Return values

NULL: If the configuration job creation fails.

Configuration job can be created if the tasks are created and linked first in order to provide the task_tree parameter. The created configuration job can be submitted for execution by calling btmesh_conf_submit_job function.

btmesh_conf_job_destroy#

void btmesh_conf_job_destroy (btmesh_conf_job_t *const self)

Parameters

Type	Direction	Argument Name	Description
btmesh_conf_job_t *const	[in]	self	Pointer to the configuration job which shall be destroyed

Deallocates the BT Mesh Configuration Job instance and all of its tasks

btmesh_conf_job_id_generator#

uint32_t btmesh_conf_job_id_generator (void )

Parameters

Type	Direction	Argument Name	Description
void	N/A

Return generated unique BT Mesh Configuration Job identifier.

Returns

Unique configuration job identifier

Default implementation is provided in btmesh_conf_job.c and it generates job identifiers by incrementing the last one. If the deault implementation is not sufficient for the application then the function can be overridden in the application by function definition with strong symbol.

Note

Default implementation is provided with weak symbol.

btmesh_conf_job_set_next_task#

sl_status_t btmesh_conf_job_set_next_task (btmesh_conf_job_t *const self)

Parameters

Type	Direction	Argument Name	Description
btmesh_conf_job_t *const	[in]	self	Pointer to the configuration job instance

Set next BT Mesh configuration task based on the current active task of a job

Returns

Status of the next task setup

Return values

SL_STATUS_OK: If next task is set properly.
SL_STATUS_NOT_FOUND: If next is not set because this was the last task.
SL_STATUS_FAIL: If fatal error occurred.