1 /** @file 2 * @brief Bluetooth Mesh Profile APIs. 3 */ 4 5 /* 6 * Copyright (c) 2017 Intel Corporation 7 * Additional Copyright (c) 2018 Espressif Systems (Shanghai) PTE LTD 8 * 9 * SPDX-License-Identifier: Apache-2.0 10 */ 11 #ifndef _BLE_MESH_MAIN_H_ 12 #define _BLE_MESH_MAIN_H_ 13 14 #include "mesh_access.h" 15 16 /** 17 * @brief Bluetooth Mesh Provisioning 18 * @defgroup bt_mesh_prov Bluetooth Mesh Provisioning 19 * @ingroup bt_mesh 20 * @{ 21 */ 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 typedef enum { 28 BLE_MESH_NO_OUTPUT = 0, 29 BLE_MESH_BLINK = BIT(0), 30 BLE_MESH_BEEP = BIT(1), 31 BLE_MESH_VIBRATE = BIT(2), 32 BLE_MESH_DISPLAY_NUMBER = BIT(3), 33 BLE_MESH_DISPLAY_STRING = BIT(4), 34 } bt_mesh_output_action_t; 35 36 typedef enum { 37 BLE_MESH_NO_INPUT = 0, 38 BLE_MESH_PUSH = BIT(0), 39 BLE_MESH_TWIST = BIT(1), 40 BLE_MESH_ENTER_NUMBER = BIT(2), 41 BLE_MESH_ENTER_STRING = BIT(3), 42 } bt_mesh_input_action_t; 43 44 typedef enum { 45 BLE_MESH_PROV_ADV = BIT(0), 46 BLE_MESH_PROV_GATT = BIT(1), 47 } bt_mesh_prov_bearer_t; 48 49 typedef enum { 50 BLE_MESH_PROV_OOB_OTHER = BIT(0), 51 BLE_MESH_PROV_OOB_URI = BIT(1), 52 BLE_MESH_PROV_OOB_2D_CODE = BIT(2), 53 BLE_MESH_PROV_OOB_BAR_CODE = BIT(3), 54 BLE_MESH_PROV_OOB_NFC = BIT(4), 55 BLE_MESH_PROV_OOB_NUMBER = BIT(5), 56 BLE_MESH_PROV_OOB_STRING = BIT(6), 57 /* 7 - 10 are reserved */ 58 BLE_MESH_PROV_OOB_ON_BOX = BIT(11), 59 BLE_MESH_PROV_OOB_IN_BOX = BIT(12), 60 BLE_MESH_PROV_OOB_ON_PAPER = BIT(13), 61 BLE_MESH_PROV_OOB_IN_MANUAL = BIT(14), 62 BLE_MESH_PROV_OOB_ON_DEV = BIT(15), 63 } bt_mesh_prov_oob_info_t; 64 65 #define BLE_MESH_PROV_STATIC_OOB_MAX_LEN 16 66 #define BLE_MESH_PROV_OUTPUT_OOB_MAX_LEN 8 67 #define BLE_MESH_PROV_INPUT_OOB_MAX_LEN 8 68 69 /** Provisioning properties & capabilities. */ 70 struct bt_mesh_prov { 71 #if CONFIG_BLE_MESH_NODE 72 /** The UUID that's used when advertising as unprovisioned */ 73 const uint8_t *uuid; 74 75 /** Optional URI. This will be advertised separately from the 76 * unprovisioned beacon, however the unprovisioned beacon will 77 * contain a hash of it so the two can be associated by the 78 * provisioner. 79 */ 80 const char *uri; 81 82 /** Out of Band information field. */ 83 bt_mesh_prov_oob_info_t oob_info; 84 85 /** Flag indicates whether unprovisioned devices support OOB public key */ 86 bool oob_pub_key; 87 88 /** @brief Set device OOB public key. 89 * 90 * This callback notifies the application to 91 * set OOB public key & private key pair. 92 */ 93 void (*oob_pub_key_cb)(void); 94 95 /** Static OOB value */ 96 const uint8_t *static_val; 97 /** Static OOB value length */ 98 uint8_t static_val_len; 99 100 /** Maximum size of Output OOB supported */ 101 uint8_t output_size; 102 /** Supported Output OOB Actions */ 103 uint16_t output_actions; 104 105 /* Maximum size of Input OOB supported */ 106 uint8_t input_size; 107 /** Supported Input OOB Actions */ 108 uint16_t input_actions; 109 110 /** @brief Output of a number is requested. 111 * 112 * This callback notifies the application to 113 * output the given number using the given action. 114 * 115 * @param act Action for outputting the number. 116 * @param num Number to be out-put. 117 * 118 * @return Zero on success or negative error code otherwise 119 */ 120 int (*output_number)(bt_mesh_output_action_t act, uint32_t num); 121 122 /** @brief Output of a string is requested. 123 * 124 * This callback notifies the application to 125 * display the given string to the user. 126 * 127 * @param str String to be displayed. 128 * 129 * @return Zero on success or negative error code otherwise 130 */ 131 int (*output_string)(const char *str); 132 133 /** @brief Input is requested. 134 * 135 * This callback notifies the application to request 136 * input from the user using the given action. The 137 * requested input will either be a string or a number, and 138 * the application needs to consequently call the 139 * bt_mesh_input_string() or bt_mesh_input_number() functions 140 * once the data has been acquired from the user. 141 * 142 * @param act Action for inputting data. 143 * @param num Maximum size of the in-put data. 144 * 145 * @return Zero on success or negative error code otherwise 146 */ 147 int (*input)(bt_mesh_input_action_t act, uint8_t size); 148 149 /** @brief Provisioning link has been opened. 150 * 151 * This callback notifies the application that a provisioning 152 * link has been opened on the given provisioning bearer. 153 * 154 * @param bearer Provisioning bearer. 155 */ 156 void (*link_open)(bt_mesh_prov_bearer_t bearer); 157 158 /** @brief Provisioning link has been closed. 159 * 160 * This callback notifies the application that a provisioning 161 * link has been closed on the given provisioning bearer. 162 * 163 * @param bearer Provisioning bearer. 164 */ 165 void (*link_close)(bt_mesh_prov_bearer_t bearer); 166 167 /** @brief Provisioning is complete. 168 * 169 * This callback notifies the application that provisioning has 170 * been successfully completed, and that the local node has been 171 * assigned the specified NetKeyIndex and primary element address. 172 * 173 * @param net_idx NetKeyIndex given during provisioning. 174 * @param net_key NetKey given during provisioning. 175 * @param addr Primary element address. 176 * @param flags Key Refresh & IV Update flags 177 * @param iv_index IV Index. 178 */ 179 void (*complete)(uint16_t net_idx, const uint8_t net_key[16], uint16_t addr, uint8_t flags, uint32_t iv_index); 180 181 /** @brief Node has been reset. 182 * 183 * This callback notifies the application that the local node 184 * has been reset and needs to be reprovisioned. The node will 185 * not automatically advertise as unprovisioned, rather the 186 * bt_mesh_prov_enable() API needs to be called to enable 187 * unprovisioned advertising on one or more provisioning bearers. 188 */ 189 void (*reset)(void); 190 #endif /* CONFIG_BLE_MESH_NODE */ 191 192 #if CONFIG_BLE_MESH_PROVISIONER 193 /* Provisioner device uuid */ 194 const uint8_t *prov_uuid; 195 196 /* 197 * Primary element address of the provisioner. 198 * No need to initialize it for fast provisioning. 199 */ 200 const uint16_t prov_unicast_addr; 201 202 /* 203 * Starting unicast address going to assigned. 204 * No need to initialize it for fast provisioning. 205 */ 206 uint16_t prov_start_address; 207 208 /* Attention timer contained in Provisioning Invite */ 209 uint8_t prov_attention; 210 211 /* Provisioner provisioning Algorithm */ 212 uint8_t prov_algorithm; 213 214 /* Provisioner public key oob */ 215 uint8_t prov_pub_key_oob; 216 217 /** @brief Input is requested. 218 * 219 * This callback notifies the application that it should 220 * read device's public key with OOB 221 * 222 * @param link_idx: The provisioning link index 223 * 224 * @return Zero on success or negative error code otherwise 225 */ 226 int (*prov_pub_key_oob_cb)(uint8_t link_idx); 227 228 /* Provisioner static oob value */ 229 uint8_t *prov_static_oob_val; 230 231 /* Provisioner static oob value length */ 232 uint8_t prov_static_oob_len; 233 234 /** @brief Provisioner input a number read from device output 235 * 236 * This callback notifies the application that it should 237 * input the number given by the device. 238 * 239 * @param method: The OOB authentication method 240 * @param act: The output action of the device 241 * @param size: The output size of the device 242 * @param link_idx: The provisioning link index 243 * 244 * @return Zero on success or negative error code otherwise 245 */ 246 int (*prov_input_num)(uint8_t method, bt_mesh_output_action_t act, uint8_t size, uint8_t link_idx); 247 248 /** @brief Provisioner output a number to the device 249 * 250 * This callback notifies the application that it should 251 * output the number to the device. 252 * 253 * @param method: The OOB authentication method 254 * @param act: The input action of the device 255 * @param data: The input number/string of the device 256 * @param size: The input size of the device 257 * @param link_idx: The provisioning link index 258 * 259 * @return Zero on success or negative error code otherwise 260 */ 261 int (*prov_output_num)(uint8_t method, bt_mesh_input_action_t act, void *data, uint8_t size, uint8_t link_idx); 262 263 /* 264 * Key refresh and IV update flag. 265 * No need to initialize it for fast provisioning. 266 */ 267 uint8_t flags; 268 269 /* 270 * IV index. No need to initialize it for fast provisioning. 271 */ 272 uint32_t iv_index; 273 274 /** @brief Provisioner has opened a provisioning link. 275 * 276 * This callback notifies the application that a provisioning 277 * link has been opened on the given provisioning bearer. 278 * 279 * @param bearer Provisioning bearer. 280 */ 281 void (*prov_link_open)(bt_mesh_prov_bearer_t bearer); 282 283 /** @brief Provisioner has closed a provisioning link. 284 * 285 * This callback notifies the application that a provisioning 286 * link has been closed on the given provisioning bearer. 287 * 288 * @param bearer Provisioning bearer. 289 * @param reason Provisioning link close reason(disconnect reason) 290 */ 291 void (*prov_link_close)(bt_mesh_prov_bearer_t bearer, uint8_t reason); 292 293 /** @brief Provision one device is complete. 294 * 295 * This callback notifies the application that provisioner has 296 * successfully provisioned a device, and the node has been assigned 297 * the specified NetKeyIndex and primary element address. 298 * 299 * @param node_idx Node index within the node(provisioned device) queue. 300 * @param device_uuid Provisioned device uuid pointer. 301 * @param unicast_addr Provisioned device assigned unicast address. 302 * @param element_num Provisioned device element number. 303 * @param netkey_idx Provisioned device assigned netkey index. 304 */ 305 void (*prov_complete)(uint16_t node_idx, const uint8_t device_uuid[16], 306 uint16_t unicast_addr, uint8_t element_num, 307 uint16_t netkey_idx); 308 #endif /* CONFIG_BLE_MESH_PROVISIONER */ 309 }; 310 311 enum ble_mesh_role { 312 NODE = 0, 313 PROVISIONER, 314 FAST_PROV, 315 ROLE_NVAL, 316 }; 317 318 /* The following APIs are for BLE Mesh Node */ 319 320 /** @brief Provide provisioning input OOB string. 321 * 322 * This is intended to be called after the bt_mesh_prov input callback 323 * has been called with BLE_MESH_ENTER_STRING as the action. 324 * 325 * @param str String. 326 * 327 * @return Zero on success or (negative) error code otherwise. 328 */ 329 int bt_mesh_input_string(const char *str); 330 331 /** @brief Provide provisioning input OOB number. 332 * 333 * This is intended to be called after the bt_mesh_prov input callback 334 * has been called with BLE_MESH_ENTER_NUMBER as the action. 335 * 336 * @param num Number. 337 * 338 * @return Zero on success or (negative) error code otherwise. 339 */ 340 int bt_mesh_input_number(uint32_t num); 341 342 /** @brief Enable specific provisioning bearers 343 * 344 * Enable one or more provisioning bearers. 345 * 346 * @param Bit-wise OR of provisioning bearers. 347 * 348 * @return Zero on success or (negative) error code otherwise. 349 */ 350 int bt_mesh_prov_enable(bt_mesh_prov_bearer_t bearers); 351 352 /** @brief Disable specific provisioning bearers 353 * 354 * Disable one or more provisioning bearers. 355 * 356 * @param Bit-wise OR of provisioning bearers. 357 * 358 * @return Zero on success or (negative) error code otherwise. 359 */ 360 int bt_mesh_prov_disable(bt_mesh_prov_bearer_t bearers); 361 362 /* The following APIs are for BLE Mesh Provisioner */ 363 364 /** @brief Provide provisioning input OOB string. 365 * 366 * This is intended to be called after the bt_mesh_prov input callback 367 * has been called with BLE_MESH_ENTER_STRING as the action. 368 * 369 * @param str String. 370 * 371 * @return Zero on success or (negative) error code otherwise. 372 */ 373 int bt_mesh_prov_input_string(const char *str); 374 375 /** @brief Provide provisioning input OOB number. 376 * 377 * This is intended to be called after the bt_mesh_prov input callback 378 * has been called with BLE_MESH_ENTER_NUMBER as the action. 379 * 380 * @param num Number. 381 * 382 * @return Zero on success or (negative) error code otherwise. 383 */ 384 int bt_mesh_prov_input_number(uint32_t num); 385 386 /** @brief Enable specific provisioning bearers 387 * 388 * Enable one or more provisioning bearers. 389 * 390 * @param bearers Bit-wise OR of provisioning bearers. 391 * 392 * @return Zero on success or (negative) error code otherwise. 393 */ 394 int bt_mesh_provisioner_enable(bt_mesh_prov_bearer_t bearers); 395 396 /** @brief Disable specific provisioning bearers 397 * 398 * Disable one or more provisioning bearers. 399 * 400 * @param bearers Bit-wise OR of provisioning bearers. 401 * 402 * @return Zero on success or (negative) error code otherwise. 403 */ 404 int bt_mesh_provisioner_disable(bt_mesh_prov_bearer_t bearers); 405 406 /** 407 * @} 408 */ 409 410 /** 411 * @brief Bluetooth Mesh 412 * @defgroup bt_mesh Bluetooth Mesh 413 * @ingroup bluetooth 414 * @{ 415 */ 416 417 /* Primary Network Key index */ 418 #define BLE_MESH_NET_PRIMARY 0x000 419 420 #define BLE_MESH_RELAY_DISABLED 0x00 421 #define BLE_MESH_RELAY_ENABLED 0x01 422 #define BLE_MESH_RELAY_NOT_SUPPORTED 0x02 423 424 #define BLE_MESH_BEACON_DISABLED 0x00 425 #define BLE_MESH_BEACON_ENABLED 0x01 426 427 #define BLE_MESH_GATT_PROXY_DISABLED 0x00 428 #define BLE_MESH_GATT_PROXY_ENABLED 0x01 429 #define BLE_MESH_GATT_PROXY_NOT_SUPPORTED 0x02 430 431 #define BLE_MESH_FRIEND_DISABLED 0x00 432 #define BLE_MESH_FRIEND_ENABLED 0x01 433 #define BLE_MESH_FRIEND_NOT_SUPPORTED 0x02 434 435 #define BLE_MESH_NODE_IDENTITY_STOPPED 0x00 436 #define BLE_MESH_NODE_IDENTITY_RUNNING 0x01 437 #define BLE_MESH_NODE_IDENTITY_NOT_SUPPORTED 0x02 438 439 /* Features */ 440 #define BLE_MESH_FEAT_RELAY BIT(0) 441 #define BLE_MESH_FEAT_PROXY BIT(1) 442 #define BLE_MESH_FEAT_FRIEND BIT(2) 443 #define BLE_MESH_FEAT_LOW_POWER BIT(3) 444 #define BLE_MESH_FEAT_SUPPORTED (BLE_MESH_FEAT_RELAY | \ 445 BLE_MESH_FEAT_PROXY | \ 446 BLE_MESH_FEAT_FRIEND | \ 447 BLE_MESH_FEAT_LOW_POWER) 448 449 /** @brief Check if the mesh stack is initialized. 450 * 451 * @return true - yes, false - no. 452 */ 453 bool bt_mesh_is_initialized(void); 454 455 /** @brief Initialize Mesh support 456 * 457 * After calling this API, the node will not automatically advertise as 458 * unprovisioned, rather the bt_mesh_prov_enable() API needs to be called 459 * to enable unprovisioned advertising on one or more provisioning bearers. 460 * 461 * @param prov Node provisioning information. 462 * @param comp Node Composition. 463 * 464 * @return Zero on success or (negative) error code otherwise. 465 */ 466 int bt_mesh_init(const struct bt_mesh_prov *prov, 467 const struct bt_mesh_comp *comp); 468 469 /* BLE Mesh deinit parameters */ 470 struct bt_mesh_deinit_param { 471 bool erase; /* Indicate if erasing flash when deinit mesh stack */ 472 }; 473 474 /** @brief De-initialize Mesh support 475 * 476 * @param param BLE Mesh deinit parameters. 477 * 478 * @return Zero on success or (negative) error code otherwise. 479 */ 480 int bt_mesh_deinit(struct bt_mesh_deinit_param *param); 481 482 /** @brief Reset the state of the local Mesh node. 483 * 484 * Resets the state of the node, which means that it needs to be 485 * reprovisioned to become an active node in a Mesh network again. 486 * 487 * After calling this API, the node will not automatically advertise as 488 * unprovisioned, rather the bt_mesh_prov_enable() API needs to be called 489 * to enable unprovisioned advertising on one or more provisioning bearers. 490 * 491 */ 492 void bt_mesh_node_reset(void); 493 494 /** @brief Suspend the Mesh network temporarily. 495 * 496 * This API can be used for power saving purposes, but the user should be 497 * aware that leaving the local node suspended for a long period of time 498 * may cause it to become permanently disconnected from the Mesh network. 499 * If at all possible, the Friendship feature should be used instead, to 500 * make the node into a Low Power Node. 501 * 502 * @return 0 on success, or (negative) error code on failure. 503 */ 504 int bt_mesh_suspend(void); 505 506 /** @brief Resume a suspended Mesh network. 507 * 508 * This API resumes the local node, after it has been suspended using the 509 * bt_mesh_suspend() API. 510 * 511 * @return 0 on success, or (negative) error code on failure. 512 */ 513 int bt_mesh_resume(void); 514 515 /** @brief Provision the local Mesh Node. 516 * 517 * This API should normally not be used directly by the application. The 518 * only exception is for testing purposes where manual provisioning is 519 * desired without an actual external provisioner. 520 * 521 * @param net_key Network Key 522 * @param net_idx Network Key Index 523 * @param flags Provisioning Flags 524 * @param iv_index IV Index 525 * @param addr Primary element address 526 * @param dev_key Device Key 527 * 528 * @return Zero on success or (negative) error code otherwise. 529 */ 530 int bt_mesh_provision(const uint8_t net_key[16], uint16_t net_idx, 531 uint8_t flags, uint32_t iv_index, uint16_t addr, 532 const uint8_t dev_key[16]); 533 534 /** @brief Check if the device is an unprovisioned device 535 * and will act as a node once provisioned. 536 * 537 * @return true - yes, false - no. 538 */ 539 bool bt_mesh_is_node(void); 540 541 /** @brief Check if the local node has been provisioned. 542 * 543 * This API can be used to check if the local node has been provisioned 544 * or not. It can e.g. be helpful to determine if there was a stored 545 * network in flash, i.e. if the network was restored after calling 546 * settings_load(). 547 * 548 * @return True if the node is provisioned. False otherwise. 549 */ 550 bool bt_mesh_is_provisioned(void); 551 552 /** @brief Check if the device is a Provisioner. 553 * 554 * @return true - yes, false - no. 555 */ 556 bool bt_mesh_is_provisioner(void); 557 558 /** @brief Check if the Provisioner is enabled 559 * 560 * @return true - enabled, false - disabled. 561 */ 562 bool bt_mesh_is_provisioner_en(void); 563 564 /** @brief Toggle the IV Update test mode 565 * 566 * This API is only available if the IV Update test mode has been enabled 567 * in Kconfig. It is needed for passing most of the IV Update qualification 568 * test cases. 569 * 570 * @param enable true to enable IV Update test mode, false to disable it. 571 */ 572 void bt_mesh_iv_update_test(bool enable); 573 574 /** @brief Toggle the IV Update state 575 * 576 * This API is only available if the IV Update test mode has been enabled 577 * in Kconfig. It is needed for passing most of the IV Update qualification 578 * test cases. 579 * 580 * @return true if IV Update In Progress state was entered, false otherwise. 581 */ 582 bool bt_mesh_iv_update(void); 583 584 /** @brief Toggle the Low Power feature of the local device 585 * 586 * Enables or disables the Low Power feature of the local device. This is 587 * exposed as a run-time feature, since the device might want to change 588 * this e.g. based on being plugged into a stable power source or running 589 * from a battery power source. 590 * 591 * @param enable true to enable LPN functionality, false to disable it. 592 * @param force when disable LPN functionality, use this flag to indicate 593 * whether directly clear corresponding information or sending 594 * friend clear to disable it. 595 * 596 * @return Zero on success or (negative) error code otherwise. 597 */ 598 int bt_mesh_lpn_set(bool enable, bool force); 599 600 /** @brief Send out a Friend Poll message. 601 * 602 * Send a Friend Poll message to the Friend of this node. If there is no 603 * established Friendship the function will return an error. 604 * 605 * @return Zero on success or (negative) error code otherwise. 606 */ 607 int bt_mesh_lpn_poll(void); 608 609 /** @brief Register a callback for Friendship changes. 610 * 611 * Registers a callback that will be called whenever Friendship gets 612 * established or is lost. 613 * 614 * @param cb Function to call when the Friendship status changes. 615 */ 616 void bt_mesh_lpn_set_cb(void (*cb)(uint16_t friend_addr, bool established)); 617 618 /** @brief Register a callback for Friendship changes of friend node. 619 * 620 * Registers a callback that will be called whenever Friendship gets 621 * established or is terminated. 622 * 623 * @param cb Function to call when the Friendship status of friend node changes. 624 */ 625 void bt_mesh_friend_set_cb(void (*cb)(bool establish, uint16_t lpn_addr, uint8_t reason)); 626 627 #ifdef __cplusplus 628 } 629 #endif 630 631 /** 632 * @} 633 */ 634 635 #endif /* _BLE_MESH_MAIN_H_ */ 636
