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 __BT_MESH_MAIN_H 11 #define __BT_MESH_MAIN_H 12 13 /** 14 * @brief Bluetooth Mesh Provisioning 15 * @defgroup bt_mesh_prov Bluetooth Mesh Provisioning 16 * @ingroup bt_mesh 17 * @{ 18 */ 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 #ifndef bool 25 #define bool unsigned char 26 #endif 27 28 #define BITN(n) (1U << (n)) 29 30 typedef enum { 31 BT_MESH_NO_OUTPUT = 0, 32 BT_MESH_BLINK = BITN(0), 33 BT_MESH_BEEP = BITN(1), 34 BT_MESH_VIBRATE = BITN(2), 35 BT_MESH_DISPLAY_NUMBER = BITN(3), 36 BT_MESH_DISPLAY_STRING = BITN(4), 37 } bt_mesh_output_action_t; 38 39 typedef enum { 40 BT_MESH_NO_INPUT = 0, 41 BT_MESH_PUSH = BITN(0), 42 BT_MESH_TWIST = BITN(1), 43 BT_MESH_ENTER_NUMBER = BITN(2), 44 BT_MESH_ENTER_STRING = BITN(3), 45 } bt_mesh_input_action_t; 46 47 typedef enum { 48 BT_MESH_PROV_ADV = BITN(0), 49 BT_MESH_PROV_GATT = BITN(1), 50 } bt_mesh_prov_bearer_t; 51 52 typedef enum { 53 BT_MESH_PROV_OOB_OTHER = BITN(0), 54 BT_MESH_PROV_OOB_URI = BITN(1), 55 BT_MESH_PROV_OOB_2D_CODE = BITN(2), 56 BT_MESH_PROV_OOB_BAR_CODE = BITN(3), 57 BT_MESH_PROV_OOB_NFC = BITN(4), 58 BT_MESH_PROV_OOB_NUMBER = BITN(5), 59 BT_MESH_PROV_OOB_STRING = BITN(6), 60 /* 7 - 10 are reserved */ 61 BT_MESH_PROV_OOB_ON_BOX = BITN(11), 62 BT_MESH_PROV_OOB_IN_BOX = BITN(12), 63 BT_MESH_PROV_OOB_ON_PAPER = BITN(13), 64 BT_MESH_PROV_OOB_IN_MANUAL = BITN(14), 65 BT_MESH_PROV_OOB_ON_DEV = BITN(15), 66 } bt_mesh_prov_oob_info_t; 67 68 /** Provisioning properties & capabilities. */ 69 struct bt_mesh_prov { 70 /** The UUID that's used when advertising as unprovisioned */ 71 const u8_t *uuid; 72 73 /** Optional URI. This will be advertised separately from the 74 * unprovisioned beacon, however the unprovisioned beacon will 75 * contain a hash of it so the two can be associated by the 76 * provisioner. 77 */ 78 const char *uri; 79 80 /** Out of Band information field. */ 81 bt_mesh_prov_oob_info_t oob_info; 82 83 /** Static OOB value */ 84 const u8_t *static_val; 85 /** Static OOB value length */ 86 u8_t static_val_len; 87 88 /** Maximum size of Output OOB supported */ 89 u8_t output_size; 90 /** Supported Output OOB Actions */ 91 u16_t output_actions; 92 93 /* Maximum size of Input OOB supported */ 94 u8_t input_size; 95 /** Supported Input OOB Actions */ 96 u16_t input_actions; 97 98 /** @brief Output of a number is requested. 99 * 100 * This callback notifies the application that it should 101 * output the given number using the given action. 102 * 103 * @param act Action for outputting the number. 104 * @param num Number to be outputted. 105 * 106 * @return Zero on success or negative error code otherwise 107 */ 108 int (*output_number)(bt_mesh_output_action_t act, bt_u32_t num); 109 110 /** @brief Output of a string is requested. 111 * 112 * This callback notifies the application that it should 113 * display the given string to the user. 114 * 115 * @param str String to be displayed. 116 * 117 * @return Zero on success or negative error code otherwise 118 */ 119 int (*output_string)(const char *str); 120 121 /** @brief Input is requested. 122 * 123 * This callback notifies the application that it should 124 * request input from the user using the given action. The 125 * requested input will either be a string or a number, and 126 * the application needs to consequently call the 127 * bt_mesh_input_string() or bt_mesh_input_number() functions 128 * once the data has been acquired from the user. 129 * 130 * @param act Action for inputting data. 131 * @param num Maximum size of the inputted data. 132 * 133 * @return Zero on success or negative error code otherwise 134 */ 135 int (*input)(bt_mesh_input_action_t act, u8_t size); 136 137 /** @brief Provisioning link has been opened. 138 * 139 * This callback notifies the application that a provisioning 140 * link has been opened on the given provisioning bearer. 141 * 142 * @param bearer Provisioning bearer. 143 */ 144 void (*link_open)(bt_mesh_prov_bearer_t bearer); 145 146 /** @brief Provisioning link has been closed. 147 * 148 * This callback notifies the application that a provisioning 149 * link has been closed on the given provisioning bearer. 150 * 151 * @param bearer Provisioning bearer. 152 */ 153 void (*link_close)(bt_mesh_prov_bearer_t bearer); 154 155 /** @brief Provisioning is complete. 156 * 157 * This callback notifies the application that provisioning has 158 * been successfully completed, and that the local node has been 159 * assigned the specified NetKeyIndex and primary element address. 160 * 161 * @param net_idx NetKeyIndex given during provisioning. 162 * @param addr Primary element address. 163 */ 164 void (*complete)(u16_t net_idx, u16_t addr); 165 166 /** @brief Node has been reset. 167 * 168 * This callback notifies the application that the local node 169 * has been reset and needs to be reprovisioned. The node will 170 * not automatically advertise as unprovisioned, rather the 171 * bt_mesh_prov_enable() API needs to be called to enable 172 * unprovisioned advertising on one or more provisioning bearers. 173 */ 174 void (*reset)(void); 175 }; 176 177 struct bt_mesh_provisioner { 178 /* Provisioner device uuid */ 179 const u8_t *prov_uuid; 180 181 /* 182 * Primary element address of the provisioner, for 183 * temporary provisioner no need to initialize it. 184 */ 185 u16_t prov_unicast_addr; 186 187 /* 188 * Starting unicast address going to assigned, for 189 * temporary provisioner no need to initialize it. 190 */ 191 u16_t prov_start_address; 192 193 /* Attention timer contained in Provisioning Invite */ 194 u8_t prov_attention; 195 196 /* Provisioner provisioning Algorithm */ 197 u8_t prov_algorithm; 198 199 /* Provisioner public key oob */ 200 u8_t prov_pub_key_oob; 201 202 /** @brief Input is requested. 203 * 204 * This callback notifies the application that it should 205 * read device's public key with OOB 206 * 207 * @param remote_pub_key Public key pointer of the device. 208 * 209 * @return Zero on success or negative error code otherwise 210 */ 211 int (*prov_pub_key_oob_cb)(u8_t remote_pub_key[64]); 212 213 /* Provisioner static oob value */ 214 u8_t *prov_static_oob_val; 215 216 /* Provisioner static oob value length */ 217 u8_t prov_static_oob_len; 218 219 /** @brief Provisioner input a number read from device output 220 * 221 * This callback notifies the application that it should 222 * input the number given by the device. 223 * 224 * @param act: The output action of the device 225 * @param size: The output size of the device 226 * 227 * @return Zero on success or negative error code otherwise 228 */ 229 int (*prov_input_num)(bt_mesh_output_action_t act, u8_t size); 230 /** @brief Provisioner input static oob 231 * 232 * This callback notifies the application that it should 233 * 234 * @param size: The output size of the device 235 * 236 * @return Zero on success or negative error code otherwise 237 */ 238 239 int (*prov_input_static_oob)(); 240 241 /** @brief Provisioner output a number to the device 242 * 243 * This callback notifies the application that it should 244 * output the number to the device. 245 * 246 * @param act: The input action of the device 247 * @param size: The input size of the device 248 * 249 * @return Zero on success or negative error code otherwise 250 */ 251 int (*prov_output_num)(bt_mesh_input_action_t act, u8_t size); 252 253 /* 254 * Key refresh and IV update flag, for temporary provisioner no 255 * need to initialize it. 256 */ 257 u8_t flags; 258 259 /* 260 * IV index, for temporary provisioner no need to initialize it. 261 */ 262 bt_u32_t iv_index; 263 264 /** @brief Provisioner has opened a provisioning link. 265 * 266 * This callback notifies the application that a provisioning 267 * link has been opened on the given provisioning bearer. 268 * 269 * @param bearer Provisioning bearer. 270 * @param link info. 271 */ 272 void (*prov_link_open)(bt_mesh_prov_bearer_t bearer, u8_t addr_val[6], u8_t addr_type, u8_t uuid[16], 273 u8_t prov_count); 274 275 /** @brief Provisioner has closed a provisioning link. 276 * 277 * This callback notifies the application that a provisioning 278 * link has been closed on the given provisioning bearer. 279 * 280 * @param bearer Provisioning bearer. 281 * @param reason Provisioning link close reason(disconnect reason) 282 * @param link info. 283 */ 284 void (*prov_link_close)(bt_mesh_prov_bearer_t bearer, u8_t reason, u8_t addr_val[6], u8_t addr_type, u8_t uuid[16], 285 u8_t prov_count); 286 287 /** @brief Provision one device is complete. 288 * 289 * This callback notifies the application that provisioner has 290 * successfully provisioned a device, and the node has been assigned 291 * with the specified NetKeyIndex and primary element address. 292 * 293 * @param node_idx Node index within the node(provisioned device) queue. 294 * @param device_uuid Provisioned device device uuid pointer. 295 * @param unicast_addr Provisioned device assigned unicast address. 296 * @param element_num Provisioned device element number. 297 * @param netkey_idx Provisioned device assigned netkey index. 298 */ 299 void (*prov_complete)(int node_idx, const u8_t device_uuid[16], u16_t unicast_addr, u8_t element_num, 300 u16_t netkey_idx, bool gatt_flag); 301 }; 302 303 /** @brief Provide provisioning input OOB string. 304 * 305 * This is intended to be called after the bt_mesh_prov input callback 306 * has been called with BT_MESH_ENTER_STRING as the action. 307 * 308 * @param str String. 309 * 310 * @return Zero on success or (negative) error code otherwise. 311 */ 312 int bt_mesh_input_string(const char *str); 313 314 /** @brief Provide provisioning input OOB number. 315 * 316 * This is intended to be called after the bt_mesh_prov input callback 317 * has been called with BT_MESH_ENTER_NUMBER as the action. 318 * 319 * @param num Number. 320 * 321 * @return Zero on success or (negative) error code otherwise. 322 */ 323 int bt_mesh_input_number(bt_u32_t num); 324 325 /** @brief Enable specific provisioning bearers 326 * 327 * Enable one or more provisioning bearers. 328 * 329 * @param bearers Bit-wise or of provisioning bearers. 330 * 331 * @return Zero on success or (negative) error code otherwise. 332 */ 333 int bt_mesh_prov_enable(bt_mesh_prov_bearer_t bearers); 334 335 /** @brief Disable specific provisioning bearers 336 * 337 * Disable one or more provisioning bearers. 338 * 339 * @param bearers Bit-wise or of provisioning bearers. 340 * 341 * @return Zero on success or (negative) error code otherwise. 342 */ 343 int bt_mesh_prov_disable(bt_mesh_prov_bearer_t bearers); 344 345 /** 346 * @} 347 */ 348 349 /** 350 * @brief Bluetooth Mesh 351 * @defgroup bt_mesh Bluetooth Mesh 352 * @ingroup bluetooth 353 * @{ 354 */ 355 356 /* Primary Network Key index */ 357 #define BT_MESH_NET_PRIMARY 0x000 358 359 #define BT_MESH_RELAY_DISABLED 0x00 360 #define BT_MESH_RELAY_ENABLED 0x01 361 #define BT_MESH_RELAY_NOT_SUPPORTED 0x02 362 363 #define BT_MESH_BEACON_DISABLED 0x00 364 #define BT_MESH_BEACON_ENABLED 0x01 365 366 #define BT_MESH_GATT_PROXY_DISABLED 0x00 367 #define BT_MESH_GATT_PROXY_ENABLED 0x01 368 #define BT_MESH_GATT_PROXY_NOT_SUPPORTED 0x02 369 370 #define BT_MESH_FRIEND_DISABLED 0x00 371 #define BT_MESH_FRIEND_ENABLED 0x01 372 #define BT_MESH_FRIEND_NOT_SUPPORTED 0x02 373 374 #define BT_MESH_NODE_IDENTITY_STOPPED 0x00 375 #define BT_MESH_NODE_IDENTITY_RUNNING 0x01 376 #define BT_MESH_NODE_IDENTITY_NOT_SUPPORTED 0x02 377 378 /* Features */ 379 #define BT_MESH_FEAT_RELAY BITN(0) 380 #define BT_MESH_FEAT_PROXY BITN(1) 381 #define BT_MESH_FEAT_FRIEND BITN(2) 382 #define BT_MESH_FEAT_LOW_POWER BITN(3) 383 #define BT_MESH_FEAT_SUPPORTED (BT_MESH_FEAT_RELAY | BT_MESH_FEAT_PROXY | BT_MESH_FEAT_FRIEND | BT_MESH_FEAT_LOW_POWER) 384 385 /** @brief Initialize Mesh support 386 * 387 * After calling this API, the node will not automatically advertise as 388 * unprovisioned, rather the bt_mesh_prov_enable() API needs to be called 389 * to enable unprovisioned advertising on one or more provisioning bearers. 390 * 391 * @param prov Node provisioning information. 392 * @param comp Node Composition. 393 * 394 * @return Zero on success or (negative) error code otherwise. 395 */ 396 int bt_mesh_init(const struct bt_mesh_prov *prov, const struct bt_mesh_comp *comp, 397 const struct bt_mesh_provisioner *provisioner); 398 399 /** @brief Reset the state of the local Mesh node. 400 * 401 * Resets the state of the node, which means that it needs to be 402 * reprovisioned to become an active node in a Mesh network again. 403 * 404 * After calling this API, the node will not automatically advertise as 405 * unprovisioned, rather the bt_mesh_prov_enable() API needs to be called 406 * to enable unprovisioned advertising on one or more provisioning bearers. 407 * 408 */ 409 void bt_mesh_reset(void); 410 411 /** @brief Suspend the Mesh network temporarily. 412 * 413 * This API can be used for power saving purposes, but the user should be 414 * aware that leaving the local node suspended for a long period of time 415 * may cause it to become permanently disconnected from the Mesh network. 416 * If at all possible, the Friendship feature should be used instead, to 417 * make the node into a Low Power Node. 418 * 419 * @return 0 on success, or (negative) error code on failure. 420 */ 421 int bt_mesh_suspend(bool force); 422 423 /** @brief Resume a suspended Mesh network. 424 * 425 * This API resumes the local node, after it has been suspended using the 426 * bt_mesh_suspend() API. 427 * 428 * @return 0 on success, or (negative) error code on failure. 429 */ 430 int bt_mesh_resume(void); 431 432 /** @brief Provision the local Mesh Node. 433 * 434 * This API should normally not be used directly by the application. The 435 * only exception is for testing purposes where manual provisioning is 436 * desired without an actual external provisioner. 437 * 438 * @param net_key Network Key 439 * @param net_idx Network Key Index 440 * @param flags Provisioning Flags 441 * @param iv_index IV Index 442 * @param addr Primary element address 443 * @param dev_key Device Key 444 * 445 * @return Zero on success or (negative) error code otherwise. 446 */ 447 int bt_mesh_provision(const u8_t net_key[16], u16_t net_idx, u8_t flags, bt_u32_t iv_index, u16_t addr, 448 const u8_t dev_key[16]); 449 450 /** @brief Check if the local node has been provisioned. 451 * 452 * This API can be used to check if the local node has been provisioned 453 * or not. It can e.g. be helpful to determine if there was a stored 454 * network in flash, i.e. if the network was restored after calling 455 * settings_load(). 456 * 457 * @return True if the node is provisioned. False otherwise. 458 */ 459 bool bt_mesh_is_provisioned(void); 460 461 /** @brief Toggle the IV Update test mode 462 * 463 * This API is only available if the IV Update test mode has been enabled 464 * in Kconfig. It is needed for passing most of the IV Update qualification 465 * test cases. 466 * 467 * @param enable true to enable IV Update test mode, false to disable it. 468 */ 469 void bt_mesh_iv_update_test(bool enable); 470 471 /** @brief Toggle the IV Update state 472 * 473 * This API is only available if the IV Update test mode has been enabled 474 * in Kconfig. It is needed for passing most of the IV Update qualification 475 * test cases. 476 * 477 * @return true if IV Update In Progress state was entered, false otherwise. 478 */ 479 bool bt_mesh_iv_update(void); 480 481 /** @brief Toggle the Low Power feature of the local device 482 * 483 * Enables or disables the Low Power feature of the local device. This is 484 * exposed as a run-time feature, since the device might want to change 485 * this e.g. based on being plugged into a stable power source or running 486 * from a battery power source. 487 * 488 * @param enable true to enable LPN functionality, false to disable it. 489 * 490 * @return Zero on success or (negative) error code otherwise. 491 */ 492 int bt_mesh_lpn_set(bool enable); 493 494 /** @brief Send out a Friend Poll message. 495 * 496 * Send a Friend Poll message to the Friend of this node. If there is no 497 * established Friendship the function will return an error. 498 * 499 * @return Zero on success or (negative) error code otherwise. 500 */ 501 int bt_mesh_lpn_poll(void); 502 503 /** @brief Register a callback for Friendship changes. 504 * 505 * Registers a callback that will be called whenever Friendship gets 506 * established or is lost. 507 * 508 * @param cb Function to call when the Friendship status changes. 509 */ 510 void bt_mesh_lpn_set_cb(void (*cb)(u16_t friend_addr, bool established)); 511 512 int bt_mesh_provisioner_enable(bt_mesh_prov_bearer_t bearers); 513 int bt_mesh_provisioner_disable(bt_mesh_prov_bearer_t bearers); 514 int bt_mesh_is_init(); 515 516 struct adv_addr_t { 517 u8_t type; 518 u8_t val[6]; 519 }; 520 521 int bt_mesh_vnd_adv_set_cb(void (*cb)(const struct adv_addr_t *addr, s8_t rssi, u8_t adv_type, void *user_data, 522 u16_t len)); 523 524 #ifdef __cplusplus 525 } 526 #endif 527 528 /** 529 * @} 530 */ 531 532 #endif /* __BT_MESH_MAIN_H */ 533