BT Mesh Configurator Component#

btmesh_conf_sig_model_attr_bitmask_t#

btmesh_conf_sig_model_attr_bitmask_t

Information about the supported configuration operations on a model.

btmesh_conf_init#

sl_status_t btmesh_conf_init (void )

Initialize the BT Mesh Configurator component

Returns

• Status of the initialization.

Return values

• SL_STATUS_OK: If the initialization is successful.

• SL_STATUS_ALLOCATION_FAILED: If the dynamic memory allocation of internal data structures is failed.

• SL_STATUS_INVALID_CONFIGURATION: If the configured model information is not valid. (array elems are not arranged in ascending order by model ID)

The initialization is performed automatically when the BT Mesh Stack triggers the sl_btmesh_evt_prov_initialized_id event. The application code shall call this function if it deinitialized the configurator component beforehand (btmesh_conf_deinit).

btmesh_conf_deinit#

sl_status_t btmesh_conf_deinit (void )

Deinitialize the BT Mesh Configurator component

Returns

• Status of the deinitialization.

Return values

• SL_STATUS_OK: If the deinitialization is successful.

• SL_STATUS_INVALID_STATE: If the deinitialization can't be started because it is initiated from

Deallocates the internal data structures and stops the processing of BT Mesh stack events. Deinitialization shall not be called from btmesh_conf_job_t::on_job_notification callback.

btmesh_conf_submit_job#

sl_status_t btmesh_conf_submit_job (btmesh_conf_job_t * job)

Submit a configuration job for execution

Returns

• Status of the job submission.

Return values

• SL_STATUS_OK: If the job is submitted successfully.

• SL_STATUS_INVALID_STATE: If the BT Mesh configurator is not initialized.

Each configuration job aggregates configuration tasks which targets the same remote node (configuration server model).

If a configuration job is submitted to the BT Mesh Configurator then it is added to the end of a wait queue. Therefore it is not guaranteed that the execution a job is started immediately. Configuration jobs with the same server addresses are executed in the order of submission however jobs with different server addresses might be executed in parallel.

If the submit operation is successful then the BT Mesh Configurator takes over the ownership of the job and consequently the application is no longer allowed to modify the submitted job or its tasks. If the submit operation fails and btmesh_conf_job_t::auto_destroy is set and SL_BTMESH_CONF_JOB_AUTO_DESTROY_ON_SUBMIT_FAILURE_CFG_VAL is turned on then the job is deallocated automatically in the submit call and consequently the job shall not be referenced when the submit returns with failure.

If task execution path ends in the configuration job then the job ends as well and btmesh_conf_job_t::on_job_notification callback is called with the result. The btmesh_conf_job_t::result structure member contains the result of the job. If the btmesh_conf_job_t::auto_destroy is set to true then the job and its tasks are deallocated automatically after the callback returns.

Warnings

• If the auto destroy feature is used then the job shall not be referenced after the callback is executed.

Note

• Te 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.

btmesh_conf_dcd_get#

sl_status_t btmesh_conf_dcd_get (uint16_t netkey_index, uint16_t server_address, uint8_t page, btmesh_conf_on_job_notification_t on_job_notification)

Submit a configuration job with a DCD get task

Returns

• Status of the DCD get request.

Return values

• SL_STATUS_OK: If the job is submitted successfully.

• SL_STATUS_INVALID_STATE: If the BT Mesh configurator is not initialized.

• SL_STATUS_ALLOCATION_FAILED: If allocation of job or task is failed.

Configuration job with DCD get task is created automatically and submitted for execution. The allocation and deallocation of task and job is handled automatically in this function.

Note

• It is a quite common usecase to get the DCD first and based on the content of the DCD further configuration tasks are defined and executed.
  This utility function makes it easier to get the DCD however it is possible to query the DCD with the following (basic) API calls as well:

  • btmesh_conf_task_dcd_get_create

  • btmesh_conf_job_create

  • btmesh_conf_submit_job

btmesh_conf_reset_node#

sl_status_t btmesh_conf_reset_node (uint16_t netkey_index, uint16_t server_address, btmesh_conf_on_job_notification_t on_job_notification)

Submit a configuration job with a reset node task

Returns

• Status of the reset node request.

Return values

• SL_STATUS_OK: If the job is submitted successfully.

• SL_STATUS_INVALID_STATE: If the BT Mesh configurator is not initialized.

• SL_STATUS_ALLOCATION_FAILED: If allocation of job or task is failed.

Configuration job with reset node task is created automatically and submitted for execution. The allocation and deallocation of task and job is handled automatically in this function.

Note

• This utility function makes it easier to reset a node however it is possible to reset a node with the following (basic) API calls as well:

  • btmesh_conf_task_reset_node_create

  • btmesh_conf_job_create

  • btmesh_conf_submit_job

btmesh_conf_on_event#

void btmesh_conf_on_event (const sl_btmesh_msg_t * evt)

BT Mesh Configurator event handler

The BT Mesh Configurator event handler shall be called with event provided sl_btmesh_pop_event or sl_btmesh_wait_event BT Mesh Stack API functions.

btmesh_conf_step#

void btmesh_conf_step (void )

Process one step of BT Mesh Configurator

The step API shall be called periodically from the main loop of the application.

btmesh_conf_on_job_notification#

void btmesh_conf_on_job_notification (btmesh_conf_job_t *const job)

Job status notification callback for lower layers

This callback is called when the status of the job changes because its execution is ended. The result of the job is provided in the btmesh_conf_job_t::result structure member. This callback calls btmesh_conf_job_t::on_job_notification with the job to notify the application. If btmesh_conf_job_t::on_job_notification is NULL then the application is not notified.

btmesh_conf_get_handle_from_event#

sl_status_t btmesh_conf_get_handle_from_event (const sl_btmesh_msg_t * evt, uint32_t * handle)

Provides the handle value from Configuration Client events of BT Mesh Stack

Returns

• Status of the handle retrieval from event.

Return values

• SL_STATUS_OK: If config client handle is retrieved successfully.

• SL_STATUS_NOT_FOUND: If the given event is not a config client event.

• SL_STATUS_NULL_POINTER: If any of its parameter is a NULL pointer.

btmesh_conf_get_sig_model_attributes#

sl_status_t btmesh_conf_get_sig_model_attributes (uint16_t model_id, btmesh_conf_sig_model_attr_bitmask_t * attributes)

Provide the model attributes of the given BT Mesh SIG model ID

Returns

• Status of the get model attributes.

Return values

• SL_STATUS_OK: If model attributes are provided successfully.

• SL_STATUS_NOT_FOUND: If the model ID is unknown.

• SL_STATUS_NULL_POINTER: If NULL pointer is given as attributes.

btmesh_conf_sig_model_id_to_string#

const char * btmesh_conf_sig_model_id_to_string (uint16_t model_id)

Return string representation of the given BT Mesh SIG model ID

Returns

• String representation of BT Mesh SIG model ID (model name)

Return values

• UnknownSigModel: If the model ID is unknown.

Note

• This function always returns a valid string which makes it easier to use this function with snprintf like functions because those expects valid (non-NULL) for s format specifier.

btmesh_conf_is_configuration_event#

bool btmesh_conf_is_configuration_event (uint32_t event_id)

Check if a given BT Mesh Stack event is a configuration client event

btmesh_conf_any_severe_log_level#

bool btmesh_conf_any_severe_log_level (uint8_t start_level)

Check if a given log level or other more severe log levels are enabled