1 /** @file 2 * @brief Bluetooth mesh Profile 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 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 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 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 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 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 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 struct bt_mesh_dev_capabilities { 89 /** Number of elements supported by the device */ 90 uint8_t elem_count; 91 92 /** Supported algorithms and other capabilities */ 93 uint16_t algorithms; 94 95 /** Supported public key types */ 96 uint8_t pub_key_type; 97 98 /** Supported OOB Types */ 99 uint8_t oob_type; 100 101 /** Supported Output OOB Actions */ 102 bt_mesh_output_action_t output_actions; 103 104 /** Supported Input OOB Actions */ 105 bt_mesh_input_action_t input_actions; 106 107 /** Maximum size of Output OOB supported */ 108 uint8_t output_size; 109 110 /** Maximum size in octets of Input OOB supported */ 111 uint8_t input_size; 112 }; 113 114 /** Provisioning properties & capabilities. */ 115 struct bt_mesh_prov { 116 /** The UUID that's used when advertising as unprovisioned */ 117 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 const char *uri; 125 126 /** Out of Band information field. */ 127 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 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 const uint8_t *private_key_be; 145 146 /** Static OOB value */ 147 const uint8_t *static_val; 148 /** Static OOB value length */ 149 uint8_t static_val_len; 150 151 /** Maximum size of Output OOB supported */ 152 uint8_t output_size; 153 /** Supported Output OOB Actions */ 154 uint16_t output_actions; 155 156 /** Maximum size of Input OOB supported */ 157 uint8_t input_size; 158 /** Supported Input OOB Actions */ 159 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 #define BT_MESH_NET_PRIMARY 0x000 561 562 /** Relay feature */ 563 #define BT_MESH_FEAT_RELAY BIT(0) 564 /** GATT Proxy feature */ 565 #define BT_MESH_FEAT_PROXY BIT(1) 566 /** Friend feature */ 567 #define BT_MESH_FEAT_FRIEND BIT(2) 568 /** Low Power Node feature */ 569 #define BT_MESH_FEAT_LOW_POWER BIT(3) 570 /** Supported heartbeat publication features */ 571 #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 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 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 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 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 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 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 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 int bt_mesh_lpn_poll(void); 664 665 /** Low Power Node callback functions. */ 666 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 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 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 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 #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 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 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 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 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 #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 #if defined(CONFIG_BT_MESH_V1d1) 783 struct bt_mesh_prb { 784 /** Random */ 785 uint8_t random[13]; 786 787 /** Flags */ 788 uint8_t flags; 789 790 /** IV Index */ 791 uint32_t iv_idx; 792 793 /** Authentication tag */ 794 uint64_t auth_tag; 795 }; 796 #endif 797 798 /** Beacon callback functions. */ 799 struct bt_mesh_beacon_cb { 800 /** @brief Secure Network Beacon received. 801 * 802 * This callback notifies the application that Secure Network Beacon 803 * was received. 804 * 805 * @param snb Structure describing received Secure Network Beacon 806 */ 807 void (*snb_received)(const struct bt_mesh_snb *snb); 808 809 #if defined(CONFIG_BT_MESH_V1d1) 810 /** @brief Private Beacon received. 811 * 812 * This callback notifies the application that Private Beacon 813 * was received and successfully decrypted. 814 * 815 * @param prb Structure describing received Private Beacon 816 */ 817 void (*priv_received)(const struct bt_mesh_prb *prb); 818 #endif 819 }; 820 821 /** 822 * @brief Register a callback structure for beacon events. 823 * 824 * Registers a callback structure that will be called whenever beacon advertisement 825 * is received. 826 * 827 * @param _name Name of callback structure. 828 */ 829 #define BT_MESH_BEACON_CB_DEFINE(_name) \ 830 static const STRUCT_SECTION_ITERABLE(bt_mesh_beacon_cb, \ 831 _CONCAT(bt_mesh_beacon_cb_, \ 832 _name)) 833 #endif 834 835 /** @brief Terminate Friendship. 836 * 837 * Terminated Friendship for given LPN. 838 * 839 * @param lpn_addr Low Power Node address. 840 * 841 * @return Zero on success or (negative) error code otherwise. 842 */ 843 int bt_mesh_friend_terminate(uint16_t lpn_addr); 844 845 /** @brief Store pending RPL entry(ies) in the persistent storage. 846 * 847 * This API allows the user to store pending RPL entry(ies) in the persistent 848 * storage without waiting for the timeout. 849 * 850 * @note When flash is used as the persistent storage, calling this API too 851 * frequently may wear it out. 852 * 853 * @param addr Address of the node which RPL entry needs to be stored or 854 * @ref BT_MESH_ADDR_ALL_NODES to store all pending RPL entries. 855 */ 856 void bt_mesh_rpl_pending_store(uint16_t addr); 857 858 /** @brief Iterate stored Label UUIDs. 859 * 860 * When @c addr is @ref BT_MESH_ADDR_UNASSIGNED, this function iterates over all available addresses 861 * starting with @c uuid. In this case, use @c retaddr to get virtual address representation of 862 * the returned Label UUID. When @c addr is a virtual address, this function returns next Label 863 * UUID corresponding to the @c addr. When @c uuid is NULL, this function returns the first 864 * available UUID. If @c uuid is previously returned uuid, this function returns following uuid. 865 * 866 * @param addr Virtual address to search for, or @ref BT_MESH_ADDR_UNASSIGNED. 867 * @param uuid Pointer to the previously returned Label UUID or NULL. 868 * @param retaddr Pointer to a memory where virtual address representation of the returning UUID is 869 * to be stored to. 870 * 871 * @return Pointer to Label UUID, or NULL if no more entries found. 872 */ 873 const uint8_t *bt_mesh_va_uuid_get(uint16_t addr, const uint8_t *uuid, uint16_t *retaddr); 874 875 #ifdef __cplusplus 876 } 877 #endif 878 879 /** 880 * @} 881 */ 882 883 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_MESH_MAIN_H_ */ 884
