1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20 #ifndef H_BLE_HS_ 21 #define H_BLE_HS_ 22 23 /** 24 * @brief Bluetooth Host 25 * @defgroup bt_host Bluetooth Host 26 * @{ 27 */ 28 29 #include <inttypes.h> 30 #include "nimble/hci_common.h" 31 #include "host/ble_att.h" 32 #include "host/ble_eddystone.h" 33 #include "host/ble_gap.h" 34 #include "host/ble_gatt.h" 35 #include "host/ble_hs_adv.h" 36 #include "host/ble_hs_id.h" 37 #include "host/ble_hs_hci.h" 38 #include "host/ble_hs_log.h" 39 #include "host/ble_hs_test.h" 40 #include "host/ble_hs_mbuf.h" 41 #include "host/ble_hs_stop.h" 42 #include "host/ble_ibeacon.h" 43 #include "host/ble_l2cap.h" 44 #include "host/ble_sm.h" 45 #include "host/ble_store.h" 46 #include "host/ble_uuid.h" 47 #include "nimble/nimble_npl.h" 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 #define BLE_HS_FOREVER INT32_MAX 54 55 /** Connection handle not present */ 56 #define BLE_HS_CONN_HANDLE_NONE 0xffff 57 58 /** 59 * @brief Bluetooth Host Error Code 60 * @defgroup bt_host_err Bluetooth Host Error Code 61 * 62 * Defines error codes returned by Bluetooth host. If error comes from specific 63 * component (eg L2CAP or Security Manager) it is shifted by base allowing to 64 * identify component. 65 * @{ 66 */ 67 68 #define BLE_HS_EAGAIN 1 69 #define BLE_HS_EALREADY 2 70 #define BLE_HS_EINVAL 3 71 #define BLE_HS_EMSGSIZE 4 72 #define BLE_HS_ENOENT 5 73 #define BLE_HS_ENOMEM 6 74 #define BLE_HS_ENOTCONN 7 75 #define BLE_HS_ENOTSUP 8 76 #define BLE_HS_EAPP 9 77 #define BLE_HS_EBADDATA 10 78 #define BLE_HS_EOS 11 79 #define BLE_HS_ECONTROLLER 12 80 #define BLE_HS_ETIMEOUT 13 81 #define BLE_HS_EDONE 14 82 #define BLE_HS_EBUSY 15 83 #define BLE_HS_EREJECT 16 84 #define BLE_HS_EUNKNOWN 17 85 #define BLE_HS_EROLE 18 86 #define BLE_HS_ETIMEOUT_HCI 19 87 #define BLE_HS_ENOMEM_EVT 20 88 #define BLE_HS_ENOADDR 21 89 #define BLE_HS_ENOTSYNCED 22 90 #define BLE_HS_EAUTHEN 23 91 #define BLE_HS_EAUTHOR 24 92 #define BLE_HS_EENCRYPT 25 93 #define BLE_HS_EENCRYPT_KEY_SZ 26 94 #define BLE_HS_ESTORE_CAP 27 95 #define BLE_HS_ESTORE_FAIL 28 96 #define BLE_HS_EPREEMPTED 29 97 #define BLE_HS_EDISABLED 30 98 99 /** Error base for ATT errors */ 100 #define BLE_HS_ERR_ATT_BASE 0x100 101 102 /** Converts error to ATT base */ 103 #define BLE_HS_ATT_ERR(x) ((x) ? BLE_HS_ERR_ATT_BASE + (x) : 0) 104 105 /** Error base for HCI errors */ 106 #define BLE_HS_ERR_HCI_BASE 0x200 107 108 /** Converts error to HCI base */ 109 #define BLE_HS_HCI_ERR(x) ((x) ? BLE_HS_ERR_HCI_BASE + (x) : 0) 110 111 /** Error base for L2CAP errors */ 112 #define BLE_HS_ERR_L2C_BASE 0x300 113 114 /** Converts error to L2CAP base */ 115 #define BLE_HS_L2C_ERR(x) ((x) ? BLE_HS_ERR_L2C_BASE + (x) : 0) 116 117 /** Error base for local Security Manager errors */ 118 #define BLE_HS_ERR_SM_US_BASE 0x400 119 120 /** Converts error to local Security Manager base */ 121 #define BLE_HS_SM_US_ERR(x) ((x) ? BLE_HS_ERR_SM_US_BASE + (x) : 0) 122 123 /** Error base for remote (peer) Security Manager errors */ 124 #define BLE_HS_ERR_SM_PEER_BASE 0x500 125 126 /** Converts error to remote (peer) Security Manager base */ 127 #define BLE_HS_SM_PEER_ERR(x) ((x) ? BLE_HS_ERR_SM_PEER_BASE + (x) : 0) 128 129 /** Error base for hardware errors */ 130 #define BLE_HS_ERR_HW_BASE 0x600 131 132 /** Converts error to hardware error base */ 133 #define BLE_HS_HW_ERR(x) (BLE_HS_ERR_HW_BASE + (x)) 134 135 /** 136 * @} 137 */ 138 139 /** 140 * @brief Bluetooth Host Configuration 141 * @defgroup bt_host_conf Bluetooth Host Configuration 142 * 143 * @{ 144 */ 145 146 /** 147 * @brief Local Input-Output capabilities of device 148 * @defgroup bt_host_io_local Local Input-Output capabilities of device 149 * 150 * @{ 151 */ 152 153 /** DisplayOnly IO capability */ 154 #define BLE_HS_IO_DISPLAY_ONLY 0x00 155 156 /** DisplayYesNo IO capability */ 157 #define BLE_HS_IO_DISPLAY_YESNO 0x01 158 159 /** KeyboardOnly IO capability */ 160 #define BLE_HS_IO_KEYBOARD_ONLY 0x02 161 162 /** NoInputNoOutput IO capability */ 163 #define BLE_HS_IO_NO_INPUT_OUTPUT 0x03 164 165 /** KeyboardDisplay Only IO capability */ 166 #define BLE_HS_IO_KEYBOARD_DISPLAY 0x04 167 168 /** 169 * @} 170 */ 171 172 /** @brief Stack reset callback 173 * 174 * @param reason Reason code for reset 175 */ 176 typedef void ble_hs_reset_fn(int reason); 177 178 179 /** @brief Stack sync callback */ 180 typedef void ble_hs_sync_fn(void); 181 182 /** @brief Bluetooth Host main configuration structure 183 * 184 * Those can be used by application to configure stack. 185 * 186 * The only reason Security Manager (sm_ members) is configurable at runtime is 187 * to simplify security testing. Defaults for those are configured by selecting 188 * proper options in application's syscfg. 189 */ 190 struct ble_hs_cfg { 191 /** 192 * An optional callback that gets executed upon registration of each GATT 193 * resource (service, characteristic, or descriptor). 194 */ 195 ble_gatt_register_fn *gatts_register_cb; 196 197 /** 198 * An optional argument that gets passed to the GATT registration 199 * callback. 200 */ 201 void *gatts_register_arg; 202 203 /** Security Manager Local Input Output Capabilities */ 204 uint8_t sm_io_cap; 205 206 /** @brief Security Manager OOB flag 207 * 208 * If set proper flag in Pairing Request/Response will be set. 209 */ 210 unsigned sm_oob_data_flag:1; 211 212 /** @brief Security Manager Bond flag 213 * 214 * If set proper flag in Pairing Request/Response will be set. This results 215 * in storing keys distributed during bonding. 216 */ 217 unsigned sm_bonding:1; 218 219 /** @brief Security Manager MITM flag 220 * 221 * If set proper flag in Pairing Request/Response will be set. This results 222 * in requiring Man-In-The-Middle protection when pairing. 223 */ 224 unsigned sm_mitm:1; 225 226 /** @brief Security Manager Secure Connections flag 227 * 228 * If set proper flag in Pairing Request/Response will be set. This results 229 * in using LE Secure Connections for pairing if also supported by remote 230 * device. Fallback to legacy pairing if not supported by remote. 231 */ 232 unsigned sm_sc:1; 233 234 /** @brief Security Manager Key Press Notification flag 235 * 236 * Currently unsupported and should not be set. 237 */ 238 unsigned sm_keypress:1; 239 240 /** @brief Security Manager Local Key Distribution Mask */ 241 uint8_t sm_our_key_dist; 242 243 /** @brief Security Manager Remote Key Distribution Mask */ 244 uint8_t sm_their_key_dist; 245 246 /** @brief Stack reset callback 247 * 248 * This callback is executed when the host resets itself and the controller 249 * due to fatal error. 250 */ 251 ble_hs_reset_fn *reset_cb; 252 253 /** @brief Stack sync callback 254 * 255 * This callback is executed when the host and controller become synced. 256 * This happens at startup and after a reset. 257 */ 258 ble_hs_sync_fn *sync_cb; 259 260 /* XXX: These need to go away. Instead, the nimble host package should 261 * require the host-store API (not yet implemented).. 262 */ 263 /** Storage Read callback handles read of security material */ 264 ble_store_read_fn *store_read_cb; 265 266 /** Storage Write callback handles write of security material */ 267 ble_store_write_fn *store_write_cb; 268 269 /** Storage Delete callback handles deletion of security material */ 270 ble_store_delete_fn *store_delete_cb; 271 272 /** @brief Storage Status callback. 273 * 274 * This callback gets executed when a persistence operation cannot be 275 * performed or a persistence failure is imminent. For example, if is 276 * insufficient storage capacity for a record to be persisted, this 277 * function gets called to give the application the opportunity to make 278 * room. 279 */ 280 ble_store_status_fn *store_status_cb; 281 282 /** An optional argument that gets passed to the storage status callback. */ 283 void *store_status_arg; 284 }; 285 286 extern struct ble_hs_cfg ble_hs_cfg; 287 288 /** 289 * @} 290 */ 291 292 /** 293 * @brief Indicates whether the host is enabled. The host is enabled if it is 294 * starting or fully started. It is disabled if it is stopping or stopped. 295 * 296 * @return 1 if the host is enabled; 297 * 0 if the host is disabled. 298 */ 299 int ble_hs_is_enabled(void); 300 301 /** 302 * Indicates whether the host has synchronized with the controller. 303 * Synchronization must occur before any host procedures can be performed. 304 * 305 * @return 1 if the host and controller are in sync; 306 * 0 if the host and controller are out of sync. 307 */ 308 int ble_hs_synced(void); 309 310 /** 311 * Synchronizes the host with the controller by sending a sequence of HCI 312 * commands. This function must be called before any other host functionality 313 * is used, but it must be called after both the host and controller are 314 * initialized. Typically, the host-parent-task calls this function at the top 315 * of its task routine. This function must only be called in the host parent 316 * task. A safe alternative for starting the stack from any task is to call 317 * `ble_hs_sched_start()`. 318 * 319 * If the host fails to synchronize with the controller (if the controller is 320 * not fully booted, for example), the host will attempt to resynchronize every 321 * 100 ms. For this reason, an error return code is not necessarily fatal. 322 * 323 * @return 0 on success; nonzero on error. 324 */ 325 int ble_hs_start(void); 326 327 /** 328 * Enqueues a host start event to the default event queue. The actual host 329 * startup is performed in the host parent task, but using the default queue 330 * here ensures the event won't run until the end of main() when this is 331 * called during system initialization. This allows the application to 332 * configure the host package in the meantime. 333 * 334 * If auto-start is disabled, the application should use this function to start 335 * the BLE stack. This function can be called at any time as long as the host 336 * is stopped. When the host successfully starts, the application is notified 337 * via the ble_hs_cfg.sync_cb callback. 338 */ 339 void ble_hs_sched_start(void); 340 341 /** 342 * Causes the host to reset the NimBLE stack as soon as possible. The 343 * application is notified when the reset occurs via the host reset callback. 344 * 345 * @param reason The host error code that gets passed to the reset callback. 346 */ 347 void ble_hs_sched_reset(int reason); 348 349 /** 350 * Designates the specified event queue for NimBLE host work. By default, the 351 * host uses the default event queue and runs in the main task. This function 352 * is useful if you want the host to run in a different task. 353 * 354 * @param evq The event queue to use for host work. 355 */ 356 void ble_hs_evq_set(struct ble_npl_eventq *evq); 357 358 /** 359 * Initializes the NimBLE host. This function must be called before the OS is 360 * started. The NimBLE stack requires an application task to function. One 361 * application task in particular is designated as the "host parent task". In 362 * addition to application-specific work, the host parent task does work for 363 * NimBLE by processing events generated by the host. 364 */ 365 void ble_hs_init(void); 366 367 /** 368 * @brief Called when the system is shutting down. Stops the BLE host. 369 * 370 * @param reason The reason for the shutdown. One of the 371 * HAL_RESET_[...] codes or an 372 * implementation-defined value. 373 * 374 * @return SYSDOWN_IN_PROGRESS. 375 */ 376 int ble_hs_shutdown(int reason); 377 378 #ifdef __cplusplus 379 } 380 #endif 381 382 /** 383 * @} 384 */ 385 386 #endif 387