1.. _bluetooth_mesh_models_rpr_cli:
2
3Remote Provisioning Client
4##########################
5
6The Remote Provisioning Client model is a foundation model defined by the Bluetooth
7mesh specification. It is enabled with the
8:kconfig:option:`CONFIG_BT_MESH_RPR_CLI` option.
9
10The Remote Provisioning Client model is introduced in the Bluetooth Mesh Protocol
11Specification version 1.1.
12This model provides functionality to remotely provision devices into a mesh network, and perform
13Node Provisioning Protocol Interface procedures by interacting with mesh nodes that support the
14:ref:`bluetooth_mesh_models_rpr_srv` model.
15
16The Remote Provisioning Client model communicates with a Remote Provisioning Server model
17using the device key of the node containing the target Remote Provisioning Server model instance.
18
19If present, the Remote Provisioning Client model must be instantiated on the primary
20element.
21
22Scanning
23********
24
25The scanning procedure is used to scan for unprovisioned devices located nearby the Remote
26Provisioning Server. The Remote Provisioning Client starts a scan procedure by using the
27:c:func:`bt_mesh_rpr_scan_start` call:
28
29.. code-block:: C
30
31      static void rpr_scan_report(struct bt_mesh_rpr_cli *cli,
32                  const struct bt_mesh_rpr_node *srv,
33                  struct bt_mesh_rpr_unprov *unprov,
34                  struct net_buf_simple *adv_data)
35      {
36
37      }
38
39      struct bt_mesh_rpr_cli rpr_cli = {
40         .scan_report = rpr_scan_report,
41      };
42
43      const struct bt_mesh_rpr_node srv = {
44         .addr = 0x0004,
45         .net_idx = 0,
46         .ttl = BT_MESH_TTL_DEFAULT,
47      };
48
49      struct bt_mesh_rpr_scan_status status;
50      uint8_t *uuid = NULL;
51      uint8_t timeout = 10;
52      uint8_t max_devs = 3;
53
54      bt_mesh_rpr_scan_start(&rpr_cli, &srv, uuid, timeout, max_devs, &status);
55
56The above example shows pseudo code for starting a scan procedure on the target Remote Provisioning
57Server node. This procedure will start a ten-second, multiple-device scanning where the generated
58scan report will contain a maximum of three unprovisioned devices. If the UUID argument was
59specified, the same procedure would only scan for the device with the corresponding UUID. After the
60procedure completes, the server sends the scan report that will be handled in the client's
61:c:member:`bt_mesh_rpr_cli.scan_report` callback.
62
63Additionally, the Remote Provisioning Client model also supports extended scanning with the
64:c:func:`bt_mesh_rpr_scan_start_ext` call. Extended scanning supplements regular scanning by
65allowing the Remote Provisioning Server to report additional data for a specific device. The Remote
66Provisioning Server will use active scanning to request a scan response from the unprovisioned
67device if it is supported by the unprovisioned device.
68
69Provisioning
70************
71
72The Remote Provisioning Client starts a provisioning procedure by using the
73:c:func:`bt_mesh_provision_remote` call:
74
75.. code-block:: C
76
77      struct bt_mesh_rpr_cli rpr_cli;
78
79      const struct bt_mesh_rpr_node srv = {
80         .addr = 0x0004,
81         .net_idx = 0,
82         .ttl = BT_MESH_TTL_DEFAULT,
83      };
84
85      uint8_t uuid[16] = { 0xaa };
86      uint16_t addr = 0x0006;
87      uint16_t net_idx = 0;
88
89      bt_mesh_provision_remote(&rpr_cli, &srv, uuid, net_idx, addr);
90
91The above example shows pseudo code for remotely provisioning a device through a Remote Provisioning
92Server node. This procedure will attempt to provision the device with the corresponding UUID, and
93assign the address 0x0006 to its primary element using the network key located at index zero.
94
95.. note::
96   During the remote provisioning, the same :c:struct:`bt_mesh_prov` callbacks are triggered as for
97   ordinary provisioning. See section :ref:`bluetooth_mesh_provisioning` for further details.
98
99Re-provisioning
100***************
101
102In addition to scanning and provisioning functionality, the Remote Provisioning Client also provides
103means to reconfigure node addresses, device keys and Composition Data on devices that support the
104:ref:`bluetooth_mesh_models_rpr_srv` model. This is provided through the Node Provisioning Protocol
105Interface (NPPI) which supports the following three procedures:
106
107* Device Key Refresh procedure: Used to change the device key of the Target node without a need to
108  reconfigure the node.
109* Node Address Refresh procedure: Used to change the node’s device key and unicast address.
110* Node Composition Refresh procedure: Used to change the device key of the node, and to add or
111  delete models or features of the node.
112
113The three NPPI procedures can be initiated with the :c:func:`bt_mesh_reprovision_remote` call:
114
115.. code-block:: C
116
117      struct bt_mesh_rpr_cli rpr_cli;
118      struct bt_mesh_rpr_node srv = {
119         .addr = 0x0006,
120         .net_idx = 0,
121         .ttl = BT_MESH_TTL_DEFAULT,
122      };
123
124      bool composition_changed = false;
125      uint16_t new_addr = 0x0009;
126
127      bt_mesh_reprovision_remote(&rpr_cli, &srv, new_addr, composition_changed);
128
129The above example shows pseudo code for triggering a Node Address Refresh procedure on the Target
130node. The specific procedure is not chosen directly, but rather through the other parameters that
131are inputted. In the example we can see that the current unicast address of the Target is 0x0006,
132while the new address is set to 0x0009. If the two addresses were the same, and the
133``composition_changed`` flag was set to true, this code would instead trigger a Node Composition
134Refresh procedure. If the two addresses were the same, and the ``composition_changed`` flag was set
135to false, this code would trigger a Device Key Refresh procedure.
136
137API reference
138*************
139
140.. doxygengroup:: bt_mesh_rpr_cli
141   :project: Zephyr
142   :members:
143