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 typedef enum { 25 BT_MESH_NO_OUTPUT = 0, 26 BT_MESH_BLINK = BIT(0), 27 BT_MESH_BEEP = BIT(1), 28 BT_MESH_VIBRATE = BIT(2), 29 BT_MESH_DISPLAY_NUMBER = BIT(3), 30 BT_MESH_DISPLAY_STRING = BIT(4), 31 } bt_mesh_output_action_t; 32 33 typedef enum { 34 BT_MESH_NO_INPUT = 0, 35 BT_MESH_PUSH = BIT(0), 36 BT_MESH_TWIST = BIT(1), 37 BT_MESH_ENTER_NUMBER = BIT(2), 38 BT_MESH_ENTER_STRING = BIT(3), 39 } bt_mesh_input_action_t; 40 41 typedef enum { 42 BT_MESH_PROV_ADV = BIT(0), 43 BT_MESH_PROV_GATT = BIT(1), 44 } bt_mesh_prov_bearer_t; 45 46 typedef enum { 47 BT_MESH_PROV_OOB_OTHER = BIT(0), 48 BT_MESH_PROV_OOB_URI = BIT(1), 49 BT_MESH_PROV_OOB_2D_CODE = BIT(2), 50 BT_MESH_PROV_OOB_BAR_CODE = BIT(3), 51 BT_MESH_PROV_OOB_NFC = BIT(4), 52 BT_MESH_PROV_OOB_NUMBER = BIT(5), 53 BT_MESH_PROV_OOB_STRING = BIT(6), 54 /* 7 - 10 are reserved */ 55 BT_MESH_PROV_OOB_ON_BOX = BIT(11), 56 BT_MESH_PROV_OOB_IN_BOX = BIT(12), 57 BT_MESH_PROV_OOB_ON_PAPER = BIT(13), 58 BT_MESH_PROV_OOB_IN_MANUAL = BIT(14), 59 BT_MESH_PROV_OOB_ON_DEV = BIT(15), 60 } bt_mesh_prov_oob_info_t; 61 62 /** Provisioning properties & capabilities. */ 63 struct bt_mesh_prov { 64 /** The UUID that's used when advertising as unprovisioned */ 65 const u8_t *uuid; 66 67 /** Optional URI. This will be advertised separately from the 68 * unprovisioned beacon, however the unprovisioned beacon will 69 * contain a hash of it so the two can be associated by the 70 * provisioner. 71 */ 72 const char *uri; 73 74 /** Out of Band information field. */ 75 bt_mesh_prov_oob_info_t oob_info; 76 77 /** Static OOB value */ 78 const u8_t *static_val; 79 /** Static OOB value length */ 80 u8_t static_val_len; 81 82 /** Maximum size of Output OOB supported */ 83 u8_t output_size; 84 /** Supported Output OOB Actions */ 85 u16_t output_actions; 86 87 /* Maximum size of Input OOB supported */ 88 u8_t input_size; 89 /** Supported Input OOB Actions */ 90 u16_t input_actions; 91 92 /** @brief Output of a number is requested. 93 * 94 * This callback notifies the application that it should 95 * output the given number using the given action. 96 * 97 * @param act Action for outputting the number. 98 * @param num Number to be outputted. 99 * 100 * @return Zero on success or negative error code otherwise 101 */ 102 int (*output_number)(bt_mesh_output_action_t act, u32_t num); 103 104 /** @brief Output of a string is requested. 105 * 106 * This callback notifies the application that it should 107 * display the given string to the user. 108 * 109 * @param str String to be displayed. 110 * 111 * @return Zero on success or negative error code otherwise 112 */ 113 int (*output_string)(const char *str); 114 115 /** @brief Input is requested. 116 * 117 * This callback notifies the application that it should 118 * request input from the user using the given action. The 119 * requested input will either be a string or a number, and 120 * the application needs to consequently call the 121 * bt_mesh_input_string() or bt_mesh_input_number() functions 122 * once the data has been acquired from the user. 123 * 124 * @param act Action for inputting data. 125 * @param num Maximum size of the inputted data. 126 * 127 * @return Zero on success or negative error code otherwise 128 */ 129 int (*input)(bt_mesh_input_action_t act, u8_t size); 130 131 /** @brief The other device finished their OOB input. 132 * 133 * This callback notifies the application that it should stop 134 * displaying its output OOB value, as the other party finished their 135 * OOB input. 136 */ 137 void (*input_complete)(void); 138 139 /** @brief Unprovisioned beacon has been received. 140 * 141 * This callback notifies the application that an unprovisioned 142 * beacon has been received. 143 * 144 * @param uuid UUID 145 * @param oob_info OOB Information 146 * @param uri_hash Pointer to URI Hash value. NULL if no hash was 147 * present in the beacon. 148 */ 149 void (*unprovisioned_beacon)(u8_t uuid[16], 150 bt_mesh_prov_oob_info_t oob_info, 151 u32_t *uri_hash); 152 153 /** @brief Provisioning link has been opened. 154 * 155 * This callback notifies the application that a provisioning 156 * link has been opened on the given provisioning bearer. 157 * 158 * @param bearer Provisioning bearer. 159 */ 160 void (*link_open)(bt_mesh_prov_bearer_t bearer); 161 162 /** @brief Provisioning link has been closed. 163 * 164 * This callback notifies the application that a provisioning 165 * link has been closed on the given provisioning bearer. 166 * 167 * @param bearer Provisioning bearer. 168 */ 169 void (*link_close)(bt_mesh_prov_bearer_t bearer); 170 171 /** @brief Provisioning is complete. 172 * 173 * This callback notifies the application that provisioning has 174 * been successfully completed, and that the local node has been 175 * assigned the specified NetKeyIndex and primary element address. 176 * 177 * @param net_idx NetKeyIndex given during provisioning. 178 * @param addr Primary element address. 179 */ 180 void (*complete)(u16_t net_idx, u16_t addr); 181 182 /** @brief A new node has been added to the provisioning database. 183 * 184 * This callback notifies the application that provisioning has 185 * been successfully completed, and that a node has been assigned 186 * the specified NetKeyIndex and primary element address. 187 * 188 * @param net_idx NetKeyIndex given during provisioning. 189 * @param addr Primary element address. 190 * @param num_elem Number of elements that this node has. 191 */ 192 void (*node_added)(u16_t net_idx, u16_t addr, u8_t num_elem); 193 194 /** @brief Node has been reset. 195 * 196 * This callback notifies the application that the local node 197 * has been reset and needs to be reprovisioned. The node will 198 * not automatically advertise as unprovisioned, rather the 199 * bt_mesh_prov_enable() API needs to be called to enable 200 * unprovisioned advertising on one or more provisioning bearers. 201 */ 202 void (*reset)(void); 203 }; 204 205 /** @brief Provide provisioning input OOB string. 206 * 207 * This is intended to be called after the bt_mesh_prov input callback 208 * has been called with BT_MESH_ENTER_STRING as the action. 209 * 210 * @param str String. 211 * 212 * @return Zero on success or (negative) error code otherwise. 213 */ 214 int bt_mesh_input_string(const char *str); 215 216 /** @brief Provide provisioning input OOB number. 217 * 218 * This is intended to be called after the bt_mesh_prov input callback 219 * has been called with BT_MESH_ENTER_NUMBER as the action. 220 * 221 * @param num Number. 222 * 223 * @return Zero on success or (negative) error code otherwise. 224 */ 225 int bt_mesh_input_number(u32_t num); 226 227 /** @brief Enable specific provisioning bearers 228 * 229 * Enable one or more provisioning bearers. 230 * 231 * @param bearers Bit-wise or of provisioning bearers. 232 * 233 * @return Zero on success or (negative) error code otherwise. 234 */ 235 int bt_mesh_prov_enable(bt_mesh_prov_bearer_t bearers); 236 237 /** @brief Disable specific provisioning bearers 238 * 239 * Disable one or more provisioning bearers. 240 * 241 * @param bearers Bit-wise or of provisioning bearers. 242 * 243 * @return Zero on success or (negative) error code otherwise. 244 */ 245 int bt_mesh_prov_disable(bt_mesh_prov_bearer_t bearers); 246 247 /** 248 * @} 249 */ 250 251 /** 252 * @brief Bluetooth Mesh 253 * @defgroup bt_mesh Bluetooth Mesh 254 * @ingroup bluetooth 255 * @{ 256 */ 257 258 /* Primary Network Key index */ 259 #define BT_MESH_NET_PRIMARY 0x000 260 261 #define BT_MESH_RELAY_DISABLED 0x00 262 #define BT_MESH_RELAY_ENABLED 0x01 263 #define BT_MESH_RELAY_NOT_SUPPORTED 0x02 264 265 #define BT_MESH_BEACON_DISABLED 0x00 266 #define BT_MESH_BEACON_ENABLED 0x01 267 268 #define BT_MESH_GATT_PROXY_DISABLED 0x00 269 #define BT_MESH_GATT_PROXY_ENABLED 0x01 270 #define BT_MESH_GATT_PROXY_NOT_SUPPORTED 0x02 271 272 #define BT_MESH_FRIEND_DISABLED 0x00 273 #define BT_MESH_FRIEND_ENABLED 0x01 274 #define BT_MESH_FRIEND_NOT_SUPPORTED 0x02 275 276 #define BT_MESH_NODE_IDENTITY_STOPPED 0x00 277 #define BT_MESH_NODE_IDENTITY_RUNNING 0x01 278 #define BT_MESH_NODE_IDENTITY_NOT_SUPPORTED 0x02 279 280 /* Features */ 281 #define BT_MESH_FEAT_RELAY BIT(0) 282 #define BT_MESH_FEAT_PROXY BIT(1) 283 #define BT_MESH_FEAT_FRIEND BIT(2) 284 #define BT_MESH_FEAT_LOW_POWER BIT(3) 285 #define BT_MESH_FEAT_SUPPORTED (BT_MESH_FEAT_RELAY | \ 286 BT_MESH_FEAT_PROXY | \ 287 BT_MESH_FEAT_FRIEND | \ 288 BT_MESH_FEAT_LOW_POWER) 289 290 /** @brief Initialize Mesh support 291 * 292 * After calling this API, the node will not automatically advertise as 293 * unprovisioned, rather the bt_mesh_prov_enable() API needs to be called 294 * to enable unprovisioned advertising on one or more provisioning bearers. 295 * 296 * @param own_addr_type Node address type 297 * @param prov Node provisioning information. 298 * @param comp Node Composition. 299 * 300 * @return Zero on success or (negative) error code otherwise. 301 */ 302 int bt_mesh_init(u8_t own_addr_type, 303 const struct bt_mesh_prov *prov, 304 const struct bt_mesh_comp *comp); 305 306 /** @brief Reset the state of the local Mesh node. 307 * 308 * Resets the state of the node, which means that it needs to be 309 * reprovisioned to become an active node in a Mesh network again. 310 * 311 * After calling this API, the node will not automatically advertise as 312 * unprovisioned, rather the bt_mesh_prov_enable() API needs to be called 313 * to enable unprovisioned advertising on one or more provisioning bearers. 314 * 315 */ 316 void bt_mesh_reset(void); 317 318 /** @brief Suspend the Mesh network temporarily. 319 * 320 * This API can be used for power saving purposes, but the user should be 321 * aware that leaving the local node suspended for a long period of time 322 * may cause it to become permanently disconnected from the Mesh network. 323 * If at all possible, the Friendship feature should be used instead, to 324 * make the node into a Low Power Node. 325 * 326 * @return 0 on success, or (negative) error code on failure. 327 */ 328 int bt_mesh_suspend(void); 329 330 /** @brief Resume a suspended Mesh network. 331 * 332 * This API resumes the local node, after it has been suspended using the 333 * bt_mesh_suspend() API. 334 * 335 * @return 0 on success, or (negative) error code on failure. 336 */ 337 int bt_mesh_resume(void); 338 339 /** @brief Provision the local Mesh Node. 340 * 341 * This API should normally not be used directly by the application. The 342 * only exception is for testing purposes where manual provisioning is 343 * desired without an actual external provisioner. 344 * 345 * @param net_key Network Key 346 * @param net_idx Network Key Index 347 * @param flags Provisioning Flags 348 * @param iv_index IV Index 349 * @param addr Primary element address 350 * @param dev_key Device Key 351 * 352 * @return Zero on success or (negative) error code otherwise. 353 */ 354 int bt_mesh_provision(const u8_t net_key[16], u16_t net_idx, 355 u8_t flags, u32_t iv_index, u16_t addr, 356 const u8_t dev_key[16]); 357 358 /** @brief Provision a Mesh Node using PB-ADV 359 * 360 * @param uuid UUID 361 * @param net_idx Network Key Index 362 * @param addr Address to assign to remote device. If addr is 0, the lowest 363 * available address will be chosen. 364 * @param attention_duration The attention duration to be send to remote device 365 * 366 * @return Zero on success or (negative) error code otherwise. 367 */ 368 int bt_mesh_provision_adv(const u8_t uuid[16], u16_t net_idx, u16_t addr, 369 u8_t attention_duration); 370 371 /** @brief Check if the local node has been provisioned. 372 * 373 * This API can be used to check if the local node has been provisioned 374 * or not. It can e.g. be helpful to determine if there was a stored 375 * network in flash, i.e. if the network was restored after calling 376 * settings_load(). 377 * 378 * @return True if the node is provisioned. False otherwise. 379 */ 380 bool bt_mesh_is_provisioned(void); 381 382 /** @brief Toggle the IV Update test mode 383 * 384 * This API is only available if the IV Update test mode has been enabled 385 * in Kconfig. It is needed for passing most of the IV Update qualification 386 * test cases. 387 * 388 * @param enable true to enable IV Update test mode, false to disable it. 389 */ 390 void bt_mesh_iv_update_test(bool enable); 391 392 /** @brief Toggle the IV Update state 393 * 394 * This API is only available if the IV Update test mode has been enabled 395 * in Kconfig. It is needed for passing most of the IV Update qualification 396 * test cases. 397 * 398 * @return true if IV Update In Progress state was entered, false otherwise. 399 */ 400 bool bt_mesh_iv_update(void); 401 402 /** @brief Toggle the Low Power feature of the local device 403 * 404 * Enables or disables the Low Power feature of the local device. This is 405 * exposed as a run-time feature, since the device might want to change 406 * this e.g. based on being plugged into a stable power source or running 407 * from a battery power source. 408 * 409 * @param enable true to enable LPN functionality, false to disable it. 410 * 411 * @return Zero on success or (negative) error code otherwise. 412 */ 413 int bt_mesh_lpn_set(bool enable); 414 415 /** @brief Send out a Friend Poll message. 416 * 417 * Send a Friend Poll message to the Friend of this node. If there is no 418 * established Friendship the function will return an error. 419 * 420 * @return Zero on success or (negative) error code otherwise. 421 */ 422 int bt_mesh_lpn_poll(void); 423 424 /** @brief Register a callback for Friendship changes. 425 * 426 * Registers a callback that will be called whenever Friendship gets 427 * established or is lost. 428 * 429 * @param cb Function to call when the Friendship status changes. 430 */ 431 void bt_mesh_lpn_set_cb(void (*cb)(u16_t friend_addr, bool established)); 432 433 #ifdef __cplusplus 434 } 435 #endif 436 437 /** 438 * @} 439 */ 440 441 #endif /* __BT_MESH_MAIN_H */ 442