Line data Source code
1 0 : /*
2 : * Copyright (c) 2020 Nordic Semiconductor ASA
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_INCLUDE_BT_MESH_RPR_CLI_H__
8 : #define ZEPHYR_INCLUDE_BT_MESH_RPR_CLI_H__
9 :
10 : #include <zephyr/kernel.h>
11 : #include <zephyr/bluetooth/mesh/access.h>
12 : #include <zephyr/bluetooth/mesh/rpr.h>
13 :
14 : #ifdef __cplusplus
15 : extern "C" {
16 : #endif
17 :
18 : /**
19 : * @defgroup bt_mesh_rpr_cli Remote Provisioning Client model
20 : * @ingroup bt_mesh
21 : * @{
22 : */
23 :
24 : /** Special value for the @c max_devs parameter of @ref bt_mesh_rpr_scan_start.
25 : *
26 : * Tells the Remote Provisioning Server not to put restrictions on the max
27 : * number of devices reported to the Client.
28 : */
29 1 : #define BT_MESH_RPR_SCAN_MAX_DEVS_ANY 0
30 :
31 : struct bt_mesh_rpr_cli;
32 :
33 : /**
34 : *
35 : * @brief Remote Provisioning Client model composition data entry.
36 : *
37 : * @param _cli Pointer to a @ref bt_mesh_rpr_cli instance.
38 : */
39 1 : #define BT_MESH_MODEL_RPR_CLI(_cli) \
40 : BT_MESH_MODEL_CB(BT_MESH_MODEL_ID_REMOTE_PROV_CLI, \
41 : _bt_mesh_rpr_cli_op, NULL, _cli, &_bt_mesh_rpr_cli_cb)
42 :
43 : /** Scan status response */
44 1 : struct bt_mesh_rpr_scan_status {
45 : /** Current scan status */
46 1 : enum bt_mesh_rpr_status status;
47 : /** Current scan state */
48 1 : enum bt_mesh_rpr_scan scan;
49 : /** Max number of devices to report in current scan. */
50 1 : uint8_t max_devs;
51 : /** Seconds remaining of the scan. */
52 1 : uint8_t timeout;
53 : };
54 :
55 : /** Remote Provisioning Server scanning capabilities */
56 1 : struct bt_mesh_rpr_caps {
57 : /** Max number of scannable devices */
58 1 : uint8_t max_devs;
59 : /** Supports active scan */
60 1 : bool active_scan;
61 : };
62 :
63 : /** Remote Provisioning Client model instance. */
64 1 : struct bt_mesh_rpr_cli {
65 : /** @brief Scan report callback.
66 : *
67 : * @param cli Remote Provisioning Client.
68 : * @param srv Remote Provisioning Server.
69 : * @param unprov Unprovisioned device.
70 : * @param adv_data Advertisement data for the unprovisioned device, or
71 : * NULL if extended scanning hasn't been enabled. An
72 : * empty buffer indicates that the extended scanning
73 : * finished without collecting additional information.
74 : */
75 1 : void (*scan_report)(struct bt_mesh_rpr_cli *cli,
76 : const struct bt_mesh_rpr_node *srv,
77 : struct bt_mesh_rpr_unprov *unprov,
78 : struct net_buf_simple *adv_data);
79 :
80 : /* Internal parameters */
81 :
82 0 : struct bt_mesh_msg_ack_ctx scan_ack_ctx;
83 0 : struct bt_mesh_msg_ack_ctx prov_ack_ctx;
84 :
85 : struct {
86 0 : struct k_work_delayable timeout;
87 0 : struct bt_mesh_rpr_node srv;
88 0 : uint8_t time;
89 0 : uint8_t tx_pdu;
90 0 : uint8_t rx_pdu;
91 0 : enum bt_mesh_rpr_link_state state;
92 0 : } link;
93 :
94 0 : const struct bt_mesh_model *mod;
95 : };
96 :
97 : /** @brief Get scanning capabilities of Remote Provisioning Server.
98 : *
99 : * @param cli Remote Provisioning Client.
100 : * @param srv Remote Provisioning Server.
101 : * @param caps Capabilities response buffer.
102 : *
103 : * @return 0 on success, or (negative) error code otherwise.
104 : */
105 1 : int bt_mesh_rpr_scan_caps_get(struct bt_mesh_rpr_cli *cli,
106 : const struct bt_mesh_rpr_node *srv,
107 : struct bt_mesh_rpr_caps *caps);
108 :
109 : /** @brief Get current scanning state of Remote Provisioning Server.
110 : *
111 : * @param cli Remote Provisioning Client.
112 : * @param srv Remote Provisioning Server.
113 : * @param status Scan status response buffer.
114 : *
115 : * @return 0 on success, or (negative) error code otherwise.
116 : */
117 1 : int bt_mesh_rpr_scan_get(struct bt_mesh_rpr_cli *cli,
118 : const struct bt_mesh_rpr_node *srv,
119 : struct bt_mesh_rpr_scan_status *status);
120 :
121 : /** @brief Start scanning for unprovisioned devices.
122 : *
123 : * Tells the Remote Provisioning Server to start scanning for unprovisioned
124 : * devices. The Server will report back the results through the @ref
125 : * bt_mesh_rpr_cli::scan_report callback.
126 : *
127 : * Use the @c uuid parameter to scan for a specific device, or leave it as NULL
128 : * to report all unprovisioned devices.
129 : *
130 : * The Server will ignore duplicates, and report up to @c max_devs number of
131 : * devices. Requesting a @c max_devs number that's higher than the Server's
132 : * capability will result in an error.
133 : *
134 : * @param cli Remote Provisioning Client.
135 : * @param srv Remote Provisioning Server.
136 : * @param uuid Device UUID to scan for, or NULL to report all devices.
137 : * @param timeout Scan timeout in seconds. Must be at least 1 second.
138 : * @param max_devs Max number of devices to report, or 0 to report as many as
139 : * possible.
140 : * @param status Scan status response buffer.
141 : *
142 : * @return 0 on success, or (negative) error code otherwise.
143 : */
144 1 : int bt_mesh_rpr_scan_start(struct bt_mesh_rpr_cli *cli,
145 : const struct bt_mesh_rpr_node *srv,
146 : const uint8_t uuid[16], uint8_t timeout,
147 : uint8_t max_devs,
148 : struct bt_mesh_rpr_scan_status *status);
149 :
150 : /** @brief Start extended scanning for unprovisioned devices.
151 : *
152 : * Extended scanning supplements regular unprovisioned scanning, by allowing
153 : * the Server to report additional data for a specific device. The Remote
154 : * Provisioning Server will use active scanning to request a scan
155 : * response from the unprovisioned device, if supported. If no UUID is
156 : * provided, the Server will report a scan on its own OOB information and
157 : * advertising data.
158 : *
159 : * Use the ad_types array to specify which AD types to include in the scan
160 : * report. Some AD types invoke special behavior:
161 : * - @ref BT_DATA_NAME_COMPLETE Will report both the complete and the
162 : * shortened name.
163 : * - @ref BT_DATA_URI If the unprovisioned beacon contains a URI hash, the
164 : * Server will extend the scanning to include packets other than
165 : * the scan response, to look for URIs matching the URI hash. Only matching
166 : * URIs will be reported.
167 : *
168 : * The following AD types should not be used:
169 : * - @ref BT_DATA_NAME_SHORTENED
170 : * - @ref BT_DATA_UUID16_SOME
171 : * - @ref BT_DATA_UUID32_SOME
172 : * - @ref BT_DATA_UUID128_SOME
173 : *
174 : * Additionally, each AD type should only occur once.
175 : *
176 : * @param cli Remote Provisioning Client.
177 : * @param srv Remote Provisioning Server.
178 : * @param uuid Device UUID to start extended scanning for, or NULL to scan
179 : * the remote server.
180 : * @param timeout Scan timeout in seconds. Valid values from @ref BT_MESH_RPR_EXT_SCAN_TIME_MIN
181 : * to @ref BT_MESH_RPR_EXT_SCAN_TIME_MAX. Ignored if UUID is NULL.
182 : * @param ad_types List of AD types to include in the scan report. Must contain 1 to
183 : * CONFIG_BT_MESH_RPR_AD_TYPES_MAX entries.
184 : * @param ad_count Number of AD types in @c ad_types.
185 : *
186 : * @return 0 on success, or (negative) error code otherwise.
187 : */
188 1 : int bt_mesh_rpr_scan_start_ext(struct bt_mesh_rpr_cli *cli,
189 : const struct bt_mesh_rpr_node *srv,
190 : const uint8_t uuid[16], uint8_t timeout,
191 : const uint8_t *ad_types, size_t ad_count);
192 :
193 : /** @brief Stop any ongoing scanning on the Remote Provisioning Server.
194 : *
195 : * @param cli Remote Provisioning Client.
196 : * @param srv Remote Provisioning Server.
197 : * @param status Scan status response buffer.
198 : *
199 : * @return 0 on success, or (negative) error code otherwise.
200 : */
201 1 : int bt_mesh_rpr_scan_stop(struct bt_mesh_rpr_cli *cli,
202 : const struct bt_mesh_rpr_node *srv,
203 : struct bt_mesh_rpr_scan_status *status);
204 :
205 : /** @brief Get the current link status of the Remote Provisioning Server.
206 : *
207 : * @param cli Remote Provisioning Client.
208 : * @param srv Remote Provisioning Server.
209 : * @param rsp Link status response buffer.
210 : *
211 : * @return 0 on success, or (negative) error code otherwise.
212 : */
213 1 : int bt_mesh_rpr_link_get(struct bt_mesh_rpr_cli *cli,
214 : const struct bt_mesh_rpr_node *srv,
215 : struct bt_mesh_rpr_link *rsp);
216 :
217 : /** @brief Close any open link on the Remote Provisioning Server.
218 : *
219 : * @param cli Remote Provisioning Client.
220 : * @param srv Remote Provisioning Server.
221 : * @param rsp Link status response buffer.
222 : *
223 : * @return 0 on success, or (negative) error code otherwise.
224 : */
225 1 : int bt_mesh_rpr_link_close(struct bt_mesh_rpr_cli *cli,
226 : const struct bt_mesh_rpr_node *srv,
227 : struct bt_mesh_rpr_link *rsp);
228 :
229 : /** @brief Get the current transmission timeout value.
230 : *
231 : * @return The configured transmission timeout in milliseconds.
232 : */
233 1 : int32_t bt_mesh_rpr_cli_timeout_get(void);
234 :
235 : /** @brief Set the transmission timeout value.
236 : *
237 : * The transmission timeout controls the amount of time the Remote Provisioning
238 : * Client models will wait for a response from the Server.
239 : *
240 : * @param timeout The new transmission timeout.
241 : */
242 1 : void bt_mesh_rpr_cli_timeout_set(int32_t timeout);
243 :
244 : /** @cond INTERNAL_HIDDEN */
245 : extern const struct bt_mesh_model_op _bt_mesh_rpr_cli_op[];
246 : extern const struct bt_mesh_model_cb _bt_mesh_rpr_cli_cb;
247 : /** @endcond */
248 :
249 : /** @} */
250 :
251 : #ifdef __cplusplus
252 : }
253 : #endif
254 :
255 : #endif /* ZEPHYR_INCLUDE_BT_MESH_RPR_CLI_H__ */
|
