BT Mesh Configuration Distributor#
BT Mesh Configuration Distributor supports the parallel execution of multiple configuration jobs by distributing the jobs between executors.
BT Mesh Configuration Distributor instance is created by calling the btmesh_conf_distributor_create function. The specified number (executor_count) of BT Mesh Configuration Executor instances are created which are assigned to the created distributor instance (composition).
BT Mesh Configuration jobs can be submitted to configuration distributor with btmesh_conf_distributor_submit_job function which stores the job in a wait queue.
The configuration jobs are assigned to executors from the wait queue during distributor scheduling process. The BT Mesh Stack does not support parallel execution of two configuration job with the same server address. Therefore, the scheduling process guarantees that the configuration jobs with the same server addresses are executed one-by-one in the order of submission however jobs with different server addresses might be executed in parallel.
The configuration executors report the job status through btmesh_conf_distributor_on_job_notification function.
Note
The BT Mesh Stack does not allow the parallel execution of two configuration requests with the same server address (primary element). The limitation is added to the BT Mesh Stack because the configuration messages don't contain any transaction identifier in accordance with BT Mesh Profile specification so the status messages could not be differentiated.
Modules#
Functions#
Function Documentation#
btmesh_conf_distributor_create#
btmesh_conf_distributor_t * btmesh_conf_distributor_create (uint16_t executor_count)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint16_t | [in] | executor_count | Number of configuration executors which shall be created and added to this distributor instance. |
Create BT Mesh Configuration Distributor instance with the specified number of configuration executors.
Returns
Created configuration distributor.
Return values
NULL: If the configuration distributor creation fails.
btmesh_conf_distributor_destroy#
void btmesh_conf_distributor_destroy (btmesh_conf_distributor_t *const self)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| btmesh_conf_distributor_t *const | [in] | self | Pointer to configuration distributor which shall be destroyed |
Deallocate the BT Mesh Configuration Distributor instance
btmesh_conf_distributor_submit_job#
sl_status_t btmesh_conf_distributor_submit_job (btmesh_conf_distributor_t *const self, btmesh_conf_job_t * job)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| btmesh_conf_distributor_t *const | [in] | self | Pointer to the configuration distributor instance |
| btmesh_conf_job_t * | [in] | job | Configuration job which aggregates the configuration tasks |
Submit a configuration job for execution
Returns
Status of the job submission.
Return values
SL_STATUS_OK: If the job is submitted successfully.
BT Mesh Configuration Distributor appends the submitted configuration job to the wait queue and requests a deferred scheduling in order to assign the job to an idle BT Mesh Configuration Executor. If all executors are busy then the configuration job remains in the wait queue until an executor transitions to idle state and there is no previously submitted configuration jobs which can be started.
It is important to note that a configuration job might be executed sooner than another configuration job which was submitted earlier if the latter configurator job can't be started because one executor runs a third configuration job with the same server address.
If the execution of a configuration job is finished then the configuration executor calls the btmesh_conf_distributor_on_job_notification to notify the distributor.
btmesh_conf_distributor_on_job_notification#
void btmesh_conf_distributor_on_job_notification (btmesh_conf_distributor_t *const self, btmesh_conf_executor_t *const executor, btmesh_conf_job_t *const job)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| btmesh_conf_distributor_t *const | [in] | self | Pointer to the configuration distributor instance |
| btmesh_conf_executor_t *const | [in] | executor | Pointer to the executor which ran the configuration job |
| btmesh_conf_job_t *const | [in] | job | Pointer to the job with changed status |
BT Mesh Configuration Distributor job status notification callback for BT Mesh Configuration Executor
This callback is called when the status of the job changes because its execution is ended.
btmesh_conf_distributor_on_event#
void btmesh_conf_distributor_on_event (btmesh_conf_distributor_t *const self, const sl_btmesh_msg_t * evt)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| btmesh_conf_distributor_t *const | [in] | self | Pointer to the configuration distributor instance |
| const sl_btmesh_msg_t * | [in] | evt | BT Mesh Stack event |
Event handler of BT Mesh Configuration Distributor instance
BT Mesh Configuration Distributor forwards the BT Mesh Stack events to all of its BT Mesh Configuration Executor instances by calling the btmesh_conf_executor_on_event function with each configuration executor instance.
btmesh_conf_distributor_step#
void btmesh_conf_distributor_step (btmesh_conf_distributor_t *const self)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| btmesh_conf_distributor_t *const | [in] | self | Pointer to the configuration distributor instance |
Process one step of BT Mesh Configurator
The step function shall be called periodically by higher layer to perform deferred scheduling.