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