Bluetooth Mesh Stack Provisioner#

sl_btmesh_prov_init#

sl_status_t sl_btmesh_prov_init ()

Initialize the Bluetooth mesh stack in the Provisioner role. Note that the result code of this command only indicates that the request to initialize has been accepted for processing. When initialization is completed successfully, a sl_btmesh_evt_prov_initialized will be generated. On failed initialization a sl_btmesh_evt_prov_initialization_failed event will be generated. Note that the application must wait for an event to be generated before executing further BGAPI commands.

This command must be issued before any other Bluetooth mesh stack commands. Note that the Bluetooth mesh stack can be initialized either in the Provisioner or the Node role, but not both.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_btmesh_evt_prov_initialized

• sl_btmesh_evt_prov_initialization_failed

sl_btmesh_prov_scan_unprov_beacons#

sl_status_t sl_btmesh_prov_scan_unprov_beacons ()

Start scanning for unprovisioned device beacons.

Unprovisioned devices send out beacons containing their UUID. An sl_btmesh_evt_prov_unprov_beacon will be generated for each beacon seen. Once the UUID of a device is known, the Provisioner may start provisioning the device with the sl_btmesh_prov_create_provisioning_session command.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_btmesh_evt_prov_unprov_beacon

sl_btmesh_prov_create_provisioning_session#

sl_status_t sl_btmesh_prov_create_provisioning_session (uint16_t netkey_index, uuid_128 uuid, uint8_t attention_timer_sec)

Initialize the provisioning session. After this command, it is possible to set the provisioning parameter with the following command:

• sl_btmesh_prov_set_provisioning_suspend_event

After all optional parameters have been set, the provisioning process is triggered by one of the following commands:

• sl_btmesh_prov_provision_adv_device

• sl_btmesh_prov_provision_gatt_device

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

sl_btmesh_prov_set_provisioning_suspend_event#

sl_status_t sl_btmesh_prov_set_provisioning_suspend_event (uint8_t status)

Set whether the provisioning can be suspended at a specified point while it is occurring. Currently, this can happen after reception on provisioning capabilities message or when the provisioning link is opened.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_btmesh_evt_prov_provisioning_suspended

sl_btmesh_prov_provision_adv_device#

sl_status_t sl_btmesh_prov_provision_adv_device (uuid_128 uuid)

Provision device over PB-ADV

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_btmesh_evt_prov_device_provisioned

• sl_btmesh_evt_prov_provisioning_failed

sl_btmesh_prov_provision_gatt_device#

sl_status_t sl_btmesh_prov_provision_gatt_device (uuid_128 uuid, uint8_t connection)

Provision device over PB-GATT

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_btmesh_evt_prov_device_provisioned

• sl_btmesh_evt_prov_provisioning_failed

• sl_btmesh_evt_prov_capabilities

sl_btmesh_prov_provision_remote_device#

sl_status_t sl_btmesh_prov_provision_remote_device (uuid_128 uuid, uint16_t server)

Provision device over remote provisioning server connection

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_btmesh_evt_prov_device_provisioned

• sl_btmesh_evt_prov_provisioning_failed

• sl_btmesh_evt_prov_capabilities

sl_btmesh_prov_continue_provisioning#

sl_status_t sl_btmesh_prov_continue_provisioning (uuid_128 uuid)

Continue provisioning after the suspension indicated by sl_btmesh_evt_prov_provisioning_suspended.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

sl_btmesh_prov_abort_provisioning#

sl_status_t sl_btmesh_prov_abort_provisioning (uuid_128 uuid, uint8_t reason)

Abort provisioning. This command is typically used after the suspension indicated by sl_btmesh_evt_prov_provisioning_suspended.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

sl_btmesh_prov_set_device_address#

sl_status_t sl_btmesh_prov_set_device_address (uuid_128 uuid, uint16_t address)

Set the address for the device after the provisioning has been suspended, as indicated by sl_btmesh_evt_prov_provisioning_suspended event.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

sl_btmesh_prov_create_network#

sl_status_t sl_btmesh_prov_create_network (uint16_t netkey_index, size_t key_len, const uint8_t * key)

Create a new network key on the Provisioner.

The created key can be deployed on a node using the sl_btmesh_config_client_add_netkey command.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_create_appkey#

sl_status_t sl_btmesh_prov_create_appkey (uint16_t netkey_index, uint16_t appkey_index, size_t key_len, const uint8_t * key, size_t max_application_key_size, size_t * application_key_len, uint8_t * application_key)

Create a new application key on the Provisioner.

An application key is always bound to a network key. In other words, the application key is only valid in the context of a particular network key. The selected network key must exist on the Provisioner (see sl_btmesh_prov_create_network command).

The created application key can be deployed on a node using the sl_btmesh_config_client_add_appkey command.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_send_oob_pkey_response#

sl_status_t sl_btmesh_prov_send_oob_pkey_response (uuid_128 uuid, size_t pkey_len, const uint8_t * pkey)

Respond to the prov_oob_pkey_request.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_send_oob_auth_response#

sl_status_t sl_btmesh_prov_send_oob_auth_response (uuid_128 uuid, size_t data_len, const uint8_t * data)

Respond to the prov_oob_auth_request.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_set_oob_requirements#

sl_status_t sl_btmesh_prov_set_oob_requirements (uuid_128 uuid, uint8_t public_key, uint8_t auth_methods, uint16_t output_actions, uint16_t input_actions, uint8_t min_size, uint8_t max_size)

Set the OOB requirements for a device being provisioned. This command can be issued after sl_btmesh_prov_create_provisioning_session.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_start_key_refresh#

sl_status_t sl_btmesh_prov_start_key_refresh (uint16_t netkey_index, uint8_t num_appkeys, size_t appkey_indices_len, const uint8_t * appkey_indices)

Start a key refresh procedure in the network.

A key refresh procedure updates a network key and, optionally, application keys associated with it in all nodes of the network except for excluded nodes. After the refresh procedure is complete, the old keys will be discarded. Therefore, the excluded nodes, which did not receive new keys will be shut out of the network at the completion of the procedure.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_btmesh_evt_prov_key_refresh_node_update

• sl_btmesh_evt_prov_key_refresh_phase_update

• sl_btmesh_evt_prov_key_refresh_complete

sl_btmesh_prov_get_key_refresh_exclusion#

sl_status_t sl_btmesh_prov_get_key_refresh_exclusion (uint16_t key, uuid_128 uuid, uint8_t * status)

Check the key refresh exclusion status of a node. Excluded nodes do not participate in the key refresh procedure and can therefore be shut out of the network.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_set_key_refresh_exclusion#

sl_status_t sl_btmesh_prov_set_key_refresh_exclusion (uint16_t key, uint8_t status, uuid_128 uuid)

Set the key refresh exclusion status of a node. Excluded nodes do not participate in the key refresh procedure and can therefore be shut out of the network.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_set_key_refresh_failure#

sl_status_t sl_btmesh_prov_set_key_refresh_failure (uint16_t key, uuid_128 uuid)

Mark the node as failed for the keyrefresh. This function should be called if the provisioner knows that the node has become unresponsive for some external reason (such as factory reset performed by the end user), and will not respond to key refresh messages even after a long delay. Note that if a node drops out of the key refresh procedure, it will not be possible to communicate with the node using the key that was refreshed during the key refresh procedure.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_phase_timeout_get#

sl_status_t sl_btmesh_prov_phase_timeout_get (uint32_t * phase_timeout_s)

Get the phase_timeout_s parameter that will be used for the start key refresh command. A node fails the key refresh procedure phase, if it doesnt reply to the provisioner during the timeout.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_phase_timeout_set#

sl_status_t sl_btmesh_prov_phase_timeout_set (uint32_t phase_timeout_s)

Set the phase_timeout_s parameter that will be used for the start key refresh command. A node fails the key refresh procedure phase, if it doesnt reply to the provisioner during the timeout. Maximum allowed value is 345600 sec (4days).

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_get_ddb_entry#

sl_status_t sl_btmesh_prov_get_ddb_entry (uuid_128 uuid, aes_key_128 * device_key, uint16_t * netkey_index, uint16_t * address, uint8_t * elements)

Get a Provisioner device database entry with a matching UUID.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_delete_ddb_entry#

sl_status_t sl_btmesh_prov_delete_ddb_entry (uuid_128 uuid)

Delete the node information from the Provisioner database. Note that a successful result from this command only means the command has been accepted for processing. The status of the actual operation will be returned in the following event; application should not make new BGAPI requests until the event is received. Note also that this should be followed by a sl_btmesh_prov_start_key_refresh updating the keys of the remaining nodes to make sure the deleted node is shut off from the network.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_btmesh_evt_prov_delete_ddb_entry_complete

sl_btmesh_prov_add_ddb_entry#

sl_status_t sl_btmesh_prov_add_ddb_entry (uuid_128 uuid, aes_key_128 device_key, uint16_t netkey_index, uint16_t address, uint8_t elements)

Add a new node entry to the Provisioner's device database. Note that a successful result from this command only means the command has been accepted for processing. The status of the actual operation will be returned in the following event; application should not make new BGAPI requests until the event is received. Note also that the device key, primary element address, and network key need to be deployed to the node being added to ensure it's configurable. See sl_btmesh_node_set_provisioning_data command.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_btmesh_evt_prov_add_ddb_entry_complete

sl_btmesh_prov_list_ddb_entries#

sl_status_t sl_btmesh_prov_list_ddb_entries (uint16_t * count)

List nodes known by this Provisioner. A number of sl_btmesh_evt_prov_ddb_list events will be generated.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_btmesh_evt_prov_ddb_list

sl_btmesh_prov_initialize_network#

sl_status_t sl_btmesh_prov_initialize_network (uint16_t address, uint32_t ivi)

Initialize the mesh network and assign the provisioner address and IV index for the network. If this command is not invoked prior to invoking sl_btmesh_prov_create_network, the network will be initialized with default address and IV index.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_get_key_refresh_appkey_exclusion#

sl_status_t sl_btmesh_prov_get_key_refresh_appkey_exclusion (uint16_t netkey_index, uint16_t appkey_index, uuid_128 uuid, uint8_t * status)

Check the application key refresh exclusion status of a node. Nodes which are excluded for a given application key do not receive updates for that particular application key, but do participate in the key refresh procedure as a whole. This enables the Provisioner to set up and update restricted sets of application keys across nodes.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_set_key_refresh_appkey_exclusion#

sl_status_t sl_btmesh_prov_set_key_refresh_appkey_exclusion (uint16_t netkey_index, uint16_t appkey_index, uint8_t status, uuid_128 uuid)

Set the application key refresh exclusion status of a node. Nodes which are excluded for a given application key do not receive updates for that particular application key, but do participate in the key refresh procedure as a whole. This enables the Provisioner to set up and update restricted sets of application keys across nodes.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_stop_scan_unprov_beacons#

sl_status_t sl_btmesh_prov_stop_scan_unprov_beacons ()

Stop scanning for unprovisioned device beacons.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_update_device_netkey_index#

sl_status_t sl_btmesh_prov_update_device_netkey_index (uuid_128 uuid, uint16_t netkey_index)

Update a node's entry in the Provisioner's device database by setting a new value to the netkey_index field. The netkey_index field is used to determine the network key to use when encrypting and decrypting configuration model messages to and from the node.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_suspend_key_refresh#

sl_status_t sl_btmesh_prov_suspend_key_refresh (uint16_t netkey_index)

Suspend an ongoing key refresh procedure.

Suspending a key refresh procedure means no further requests for updating keys or setting key refresh phase will be sent to the network by the Provisioner until the key refresh procedure is resumed.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_resume_key_refresh#

sl_status_t sl_btmesh_prov_resume_key_refresh (uint16_t netkey_index)

Resume a suspended key refresh procedure.

By resuming a suspended key refresh procedure, the Provisioner will again start to send requests for updating keys or setting key refresh phase to the network.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_get_key_refresh_phase#

sl_status_t sl_btmesh_prov_get_key_refresh_phase (uint16_t netkey_index, uint8_t * phase)

Get the key refresh phase of an ongoing key refresh procedure.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_start_key_refresh_from_phase#

sl_status_t sl_btmesh_prov_start_key_refresh_from_phase (uint8_t phase, uint16_t netkey_index, uint8_t num_appkeys, size_t appkey_indices_len, const uint8_t * appkey_indices)

Start a key refresh procedure from a non-default phase. Before calling this function, keys to be used in the key refresh procedure should have been specified by calling sl_btmesh_test_prov_prepare_key_refresh command.

Note that this command should not normally be used. It is intended only for resuming an interrupted key refresh procedure on a backup Provisioner when the original Provisioner, that started the key refresh procedure, is no longer available to complete the procedure.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_btmesh_evt_prov_key_refresh_node_update

• sl_btmesh_evt_prov_key_refresh_phase_update

• sl_btmesh_evt_prov_key_refresh_complete

sl_btmesh_prov_flush_key_refresh_state#

sl_status_t sl_btmesh_prov_flush_key_refresh_state (uint16_t netkey_index)

Clear the key refresh state stored in persistent storage.

Note that this command should not normally be used. It is intended only for clearing stored key refresh state when a key refresh procedure has been suspended and will not be resumed, either because the network key has been deleted from all nodes or the responsibility for completing the key refresh has been moved to another Provisioner.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_test_identity#

SL_BGAPI_DEPRECATED sl_status_t sl_btmesh_prov_test_identity (uint16_t address, uint16_t netkey_index, size_t data_len, const uint8_t * data, uint8_t * match)

Test if data in the identity beacon matches the mesh device and network. This is a deprecated function. Please use sl_btmesh_node_test_identity

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_prov_get_provisioning_records_list#

sl_status_t sl_btmesh_prov_get_provisioning_records_list (uuid_128 uuid)

Get the list of provisioning records on the device. This command can be issued when provisioning is suspended after the provisioning session has been opened, but no earlier or later. The list of provisioning records on the device will be delivered with the sl_btmesh_evt_prov_provisioning_records_list event.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_btmesh_evt_prov_provisioning_records_list

sl_btmesh_prov_get_provisioning_record_data#

sl_status_t sl_btmesh_prov_get_provisioning_record_data (uuid_128 uuid, uint16_t record)

Get provisioning record data from the device. This command can be issued when provisioning is suspended after the provisioning session has been opened, but no earlier or later. The provisioning record data will be delivered with the sl_btmesh_evt_prov_provisioning_record_data event.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_btmesh_evt_prov_provisioning_record_data

sl_btmesh_prov_init_provisioning_records#

sl_status_t sl_btmesh_prov_init_provisioning_records ()

Initialize provisioning record retrieval functionality on the Provisioner. This must be called before trying to retrieve provisioning records list or individual record data.

Returns

• SL_STATUS_OK if successful. Error code otherwise.