| .. _bluetooth_mesh_models_rpr_cli: |
| |
| Remote Provisioning Client |
| ########################## |
| |
| The Remote Provisioning Client model is a foundation model defined by the Bluetooth |
| mesh specification. It is enabled with the |
| :kconfig:option:`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 :ref:`bluetooth_mesh_models_rpr_srv` 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 :c:func:`bt_mesh_rpr_scan_start` call: |
| |
| .. code-block:: C |
| |
| 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 :c:member:`bt_mesh_rpr_cli.scan_report` callback. |
| |
| Additionally, the Remote Provisioning Client model also supports extended scanning with the |
| :c:func:`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 :c:func:`bt_mesh_provision_remote` call: |
| |
| .. code-block:: C |
| |
| 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 :c:struct:`bt_mesh_prov` callbacks are triggered as for ordinary |
| provisioning. See section :ref:`bluetooth_mesh_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 |
| :ref:`bluetooth_mesh_models_rpr_srv` 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 :c:func:`bt_mesh_reprovision_remote` call: |
| |
| .. code-block:: C |
| |
| 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 |
| ************* |
| |
| .. doxygengroup:: bt_mesh_rpr_cli |
| :project: Zephyr |
| :members: |