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.

The Remote Provisioning Client model is introduced in the Bluetooth Mesh Protocol Specification version 1.1. This model provides functionality to remotely provision devices into a mesh network, and perform Node Provisioning Protocol Interface procedures 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 above example shows pseudo code for starting a scan procedure on the target Remote Provisioning Server node. This procedure will start a ten-second, multiple-device scanning where the generated scan report will contain a maximum of three unprovisioned devices. If the UUID argument was specified, the same procedure would only scan for the device with the corresponding UUID. After the procedure completes, the server sends the scan report that will be handled in the client’s bt_mesh_rpr_cli.scan_report callback.

Additionally, the Remote Provisioning Client model also supports extended scanning with the bt_mesh_rpr_scan_start_ext() call. Extended scanning supplements regular scanning by allowing the Remote Provisioning 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 it is supported by the unprovisioned device.

Provisioning

The Remote Provisioning Client starts a provisioning procedure 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 above example shows pseudo code for remotely provisioning a device through a Remote Provisioning Server node. This procedure will attempt to provision the device with the corresponding UUID, and assign the address 0x0006 to its primary element using the network key located at index zero.

Note

During the remote provisioning, the same bt_mesh_prov callbacks are triggered as for ordinary provisioning. See section Provisioning for further details.

Re-provisioning

In addition to scanning and provisioning functionality, the Remote Provisioning Client also provides means to reconfigure node addresses, device keys and Composition Data on devices that support the Remote Provisioning Server model. This is provided through the Node Provisioning Protocol Interface (NPPI) which supports the following three procedures:

Device Key Refresh procedure: Used to change the device key of the Target node without a need to reconfigure the node.
Node Address Refresh procedure: Used to change the node’s device key and unicast address.
Node Composition Refresh procedure: Used to change the device key of the node, and to add or delete models or features of the node.

The three NPPI procedures can be initiated with 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 above example shows pseudo code for triggering a Node Address Refresh procedure on the Target node. The specific procedure is not chosen directly, but rather through the other parameters that are inputted. In the example we can see that the current unicast address of the Target is 0x0006, while the new address is set to 0x0009. If the two addresses were the same, and the composition_changed flag was set to true, this code would instead trigger a Node Composition Refresh procedure. If the two addresses were the same, and the composition_changed flag was set to false, this code would trigger a 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:

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

#include <rpr_cli.h>

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

#include <rpr_cli.h>

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

#include <rpr_cli.h>

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.