Line data Source code
1 1 : /** @file
2 : * @brief Bluetooth Mesh Protocol APIs.
3 : */
4 :
5 : /*
6 : * Copyright (c) 2017 Intel Corporation
7 : *
8 : * SPDX-License-Identifier: Apache-2.0
9 : */
10 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_MESH_MAIN_H_
11 : #define ZEPHYR_INCLUDE_BLUETOOTH_MESH_MAIN_H_
12 :
13 : #include <stdbool.h>
14 : #include <stdint.h>
15 :
16 : #include <zephyr/kernel.h>
17 : #include <zephyr/sys/iterable_sections.h>
18 :
19 : /**
20 : * @brief Provisioning
21 : * @defgroup bt_mesh_prov Provisioning
22 : * @ingroup bt_mesh
23 : * @{
24 : */
25 :
26 : #ifdef __cplusplus
27 : extern "C" {
28 : #endif
29 :
30 : /** Available authentication algorithms. */
31 0 : enum {
32 : BT_MESH_PROV_AUTH_CMAC_AES128_AES_CCM,
33 : BT_MESH_PROV_AUTH_HMAC_SHA256_AES_CCM,
34 : };
35 :
36 : /** OOB Type field values. */
37 1 : enum {
38 : BT_MESH_STATIC_OOB_AVAILABLE = BIT(0), /**< Static OOB information available */
39 : BT_MESH_OOB_AUTH_REQUIRED = BIT(1) /**< OOB authentication required */
40 : };
41 :
42 : /** Available Provisioning output authentication actions. */
43 0 : typedef enum {
44 : BT_MESH_NO_OUTPUT = 0,
45 : BT_MESH_BLINK = BIT(0), /**< Blink */
46 : BT_MESH_BEEP = BIT(1), /**< Beep */
47 : BT_MESH_VIBRATE = BIT(2), /**< Vibrate */
48 : BT_MESH_DISPLAY_NUMBER = BIT(3), /**< Output numeric */
49 : BT_MESH_DISPLAY_STRING = BIT(4), /**< Output alphanumeric */
50 : } bt_mesh_output_action_t;
51 :
52 : /** Available Provisioning input authentication actions. */
53 0 : typedef enum {
54 : BT_MESH_NO_INPUT = 0,
55 : BT_MESH_PUSH = BIT(0), /**< Push */
56 : BT_MESH_TWIST = BIT(1), /**< Twist */
57 : BT_MESH_ENTER_NUMBER = BIT(2), /**< Input number */
58 : BT_MESH_ENTER_STRING = BIT(3), /**< Input alphanumeric */
59 : } bt_mesh_input_action_t;
60 :
61 : /** Available Provisioning bearers. */
62 1 : typedef enum {
63 : BT_MESH_PROV_ADV = BIT(0), /**< PB-ADV bearer */
64 : BT_MESH_PROV_GATT = BIT(1), /**< PB-GATT bearer */
65 : BT_MESH_PROV_REMOTE = BIT(2), /**< PB-Remote bearer */
66 : } bt_mesh_prov_bearer_t;
67 :
68 : /** Out of Band information location. */
69 1 : typedef enum {
70 : BT_MESH_PROV_OOB_OTHER = BIT(0), /**< Other */
71 : BT_MESH_PROV_OOB_URI = BIT(1), /**< Electronic / URI */
72 : BT_MESH_PROV_OOB_2D_CODE = BIT(2), /**< 2D machine-readable code */
73 : BT_MESH_PROV_OOB_BAR_CODE = BIT(3), /**< Bar Code */
74 : BT_MESH_PROV_OOB_NFC = BIT(4), /**< Near Field Communication (NFC) */
75 : BT_MESH_PROV_OOB_NUMBER = BIT(5), /**< Number */
76 : BT_MESH_PROV_OOB_STRING = BIT(6), /**< String */
77 : BT_MESH_PROV_OOB_CERTIFICATE = BIT(7), /**< Support for certificate-based provisioning */
78 : BT_MESH_PROV_OOB_RECORDS = BIT(8), /**< Support for provisioning records */
79 : /* 9 - 10 are reserved */
80 : BT_MESH_PROV_OOB_ON_BOX = BIT(11), /**< On box */
81 : BT_MESH_PROV_OOB_IN_BOX = BIT(12), /**< Inside box */
82 : BT_MESH_PROV_OOB_ON_PAPER = BIT(13), /**< On piece of paper */
83 : BT_MESH_PROV_OOB_IN_MANUAL = BIT(14), /**< Inside manual */
84 : BT_MESH_PROV_OOB_ON_DEV = BIT(15), /**< On device */
85 : } bt_mesh_prov_oob_info_t;
86 :
87 : /** Device Capabilities. */
88 1 : struct bt_mesh_dev_capabilities {
89 : /** Number of elements supported by the device */
90 1 : uint8_t elem_count;
91 :
92 : /** Supported algorithms and other capabilities */
93 1 : uint16_t algorithms;
94 :
95 : /** Supported public key types */
96 1 : uint8_t pub_key_type;
97 :
98 : /** Supported OOB Types */
99 1 : uint8_t oob_type;
100 :
101 : /** Supported Output OOB Actions */
102 1 : bt_mesh_output_action_t output_actions;
103 :
104 : /** Supported Input OOB Actions */
105 1 : bt_mesh_input_action_t input_actions;
106 :
107 : /** Maximum size of Output OOB supported */
108 1 : uint8_t output_size;
109 :
110 : /** Maximum size in octets of Input OOB supported */
111 1 : uint8_t input_size;
112 : };
113 :
114 : /** Provisioning properties & capabilities. */
115 1 : struct bt_mesh_prov {
116 : /** The UUID that's used when advertising as unprovisioned */
117 1 : const uint8_t *uuid;
118 :
119 : /** Optional URI. This will be advertised separately from the
120 : * unprovisioned beacon, however the unprovisioned beacon will
121 : * contain a hash of it so the two can be associated by the
122 : * provisioner.
123 : */
124 1 : const char *uri;
125 :
126 : /** Out of Band information field. */
127 1 : bt_mesh_prov_oob_info_t oob_info;
128 :
129 : /** Pointer to Public Key in big-endian for OOB public key type support.
130 : *
131 : * Remember to enable @kconfig{CONFIG_BT_MESH_PROV_OOB_PUBLIC_KEY}
132 : * when initializing this parameter.
133 : *
134 : * Must be used together with @ref bt_mesh_prov::private_key_be.
135 : */
136 1 : const uint8_t *public_key_be;
137 : /** Pointer to Private Key in big-endian for OOB public key type support.
138 : *
139 : * Remember to enable @kconfig{CONFIG_BT_MESH_PROV_OOB_PUBLIC_KEY}
140 : * when initializing this parameter.
141 : *
142 : * Must be used together with @ref bt_mesh_prov::public_key_be.
143 : */
144 1 : const uint8_t *private_key_be;
145 :
146 : /** Static OOB value */
147 1 : const uint8_t *static_val;
148 : /** Static OOB value length */
149 1 : uint8_t static_val_len;
150 :
151 : /** Maximum size of Output OOB supported */
152 1 : uint8_t output_size;
153 : /** Supported Output OOB Actions */
154 1 : uint16_t output_actions;
155 :
156 : /** Maximum size of Input OOB supported */
157 1 : uint8_t input_size;
158 : /** Supported Input OOB Actions */
159 1 : uint16_t input_actions;
160 :
161 : /** @brief Provisioning Capabilities.
162 : *
163 : * This callback notifies the application that the provisioning capabilities
164 : * of the unprovisioned device has been received.
165 : *
166 : * The application can consequently call bt_mesh_auth_method_set_<*> to
167 : * select suitable provisioning oob authentication method.
168 : *
169 : * When this callback returns, the provisioner will start authentication with
170 : * the chosen method.
171 : *
172 : * @param cap capabilities supported by device.
173 : */
174 1 : void (*capabilities)(const struct bt_mesh_dev_capabilities *cap);
175 :
176 : /** @brief Output of a number is requested.
177 : *
178 : * This callback notifies the application that it should
179 : * output the given number using the given action.
180 : *
181 : * @param act Action for outputting the number.
182 : * @param num Number to be outputted.
183 : *
184 : * @return Zero on success or negative error code otherwise
185 : */
186 1 : int (*output_number)(bt_mesh_output_action_t act, uint32_t num);
187 :
188 : /** @brief Output of a string is requested.
189 : *
190 : * This callback notifies the application that it should
191 : * display the given string to the user.
192 : *
193 : * @param str String to be displayed.
194 : *
195 : * @return Zero on success or negative error code otherwise
196 : */
197 1 : int (*output_string)(const char *str);
198 :
199 : /** @brief Input is requested.
200 : *
201 : * This callback notifies the application that it should
202 : * request input from the user using the given action. The
203 : * requested input will either be a string or a number, and
204 : * the application needs to consequently call the
205 : * bt_mesh_input_string() or bt_mesh_input_number() functions
206 : * once the data has been acquired from the user.
207 : *
208 : * @param act Action for inputting data.
209 : * @param num Maximum size of the inputted data.
210 : *
211 : * @return Zero on success or negative error code otherwise
212 : */
213 1 : int (*input)(bt_mesh_input_action_t act, uint8_t size);
214 :
215 : /** @brief The other device finished their OOB input.
216 : *
217 : * This callback notifies the application that it should stop
218 : * displaying its output OOB value, as the other party finished their
219 : * OOB input.
220 : */
221 1 : void (*input_complete)(void);
222 :
223 : /** @brief Unprovisioned beacon has been received.
224 : *
225 : * This callback notifies the application that an unprovisioned
226 : * beacon has been received.
227 : *
228 : * @param uuid UUID
229 : * @param oob_info OOB Information
230 : * @param uri_hash Pointer to URI Hash value. NULL if no hash was
231 : * present in the beacon.
232 : */
233 1 : void (*unprovisioned_beacon)(uint8_t uuid[16],
234 : bt_mesh_prov_oob_info_t oob_info,
235 : uint32_t *uri_hash);
236 :
237 : /** @brief PB-GATT Unprovisioned Advertising has been received.
238 : *
239 : * This callback notifies the application that an PB-GATT
240 : * unprovisioned Advertising has been received.
241 : *
242 : * @param uuid UUID
243 : * @param oob_info OOB Information
244 : */
245 1 : void (*unprovisioned_beacon_gatt)(uint8_t uuid[16],
246 : bt_mesh_prov_oob_info_t oob_info);
247 :
248 : /** @brief Provisioning link has been opened.
249 : *
250 : * This callback notifies the application that a provisioning
251 : * link has been opened on the given provisioning bearer.
252 : *
253 : * @param bearer Provisioning bearer.
254 : */
255 1 : void (*link_open)(bt_mesh_prov_bearer_t bearer);
256 :
257 : /** @brief Provisioning link has been closed.
258 : *
259 : * This callback notifies the application that a provisioning
260 : * link has been closed on the given provisioning bearer.
261 : *
262 : * @param bearer Provisioning bearer.
263 : */
264 1 : void (*link_close)(bt_mesh_prov_bearer_t bearer);
265 :
266 : /** @brief Provisioning is complete.
267 : *
268 : * This callback notifies the application that provisioning has
269 : * been successfully completed, and that the local node has been
270 : * assigned the specified NetKeyIndex and primary element address.
271 : *
272 : * @param net_idx NetKeyIndex given during provisioning.
273 : * @param addr Primary element address.
274 : */
275 1 : void (*complete)(uint16_t net_idx, uint16_t addr);
276 :
277 : /** @brief Local node has been reprovisioned.
278 : *
279 : * This callback notifies the application that reprovisioning has
280 : * been successfully completed.
281 : *
282 : * @param addr New primary element address.
283 : */
284 1 : void (*reprovisioned)(uint16_t addr);
285 :
286 : /** @brief A new node has been added to the provisioning database.
287 : *
288 : * This callback notifies the application that provisioning has
289 : * been successfully completed, and that a node has been assigned
290 : * the specified NetKeyIndex and primary element address.
291 : *
292 : * @param net_idx NetKeyIndex given during provisioning.
293 : * @param uuid UUID of the added node
294 : * @param addr Primary element address.
295 : * @param num_elem Number of elements that this node has.
296 : */
297 1 : void (*node_added)(uint16_t net_idx, uint8_t uuid[16], uint16_t addr,
298 : uint8_t num_elem);
299 :
300 : /** @brief Node has been reset.
301 : *
302 : * This callback notifies the application that the local node
303 : * has been reset and needs to be provisioned again. The node will
304 : * not automatically advertise as unprovisioned, rather the
305 : * bt_mesh_prov_enable() API needs to be called to enable
306 : * unprovisioned advertising on one or more provisioning bearers.
307 : */
308 1 : void (*reset)(void);
309 : };
310 :
311 : struct bt_mesh_rpr_cli;
312 : struct bt_mesh_rpr_node;
313 :
314 : /** @brief Provide provisioning input OOB string.
315 : *
316 : * This is intended to be called after the bt_mesh_prov input callback
317 : * has been called with BT_MESH_ENTER_STRING as the action.
318 : *
319 : * @param str String.
320 : *
321 : * @return Zero on success or (negative) error code otherwise.
322 : */
323 1 : int bt_mesh_input_string(const char *str);
324 :
325 : /** @brief Provide provisioning input OOB number.
326 : *
327 : * This is intended to be called after the bt_mesh_prov input callback
328 : * has been called with BT_MESH_ENTER_NUMBER as the action.
329 : *
330 : * @param num Number.
331 : *
332 : * @return Zero on success or (negative) error code otherwise.
333 : */
334 1 : int bt_mesh_input_number(uint32_t num);
335 :
336 : /** @brief Provide Device public key.
337 : *
338 : * @param public_key Device public key in big-endian.
339 : *
340 : * @return Zero on success or (negative) error code otherwise.
341 : */
342 1 : int bt_mesh_prov_remote_pub_key_set(const uint8_t public_key[64]);
343 :
344 : /** @brief Use Input OOB authentication.
345 : *
346 : * Provisioner only.
347 : *
348 : * Instruct the unprovisioned device to use the specified Input OOB
349 : * authentication action. When using @ref BT_MESH_PUSH, @ref BT_MESH_TWIST or
350 : * @ref BT_MESH_ENTER_NUMBER, the @ref bt_mesh_prov::output_number callback is
351 : * called with a random number that has to be entered on the unprovisioned
352 : * device.
353 : *
354 : * When using @ref BT_MESH_ENTER_STRING, the @ref bt_mesh_prov::output_string
355 : * callback is called with a random string that has to be entered on the
356 : * unprovisioned device.
357 : *
358 : * @param action Authentication action used by the unprovisioned device.
359 : * @param size Authentication size.
360 : *
361 : * @return Zero on success or (negative) error code otherwise.
362 : */
363 1 : int bt_mesh_auth_method_set_input(bt_mesh_input_action_t action, uint8_t size);
364 :
365 : /** @brief Use Output OOB authentication.
366 : *
367 : * Provisioner only.
368 : *
369 : * Instruct the unprovisioned device to use the specified Output OOB
370 : * authentication action. The @ref bt_mesh_prov::input callback will
371 : * be called.
372 : *
373 : * When using @ref BT_MESH_BLINK, @ref BT_MESH_BEEP, @ref BT_MESH_VIBRATE
374 : * or @ref BT_MESH_DISPLAY_NUMBER, and the application has to call
375 : * @ref bt_mesh_input_number with the random number indicated by
376 : * the unprovisioned device.
377 : *
378 : * When using @ref BT_MESH_DISPLAY_STRING, the application has to call
379 : * @ref bt_mesh_input_string with the random string displayed by the
380 : * unprovisioned device.
381 : *
382 : * @param action Authentication action used by the unprovisioned device.
383 : * @param size Authentication size.
384 : *
385 : * @return Zero on success or (negative) error code otherwise.
386 : */
387 1 : int bt_mesh_auth_method_set_output(bt_mesh_output_action_t action, uint8_t size);
388 :
389 : /** @brief Use static OOB authentication.
390 : *
391 : * Provisioner only.
392 : *
393 : * Instruct the unprovisioned device to use static OOB authentication, and use
394 : * the given static authentication value when provisioning.
395 : *
396 : * @param static_val Static OOB value.
397 : * @param size Static OOB value size.
398 : *
399 : * @return Zero on success or (negative) error code otherwise.
400 : */
401 1 : int bt_mesh_auth_method_set_static(const uint8_t *static_val, uint8_t size);
402 :
403 : /** @brief Don't use OOB authentication.
404 : *
405 : * Provisioner only.
406 : *
407 : * Don't use any authentication when provisioning new devices. This is the
408 : * default behavior.
409 : *
410 : * @warning Not using any authentication exposes the mesh network to
411 : * impersonation attacks, where attackers can pretend to be the
412 : * unprovisioned device to gain access to the network. Authentication
413 : * is strongly encouraged.
414 : *
415 : * @return Zero on success or (negative) error code otherwise.
416 : */
417 1 : int bt_mesh_auth_method_set_none(void);
418 :
419 : /** @brief Enable specific provisioning bearers
420 : *
421 : * Enable one or more provisioning bearers.
422 : *
423 : * @param bearers Bit-wise or of provisioning bearers.
424 : *
425 : * @return Zero on success or (negative) error code otherwise.
426 : */
427 1 : int bt_mesh_prov_enable(bt_mesh_prov_bearer_t bearers);
428 :
429 : /** @brief Disable specific provisioning bearers
430 : *
431 : * Disable one or more provisioning bearers.
432 : *
433 : * @param bearers Bit-wise or of provisioning bearers.
434 : *
435 : * @return Zero on success or (negative) error code otherwise.
436 : */
437 1 : int bt_mesh_prov_disable(bt_mesh_prov_bearer_t bearers);
438 :
439 : /** @brief Provision the local Mesh Node.
440 : *
441 : * This API should normally not be used directly by the application. The
442 : * only exception is for testing purposes where manual provisioning is
443 : * desired without an actual external provisioner.
444 : *
445 : * @param net_key Network Key
446 : * @param net_idx Network Key Index
447 : * @param flags Provisioning Flags
448 : * @param iv_index IV Index
449 : * @param addr Primary element address
450 : * @param dev_key Device Key
451 : *
452 : * @return Zero on success or (negative) error code otherwise.
453 : */
454 1 : int bt_mesh_provision(const uint8_t net_key[16], uint16_t net_idx,
455 : uint8_t flags, uint32_t iv_index, uint16_t addr,
456 : const uint8_t dev_key[16]);
457 :
458 : /** @brief Provision a Mesh Node using PB-ADV
459 : *
460 : * @param uuid UUID
461 : * @param net_idx Network Key Index
462 : * @param addr Address to assign to remote device. If addr is 0,
463 : * the lowest available address will be chosen.
464 : * @param attention_duration The attention duration to be send to remote device
465 : *
466 : * @return Zero on success or (negative) error code otherwise.
467 : */
468 1 : int bt_mesh_provision_adv(const uint8_t uuid[16], uint16_t net_idx, uint16_t addr,
469 : uint8_t attention_duration);
470 :
471 : /** @brief Provision a Mesh Node using PB-GATT
472 : *
473 : * @param uuid UUID
474 : * @param net_idx Network Key Index
475 : * @param addr Address to assign to remote device. If addr is 0,
476 : * the lowest available address will be chosen.
477 : * @param attention_duration The attention duration to be send to remote device
478 : *
479 : * @return Zero on success or (negative) error code otherwise.
480 : */
481 1 : int bt_mesh_provision_gatt(const uint8_t uuid[16], uint16_t net_idx, uint16_t addr,
482 : uint8_t attention_duration);
483 :
484 : /** @brief Provision a Mesh Node using PB-Remote
485 : *
486 : * @param cli Remote Provisioning Client Model to provision with.
487 : * @param srv Remote Provisioning Server that should be used to tunnel the
488 : * provisioning.
489 : * @param uuid UUID of the unprovisioned node
490 : * @param net_idx Network Key Index to give to the unprovisioned node.
491 : * @param addr Address to assign to remote device. If addr is 0,
492 : * the lowest available address will be chosen.
493 : *
494 : * @return Zero on success or (negative) error code otherwise.
495 : */
496 1 : int bt_mesh_provision_remote(struct bt_mesh_rpr_cli *cli,
497 : const struct bt_mesh_rpr_node *srv,
498 : const uint8_t uuid[16], uint16_t net_idx,
499 : uint16_t addr);
500 :
501 : /** @brief Reprovision a Mesh Node using PB-Remote
502 : *
503 : * Reprovisioning can be used to change the device key, unicast address and
504 : * composition data of another device. The reprovisioning procedure uses the
505 : * same protocol as normal provisioning, with the same level of security.
506 : *
507 : * There are three tiers of reprovisioning:
508 : * 1. Refreshing the device key
509 : * 2. Refreshing the device key and node address. Composition data may change,
510 : * including the number of elements.
511 : * 3. Refreshing the device key and composition data, in case the composition
512 : * data of the target node changed due to a firmware update or a similar
513 : * procedure.
514 : *
515 : * The target node indicates that its composition data changed by instantiating
516 : * its composition data page 128. If the number of elements have changed, it
517 : * may be necessary to move the unicast address of the target node as well, to
518 : * avoid overlapping addresses.
519 : *
520 : * @note Changing the unicast addresses of the target node requires changes to
521 : * all nodes that publish directly to any of the target node's models.
522 : *
523 : * @param cli Remote Provisioning Client Model to provision on
524 : * @param srv Remote Provisioning Server to reprovision
525 : * @param addr Address to assign to remote device. If addr is 0, the
526 : * lowest available address will be chosen.
527 : * @param comp_change The target node has indicated that its composition
528 : * data has changed. Note that the target node will reject
529 : * the update if this isn't true.
530 : *
531 : * @return Zero on success or (negative) error code otherwise.
532 : */
533 1 : int bt_mesh_reprovision_remote(struct bt_mesh_rpr_cli *cli,
534 : struct bt_mesh_rpr_node *srv,
535 : uint16_t addr, bool comp_change);
536 :
537 : /** @brief Check if the local node has been provisioned.
538 : *
539 : * This API can be used to check if the local node has been provisioned
540 : * or not. It can e.g. be helpful to determine if there was a stored
541 : * network in flash, i.e. if the network was restored after calling
542 : * settings_load().
543 : *
544 : * @return True if the node is provisioned. False otherwise.
545 : */
546 1 : bool bt_mesh_is_provisioned(void);
547 :
548 : /**
549 : * @}
550 : */
551 :
552 : /**
553 : * @brief Bluetooth Mesh
554 : * @defgroup bt_mesh Bluetooth Mesh
555 : * @ingroup bluetooth
556 : * @{
557 : */
558 :
559 : /** Primary Network Key index */
560 1 : #define BT_MESH_NET_PRIMARY 0x000
561 :
562 : /** Relay feature */
563 1 : #define BT_MESH_FEAT_RELAY BIT(0)
564 : /** GATT Proxy feature */
565 1 : #define BT_MESH_FEAT_PROXY BIT(1)
566 : /** Friend feature */
567 1 : #define BT_MESH_FEAT_FRIEND BIT(2)
568 : /** Low Power Node feature */
569 1 : #define BT_MESH_FEAT_LOW_POWER BIT(3)
570 : /** Supported heartbeat publication features */
571 1 : #define BT_MESH_FEAT_SUPPORTED (BT_MESH_FEAT_RELAY | \
572 : BT_MESH_FEAT_PROXY | \
573 : BT_MESH_FEAT_FRIEND | \
574 : BT_MESH_FEAT_LOW_POWER)
575 :
576 : /** @brief Initialize Mesh support
577 : *
578 : * After calling this API, the node will not automatically advertise as
579 : * unprovisioned, rather the bt_mesh_prov_enable() API needs to be called
580 : * to enable unprovisioned advertising on one or more provisioning bearers.
581 : *
582 : * @param prov Node provisioning information.
583 : * @param comp Node Composition.
584 : *
585 : * @return Zero on success or (negative) error code otherwise.
586 : */
587 1 : int bt_mesh_init(const struct bt_mesh_prov *prov,
588 : const struct bt_mesh_comp *comp);
589 :
590 : /** @brief Reset the state of the local Mesh node.
591 : *
592 : * Resets the state of the node, which means that it needs to be
593 : * reprovisioned to become an active node in a Mesh network again.
594 : *
595 : * After calling this API, the node will not automatically advertise as
596 : * unprovisioned, rather the bt_mesh_prov_enable() API needs to be called
597 : * to enable unprovisioned advertising on one or more provisioning bearers.
598 : *
599 : */
600 1 : void bt_mesh_reset(void);
601 :
602 : /** @brief Suspend the Mesh network temporarily.
603 : *
604 : * This API can be used for power saving purposes, but the user should be
605 : * aware that leaving the local node suspended for a long period of time
606 : * may cause it to become permanently disconnected from the Mesh network.
607 : * If at all possible, the Friendship feature should be used instead, to
608 : * make the node into a Low Power Node.
609 : *
610 : * @return 0 on success, or (negative) error code on failure.
611 : */
612 1 : int bt_mesh_suspend(void);
613 :
614 : /** @brief Resume a suspended Mesh network.
615 : *
616 : * This API resumes the local node, after it has been suspended using the
617 : * bt_mesh_suspend() API.
618 : *
619 : * @return 0 on success, or (negative) error code on failure.
620 : */
621 1 : int bt_mesh_resume(void);
622 :
623 : /** @brief Toggle the IV Update test mode
624 : *
625 : * This API is only available if the IV Update test mode has been enabled
626 : * in Kconfig. It is needed for passing most of the IV Update qualification
627 : * test cases.
628 : *
629 : * @param enable true to enable IV Update test mode, false to disable it.
630 : */
631 1 : void bt_mesh_iv_update_test(bool enable);
632 :
633 : /** @brief Toggle the IV Update state
634 : *
635 : * This API is only available if the IV Update test mode has been enabled
636 : * in Kconfig. It is needed for passing most of the IV Update qualification
637 : * test cases.
638 : *
639 : * @return true if IV Update In Progress state was entered, false otherwise.
640 : */
641 1 : bool bt_mesh_iv_update(void);
642 :
643 : /** @brief Toggle the Low Power feature of the local device
644 : *
645 : * Enables or disables the Low Power feature of the local device. This is
646 : * exposed as a run-time feature, since the device might want to change
647 : * this e.g. based on being plugged into a stable power source or running
648 : * from a battery power source.
649 : *
650 : * @param enable true to enable LPN functionality, false to disable it.
651 : *
652 : * @return Zero on success or (negative) error code otherwise.
653 : */
654 1 : int bt_mesh_lpn_set(bool enable);
655 :
656 : /** @brief Send out a Friend Poll message.
657 : *
658 : * Send a Friend Poll message to the Friend of this node. If there is no
659 : * established Friendship the function will return an error.
660 : *
661 : * @return Zero on success or (negative) error code otherwise.
662 : */
663 1 : int bt_mesh_lpn_poll(void);
664 :
665 : /** Low Power Node callback functions. */
666 1 : struct bt_mesh_lpn_cb {
667 : /** @brief Friendship established.
668 : *
669 : * This callback notifies the application that friendship has
670 : * been successfully established.
671 : *
672 : * @param net_idx NetKeyIndex used during friendship establishment.
673 : * @param friend_addr Friend address.
674 : * @param queue_size Friend queue size.
675 : * @param recv_window Low Power Node's listens duration for
676 : * Friend response.
677 : */
678 1 : void (*established)(uint16_t net_idx, uint16_t friend_addr,
679 : uint8_t queue_size, uint8_t recv_window);
680 :
681 : /** @brief Friendship terminated.
682 : *
683 : * This callback notifies the application that friendship has
684 : * been terminated.
685 : *
686 : * @param net_idx NetKeyIndex used during friendship establishment.
687 : * @param friend_addr Friend address.
688 : */
689 1 : void (*terminated)(uint16_t net_idx, uint16_t friend_addr);
690 :
691 : /** @brief Local Poll Request.
692 : *
693 : * This callback notifies the application that the local node has
694 : * polled the friend node.
695 : *
696 : * This callback will be called before @ref bt_mesh_lpn_cb::established
697 : * when attempting to establish a friendship.
698 : *
699 : * @param net_idx NetKeyIndex used during friendship establishment.
700 : * @param friend_addr Friend address.
701 : * @param retry Retry or first poll request for each transaction.
702 : */
703 1 : void (*polled)(uint16_t net_idx, uint16_t friend_addr, bool retry);
704 : };
705 :
706 : /**
707 : * @brief Register a callback structure for Friendship events.
708 : *
709 : * @param _name Name of callback structure.
710 : */
711 1 : #define BT_MESH_LPN_CB_DEFINE(_name) \
712 : static const STRUCT_SECTION_ITERABLE(bt_mesh_lpn_cb, \
713 : _CONCAT(bt_mesh_lpn_cb_, \
714 : _name))
715 :
716 : /** Friend Node callback functions. */
717 1 : struct bt_mesh_friend_cb {
718 : /** @brief Friendship established.
719 : *
720 : * This callback notifies the application that friendship has
721 : * been successfully established.
722 : *
723 : * @param net_idx NetKeyIndex used during friendship establishment.
724 : * @param lpn_addr Low Power Node address.
725 : * @param recv_delay Receive Delay in units of 1 millisecond.
726 : * @param polltimeout PollTimeout in units of 1 millisecond.
727 : */
728 1 : void (*established)(uint16_t net_idx, uint16_t lpn_addr,
729 : uint8_t recv_delay, uint32_t polltimeout);
730 :
731 : /** @brief Friendship terminated.
732 : *
733 : * This callback notifies the application that friendship has
734 : * been terminated.
735 : *
736 : * @param net_idx NetKeyIndex used during friendship establishment.
737 : * @param lpn_addr Low Power Node address.
738 : */
739 1 : void (*terminated)(uint16_t net_idx, uint16_t lpn_addr);
740 :
741 : /** @brief Friend Poll Request.
742 : *
743 : * This callback notifies the application that the low power node has
744 : * polled the friend node.
745 : *
746 : * This callback will be called before @ref bt_mesh_friend_cb::established
747 : * when attempting to establish a friendship.
748 : *
749 : * @param net_idx NetKeyIndex used during friendship establishment.
750 : * @param lpn_addr LPN address.
751 : */
752 1 : void (*polled)(uint16_t net_idx, uint16_t lpn_addr);
753 : };
754 :
755 : /**
756 : * @brief Register a callback structure for Friendship events.
757 : *
758 : * Registers a callback structure that will be called whenever Friendship
759 : * gets established or terminated.
760 : *
761 : * @param _name Name of callback structure.
762 : */
763 1 : #define BT_MESH_FRIEND_CB_DEFINE(_name) \
764 : static const STRUCT_SECTION_ITERABLE(bt_mesh_friend_cb, \
765 : _CONCAT(bt_mesh_friend_cb_, \
766 : _name))
767 : #if defined(CONFIG_BT_TESTING)
768 : struct bt_mesh_snb {
769 : /** Flags */
770 : uint8_t flags;
771 :
772 : /** Network ID */
773 : uint64_t net_id;
774 :
775 : /** IV Index */
776 : uint32_t iv_idx;
777 :
778 : /** Authentication Value */
779 : uint64_t auth_val;
780 : };
781 :
782 : struct bt_mesh_prb {
783 : /** Random */
784 : uint8_t random[13];
785 :
786 : /** Flags */
787 : uint8_t flags;
788 :
789 : /** IV Index */
790 : uint32_t iv_idx;
791 :
792 : /** Authentication tag */
793 : uint64_t auth_tag;
794 : };
795 :
796 : /** Beacon callback functions. */
797 : struct bt_mesh_beacon_cb {
798 : /** @brief Secure Network Beacon received.
799 : *
800 : * This callback notifies the application that Secure Network Beacon
801 : * was received.
802 : *
803 : * @param snb Structure describing received Secure Network Beacon
804 : */
805 : void (*snb_received)(const struct bt_mesh_snb *snb);
806 :
807 : /** @brief Private Beacon received.
808 : *
809 : * This callback notifies the application that Private Beacon
810 : * was received and successfully decrypted.
811 : *
812 : * @param prb Structure describing received Private Beacon
813 : */
814 : void (*priv_received)(const struct bt_mesh_prb *prb);
815 : };
816 :
817 : /**
818 : * @brief Register a callback structure for beacon events.
819 : *
820 : * Registers a callback structure that will be called whenever beacon advertisement
821 : * is received.
822 : *
823 : * @param _name Name of callback structure.
824 : */
825 : #define BT_MESH_BEACON_CB_DEFINE(_name) \
826 : static const STRUCT_SECTION_ITERABLE(bt_mesh_beacon_cb, \
827 : _CONCAT(bt_mesh_beacon_cb_, \
828 : _name))
829 : #endif
830 :
831 : /** @brief Terminate Friendship.
832 : *
833 : * Terminated Friendship for given LPN.
834 : *
835 : * @param lpn_addr Low Power Node address.
836 : *
837 : * @return Zero on success or (negative) error code otherwise.
838 : */
839 1 : int bt_mesh_friend_terminate(uint16_t lpn_addr);
840 :
841 : /** @brief Store pending RPL entry(ies) in the persistent storage.
842 : *
843 : * This API allows the user to store pending RPL entry(ies) in the persistent
844 : * storage without waiting for the timeout.
845 : *
846 : * @note When flash is used as the persistent storage, calling this API too
847 : * frequently may wear it out.
848 : *
849 : * @param addr Address of the node which RPL entry needs to be stored or
850 : * @ref BT_MESH_ADDR_ALL_NODES to store all pending RPL entries.
851 : */
852 1 : void bt_mesh_rpl_pending_store(uint16_t addr);
853 :
854 : /** @brief Iterate stored Label UUIDs.
855 : *
856 : * When @c addr is @ref BT_MESH_ADDR_UNASSIGNED, this function iterates over all available addresses
857 : * starting with @c uuid. In this case, use @c retaddr to get virtual address representation of
858 : * the returned Label UUID. When @c addr is a virtual address, this function returns next Label
859 : * UUID corresponding to the @c addr. When @c uuid is NULL, this function returns the first
860 : * available UUID. If @c uuid is previously returned uuid, this function returns following uuid.
861 : *
862 : * @param addr Virtual address to search for, or @ref BT_MESH_ADDR_UNASSIGNED.
863 : * @param uuid Pointer to the previously returned Label UUID or NULL.
864 : * @param retaddr Pointer to a memory where virtual address representation of the returning UUID is
865 : * to be stored to.
866 : *
867 : * @return Pointer to Label UUID, or NULL if no more entries found.
868 : */
869 1 : const uint8_t *bt_mesh_va_uuid_get(uint16_t addr, const uint8_t *uuid, uint16_t *retaddr);
870 :
871 : #ifdef __cplusplus
872 : }
873 : #endif
874 :
875 : /**
876 : * @}
877 : */
878 :
879 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_MESH_MAIN_H_ */
|
