This is the documentation for the latest (main) development branch. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

Remote Provisioning Client

The Remote Provisioning Client model is a foundation model defined by the Bluetooth mesh specification. It is enabled with the CONFIG_BT_MESH_RPR_CLI option.

Introduced in the Bluetooth Mesh Protocol Specification version 1.1, the Remote Configuration Client model provides the capability to remotely configure devices into a mesh network. It performs the Node Configuration Protocol Interface (NCPI) process by interacting with mesh nodes that support the Remote Provisioning Server model.

The Remote Provisioning Client model communicates with a Remote Provisioning Server model using the device key of the node containing the target Remote Provisioning Server model instance.

If present, the Remote Provisioning Client model must be instantiated on the primary element.

Scanning

The scanning procedure is used to scan for unprovisioned devices located nearby the Remote Provisioning Server. The Remote Provisioning Client starts a scan procedure by using the bt_mesh_rpr_scan_start() call:

static void rpr_scan_report(struct bt_mesh_rpr_cli *cli,
            const struct bt_mesh_rpr_node *srv,
            struct bt_mesh_rpr_unprov *unprov,
            struct net_buf_simple *adv_data)
{

}

struct bt_mesh_rpr_cli rpr_cli = {
   .scan_report = rpr_scan_report,
};

const struct bt_mesh_rpr_node srv = {
   .addr = 0x0004,
   .net_idx = 0,
   .ttl = BT_MESH_TTL_DEFAULT,
};

struct bt_mesh_rpr_scan_status status;
uint8_t *uuid = NULL;
uint8_t timeout = 10;
uint8_t max_devs = 3;

bt_mesh_rpr_scan_start(&rpr_cli, &srv, uuid, timeout, max_devs, &status);

The example above demonstrates pseudocode used to initiate a scanning process on a target Remote Configuration Server node. This process will start a multi-device scan for 10 seconds, with the generated scan report containing up to three unconfigured devices. If a UUID parameter is specified, the same process will only scan for devices with the corresponding UUID. Upon completion of the process, the server sends a scan report that will be handled in the client’s bt_mesh_rpr_cli.scan_report callback .

Furthermore, the Remote Configuration Client model also supports extended scanning using the bt_mesh_rpr_scan_start_ext call. Extended scanning complements regular scanning by allowing the Remote Configuration Server to report additional data for specific devices. The Remote Configuration Server will use active scanning to request scan responses from unconfigured devices (if supported by the unconfigured devices).

Pre-Provisioning

The Remote Configuration Client initiates the provisioning process by using the bt_mesh_provision_Remote call：

struct bt_mesh_rpr_cli rpr_cli;

const struct bt_mesh_rpr_node srv = {
   .addr = 0x0004,
   .net_idx = 0,
   .ttl = BT_MESH_TTL_DEFAULT,
};

uint8_t uuid[16] = { 0xaa };
uint16_t addr = 0x0006;
uint16_t net_idx = 0;

bt_mesh_provision_remote(&rpr_cli, &srv, uuid, net_idx, addr);

The example above demonstrates pseudocode for remotely configuring a device through a Remote Configuration Server node. This process attempts to provide the device with the corresponding UUID and assigns address 0x0006 to its primary element using the network key located at index zero.

Note

During remote configuration, the same bt_mesh_prov callbacks as in regular provisioning are triggered. For detailed information, refer to the section Provisioning .

Re-Provisioning

Beyond scanning and configuration capabilities, the Remote Configuration Client also offers support for the Remote Provisioning Server model. This is provided through the Node Configuration Protocol Interface (NPPI), which supports the following three procedures:

Device Key Refresh Procedure: Used to change the device key of the target node without the need to reconfigure the node.
Node Address Refresh Procedure: Used to change both the device key and unicast address of the node.
Node Composition Refresh Procedure: Used to change the device key and add or remove models or functionalities of the node.

The three NPPI procedures can be initiated using the bt_mesh_reprovision_remote call:

struct bt_mesh_rpr_cli rpr_cli;
struct bt_mesh_rpr_node srv = {
   .addr = 0x0006,
   .net_idx = 0,
   .ttl = BT_MESH_TTL_DEFAULT,
};

bool composition_changed = false;
uint16_t new_addr = 0x0009;

bt_mesh_reprovision_remote(&rpr_cli, &srv, new_addr, composition_changed);

The example above demonstrates pseudocode used to trigger the Node Address Refresh Procedure on a target node. The specific procedure is not directly selected but chosen based on other input parameters. In this example, we can see that the current unicast address of the Target is 0x0006, and the new address is set to 0x0009. If the two addresses are the same and the composition_changed flag is set to true, the code will trigger the Node Composition Refresh Procedure. If the two addresses are the same and the composition_changed flag is set to false, the code will trigger the Device Key Refresh Procedure.

API Reference

group bt_mesh_rpr_cli

Defines

BT_MESH_RPR_SCAN_MAX_DEVS_ANY

Special value for the max_devs parameter of bt_mesh_rpr_scan_start.

Tells the Remote Provisioning Server not to put restrictions on the max number of devices reported to the Client.

BT_MESH_MODEL_RPR_CLI(_cli)

Remote Provisioning Client model composition data entry.

Parameters:

_cli – Pointer to a Remote Provisioning Client model instance.

Functions

int bt_mesh_rpr_scan_caps_get(struct bt_mesh_rpr_cli *cli, const struct bt_mesh_rpr_node *srv, struct bt_mesh_rpr_caps *caps)

Get scanning capabilities of Remote Provisioning Server.

Parameters:

cli – Remote Provisioning Client.
srv – Remote Provisioning Server.
caps – Capabilities response buffer.

Returns:

0 on success, or (negative) error code otherwise.

int bt_mesh_rpr_scan_get(struct bt_mesh_rpr_cli *cli, const struct bt_mesh_rpr_node *srv, struct bt_mesh_rpr_scan_status *status)

Get current scanning state of Remote Provisioning Server.

Parameters:

cli – Remote Provisioning Client.
srv – Remote Provisioning Server.
status – Scan status response buffer.

Returns:

0 on success, or (negative) error code otherwise.

int bt_mesh_rpr_scan_start(struct bt_mesh_rpr_cli *cli, const struct bt_mesh_rpr_node *srv, const uint8_t uuid[16], uint8_t timeout, uint8_t max_devs, struct bt_mesh_rpr_scan_status *status)

Start scanning for unprovisioned devices.

Tells the Remote Provisioning Server to start scanning for unprovisioned devices. The Server will report back the results through the bt_mesh_rpr_cli::scan_report callback.

Use the uuid parameter to scan for a specific device, or leave it as NULL to report all unprovisioned devices.

The Server will ignore duplicates, and report up to max_devs number of devices. Requesting a max_devs number that’s higher than the Server’s capability will result in an error.

Parameters:

cli – Remote Provisioning Client.
srv – Remote Provisioning Server.
uuid – Device UUID to scan for, or NULL to report all devices.
timeout – Scan timeout in seconds. Must be at least 1 second.
max_devs – Max number of devices to report, or 0 to report as many as possible.
status – Scan status response buffer.

Returns:

0 on success, or (negative) error code otherwise.

int bt_mesh_rpr_scan_start_ext(struct bt_mesh_rpr_cli *cli, const struct bt_mesh_rpr_node *srv, const uint8_t uuid[16], uint8_t timeout, const uint8_t *ad_types, size_t ad_count)

Start extended scanning for unprovisioned devices.

Extended scanning supplements regular unprovisioned scanning, by allowing the Server to report additional data for a specific device. The Remote Provisioning Server will use active scanning to request a scan response from the unprovisioned device, if supported. If no UUID is provided, the Server will report a scan on its own OOB information and advertising data.

Use the ad_types array to specify which AD types to include in the scan report. Some AD types invoke special behavior:

BT_DATA_NAME_COMPLETE Will report both the complete and the shortened name.
BT_DATA_URI If the unprovisioned beacon contains a URI hash, the Server will extend the scanning to include packets other than the scan response, to look for URIs matching the URI hash. Only matching URIs will be reported.

The following AD types should not be used:

BT_DATA_NAME_SHORTENED
BT_DATA_UUID16_SOME
BT_DATA_UUID32_SOME
BT_DATA_UUID128_SOME

Additionally, each AD type should only occur once.

Parameters:

cli – Remote Provisioning Client.
srv – Remote Provisioning Server.
uuid – Device UUID to start extended scanning for, or NULL to scan the remote server.
timeout – Scan timeout in seconds. Valid values from BT_MESH_RPR_EXT_SCAN_TIME_MIN to BT_MESH_RPR_EXT_SCAN_TIME_MAX. Ignored if UUID is NULL.
ad_types – List of AD types to include in the scan report. Must contain 1 to CONFIG_BT_MESH_RPR_AD_TYPES_MAX entries.
ad_count – Number of AD types in ad_types.

Returns:

0 on success, or (negative) error code otherwise.

int bt_mesh_rpr_scan_stop(struct bt_mesh_rpr_cli *cli, const struct bt_mesh_rpr_node *srv, struct bt_mesh_rpr_scan_status *status)

Stop any ongoing scanning on the Remote Provisioning Server.

Parameters:

cli – Remote Provisioning Client.
srv – Remote Provisioning Server.
status – Scan status response buffer.

Returns:

0 on success, or (negative) error code otherwise.

int bt_mesh_rpr_link_get(struct bt_mesh_rpr_cli *cli, const struct bt_mesh_rpr_node *srv, struct bt_mesh_rpr_link *rsp)

Get the current link status of the Remote Provisioning Server.

Parameters:

cli – Remote Provisioning Client.
srv – Remote Provisioning Server.
rsp – Link status response buffer.

Returns:

0 on success, or (negative) error code otherwise.

int bt_mesh_rpr_link_close(struct bt_mesh_rpr_cli *cli, const struct bt_mesh_rpr_node *srv, struct bt_mesh_rpr_link *rsp)

Close any open link on the Remote Provisioning Server.

Parameters:

cli – Remote Provisioning Client.
srv – Remote Provisioning Server.
rsp – Link status response buffer.

Returns:

0 on success, or (negative) error code otherwise.

int32_t bt_mesh_rpr_cli_timeout_get(void)

Get the current transmission timeout value.

Returns:: The configured transmission timeout in milliseconds.

void bt_mesh_rpr_cli_timeout_set(int32_t timeout)

Set the transmission timeout value.

The transmission timeout controls the amount of time the Remote Provisioning Client models will wait for a response from the Server.

Parameters:: timeout – The new transmission timeout.

struct bt_mesh_rpr_scan_status

Scan status response

Public Members

enum bt_mesh_rpr_status status: Current scan status

enum bt_mesh_rpr_scan scan: Current scan state

uint8_t max_devs: Max number of devices to report in current scan.

uint8_t timeout: Seconds remaining of the scan.

struct bt_mesh_rpr_caps

Remote Provisioning Server scanning capabilities

Public Members

uint8_t max_devs: Max number of scannable devices

bool active_scan: Supports active scan

struct bt_mesh_rpr_cli

Remote Provisioning Client model instance.

Public Members

void (*scan_report)(struct bt_mesh_rpr_cli *cli, const struct bt_mesh_rpr_node *srv, struct bt_mesh_rpr_unprov *unprov, struct net_buf_simple *adv_data)

Scan report callback.

Param cli:: Remote Provisioning Client.
Param srv:: Remote Provisioning Server.
Param unprov:: Unprovisioned device.
Param adv_data:: Advertisement data for the unprovisioned device, or NULL if extended scanning hasn’t been enabled. An empty buffer indicates that the extended scanning finished without collecting additional information.