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 /** 14 * @brief Provisioning 15 * @defgroup bt_mesh_prov Provisioning 16 * @ingroup bt_mesh 17 * @{ 18 */ 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 /** Available Provisioning output authentication actions. */ 25 typedef enum { 26 BT_MESH_NO_OUTPUT = 0, 27 BT_MESH_BLINK = BIT(0), 28 BT_MESH_BEEP = BIT(1), 29 BT_MESH_VIBRATE = BIT(2), 30 BT_MESH_DISPLAY_NUMBER = BIT(3), 31 BT_MESH_DISPLAY_STRING = BIT(4), 32 } bt_mesh_output_action_t; 33 34 /** Available Provisioning input authentication actions. */ 35 typedef enum { 36 BT_MESH_NO_INPUT = 0, 37 BT_MESH_PUSH = BIT(0), 38 BT_MESH_TWIST = BIT(1), 39 BT_MESH_ENTER_NUMBER = BIT(2), 40 BT_MESH_ENTER_STRING = BIT(3), 41 } bt_mesh_input_action_t; 42 43 /** Available Provisioning bearers. */ 44 typedef enum { 45 BT_MESH_PROV_ADV = BIT(0), 46 BT_MESH_PROV_GATT = BIT(1), 47 } bt_mesh_prov_bearer_t; 48 49 /** Out of Band information location. */ 50 typedef enum { 51 BT_MESH_PROV_OOB_OTHER = BIT(0), 52 BT_MESH_PROV_OOB_URI = BIT(1), 53 BT_MESH_PROV_OOB_2D_CODE = BIT(2), 54 BT_MESH_PROV_OOB_BAR_CODE = BIT(3), 55 BT_MESH_PROV_OOB_NFC = BIT(4), 56 BT_MESH_PROV_OOB_NUMBER = BIT(5), 57 BT_MESH_PROV_OOB_STRING = BIT(6), 58 /* 7 - 10 are reserved */ 59 BT_MESH_PROV_OOB_ON_BOX = BIT(11), 60 BT_MESH_PROV_OOB_IN_BOX = BIT(12), 61 BT_MESH_PROV_OOB_ON_PAPER = BIT(13), 62 BT_MESH_PROV_OOB_IN_MANUAL = BIT(14), 63 BT_MESH_PROV_OOB_ON_DEV = BIT(15), 64 } bt_mesh_prov_oob_info_t; 65 66 /** Device Capabilities. */ 67 struct bt_mesh_dev_capabilities { 68 /** Number of elements supported by the device */ 69 uint8_t elem_count; 70 71 /** Supported algorithms and other capabilities */ 72 uint16_t algorithms; 73 74 /** Supported public key types */ 75 uint8_t pub_key_type; 76 77 /** Supported static OOB Types */ 78 uint8_t static_oob; 79 80 /** Supported Output OOB Actions */ 81 bt_mesh_output_action_t output_actions; 82 83 /** Supported Input OOB Actions */ 84 bt_mesh_input_action_t input_actions; 85 86 /** Maximum size of Output OOB supported */ 87 uint8_t output_size; 88 89 /** Maximum size in octets of Input OOB supported */ 90 uint8_t input_size; 91 }; 92 93 /** Provisioning properties & capabilities. */ 94 struct bt_mesh_prov { 95 /** The UUID that's used when advertising as unprovisioned */ 96 const uint8_t *uuid; 97 98 /** Optional URI. This will be advertised separately from the 99 * unprovisioned beacon, however the unprovisioned beacon will 100 * contain a hash of it so the two can be associated by the 101 * provisioner. 102 */ 103 const char *uri; 104 105 /** Out of Band information field. */ 106 bt_mesh_prov_oob_info_t oob_info; 107 108 /** Pointer to Public Key in big-endian for OOB public key type support. 109 * 110 * Remember to enable @kconfig{CONFIG_BT_MESH_PROV_OOB_PUBLIC_KEY} 111 * when initializing this parameter. 112 * 113 * Must be used together with @ref bt_mesh_prov::private_key_be. 114 */ 115 const uint8_t *public_key_be; 116 /** Pointer to Private Key in big-endian for OOB public key type support. 117 * 118 * Remember to enable @kconfig{CONFIG_BT_MESH_PROV_OOB_PUBLIC_KEY} 119 * when initializing this parameter. 120 * 121 * Must be used together with @ref bt_mesh_prov::public_key_be. 122 */ 123 const uint8_t *private_key_be; 124 125 /** Static OOB value */ 126 const uint8_t *static_val; 127 /** Static OOB value length */ 128 uint8_t static_val_len; 129 130 /** Maximum size of Output OOB supported */ 131 uint8_t output_size; 132 /** Supported Output OOB Actions */ 133 uint16_t output_actions; 134 135 /** Maximum size of Input OOB supported */ 136 uint8_t input_size; 137 /** Supported Input OOB Actions */ 138 uint16_t input_actions; 139 140 /** @brief Provisioning Capabilities. 141 * 142 * This callback notifies the application that the provisioning capabilities 143 * of the unprovisioned device has been received. 144 * 145 * The application can consequently call bt_mesh_auth_method_set_<*> to 146 * select suitable provisioning oob authentication method. 147 * 148 * When this callback returns, the provisioner will start authentication with 149 * the chosen method. 150 * 151 * @param cap capabilities supported by device. 152 */ 153 void (*capabilities)(const struct bt_mesh_dev_capabilities *cap); 154 155 /** @brief Output of a number is requested. 156 * 157 * This callback notifies the application that it should 158 * output the given number using the given action. 159 * 160 * @param act Action for outputting the number. 161 * @param num Number to be outputted. 162 * 163 * @return Zero on success or negative error code otherwise 164 */ 165 int (*output_number)(bt_mesh_output_action_t act, uint32_t num); 166 167 /** @brief Output of a string is requested. 168 * 169 * This callback notifies the application that it should 170 * display the given string to the user. 171 * 172 * @param str String to be displayed. 173 * 174 * @return Zero on success or negative error code otherwise 175 */ 176 int (*output_string)(const char *str); 177 178 /** @brief Input is requested. 179 * 180 * This callback notifies the application that it should 181 * request input from the user using the given action. The 182 * requested input will either be a string or a number, and 183 * the application needs to consequently call the 184 * bt_mesh_input_string() or bt_mesh_input_number() functions 185 * once the data has been acquired from the user. 186 * 187 * @param act Action for inputting data. 188 * @param num Maximum size of the inputted data. 189 * 190 * @return Zero on success or negative error code otherwise 191 */ 192 int (*input)(bt_mesh_input_action_t act, uint8_t size); 193 194 /** @brief The other device finished their OOB input. 195 * 196 * This callback notifies the application that it should stop 197 * displaying its output OOB value, as the other party finished their 198 * OOB input. 199 */ 200 void (*input_complete)(void); 201 202 /** @brief Unprovisioned beacon has been received. 203 * 204 * This callback notifies the application that an unprovisioned 205 * beacon has been received. 206 * 207 * @param uuid UUID 208 * @param oob_info OOB Information 209 * @param uri_hash Pointer to URI Hash value. NULL if no hash was 210 * present in the beacon. 211 */ 212 void (*unprovisioned_beacon)(uint8_t uuid[16], 213 bt_mesh_prov_oob_info_t oob_info, 214 uint32_t *uri_hash); 215 216 /** @brief Provisioning link has been opened. 217 * 218 * This callback notifies the application that a provisioning 219 * link has been opened on the given provisioning bearer. 220 * 221 * @param bearer Provisioning bearer. 222 */ 223 void (*link_open)(bt_mesh_prov_bearer_t bearer); 224 225 /** @brief Provisioning link has been closed. 226 * 227 * This callback notifies the application that a provisioning 228 * link has been closed on the given provisioning bearer. 229 * 230 * @param bearer Provisioning bearer. 231 */ 232 void (*link_close)(bt_mesh_prov_bearer_t bearer); 233 234 /** @brief Provisioning is complete. 235 * 236 * This callback notifies the application that provisioning has 237 * been successfully completed, and that the local node has been 238 * assigned the specified NetKeyIndex and primary element address. 239 * 240 * @param net_idx NetKeyIndex given during provisioning. 241 * @param addr Primary element address. 242 */ 243 void (*complete)(uint16_t net_idx, uint16_t addr); 244 245 /** @brief A new node has been added to the provisioning database. 246 * 247 * This callback notifies the application that provisioning has 248 * been successfully completed, and that a node has been assigned 249 * the specified NetKeyIndex and primary element address. 250 * 251 * @param net_idx NetKeyIndex given during provisioning. 252 * @param uuid UUID of the added node 253 * @param addr Primary element address. 254 * @param num_elem Number of elements that this node has. 255 */ 256 void (*node_added)(uint16_t net_idx, uint8_t uuid[16], uint16_t addr, 257 uint8_t num_elem); 258 259 /** @brief Node has been reset. 260 * 261 * This callback notifies the application that the local node 262 * has been reset and needs to be reprovisioned. The node will 263 * not automatically advertise as unprovisioned, rather the 264 * bt_mesh_prov_enable() API needs to be called to enable 265 * unprovisioned advertising on one or more provisioning bearers. 266 */ 267 void (*reset)(void); 268 }; 269 270 /** @brief Provide provisioning input OOB string. 271 * 272 * This is intended to be called after the bt_mesh_prov input callback 273 * has been called with BT_MESH_ENTER_STRING as the action. 274 * 275 * @param str String. 276 * 277 * @return Zero on success or (negative) error code otherwise. 278 */ 279 int bt_mesh_input_string(const char *str); 280 281 /** @brief Provide provisioning input OOB number. 282 * 283 * This is intended to be called after the bt_mesh_prov input callback 284 * has been called with BT_MESH_ENTER_NUMBER as the action. 285 * 286 * @param num Number. 287 * 288 * @return Zero on success or (negative) error code otherwise. 289 */ 290 int bt_mesh_input_number(uint32_t num); 291 292 /** @brief Provide Device public key. 293 * 294 * @param public_key Device public key in big-endian. 295 * 296 * @return Zero on success or (negative) error code otherwise. 297 */ 298 int bt_mesh_prov_remote_pub_key_set(const uint8_t public_key[64]); 299 300 /** @brief Use Input OOB authentication. 301 * 302 * Provisioner only. 303 * 304 * Instruct the unprovisioned device to use the specified Input OOB 305 * authentication action. When using @ref BT_MESH_PUSH, @ref BT_MESH_TWIST or 306 * @ref BT_MESH_ENTER_NUMBER, the @ref bt_mesh_prov::output_number callback is 307 * called with a random number that has to be entered on the unprovisioned 308 * device. 309 * 310 * When using @ref BT_MESH_ENTER_STRING, the @ref bt_mesh_prov::output_string 311 * callback is called with a random string that has to be entered on the 312 * unprovisioned device. 313 * 314 * @param action Authentication action used by the unprovisioned device. 315 * @param size Authentication size. 316 * 317 * @return Zero on success or (negative) error code otherwise. 318 */ 319 int bt_mesh_auth_method_set_input(bt_mesh_input_action_t action, uint8_t size); 320 321 /** @brief Use Output OOB authentication. 322 * 323 * Provisioner only. 324 * 325 * Instruct the unprovisioned device to use the specified Output OOB 326 * authentication action. The @ref bt_mesh_prov::input callback will 327 * be called. 328 * 329 * When using @ref BT_MESH_BLINK, @ref BT_MESH_BEEP, @ref BT_MESH_VIBRATE 330 * or @ref BT_MESH_DISPLAY_NUMBER, and the application has to call 331 * @ref bt_mesh_input_number with the random number indicated by 332 * the unprovisioned device. 333 * 334 * When using @ref BT_MESH_DISPLAY_STRING, the application has to call 335 * @ref bt_mesh_input_string with the random string displayed by the 336 * unprovisioned device. 337 * 338 * @param action Authentication action used by the unprovisioned device. 339 * @param size Authentication size. 340 * 341 * @return Zero on success or (negative) error code otherwise. 342 */ 343 int bt_mesh_auth_method_set_output(bt_mesh_output_action_t action, uint8_t size); 344 345 /** @brief Use static OOB authentication. 346 * 347 * Provisioner only. 348 * 349 * Instruct the unprovisioned device to use static OOB authentication, and use 350 * the given static authentication value when provisioning. 351 * 352 * @param static_val Static OOB value. 353 * @param size Static OOB value size. 354 * 355 * @return Zero on success or (negative) error code otherwise. 356 */ 357 int bt_mesh_auth_method_set_static(const uint8_t *static_val, uint8_t size); 358 359 /** @brief Don't use OOB authentication. 360 * 361 * Provisioner only. 362 * 363 * Don't use any authentication when provisioning new devices. This is the 364 * default behavior. 365 * 366 * @warning Not using any authentication exposes the mesh network to 367 * impersonation attacks, where attackers can pretend to be the 368 * unprovisioned device to gain access to the network. Authentication 369 * is strongly encouraged. 370 * 371 * @return Zero on success or (negative) error code otherwise. 372 */ 373 int bt_mesh_auth_method_set_none(void); 374 375 /** @brief Enable specific provisioning bearers 376 * 377 * Enable one or more provisioning bearers. 378 * 379 * @param bearers Bit-wise or of provisioning bearers. 380 * 381 * @return Zero on success or (negative) error code otherwise. 382 */ 383 int bt_mesh_prov_enable(bt_mesh_prov_bearer_t bearers); 384 385 /** @brief Disable specific provisioning bearers 386 * 387 * Disable one or more provisioning bearers. 388 * 389 * @param bearers Bit-wise or of provisioning bearers. 390 * 391 * @return Zero on success or (negative) error code otherwise. 392 */ 393 int bt_mesh_prov_disable(bt_mesh_prov_bearer_t bearers); 394 395 /** @brief Provision the local Mesh Node. 396 * 397 * This API should normally not be used directly by the application. The 398 * only exception is for testing purposes where manual provisioning is 399 * desired without an actual external provisioner. 400 * 401 * @param net_key Network Key 402 * @param net_idx Network Key Index 403 * @param flags Provisioning Flags 404 * @param iv_index IV Index 405 * @param addr Primary element address 406 * @param dev_key Device Key 407 * 408 * @return Zero on success or (negative) error code otherwise. 409 */ 410 int bt_mesh_provision(const uint8_t net_key[16], uint16_t net_idx, 411 uint8_t flags, uint32_t iv_index, uint16_t addr, 412 const uint8_t dev_key[16]); 413 414 /** @brief Provision a Mesh Node using PB-ADV 415 * 416 * @param uuid UUID 417 * @param net_idx Network Key Index 418 * @param addr Address to assign to remote device. If addr is 0, 419 * the lowest available address will be chosen. 420 * @param attention_duration The attention duration to be send to remote device 421 * 422 * @return Zero on success or (negative) error code otherwise. 423 */ 424 int bt_mesh_provision_adv(const uint8_t uuid[16], uint16_t net_idx, uint16_t addr, 425 uint8_t attention_duration); 426 427 /** @brief Check if the local node has been provisioned. 428 * 429 * This API can be used to check if the local node has been provisioned 430 * or not. It can e.g. be helpful to determine if there was a stored 431 * network in flash, i.e. if the network was restored after calling 432 * settings_load(). 433 * 434 * @return True if the node is provisioned. False otherwise. 435 */ 436 bool bt_mesh_is_provisioned(void); 437 438 /** 439 * @} 440 */ 441 442 /** 443 * @brief Bluetooth mesh 444 * @defgroup bt_mesh Bluetooth mesh 445 * @ingroup bluetooth 446 * @{ 447 */ 448 449 /* Primary Network Key index */ 450 #define BT_MESH_NET_PRIMARY 0x000 451 452 /** Relay feature */ 453 #define BT_MESH_FEAT_RELAY BIT(0) 454 /** GATT Proxy feature */ 455 #define BT_MESH_FEAT_PROXY BIT(1) 456 /** Friend feature */ 457 #define BT_MESH_FEAT_FRIEND BIT(2) 458 /** Low Power Node feature */ 459 #define BT_MESH_FEAT_LOW_POWER BIT(3) 460 #define BT_MESH_FEAT_SUPPORTED (BT_MESH_FEAT_RELAY | \ 461 BT_MESH_FEAT_PROXY | \ 462 BT_MESH_FEAT_FRIEND | \ 463 BT_MESH_FEAT_LOW_POWER) 464 465 /** @brief Initialize Mesh support 466 * 467 * After calling this API, the node will not automatically advertise as 468 * unprovisioned, rather the bt_mesh_prov_enable() API needs to be called 469 * to enable unprovisioned advertising on one or more provisioning bearers. 470 * 471 * @param prov Node provisioning information. 472 * @param comp Node Composition. 473 * 474 * @return Zero on success or (negative) error code otherwise. 475 */ 476 int bt_mesh_init(const struct bt_mesh_prov *prov, 477 const struct bt_mesh_comp *comp); 478 479 /** @brief Reset the state of the local Mesh node. 480 * 481 * Resets the state of the node, which means that it needs to be 482 * reprovisioned to become an active node in a Mesh network again. 483 * 484 * After calling this API, the node will not automatically advertise as 485 * unprovisioned, rather the bt_mesh_prov_enable() API needs to be called 486 * to enable unprovisioned advertising on one or more provisioning bearers. 487 * 488 */ 489 void bt_mesh_reset(void); 490 491 /** @brief Suspend the Mesh network temporarily. 492 * 493 * This API can be used for power saving purposes, but the user should be 494 * aware that leaving the local node suspended for a long period of time 495 * may cause it to become permanently disconnected from the Mesh network. 496 * If at all possible, the Friendship feature should be used instead, to 497 * make the node into a Low Power Node. 498 * 499 * @return 0 on success, or (negative) error code on failure. 500 */ 501 int bt_mesh_suspend(void); 502 503 /** @brief Resume a suspended Mesh network. 504 * 505 * This API resumes the local node, after it has been suspended using the 506 * bt_mesh_suspend() API. 507 * 508 * @return 0 on success, or (negative) error code on failure. 509 */ 510 int bt_mesh_resume(void); 511 512 /** @brief Toggle the IV Update test mode 513 * 514 * This API is only available if the IV Update test mode has been enabled 515 * in Kconfig. It is needed for passing most of the IV Update qualification 516 * test cases. 517 * 518 * @param enable true to enable IV Update test mode, false to disable it. 519 */ 520 void bt_mesh_iv_update_test(bool enable); 521 522 /** @brief Toggle the IV Update state 523 * 524 * This API is only available if the IV Update test mode has been enabled 525 * in Kconfig. It is needed for passing most of the IV Update qualification 526 * test cases. 527 * 528 * @return true if IV Update In Progress state was entered, false otherwise. 529 */ 530 bool bt_mesh_iv_update(void); 531 532 /** @brief Toggle the Low Power feature of the local device 533 * 534 * Enables or disables the Low Power feature of the local device. This is 535 * exposed as a run-time feature, since the device might want to change 536 * this e.g. based on being plugged into a stable power source or running 537 * from a battery power source. 538 * 539 * @param enable true to enable LPN functionality, false to disable it. 540 * 541 * @return Zero on success or (negative) error code otherwise. 542 */ 543 int bt_mesh_lpn_set(bool enable); 544 545 /** @brief Send out a Friend Poll message. 546 * 547 * Send a Friend Poll message to the Friend of this node. If there is no 548 * established Friendship the function will return an error. 549 * 550 * @return Zero on success or (negative) error code otherwise. 551 */ 552 int bt_mesh_lpn_poll(void); 553 554 /** Low Power Node callback functions. */ 555 struct bt_mesh_lpn_cb { 556 /** @brief Friendship established. 557 * 558 * This callback notifies the application that friendship has 559 * been successfully established. 560 * 561 * @param net_idx NetKeyIndex used during friendship establishment. 562 * @param friend_addr Friend address. 563 * @param queue_size Friend queue size. 564 * @param recv_window Low Power Node's listens duration for 565 * Friend response. 566 */ 567 void (*established)(uint16_t net_idx, uint16_t friend_addr, 568 uint8_t queue_size, uint8_t recv_window); 569 570 /** @brief Friendship terminated. 571 * 572 * This callback notifies the application that friendship has 573 * been terminated. 574 * 575 * @param net_idx NetKeyIndex used during friendship establishment. 576 * @param friend_addr Friend address. 577 */ 578 void (*terminated)(uint16_t net_idx, uint16_t friend_addr); 579 580 /** @brief Local Poll Request. 581 * 582 * This callback notifies the application that the local node has 583 * polled the friend node. 584 * 585 * This callback will be called before @ref bt_mesh_lpn_cb::established 586 * when attempting to establish a friendship. 587 * 588 * @param net_idx NetKeyIndex used during friendship establishment. 589 * @param friend_addr Friend address. 590 * @param retry Retry or first poll request for each transaction. 591 */ 592 void (*polled)(uint16_t net_idx, uint16_t friend_addr, bool retry); 593 }; 594 595 /** @def BT_MESH_LPN_CB_DEFINE 596 * 597 * @brief Register a callback structure for Friendship events. 598 * 599 * @param _name Name of callback structure. 600 */ 601 #define BT_MESH_LPN_CB_DEFINE(_name) \ 602 static const STRUCT_SECTION_ITERABLE(bt_mesh_lpn_cb, \ 603 _CONCAT(bt_mesh_lpn_cb_, \ 604 _name)) 605 606 /** Friend Node callback functions. */ 607 struct bt_mesh_friend_cb { 608 /** @brief Friendship established. 609 * 610 * This callback notifies the application that friendship has 611 * been successfully established. 612 * 613 * @param net_idx NetKeyIndex used during friendship establishment. 614 * @param lpn_addr Low Power Node address. 615 * @param recv_delay Receive Delay in units of 1 millisecond. 616 * @param polltimeout PollTimeout in units of 1 millisecond. 617 */ 618 void (*established)(uint16_t net_idx, uint16_t lpn_addr, 619 uint8_t recv_delay, uint32_t polltimeout); 620 621 /** @brief Friendship terminated. 622 * 623 * This callback notifies the application that friendship has 624 * been terminated. 625 * 626 * @param net_idx NetKeyIndex used during friendship establishment. 627 * @param lpn_addr Low Power Node address. 628 */ 629 void (*terminated)(uint16_t net_idx, uint16_t lpn_addr); 630 631 /** @brief Friend Poll Request. 632 * 633 * This callback notifies the application that the low power node has 634 * polled the friend node. 635 * 636 * This callback will be called before @ref bt_mesh_friend_cb::established 637 * when attempting to establish a friendship. 638 * 639 * @param net_idx NetKeyIndex used during friendship establishment. 640 * @param lpn_addr LPN address. 641 */ 642 void (*polled)(uint16_t net_idx, uint16_t lpn_addr); 643 }; 644 645 /** @def BT_MESH_FRIEND_CB_DEFINE 646 * 647 * @brief Register a callback structure for Friendship events. 648 * 649 * Registers a callback structure that will be called whenever Friendship 650 * gets established or terminated. 651 * 652 * @param _name Name of callback structure. 653 */ 654 #define BT_MESH_FRIEND_CB_DEFINE(_name) \ 655 static const STRUCT_SECTION_ITERABLE(bt_mesh_friend_cb, \ 656 _CONCAT(bt_mesh_friend_cb_, \ 657 _name)) 658 659 /** @brief Terminate Friendship. 660 * 661 * Terminated Friendship for given LPN. 662 * 663 * @param lpn_addr Low Power Node address. 664 * 665 * @return Zero on success or (negative) error code otherwise. 666 */ 667 int bt_mesh_friend_terminate(uint16_t lpn_addr); 668 669 /** @brief Store pending RPL entry(ies) in the persistent storage. 670 * 671 * This API allows the user to store pending RPL entry(ies) in the persistent 672 * storage without waiting for the timeout. 673 * 674 * @note When flash is used as the persistent storage, calling this API too 675 * frequently may wear it out. 676 * 677 * @param addr Address of the node which RPL entry needs to be stored or 678 * @ref BT_MESH_ADDR_ALL_NODES to store all pending RPL entries. 679 */ 680 void bt_mesh_rpl_pending_store(uint16_t addr); 681 682 #ifdef __cplusplus 683 } 684 #endif 685 686 /** 687 * @} 688 */ 689 690 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_MESH_MAIN_H_ */ 691
