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