1 /******************************************************************************* 2 * \file cy_ble_stack.h 3 * \version 3.60 4 * 5 * \brief 6 * This file contains the BLE Stack, which will be updated on the Jenkins 7 * build and the common structures, APIs. 8 * 9 ******************************************************************************* 10 * Copyright 2017-2021, Cypress Semiconductor Corporation. All rights reserved. 11 * You may use this file only in accordance with the license, terms, conditions, 12 * disclaimers, and limitations in the end user license agreement accompanying 13 * the software package with which this file was provided. 14 ******************************************************************************/ 15 16 #ifndef CY_BLE_STACK_H_ 17 #define CY_BLE_STACK_H_ 18 19 /*************************************** 20 * Common stack includes 21 ***************************************/ 22 #ifdef CY_PSOC_CREATOR_USED 23 #include "syslib/cy_syslib.h" 24 #else 25 #include "cy_syslib.h" 26 #endif /* CY_PSOC_CREATOR_USED */ 27 28 /* C binding of definitions if building with C++ compiler */ 29 #ifdef __cplusplus 30 extern "C" { 31 #endif /* __cplusplus */ 32 33 /*************************************** 34 ** Constants 35 ***************************************/ 36 37 /** BLE Stack Build Version Constants - It will be updated by Jenkins during build.*/ 38 39 /** Major version number for device firmware. */ 40 #define CY_BLE_STACK_MAJOR (5u) 41 42 /** Minor version number for device firmware. */ 43 #define CY_BLE_STACK_MINOR (0u) 44 45 /** Patch version number for device firmware. */ 46 #define CY_BLE_STACK_PATCH (10u) 47 48 /** Firmware build number. */ 49 #define CY_BLE_STACK_BUILD (365u) 50 51 /** BT Address Size */ 52 #define CY_BLE_BD_ADDR_SIZE (0x06u) 53 54 /** BLE Component ID */ 55 #define CY_BLE_ID (0x05ul << 18u) 56 57 /** Memory pool configuration data defines*/ 58 59 /** Size of internal data buffer structures */ 60 #define CY_BLE_STACK_BUFFER_MGR_UTIL_RAM_SZ (0x1Cu) 61 62 /** Memory extension offset */ 63 #define CY_BLE_MEM_EXT_SZ (0x08u) 64 65 /** Feature mask for 4.2 features */ 66 /** DLE feature */ 67 #define CY_BLE_DLE_FEATURE_MASK (0x01u) 68 /** Privacy 1.2 feature */ 69 #define CY_BLE_PRIVACY_1_2_FEATURE_MASK (0x02u) 70 /** Secured connection feature */ 71 #define CY_BLE_SECURE_CONN_FEATURE_MASK (0x04u) 72 73 /** Feature mask for Shanghai features */ 74 #define CY_BLE_PHY_UPDATE_FEATURE_MASK (0x08u) 75 76 /** Feature mask for persistent Store */ 77 /** Bonded Devices List */ 78 #define CY_BLE_PERSISTENT_STORE_BONDLIST (0x10u) 79 /** Resolving List */ 80 #define CY_BLE_PERSISTENT_STORE_RESOLVING_LIST (0x20u) 81 /** White List */ 82 #define CY_BLE_PERSISTENT_STORE_WHITELIST (0x40u) 83 /** Radio power calibration*/ 84 #define CY_BLE_PERSISTENT_RADIO_CALIBRATION_MASK (0x80u) 85 86 /** Feature mask bit-mask */ 87 #define CY_BLE_FEATURE_BIT_MASK (0x0FFu) 88 89 /** Default RPA List Entry Size */ 90 #define CY_BLE_DEFAULT_RPA_LIST_SZ (0x10u) 91 92 /** Default Bonded Devices List entry size */ 93 #define CY_BLE_DEFAULT_BONDED_DEVICE_LIST_SZ (0x10u) 94 95 /** Resolving List memory computation 96 * CY_BLE_MAX_RESOLVABLE_DEVICES: 97 * It is user configured value for size of Resolving List using BLE PDL. 98 * Range: 1 to 16, 0 if Privacy 1.2 feature is not used. 99 * Memory required = 100 * (((CY_BLE_LL_PRIVACY_HEAP_REQ * CY_BLE_MAX_RESOLVABLE_DEVICES) + 101 CY_BLE_LL_PRIVACY_RETENTION_HEAP_REQ) 102 * Note: 103 * This configurable memory should be added to 104 * CY_BLE_CONTROLLER_DEVICE_SPECIFIC_HEAP_REQ 105 * static macro value passed to BLE Stack. 106 */ 107 108 /** Internal RAM required for Resolving List retention data 109 * structure 110 */ 111 #define CY_BLE_LL_PRIVACY_RETENTION_HEAP_REQ (0x0Cu) 112 113 /** Internal RAM required for single Resolving List entry 114 */ 115 #define CY_BLE_LL_PRIVACY_HEAP_REQ (0x44u) 116 117 /** White List list memory computation 118 * CY_BLE_MAX_WHITELIST_LIST_SZ: 119 * It is a user-configured value for the size of the White List using the BLE PDL. 120 * Range: 1 to 16. 121 * Memory required = 122 * (((CY_BLE_LL_ONE_WHITELIST_HEAP_REQ * CY_BLE_MAX_WHITELIST_LIST_SZ) + 123 CY_BLE_LL_WHITELIST_RETENTION_HEAP_REQ) 124 * Note: 125 * This configurable memory should be added to 126 * the CY_BLE_CONTROLLER_DEVICE_SPECIFIC_HEAP_REQ 127 * static macro value passed to the BLE Stack. 128 */ 129 130 /** Max WhiteList size that is supported by BLE Stack */ 131 #define CY_BLE_MAX_WHITELIST_LIST_SZ (0x10u) 132 133 /** LL White List retention heap requirement */ 134 #define CY_BLE_LL_WHITELIST_RETENTION_HEAP_REQ (0x08u) 135 136 /** LL White List size for one entity */ 137 #define CY_BLE_LL_ONE_WHITELIST_HEAP_REQ (0x08u) 138 139 /** Convert Octets to Bits. */ 140 #define CY_BLE_OCTETS_TO_BITS(octets) ((octets) << 3) 141 142 /** Convert LL Data Octets to Time in micro-seconds - 1Mbps */ 143 #define CY_BLE_DATA_OCTETS_TO_US_1MBPS(octets) (CY_BLE_OCTETS_TO_BITS((octets) + 14)) 144 /** Convert LL Data Octets to Time in micro-seconds - 2Mbps */ 145 #define CY_BLE_DATA_OCTETS_TO_US_2MBPS(octets) (CY_BLE_OCTETS_TO_BITS(((octets) + 15) >> 1)) 146 147 148 /** Total Command Buffers Chunks for Command Buffer Pool */ 149 #define CY_BLE_BT_FW_LE_CMD_BUFFERS (0x05u) 150 151 /** Event Buffer Pool 1 */ 152 #define CY_BLE_BT_FW_LE_EVENT_TYPE1_BUFFERS (0x01u) 153 154 /** Event Buffer Pool 2 */ 155 #define CY_BLE_BT_FW_LE_EVENT_TYPE2_BUFFERS (0x08u) 156 157 /** Per Connection LL Control PDU Size for Tx */ 158 #define CY_BLE_BT_FW_TX_LL_PDU_Q_SZ (0x02u) 159 160 /** Per Connection LL Control PDU Size for Rx */ 161 #define CY_BLE_BT_FW_RX_LL_PDU_Q_SZ (0x02u) 162 163 /** Firmware total LE pdu packets */ 164 #define CY_BLE_BT_FW_LE_TOTAL_PDU_PKTS (CY_BLE_BT_FW_TX_LL_PDU_Q_SZ + \ 165 CY_BLE_BT_FW_RX_LL_PDU_Q_SZ) 166 167 /** Encryption and Connection Parameter Update */ 168 #define CY_BLE_BT_FW_LE_TXN_BUFFERS (0x02u) 169 170 171 /** HCI Command Buffers per single Command Buffer Pool*/ 172 #define CY_BLE_HCI_LE_CMD_BUFFER_SZ (0x50u) 173 174 /** Event packet size 175 * Max size for HCI LE event is 64 bytes 176 * Total size = 2 * (64 + 4(Event Header) + 4) 177 */ 178 #define CY_BLE_HCI_LE_EVENT_BUFFER_POOL_TYPE1_SZ (0x48u) 179 180 /** Event buffer pool for rest of the LE single mode events.*/ 181 #define CY_BLE_HCI_LE_EVENT_BUFFER_POOL_TYPE2_SZ (0x30u) 182 183 /** 184 * LL Control PDU Buffer Size per connection 185 */ 186 #define CY_BLE_LL_PDU_MAX_BUFFER_SZ (0x20u) 187 188 /** LL transaction buffer size */ 189 #define CY_BLE_LL_LE_TXN_BUFFER_SZ (0x40u) 190 191 /** Memory pool item size*/ 192 #define CY_BLE_MEM_POOL_ITEM_SZ (0x04u) 193 194 /** BLE DLE device param size */ 195 #define CY_BLE_DLE_DEVICE_PARAM_SZ (0x10u) 196 197 /** Controller per-connection data struct heap size */ 198 #define CY_BLE_CONTROLLER_PER_CONN_DATA_STRUCT_HEAP_SZ (0x0110u) 199 200 /** Heap Reserve for Controller */ 201 #define CY_BLE_BT_FW_HEAP_RESERVE_REQ (0x80u) 202 203 /** Device Specific Pool Memory for BLESS RX FIFO, HCI Command and 204 * HCI Events memory 205 */ 206 #define CY_BLE_BT_FW_DEV_SPECIFIC_POOL_REQ (CY_BLE_BT_FW_RX_ACL_MEM_POOL_REQ + \ 207 CY_BLE_BT_FW_CMD_MEM_POOL_REQ + \ 208 CY_BLE_BT_FW_EVENT_MEM_POOL_REQ) 209 /** Device specific controller heap requirement */ 210 #define CY_BLE_CONTROLLER_DEVICE_SPECIFIC_HEAP_REQ \ 211 ((CY_BLE_BT_FW_LE_EVENT_TYPE1_BUFFERS * \ 212 (CY_BLE_HCI_LE_EVENT_BUFFER_POOL_TYPE1_SZ + CY_BLE_MEM_POOL_ITEM_SZ)) + \ 213 (CY_BLE_BT_FW_LE_EVENT_TYPE2_BUFFERS * \ 214 (CY_BLE_HCI_LE_EVENT_BUFFER_POOL_TYPE2_SZ + CY_BLE_MEM_POOL_ITEM_SZ)) + \ 215 (CY_BLE_BT_FW_LE_CMD_BUFFERS * \ 216 (CY_BLE_HCI_LE_CMD_BUFFER_SZ + CY_BLE_MEM_POOL_ITEM_SZ)) + \ 217 ((CY_BLE_STACK_BUFFER_MGR_UTIL_RAM_SZ * \ 218 CY_BLE_BT_FW_DEV_SPECIFIC_POOL_REQ) + \ 219 CY_BLE_BT_FW_HEAP_RESERVE_REQ)) 220 221 222 /** Configurable Memory for Stack Manager Buffer Pool Data Structures for 223 * buffer pools that are created and maintained. 224 */ 225 /** Tx acl memory requirement */ 226 #define CY_BLE_BT_FW_TX_ACL_MEM_POOL_REQ (0x01u) 227 /** Firmware pdu memory requirement */ 228 #define CY_BLE_BT_FW_PDU_MEM_POOL_REQ (0x02u) 229 /** Firmware transaction memory requirement */ 230 #define CY_BLE_BT_FW_TXN_MEM_POOL_REQ (0x01u) 231 232 /** Heap required to for buffer pools that are created per connection 233 * Formula for total pools: 234 * (4 <Tx, Tx LL, Rx LL, LL Transaction Pool> * no. of connections) 235 */ 236 #define CY_BLE_BT_FW_CONN_SPECIFIC_POOL_REQ (CY_BLE_BT_FW_TX_ACL_MEM_POOL_REQ + \ 237 CY_BLE_BT_FW_PDU_MEM_POOL_REQ + \ 238 CY_BLE_BT_FW_TXN_MEM_POOL_REQ) 239 /** Controller connection specific heap requirement */ 240 #define CY_BLE_CONTROLLER_CONN_SPECIFIC_HEAP_REQ \ 241 ((CY_BLE_BT_FW_LE_TOTAL_PDU_PKTS * \ 242 (CY_BLE_LL_PDU_MAX_BUFFER_SZ + CY_BLE_MEM_POOL_ITEM_SZ)) + \ 243 (CY_BLE_BT_FW_LE_TXN_BUFFERS * \ 244 (CY_BLE_LL_LE_TXN_BUFFER_SZ + CY_BLE_MEM_POOL_ITEM_SZ)) + \ 245 (CY_BLE_BT_FW_CONN_SPECIFIC_POOL_REQ * \ 246 CY_BLE_STACK_BUFFER_MGR_UTIL_RAM_SZ) + \ 247 (CY_BLE_CONTROLLER_PER_CONN_DATA_STRUCT_HEAP_SZ)) 248 249 /** Rx acl memory requirement */ 250 #define CY_BLE_BT_FW_RX_ACL_MEM_POOL_REQ (0x01u) 251 /** Firmware command memory requirement */ 252 #define CY_BLE_BT_FW_CMD_MEM_POOL_REQ (0x01u) 253 /** Firmware event memory requirement */ 254 #define CY_BLE_BT_FW_EVENT_MEM_POOL_REQ (0x02u) 255 256 /** Size of the heap when the BLE Stack is built in HCI mode */ 257 #define CY_BLE_DEFAULT_CONTROLLER_RAM_SIZE (0u) 258 259 /** Default Max ACL Packet Size for LE-DATA packet both for */ 260 #define CY_BLE_LL_DEFAULT_MAX_SUPPORTED_ACL_BUFFER_SZ (0xFCu) 261 262 /** Default Max ACL Packet Size for Rx LE-DATA Packet 263 * Formula: Default ACL Size (27 bytes) ~ AlignToWord(27) = 28 264 */ 265 #define CY_BLE_LL_DEFAULT_ACL_MAX_RX_BUFFER_SZ (0x1Cu) 266 267 /** 8 Additional Bytes = (4 bytes of MIC + 4 bytes of HCI header) */ 268 #define CY_BLE_LL_ACL_DATA_PACKET_OVERHEAD_SZ (0x08u) 269 270 /** Number of Rx ACL Packet buffers, this shall not change 271 * as this should not be user configurable parameter 272 */ 273 #define CY_BLE_LL_DEFAULT_NUM_ACL_RX_PACKETS (0x04u) 274 275 /** Number of Tx ACL Packet buffers */ 276 #define CY_BLE_LL_DEFAULT_NUM_ACL_TX_PACKETS (0x03u) 277 278 /** Default Tx capability. If DLE is not enabled, this is Tx capability*/ 279 #define CY_BLE_LL_DEFAULT_TX_CAPABILITY (0x1Bu) 280 281 /** Default Rx capability. If DLE is not enabled, this is Rx capability*/ 282 #define CY_BLE_LL_DEFAULT_RX_CAPABILITY (0x1Bu) 283 284 /** Default Tx capability. If DLE is not enabled, this is Tx capability*/ 285 #define CY_BLE_MAX_DEFAULT_TX_CAPABILITY (0xFBu) 286 287 /** Default Rx capability. If DLE is not enabled, this is Rx capability*/ 288 #define CY_BLE_MAX_DEFAULT_RX_CAPABILITY (0xFBu) 289 290 /** Internal heap required for LE Data Length Extension Feature Per 291 * Connection 292 */ 293 #define CY_BLE_LL_DLE_HEAP_REQ (0x40u) 294 295 /** DLE heap required for device specific parameters */ 296 #define CY_BLE_LL_DLE_DEVICE_PARAM_HEAP_REQ (0x10u) 297 298 /** Default RPA List Entry Size */ 299 #define CY_BLE_MAX_RPA_LIST_SZ (0x10u) 300 301 /** IPC pipe client IDs for BLE */ 302 #define CY_BLE_PIPE_BLE_MSG_COMPLETE_ID (0u) /**< msg complete */ 303 #define CY_BLE_PIPE_BLE_MSG_SEND_ID (1u) /**< msg send */ 304 305 /** Mask to disable all events */ 306 #define CY_BLE_DISABLE_ALL_EVENTS_MASK (0x00u) 307 308 /** Mask to Enable connection established events */ 309 #define CY_BLE_CONN_ESTB_EVENT_MASK (0x01u) 310 311 /** Mask to Enable advertisement packet sent events */ 312 #define CY_BLE_ADV_TX_EVENT_MASK (0x02u) 313 314 /** Length of mask byte array */ 315 #define CY_BLE_EVENT_MASK_LENGTH (1u) 316 317 /** Event Mask index 0 */ 318 #define CY_BLE_EVENT_MASK_INDEX_0 (0u) 319 320 /** Number of configurable Radio PA Lobuff parameters */ 321 #define CY_BLE_MXD_PA_NUM_LOBUFF_VALS (4u) 322 323 /** Number of configurable Radio PA Target parameters */ 324 #define CY_BLE_MXD_PA_NUM_TARGET_VALS (7u) 325 326 /** Number of configurable Radio PA LDO parameters */ 327 #define CY_BLE_MXD_PA_NUM_LDO_SETTINGS (4u) 328 329 /*************************************** 330 ** Enumerated Types 331 ***************************************/ 332 333 /** 334 \addtogroup group_ble_common_api_events 335 @{ 336 */ 337 338 /** BLE stack events */ 339 typedef enum 340 { 341 /** This event is triggered by the BLE stack when the BLE Stack is in a bad state. Restarting the BLE Stack is the 342 * only way to get out of this state 343 */ 344 CY_BLE_EVT_INVALID = 0x0000u, 345 346 /* Range for Generic events - 0x1000 to 0x1FFF */ 347 348 /** This event is received when the BLE stack is initialized and turned ON by invoking the Cy_BLE_StackInit() function.*/ 349 CY_BLE_EVT_STACK_ON = 0x1000u, 350 351 /** This event is received when there is a timeout and the application must handle the event. 352 * Event parameter is of type 'cy_stc_ble_timeout_param_t'. 353 * - If reasonCode is 'CY_BLE_GATT_RSP_TO', then look for connHandle. 354 * - If reasonCode is 'CY_BLE_GENERIC_APP_TO', then look for timerHandle. 355 * - For all other cases connHandle or timerHandle is ignored 356 */ 357 CY_BLE_EVT_TIMEOUT, /* 0x1001u */ 358 359 /** This event is triggered by BLE Stack to indicate if the BLE stack is busy or not. 360 * The Event Parameter corresponding to this event will indicate the state of BLE stack's internal protocol buffers 361 * for the application to safely initiate data transactions (GATT, GAP Security, and L2CAP transactions) 362 * with the peer BLE device. 363 * Event parameter is of type cy_stc_ble_l2cap_state_info_t. 364 * cy_stc_ble_l2cap_state_info_t contains flowState and Bd handle as parameters 365 * flowState indicates the following state: 366 * CY_BLE_STACK_STATE_BUSY (0x01) = CY_BLE_STACK_STATE_BUSY indicates to the application that the BLE Stack's internal buffers 367 * are about to be filled, and the remaining buffers are required to respond to the peer BLE device. 368 * After this event, the application shall not initiate GATT, GAP Security, or L2CAP data transactions. 369 * However, the application shall respond to peer initiated transactions to prevent BLE protocol timeouts. 370 * Application initiated data transactions can be resumed after the CY_BLE_EVT_STACK_BUSY_STATUS event with 371 * parameter 'CY_BLE_STACK_STATE_FREE' is received. 372 * 373 * CY_BLE_STACK_STATE_FREE (0x00) = CY_BLE_STACK_STATE_FREE indicates to the application that pending transactions are completed 374 * and sufficient buffers are available to process application-initiated transactions. 375 * The 'CY_BLE_EVT_STACK_BUSY_STATUS' event with 'CY_BLE_STACK_STATE_FREE' indicates to the 376 * application whether the BLE Stack's internal buffer state has transitioned from 'CY_BLE_STACK_STATE_BUSY' 377 * to 'CY_BLE_STACK_STATE_FREE'. 378 * 379 * Bd handle indicates connection. 380 * To increase the BLE Stack's default queue depth(CY_BLE_L2CAP_STACK_Q_DEPTH_PER_CONN) and achieve better throughput for the attribute MTU greater than 32, 381 * use the AddQdepthPerConn parameter in the 'Expression View' of the Advanced tab in the BLE component GUI. To Access the 'Expression View', right click on 382 * the 'Advanced' tab in th BLE Component GUI and select the 'Show Expression View' option. 383 */ 384 CY_BLE_EVT_STACK_BUSY_STATUS, /* 0x1002u */ 385 386 /** This event is received when the BLE Stack wants the application to provide memory to process a remote request. 387 * The event parameter is of type cy_stc_ble_memory_request_t. 388 * This event is automatically handled by the BLE Component for the CY_BLE_PREPARED_WRITE_REQUEST request. 389 * The BLE Component allocates sufficient memory for the long write request with the assumption that attribute MTU size 390 * is negotiated to the minimum possible value. The application could use dynamic memory allocation to save static 391 * RAM memory consumption. To enable this event for the application level, set the EnableExternalPrepWriteBuff parameter 392 * in the Expression view of the Advanced tab to be true. 393 */ 394 CY_BLE_EVT_MEMORY_REQUEST, /* 0x1003u */ 395 396 /** This event is used to inform the application that a Flash write is pending. 397 * This event is generated by the BLE Stack whenever its internal data structures 398 * are modified and require back up. 399 */ 400 CY_BLE_EVT_PENDING_FLASH_WRITE, /* 0x1004u */ 401 402 /** This event is used to inform the application that persistent data stored in Flash memory is corrupted */ 403 CY_BLE_EVT_FLASH_CORRUPT, /* 0x1005u */ 404 405 /* Range for HCI events - 0x2000 to 0x2FFF */ 406 407 /** This event indicates that some internal hardware error has occurred. 408 * Reset of the hardware may be required. 409 * Event parameter returned with this event is of (uint8 *) type. The possible error codes for this event are defined 410 * in cy_ble_stack_host_error.h file. 411 */ 412 CY_BLE_EVT_HARDWARE_ERROR = 0x2000, 413 414 /** This event is triggered on successful setting of Authentication Payload timeout in the BLE Stack for 415 * LE_PING feature. Refer to Bluetooth 4.1 core specification, Volume 6, Part B, 416 * section 4.6.5 for LE Ping operation. 417 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 418 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 419 * eventParams must be cast to (uint8_t *) to access the pointer to the bdHandle corresponding to this event. 420 * eventParams is valid only if status is success (0x00) 421 */ 422 CY_BLE_EVT_WRITE_AUTH_PAYLOAD_TO_COMPLETE, /* 0x2001u */ 423 424 /** This event carries Authentication Payload timeout in the BLE Stack for the LE_PING feature. 425 * Refer to Bluetooth 4.1 core specification, Volume 6, Part B, section 4.6.5 for LE Ping operation. 426 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 427 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 428 * eventParams must be cast to (cy_stc_ble_auth_payload_info_t*) to access the authentication payload information. 429 * eventParams is valid only if status is success (0x00) 430 */ 431 CY_BLE_EVT_READ_AUTH_PAYLOAD_TO_COMPLETE, /* 0x2002u */ 432 433 /** This event indicates a channel map corresponding to one connection. 434 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 435 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 436 * eventParams must be cast to (cy_stc_ble_channel_map_info_t*) to access Channel Map Parameters Information. 437 * eventParams is valid only if status is success (0x00) 438 */ 439 CY_BLE_EVT_GET_CHANNEL_MAP_COMPLETE, /* 0x2003u */ 440 441 /** This event indicates completion of the Set LE event mask. 442 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 443 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 444 * eventParams must be ignored. 445 */ 446 CY_BLE_EVT_LE_SET_EVENT_MASK_COMPLETE, /* 0x2004u */ 447 448 /** This event indicates that the peer device has not responded 449 * with the valid MIC packet within the application configured ping authentication time. 450 */ 451 CY_BLE_EVT_LE_PING_AUTH_TIMEOUT, /* 0x2005u */ 452 453 /** This event indicates completion of the Set data length command. 454 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 455 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 456 * eventParams must be cast to (uint8_t *) to access the pointer to the bdHandle corresponding to this event. 457 * eventParams is valid only if status is success (0x00) 458 */ 459 CY_BLE_EVT_SET_DATA_LENGTH_COMPLETE, /* 0x2006u */ 460 461 /** This event indicates completion of Set suggested data length command. 462 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 463 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 464 * eventParams must be ignored. 465 */ 466 CY_BLE_EVT_SET_SUGGESTED_DATA_LENGTH_COMPLETE, /* 0x2007u */ 467 468 /** This event indicates completion of Cy_BLE_GetDataLength() function. 469 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 470 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 471 * eventParams must be cast to (cy_stc_ble_data_length_param_t*) to access the locally 472 * suggested tx/rx octets and tx/rx time and the maximum supported tx/rx octets and tx/rx time. 473 * eventParams is valid only if status is success (0x00) 474 */ 475 CY_BLE_EVT_GET_DATA_LENGTH_COMPLETE, /* 0x2008u */ 476 477 /** This event notifies the Host of a change to either the maximum Payload length or 478 * the maximum transmission time of Data Channel PDUs in either direction. The values reported are the maximum 479 * that will actually be used on the connection following the change. 480 * The event parameter is of type 'cy_stc_ble_data_length_change_event_param_t' 481 */ 482 CY_BLE_EVT_DATA_LENGTH_CHANGE, /* 0x2009u */ 483 484 /** This event indicates peer resolvable private address currently used by the BLE Stack. 485 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 486 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 487 * eventParams must be cast to (uint8_t*) to access the pointer to the peer resolvable address. 488 * eventParams is valid only if status is success (0x00) 489 */ 490 CY_BLE_EVT_GET_PEER_RPA_COMPLETE, /* 0x200Au */ 491 492 /** This event indicates local resolvable private address currently used by the BLE Stack. 493 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 494 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 495 * eventParams must be cast to (uint8_t*) to access the pointer to the local resolvable address. 496 * eventParams is valid only if status is success (0x00) 497 */ 498 CY_BLE_EVT_GET_LOCAL_RPA_COMPLETE, /* 0x200Bu */ 499 500 /** This event indicates completion of the Set RPA timeout command. 501 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 502 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 503 * eventParams must be ignored. 504 */ 505 CY_BLE_EVT_SET_RPA_TO_COMPLETE, /* 0x200Cu */ 506 507 /** This event indicates completion of Set RPA enable command. 508 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 509 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 510 * eventParams must be ignored. 511 */ 512 CY_BLE_EVT_SET_RPA_ENABLE_COMPLETE, /* 0x200Du */ 513 514 /** This event indicates completion of the Set host channel command. 515 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 516 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 517 * eventParams must be ignored. 518 */ 519 CY_BLE_EVT_SET_HOST_CHANNEL_COMPLETE, /* 0x200Eu */ 520 521 /** This event indicates completion of the add device to Resolving List command. 522 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 523 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 524 * eventParams must be ignored. 525 */ 526 CY_BLE_EVT_ADD_DEVICE_TO_RPA_LIST_COMPLETE, /* 0x200Fu */ 527 528 /** This event indicates completion of the remove device from Resolving List command. 529 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 530 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 531 * eventParams must be ignored. 532 */ 533 CY_BLE_EVT_REMOVE_DEVICE_FROM_RPA_LIST_COMPLETE, /* 0x2010u */ 534 535 /** This event indicates completion of the add device to White List command. 536 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 537 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 538 * eventParams must be ignored. 539 */ 540 CY_BLE_EVT_ADD_DEVICE_TO_WHITE_LIST_COMPLETE, /* 0x2011u */ 541 542 /** This event indicates completion of the remove device from the White List command. 543 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 544 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 545 * eventParams must be ignored. 546 */ 547 CY_BLE_EVT_REMOVE_DEVICE_FROM_WHITE_LIST_COMPLETE, /* 0x2012u */ 548 549 /** This event indicates completion of the Cy_BLE_GetPhy() function. 550 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 551 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 552 * eventParams must be cast to (cy_stc_ble_phy_param_t*) type to access the TX and RX PHY Mask as well as the 553 * bdHandle corresponding to the connection for which this information is being returned. 554 * eventParams is valid only if status is success(0x00) 555 */ 556 CY_BLE_EVT_GET_PHY_COMPLETE, /* 0x2013u */ 557 558 /** This event indicates completion of the Cy_BLE_SetDefaultPhy() function. 559 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 560 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 561 * eventParams must be ignored. 562 */ 563 CY_BLE_EVT_SET_DEFAULT_PHY_COMPLETE, /* 0x2014u */ 564 565 /** This event indicates completion of the Cy_BLE_SetPhy() function. 566 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 567 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 568 * eventParams must be ignored. 569 */ 570 CY_BLE_EVT_SET_PHY_COMPLETE, /* 0x2015u */ 571 572 /** This event indicates that the Controller has changed the transmitter PHY or receiver PHY in use. 573 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 574 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 575 * eventParams must be cast to (cy_stc_ble_phy_param_t*) type to access the TX and RX PHY Mask as well as the 576 * bdHandle corresponding to the connection for which this information is being returned. 577 * eventParams is valid only if status is success(0x00) 578 */ 579 CY_BLE_EVT_PHY_UPDATE_COMPLETE, /* 0x2016u */ 580 581 /** This event indicates completion of the set privacy mode command. 582 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 583 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 584 * eventParams must be ignored. 585 */ 586 CY_BLE_EVT_SET_PRIVACY_MODE_COMPLETE, /* 0x2017u */ 587 588 /* Range for vendor events - 0x3000 to 0x3FFF */ 589 590 /** This event indicates completion of the Cy_BLE_IsLlControlProcPending() function. 591 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 592 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 593 * eventParams must be cast to (cy_stc_ble_ll_cntrl_proc_param_t*) type to access the status of the 594 * control procedure (cntrlProcStatus) as well as the bdHandle corresponding to the connection 595 * for which this information is being returned. 596 * eventParams is valid only if status is success(0x00) 597 */ 598 CY_BLE_EVT_LL_CNTRL_PROC_PENDING_COMPLETE = 0x3000u, 599 600 /** This event indicates a soft reset completed successfully. 601 * The event parameter is NULL. 602 */ 603 CY_BLE_EVT_SOFT_RESET_COMPLETE, /* 0x3001u */ 604 605 /** This event indicates that the set device address command has completed. 606 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 607 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 608 * eventParams must be ignored. 609 */ 610 CY_BLE_EVT_SET_DEVICE_ADDR_COMPLETE, /* 0x3002u */ 611 612 /** This event indicates that the get device address command has completed. 613 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 614 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 615 * eventParams must be cast to (cy_stc_ble_bd_addrs_t*) type to access the public and private 616 * Bluetooth Device Addresses. 617 * eventParams is valid only if status is success(0x00) 618 */ 619 CY_BLE_EVT_GET_DEVICE_ADDR_COMPLETE, /* 0x3003u */ 620 621 /** This event indicates that the get RSSI command has completed. 622 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 623 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 624 * eventParams must be cast to (cy_stc_ble_rssi_info_t*) type to access the RSSI value as well as the 625 * bdHandle corresponding to the connection for which this information is being returned. 626 * eventParams is valid only if status is success(0x00) 627 */ 628 CY_BLE_EVT_GET_RSSI_COMPLETE, /* 0x3004u */ 629 630 /** This event indicates that the get Tx Power command has completed. 631 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 632 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 633 * eventParams must be cast to (cy_stc_ble_tx_pwr_lvl_info_t*) type to access the TX power level 634 * eventParams is valid only if status is success (0x00) 635 * bdHandle is valid only if bleSsChId is CY_BLE_LL_CONN_CH_TYPE 636 */ 637 CY_BLE_EVT_GET_TX_PWR_COMPLETE, /* 0x3005u */ 638 639 /** This event indicates that the set Tx Power command has completed . 640 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 641 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 642 * eventParams must be cast to (cy_stc_ble_tx_pwr_config_param_t*) type to access the powerConfig. 643 * eventParams is valid only if status is success (0x00) 644 */ 645 CY_BLE_EVT_SET_TX_PWR_COMPLETE, /* 0x3006u */ 646 647 /** This event indicates that the get clock config command has completed. 648 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 649 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 650 * eventParams must be cast to (cy_stc_ble_bless_clk_cfg_params_t*) type to access the BLE clock 651 * configuration parameters. 652 * eventParams is valid only if status is success(0x00) 653 */ 654 CY_BLE_EVT_GET_CLK_CONFIG_COMPLETE, /* 0x3007u */ 655 656 /** This event indicates that the set clock config command has completed. 657 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 658 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 659 * eventParams must be ignored. 660 */ 661 CY_BLE_EVT_SET_CLK_CONFIG_COMPLETE, /* 0x3008u */ 662 663 /** This event indicates that the random number generation command has completed successfully. 664 * The event parameter is Pointer to a buffer of size 8 bytes 665 */ 666 CY_BLE_EVT_RANDOM_NUM_GEN_COMPLETE, /* 0x3009u */ 667 668 /** This event indicates that the AES encrypt command has completed. 669 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 670 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 671 * eventParams must be cast to (uint8_t*) to access the pointer to the encrypted data (128-bit). 672 * eventParams is valid only if status is success(0x00) 673 */ 674 CY_BLE_EVT_AES_ENCRYPT_COMPLETE, /* 0x300Au */ 675 676 /** This event indicates that the AES CCM encrypt command has completed. 677 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 678 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 679 * eventParams must be cast to (cy_stc_ble_aes_ccm_param_t*) type to access the AES CCM encrypted 680 * data information. 681 * eventParams is valid only if status is success(0x00) 682 */ 683 CY_BLE_EVT_AES_CCM_ENCRYPT_COMPLETE, /* 0x300Bu */ 684 685 /** This event indicates that the AES CCM decrypt command has completed. 686 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 687 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 688 * eventParams must be cast to (cy_stc_ble_aes_ccm_param_t*) type to access the AES CCM decrypted 689 * data information. 690 * eventParams is valid only if status is success(0x00).eventParams->mic to be ignored. 691 */ 692 CY_BLE_EVT_AES_CCM_DECRYPT_COMPLETE, /* 0x300Cu */ 693 694 /* 0x300Du -> Reserved for future*/ 695 696 /* 0x300Eu -> Reserved for future*/ 697 698 /* 0x300Fu -> Reserved for future*/ 699 700 /* 0x3010u -> Reserved for future*/ 701 702 /** This event is triggered for Cy_BLE_SetSlaveLatencyMode() function. 703 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 704 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 705 * eventParams must be cast to (uint8_t *) to access the pointer to the bdHandle corresponding to this event. 706 * eventParams is valid only if status is success(0x00) 707 */ 708 CY_BLE_EVT_SET_SLAVE_LATENCY_MODE_COMPLETE = 0x3011u, /* 0x3011u */ 709 710 /** This event is used to inform the application that BLE Stack Shutdown is complete. However, the application shall 711 * wait for at least 10ms, before calling the Cy_BLE_Start() API, after receiving this event. 712 * The event parameter returned along with this event is NULL. 713 */ 714 CY_BLE_EVT_STACK_SHUTDOWN_COMPLETE, /* 0x3012u */ 715 716 /** This event is used to inform the application of temperature data as measured. Event parameter is of 717 * (cy_stc_ble_events_param_generic_t*) type. There are two members of the structure pointed to by 718 * the event parameter: status (uint8_t) and eventParams (void *). eventParams must be cast to 719 * (uint16_t *) to access the pointer to the radio temparature level in degree Celsius. 720 */ 721 CY_BLE_EVT_RADIO_TEMPERATURE, /* 0x3013u */ 722 723 /** This event is used to inform the application of voltage data as measured. Event parameter is of 724 * (cy_stc_ble_events_param_generic_t*) type. There are two members of the structure pointed to by 725 * the event parameter: status (uint8_t) and eventParams (void *). eventParams must be cast to 726 * (uint16_t *) to access the pointer to the radio voltage level in mV. 727 */ 728 CY_BLE_EVT_RADIO_VOLTAGE_LEVEL, /* 0x3014u */ 729 730 /** This event is used to inform the application that the AES CMAC generation is completed 731 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 732 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 733 * eventParams must be ignored. 734 */ 735 CY_BLE_EVT_AES_CMAC_GEN_COMPLETE, /* 0x3015 */ 736 737 /** This event is triggered on completion of setting vendor event mask. 738 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 739 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 740 * status is valid, eventParams must be ignored 741 */ 742 CY_BLE_EVT_SET_EVENT_MASK_COMPLETE, /* 0x3016u */ 743 744 /** This event is triggered on completion of setting vendor event mask. 745 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 746 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 747 * eventParams must be cast to (uint8_t *) to access the pointer to the bdHandle corresponding to this event. 748 * eventParams is valid only if status is success(0x00) 749 */ 750 CY_BLE_EVT_SET_CE_LENGTH_COMPLETE, /* 0x3017u */ 751 752 /** This event is triggered on completion of setting vendor event mask. 753 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 754 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 755 * eventParams must be cast to (uint8_t *) to access the pointer to the bdHandle corresponding to this event. 756 * eventParams is valid only if status is success(0x00) 757 */ 758 CY_BLE_EVT_SET_CONN_PRIORITY_COMPLETE, /* 0x3018u */ 759 760 /** This event is used to inform application that an HCI event (or ACL packet) has been received 761 * from controller. Event parameter returned with this event is pointer to a parameter of 762 * type 'cy_stc_ble_hci_tx_packet_info_t'. This event will only be triggered when the application 763 * enables software transport mode for HCI by calling the Cy_BLE_SoftHciTransportEnable() API. 764 */ 765 CY_BLE_EVT_HCI_PKT_RCVD, /* 0x3019u */ 766 767 /* Range for GAP events - 0x4000 to 0x4FFF */ 768 769 /** This event is triggered every time a device is discovered. A pointer to structure of type 770 * cy_stc_ble_gapc_adv_report_param_t is returned as the event parameter. 771 */ 772 CY_BLE_EVT_GAPC_SCAN_PROGRESS_RESULT = 0x4000u, 773 774 /** This event can be received by a device in Peripheral or Central role. When it is received by a device in a 775 * Peripheral role, it must Call Cy_BLE_GAPP_AuthReqReply() to reply to the authentication request 776 * from Central. When this event is received by a device in a Central role, it means that the Peripheral 777 * has requested Central to initiate authentication procedure. The device must call Cy_BLE_GAP_AuthReq() 778 * to initiate the authentication procedure. 779 * A pointer to structure of type cy_stc_ble_gap_auth_info_t is returned as the event parameter. 780 */ 781 CY_BLE_EVT_GAP_AUTH_REQ, /* 0x4001u */ 782 783 /** This event indicates that the device must send a passkey to be used during the pairing procedure. 784 * Cy_BLE_GAP_AuthPassKeyReply() is required to be called with valid parameters on receiving this event. 785 * cy_stc_ble_gap_auth_pk_info_t is returned as the event parameter. bdHandle is the only relevant parameter. 786 * Other parameters should be ignored. 787 */ 788 CY_BLE_EVT_GAP_PASSKEY_ENTRY_REQUEST, /* 0x4002u */ 789 790 /** This event indicates that the device needs to display a passkey during the pairing procedure. 791 * cy_stc_ble_gap_auth_pk_info_t is returned as the event parameter. bdHandle and passkey are relevant parameters. 792 * Other parameter(s) should be ignored. 793 * The passkey can be any 6-decimal-digit value. 794 */ 795 CY_BLE_EVT_GAP_PASSKEY_DISPLAY_REQUEST, /* 0x4003u */ 796 797 /** This event indicates that the authentication procedure is completed. 798 * The event parameter contains the security information as defined by cy_stc_ble_gap_auth_info_t. 799 * This event is generated at the end of the following three operations: 800 * * Authentication is initiated with a newly connected device 801 * * Encryption is initiated with a connected device that is already bonded 802 * * Re-Encryption is initiated with a connected device with link already encrypted 803 * During encryption/re-encryption, the Encryption Information exchanged during the pairing process 804 * is used to encrypt/re-encrypt the link. As this does not modify any of the authentication 805 * parameters with which the devices were paired, this event is generated with NULL event data 806 * and the result of the encryption operation. 807 */ 808 CY_BLE_EVT_GAP_AUTH_COMPLETE, /* 0x4004u */ 809 810 /** This event indicates that the authentication process between two devices has failed . 811 * cy_stc_ble_gap_auth_info_t is returned as the event parameter. bdHandle provides a handle for the failing device and 812 * authErr provides cy_en_ble_gap_auth_failed_reason_t indicates the reason for failure. 813 * Other parameters should be ignored. 814 */ 815 CY_BLE_EVT_GAP_AUTH_FAILED, /* 0x4005u */ 816 817 /** This event indicates that the GAP Peripheral device has started/stopped advertising. 818 * The event parameter contains the HCI Status error code, which is of type 'uint8_t'. 819 * If the data is '0x00', it indicates 'success'; anything else indicates 'failure'. 820 */ 821 CY_BLE_EVT_GAPP_ADVERTISEMENT_START_STOP, /* 0x4006u */ 822 823 /** This event is generated at the GAP Peripheral end after the connection is completed with a peer Central device. 824 * For a GAP Central device, this event is generated as an acknowledgment of receiving connection request by calling 'Cy_BLE_GAPC_InitConnection()' successfully 825 * by the BLE Stack. After the connection is completed, no other event is generated but if connection establishment fails, 826 * 'CY_BLE_EVT_GAP_DEVICE_DISCONNECTED' is generated to the application. 827 * This event is generated only if Link Layer Privacy is not enabled in the BLE Component customizer. 828 * The event parameter is a pointer to a structure of type cy_stc_ble_gap_connected_param_t. 829 * The members of the event parameter's structure are valid only if eventParams->status is success (0x00). 830 */ 831 CY_BLE_EVT_GAP_DEVICE_CONNECTED, /* 0x4007u */ 832 833 /** This event indicates that the device has disconnected from remote device or failed to establish connection. 834 * Parameter is of type 'cy_stc_ble_gap_disconnect_param_t' 835 */ 836 CY_BLE_EVT_GAP_DEVICE_DISCONNECTED, /* 0x4008u */ 837 838 /** This event indicated an encryption change event for an active connection. 839 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 840 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 841 * eventParams must be cast to (cy_stc_ble_gap_encrypt_change_param_t*) type to access the encryption state (ON/OFF) 842 * as well as the bdHandle corresponding to this event. 843 * eventParams->encryption is valid only if status is success(0x00) 844 * This is an informative event for the application when there is a change in encryption. 845 * The application may choose to ignore it. 846 */ 847 CY_BLE_EVT_GAP_ENCRYPT_CHANGE, /* 0x4009u */ 848 849 /** This event is generated at the GAP Central and the Peripheral end after a connection parameter update 850 * is requested from the host to the controller. 851 * The event parameter is a pointer to a structure of type cy_stc_ble_gap_conn_param_updated_in_controller_t. 852 */ 853 CY_BLE_EVT_GAP_CONNECTION_UPDATE_COMPLETE, /* 0x400Au */ 854 855 /** This event indicates that the Central device has started/stopped scanning. 856 * This event is generated after making a call to the Cy_BLE_GAPC_StartDiscovery() and 857 * Cy_BLE_GAPC_StopDiscovery() functions. The event parameter contains the HCI Status error code, 858 * which is of type 'uint8_t'. 859 * If the data is '0x00', it indicates 'success'; anything else indicates 'failure'. 860 */ 861 CY_BLE_EVT_GAPC_SCAN_START_STOP, /* 0x400Bu */ 862 863 /** This event indicates that the SMP keys exchange with a peer device is complete. The event handler 864 * is expected to store the peer device keys, especially IRK, which is used to resolve the 865 * peer device after the connection establishment. 866 * The event parameter returns data of type cy_stc_ble_gap_sec_key_param_t containing the peer device keys. 867 */ 868 CY_BLE_EVT_GAP_KEYINFO_EXCHNGE_CMPLT, /* 0x400Cu */ 869 870 /** This event indicates that the device must display a passkey during the 871 * secure connection pairing procedure. Cy_BLE_GAP_AuthPassKeyReply() is 872 * required to be called with valid parameters on receiving this event. 873 * Because no key is entered by the user for Numeric Comparison, the 874 * parameter passkey for the function Cy_BLE_GAP_AuthPassKeyReply() will be 875 * ignored. 876 * cy_stc_ble_gap_auth_pk_info_t is returned as the event parameter. bdHandle and passkey are relevant parameters. 877 * Other parameter(s) should be ignored. 'passkey' can be any 6-decimal-digit value. 878 */ 879 CY_BLE_EVT_GAP_NUMERIC_COMPARISON_REQUEST, /* 0x400Du */ 880 881 /** This event is generated when keypress (Secure connections) is received 882 * from peer device. 883 * cy_stc_ble_gap_sc_kp_notif_info_t is returned as event parameter. 884 */ 885 CY_BLE_EVT_GAP_KEYPRESS_NOTIFICATION, /* 0x400Eu */ 886 887 /** This event is generated when OOB generation for Secure connections is complete. 888 * The event parameter is of type 'cy_stc_ble_gap_oob_data_param_t' 889 */ 890 CY_BLE_EVT_GAP_OOB_GENERATED_NOTIFICATION, /* 0x400Fu */ 891 892 /** This event is generated at the GAP Peripheral end after the connection is completed with a peer Central device. 893 * For a GAP Central device, this event is generated as an acknowledgment of receiving connection request by calling 'Cy_BLE_GAPC_InitConnection()' successfully 894 * by the BLE Stack. After the connection is completed, no other event is generated but if connection establishment fails, 895 * 'CY_BLE_EVT_GAP_DEVICE_DISCONNECTED' event is generated to the application. 896 * This event is generated only if Link Layer Privacy is enabled in the BLE Component customizer. 897 * The event parameter is a pointer to a structure of type cy_stc_ble_gap_enhance_conn_complete_param_t. 898 * The members of the event parameter's structure are valid only if eventParams->status is success (0x00). 899 */ 900 CY_BLE_EVT_GAP_ENHANCE_CONN_COMPLETE, /* 0x4010u */ 901 902 /** This event indicates that directed advertisements have been received where 903 * the advertiser is using a resolvable private address for the InitA field in the ADV_DIRECT_IND PDU and the 904 * Scanning_Filter_Policy is equal to 0x02 or 0x03. The event parameter is of type 'cy_stc_ble_gapc_direct_adv_report_param_t' 905 */ 906 CY_BLE_EVT_GAPC_DIRECT_ADV_REPORT, /* 0x4011u */ 907 908 /** This event is raised as soon as the SMP has completed pairing properties (feature exchange) 909 * negotiation. The event parameter is cy_stc_ble_gap_auth_info_t. cy_stc_ble_gap_auth_info_t will have the 910 * negotiated parameter. The pairing should either pass with these negotiated parameters or may fail. 911 */ 912 CY_BLE_EVT_GAP_SMP_NEGOTIATED_AUTH_INFO, /* 0x4012u */ 913 914 /** This event indicates a new Bluetooth device address generated successfully as per an application requirement. 915 * The event parameter is cy_stc_ble_bd_addr_t 916 */ 917 CY_BLE_EVT_GAP_DEVICE_ADDR_GEN_COMPLETE, /* 0x4013u */ 918 919 /** This event indicates security keys are generated successfully. 920 * The event parameter is cy_stc_ble_gap_sec_key_param_t bdHandle in the parameter should be ignored 921 */ 922 CY_BLE_EVT_GAP_KEYS_GEN_COMPLETE, /* 0x4014u */ 923 924 /** This event is triggered on completion of Cy_BLE_GAPC_ResolveDevice() function. 925 * The event parameter is (cy_stc_ble_events_param_generic_t*) 926 */ 927 CY_BLE_EVT_GAP_RESOLVE_DEVICE_COMPLETE, /* 0x4015u */ 928 929 /** This event is triggered on completion of the Cy_BLE_GAP_GenerateSetLocalP256Keys() function. 930 * The event parameter is of pointer to cy_stc_ble_gap_smp_local_p256_keys_t that has 931 * generated P256 keys. 932 */ 933 CY_BLE_EVT_GAP_GEN_SET_LOCAL_P256_KEYS_COMPLETE, /* 0x4016u */ 934 935 /** This event is triggered on completion of the Cy_BLE_GAPC_CancelConnection() function. 936 * Event parameter returned with this event is of (cy_stc_ble_events_param_generic_t*) type. 937 * There are two members of the structure pointed to by the event parameter: status (uint8_t) and eventParams (void *). 938 * eventParams must be ignored 939 */ 940 CY_BLE_EVT_GAP_CREATE_CONN_CANCEL_COMPLETE, /* 0x4017u */ 941 942 /** This event is triggered on completion of connection establishment. 943 * Event parameter is (cy_stc_ble_conn_estb_param_t*) 944 */ 945 CY_BLE_EVT_GAP_CONN_ESTB, /* 0x4018u */ 946 947 /** This event indicates that the GAP Peripheral device has started/stopped advertising. 948 * This event is generated after making a call to the Cy_BLE_GAP_UpdateAdvScanData function. 949 * The event parameter contains the HCI Status error code, which is of type 'uint8_t'. 950 * If the data is '0x00', it indicates 'success'; anything else indicates 'failure'. 951 */ 952 CY_BLE_EVT_GAPP_UPDATE_ADV_SCAN_DATA_COMPLETE, /* 0x4019u */ 953 954 /** This event is triggered when an advertisement packet is sent over the air. This event will 955 * only be triggered if the CY_BLE_ADV_TX_EVENT_MASK event mask is set using the 956 * Cy_BLE_SetCustomEventMask API. The event parameter returned with this event must be 957 * ignored. 958 */ 959 CY_BLE_EVT_GAP_ADV_TX, /* 0x401Au */ 960 961 /* Range for GATT events - 0x5000 to 0x5FFF */ 962 963 /** This event is received by the GATT Client when the GATT Server cannot perform the requested 964 * operation and sends out an error response. The event parameter is a pointer to a structure 965 * of type cy_stc_ble_gatt_err_param_t. 966 */ 967 CY_BLE_EVT_GATTC_ERROR_RSP = 0x5000u, 968 969 /** This event is generated at the GAP Peripheral end after a connection is completed with a peer Central device. 970 * For a GAP Central device, this event is generated as in acknowledgment of receiving this event successfully 971 * by the BLE Stack. After connection is complete, no other event is required but if connection establishment fails, 972 * 'CY_BLE_EVT_GATT_DISCONNECT_IND' event is passed to the application. 973 * The event parameter is a pointer to a structure of type cy_stc_ble_conn_handle_t. 974 */ 975 CY_BLE_EVT_GATT_CONNECT_IND, /* 0x5001u */ 976 977 /** This event indicates that the GATT is disconnected. 978 * The event parameter is a pointer to a structure of type cy_stc_ble_conn_handle_t. 979 */ 980 CY_BLE_EVT_GATT_DISCONNECT_IND, /* 0x5002u */ 981 982 /** This event indicates that the 'GATT MTU Exchange Request' is received from GATT Client device. The event parameter 983 * is of 'cy_stc_ble_gatt_xchg_mtu_param_t' type and contains the Client RX MTU size. 984 */ 985 CY_BLE_EVT_GATTS_XCNHG_MTU_REQ, /* 0x5003u */ 986 987 /** This event indicates that the 'GATT MTU Exchange Response' is received from GATT Server device. The event parameter 988 * is a pointer to a structure of type cy_stc_ble_gatt_xchg_mtu_param_t and contains the Server RX MTU size. 989 */ 990 CY_BLE_EVT_GATTC_XCHNG_MTU_RSP, /* 0x5004u */ 991 992 /** This event indicates that the 'Read by Group Type Response' is received from GATT Server device. The event parameter 993 * is a pointer to a structure of type cy_stc_ble_gattc_read_by_grp_rsp_param_t. 994 */ 995 CY_BLE_EVT_GATTC_READ_BY_GROUP_TYPE_RSP, /* 0x5005u */ 996 997 /** This event indicates that the 'Read by Type Response' is received from GATT Server device. The event parameter is a 998 * pointer to a structure of type cy_stc_ble_gattc_read_by_type_rsp_param_t. 999 */ 1000 CY_BLE_EVT_GATTC_READ_BY_TYPE_RSP, /* 0x5006u */ 1001 1002 /** This event indicates that the 'Find Information Response' is received from GATT Server device. The event parameter is 1003 * a pointer to a structure of type 'cy_stc_ble_gattc_find_info_rsp_param_t. 1004 */ 1005 CY_BLE_EVT_GATTC_FIND_INFO_RSP, /* 0x5007u */ 1006 1007 /** This event indicates that the 'Find by Type Value Response' is received from GATT Server device. The event parameter is 1008 * a pointer to a structure of type cy_stc_ble_gattc_find_by_type_rsp_param_t. 1009 */ 1010 CY_BLE_EVT_GATTC_FIND_BY_TYPE_VALUE_RSP, /* 0x5008u */ 1011 1012 /** This event indicates that the 'Read Response' is received from GATT Server device. The event parameter is a pointer to a 1013 * structure of type cy_stc_ble_gattc_read_rsp_param_t. 1014 */ 1015 CY_BLE_EVT_GATTC_READ_RSP, /* 0x5009u */ 1016 1017 /** This event indicates that the'Read Blob Response' from GATT Server. The event parameter is a pointer to a 1018 * structure of type cy_stc_ble_gattc_read_rsp_param_t. 1019 */ 1020 CY_BLE_EVT_GATTC_READ_BLOB_RSP, /* 0x500Au */ 1021 1022 /** This event indicates that the 'Read Multiple Responses' is received from GATT Server device. The event parameter is a pointer 1023 * to a structure of type cy_stc_ble_gattc_read_rsp_param_t. The 'actualLen' field 1024 * should be ignored as it is unused in this event response. 1025 */ 1026 CY_BLE_EVT_GATTC_READ_MULTI_RSP, /* 0x500Bu */ 1027 1028 /** This event indicates that the 'Write Request' is received from GATT Client device. The event parameter is a pointer to 1029 * a structure of type cy_stc_ble_gatt_write_param_t. 1030 */ 1031 CY_BLE_EVT_GATTS_WRITE_REQ, /* 0x500Cu */ 1032 1033 /** This event indicates that the 'Write Response' is received from GATT Server device. The event parameter is a pointer 1034 * to a structure of type cy_stc_ble_conn_handle_t. 1035 */ 1036 CY_BLE_EVT_GATTC_WRITE_RSP, /* 0x500Du */ 1037 1038 /** This event indicates that the 'Write Command' is received from GATT Client device. The event parameter is a 1039 * pointer to a structure of type cy_stc_ble_gatts_write_cmd_req_param_t. 1040 */ 1041 CY_BLE_EVT_GATTS_WRITE_CMD_REQ, /* 0x500Eu */ 1042 1043 /** This event indicates that the 'Prepare Write' Request is received from GATT Client device. The event parameter is a 1044 * pointer to a structure of type cy_stc_ble_gatts_prep_write_req_param_t. 1045 */ 1046 CY_BLE_EVT_GATTS_PREP_WRITE_REQ, /* 0x500Fu */ 1047 1048 /** This event indicates that the 'Execute Write' request is received from GATT Client device. The event parameter is a 1049 * pointer to a structure of type 'cy_stc_ble_gatts_exec_write_req_t'. 1050 * This event will be triggered before GATT DB is modified. GATT DB will be updated 1051 * only if there is no error condition provided by the application. In case of an error condition triggered 1052 * during BLE Stack validation, a partial write will occur. The write will be cancelled from that handle where 1053 * the error has occurred and an error response corresponding to that handle will be sent to the remote device. 1054 * If at any point of time 'CY_BLE_GATT_EXECUTE_WRITE_CANCEL_FLAG' is received in 1055 * execWriteFlag fields of 'cy_stc_ble_gatts_exec_write_req_t' structure, then all previous 1056 * writes are cancelled. For execute cancel scenario, all elements of 1057 * 'cy_stc_ble_gatts_exec_write_req_t' should be ignored except execWriteFlag and connHandle. 1058 */ 1059 CY_BLE_EVT_GATTS_EXEC_WRITE_REQ, /* 0x5010u */ 1060 1061 /** This event indicates that the 'Execute Write' response is received from GATT Server device. The event parameter is a 1062 * pointer to a structure of type cy_stc_ble_gattc_exec_write_rsp_param_t. 1063 */ 1064 CY_BLE_EVT_GATTC_EXEC_WRITE_RSP, /* 0x5011u */ 1065 1066 /** This event indicates that Notification data is received from GATT Server device. The event parameter 1067 * is a pointer to a structure of type cy_stc_ble_gattc_handle_value_ntf_param_t. 1068 */ 1069 CY_BLE_EVT_GATTC_HANDLE_VALUE_NTF, /* 0x5012u */ 1070 1071 /** This event indicates that Indication data is received from GATT Server device. The event parameter is 1072 * a pointer to a structure of type cy_stc_ble_gattc_handle_value_ind_param_t. 1073 */ 1074 CY_BLE_EVT_GATTC_HANDLE_VALUE_IND, /* 0x5013u */ 1075 1076 /** This event indicates that an Indication Response is received from the GATT Client. The event 1077 * parameter is a pointer to a structure of type cy_stc_ble_conn_handle_t. 1078 */ 1079 CY_BLE_EVT_GATTS_HANDLE_VALUE_CNF, /* 0x5014u */ 1080 1081 /** This event indicates that a 'GATT Signed Write' command is received from GATT Client. The event 1082 * parameter is a pointer to a structure of type cy_stc_ble_gatts_signed_write_cmd_req_param_t. 1083 * If value.val parameter is set to Zero, then the signature is not matched and is ignored by the BLE Stack 1084 */ 1085 CY_BLE_EVT_GATTS_DATA_SIGNED_CMD_REQ, /* 0x5015u */ 1086 1087 /** This event indicates that a GATT group procedure has stopped or completed. This event occurs 1088 * only if the application has called the Cy_BLE_GATTC_StopCmd() function. 1089 * The parameter is a pointer to a structure of type cy_stc_ble_conn_handle_t. 1090 */ 1091 CY_BLE_EVT_GATTC_STOP_CMD_COMPLETE, /* 0x5016u */ 1092 1093 /** This event is triggered on the GATT Server side when the GATT Client sends a read request and 1094 * when characteristic has the CY_BLE_GATT_DB_ATTR_CHAR_VAL_RD_EVENT property set. The event 1095 * parameter is of 'cy_stc_ble_gatts_char_val_read_req_t' type. This event could be ignored by the 1096 * application unless it needs to respond by an error response, which must be set in the gattErrorCode 1097 * field of the event parameter. 1098 */ 1099 CY_BLE_EVT_GATTS_READ_CHAR_VAL_ACCESS_REQ, /* 0x5017u */ 1100 1101 /** This event indicates that the GATT long procedure has ended and the BLE Stack will not send any further 1102 * requests to the peer. The event parameter is of type 'cy_stc_ble_gattc_long_procedure_end_param_t'. 1103 * Either this event or 'CY_BLE_EVT_GATTC_ERROR_RSP' will be received 1104 * by the application. This event may be triggered for the following GATT long procedures: 1105 * 1. Cy_BLE_GATTC_DiscoverAllPrimaryServices() 1106 * 2. Cy_BLE_GATTC_DiscoverPrimaryServiceByUuid() 1107 * 3. Cy_BLE_GATTC_FindIncludedServices() 1108 * 4. Cy_BLE_GATTC_DiscoverAllCharacteristics() 1109 * 5. Cy_BLE_GATTC_DiscoverCharacteristicByUuid() 1110 * 6. Cy_BLE_GATTC_DiscoverAllCharacteristicDescriptors() 1111 * 7. Cy_BLE_GATTC_ReadLongCharacteristicValues() 1112 * 8. Cy_BLE_GATTC_WriteLongCharacteristicValues() 1113 * 9. Cy_BLE_GATTC_ReliableWrites() 1114 * 10. Cy_BLE_GATTC_ReadLongCharacteristicDescriptors() 1115 * 11. Cy_BLE_GATTC_WriteLongCharacteristicDescriptors() 1116 * 12. Cy_BLE_GATTC_ReadByTypeReq() \n 1117 * The event parameter is ATT opcode for the corresponding long GATT Procedure. 1118 */ 1119 CY_BLE_EVT_GATTC_LONG_PROCEDURE_END, /* 0x5018u */ 1120 1121 /* Range for L2CAP events - 0x6000 to 0x6FFF */ 1122 1123 /** This event indicates the connection parameter update is received 1124 * from the remote device. The application is expected to reply to L2CAP using the 1125 * Cy_BLE_L2CAP_LeConnectionParamUpdateResponse() function to respond to the remote 1126 * device, whether parameters are accepted or rejected. 1127 * 1128 * The event parameter pointer points to data of type 'cy_stc_ble_gap_conn_update_param_info_t' 1129 */ 1130 CY_BLE_EVT_L2CAP_CONN_PARAM_UPDATE_REQ = 0x6000u, 1131 1132 /** This event indicates the connection parameter update response is received 1133 * from the master. The event parameter is a pointer to a structure of type 1134 * cy_stc_ble_l2cap_conn_update_rsp_param_t. 1135 */ 1136 CY_BLE_EVT_L2CAP_CONN_PARAM_UPDATE_RSP, /* 0x6001u */ 1137 1138 /** This event indicates that the request to send over L2CAP signaling is 1139 * rejected. The event parameter is a pointer to a structure of type 1140 * cy_stc_ble_l2cap_cmd_rej_param_t. 1141 */ 1142 CY_BLE_EVT_L2CAP_COMMAND_REJ, /* 0x6002u */ 1143 1144 /** This event is used to inform the application of the incoming L2CAP CBFC 1145 * Connection Request. The event parameter is a pointer to a structure of type 1146 * cy_stc_ble_l2cap_cbfc_conn_ind_param_t. 1147 */ 1148 CY_BLE_EVT_L2CAP_CBFC_CONN_IND, /* 0x6003u */ 1149 1150 /** This event is used to inform application of the L2CAP CBFC Connection 1151 * Response/Confirmation. The event parameter is a pointer to a structure of 1152 * type cy_stc_ble_l2cap_cbfc_conn_cnf_param_t. 1153 */ 1154 CY_BLE_EVT_L2CAP_CBFC_CONN_CNF, /* 0x6004u */ 1155 1156 /** This event is used to inform the application of the L2CAP CBFC Disconnection 1157 * Request received from the Peer device. The event parameter is a pointer to 1158 * a Local CID of type uint16. 1159 */ 1160 CY_BLE_EVT_L2CAP_CBFC_DISCONN_IND, /* 0x6005u */ 1161 1162 /** This event is used to inform the application of the L2CAP CBFC Disconnection 1163 * confirmation/response received from the peer device. The event parameter is a 1164 * pointer to a structure of type cy_stc_ble_l2cap_cbfc_disconn_cnf_param_t. 1165 */ 1166 CY_BLE_EVT_L2CAP_CBFC_DISCONN_CNF, /* 0x6006u */ 1167 1168 /** This event is used to inform the application of data received over the L2CAP 1169 * CBFC channel. The event parameter is a pointer to a structure of type 1170 * cy_stc_ble_l2cap_cbfc_rx_param_t. 1171 */ 1172 CY_BLE_EVT_L2CAP_CBFC_DATA_READ, /* 0x6007u */ 1173 1174 /** This event is generated when the Receive Credits have reached the 1175 * low water mark for a CBFC channel. After receiving L2CAP data/payload from a peer device for a 1176 * CBFC channel, the available credits are calculated. If the credit count goes 1177 * below the low water mark, this event is generated to inform 1178 * the application of the condition. Now, if the application wants, it can 1179 * send more credits to the peer device. 1180 * 1181 * The event parameter is a pointer to a structure of type 1182 * cy_stc_ble_l2cap_cbfc_low_rx_credit_param_t. 1183 */ 1184 CY_BLE_EVT_L2CAP_CBFC_RX_CREDIT_IND, /* 0x6008u */ 1185 1186 /** This event is generated when the BLE Stack receives Transmit Credits for a CBFC channel. 1187 * This event is called on receiving LE Flow Control Credit from a peer 1188 * device. 1189 * 1190 * The event parameter is a pointer to a structure of type 1191 * cy_stc_ble_l2cap_cbfc_low_tx_credit_param_t. 1192 * 1193 * If the 'result' field of the received data is non-zero, this indicates an 1194 * error. If the sum of 'credit' field value of the received data and the previously available credit 1195 * at the device exceeds 65535, it indicates a 'credit overflow' error. 1196 * 1197 * If there is an error, the peer device receiving this event should initiate 1198 * disconnection of the L2CAP channel by invoking the Cy_BLE_L2CAP_DisconnectReq() 1199 * function. 1200 */ 1201 CY_BLE_EVT_L2CAP_CBFC_TX_CREDIT_IND, /* 0x6009u */ 1202 1203 /** This event is used to inform the application that L2CAP CBFC data transmission is scheduled 1204 * for transmission in the BLE Stack. The application can send the next data. 1205 * The event parameter is of type 'cy_stc_ble_l2cap_cbfc_rx_data_param_t'. 1206 * The L2CAP CBFC application must wait for this event before transmitting the next CBFC L2CAP data. 1207 * The application can send the next data only when the CY_BLE_EVT_L2CAP_CBFC_DATA_WRITE_IND event is received for 1208 * previously sent data and CY_BLE_EVT_STACK_BUSY_STATUS is received with status CY_BLE_STACK_STATE_FREE. 1209 */ 1210 CY_BLE_EVT_L2CAP_CBFC_DATA_WRITE_IND, /* 0x600Au */ 1211 1212 /*Range for qualification events - 0x7000 to 0x7FFF*/ 1213 1214 #ifdef CY_BLE_HOST_QUALIFICATION 1215 /** Tester to manipulate pairing request or response PDU. The event parameter is a pointer to 1 byte data. 1216 * The tester can manipulate the bits of the byte. 1217 */ 1218 CY_BLE_EVT_QUAL_SMP_PAIRING_REQ_RSP = 0x7000u, 1219 1220 /** Tester to manipulate local Public Key. The event parameter is a pointer to local public key of size 64 Bytes. 1221 * The tester can manipulate the bits/bytes. 1222 */ 1223 CY_BLE_EVT_QUAL_SMP_LOCAL_PUBLIC_KEY, /* 0x7001u */ 1224 1225 /** Tester to assign pairing failed error code. The event parameter is a pointer to 16 bits value. 1226 * The tester should assign an error code to the lower bits. 1227 */ 1228 CY_BLE_EVT_QUAL_SMP_PAIRING_FAILED_CMD, /* 0x7002u */ 1229 1230 #endif /* CY_BLE_HOST_QUALIFICATION */ 1231 1232 /*##Range for for future use - 0x8000 to 0xFFFE*/ 1233 1234 1235 /** Maximum value of cy_en_ble_event_t type */ 1236 CY_BLE_EVT_MAX = 0xFFFF 1237 1238 } cy_en_ble_event_t; 1239 1240 /** @} */ 1241 1242 /** 1243 \addtogroup group_ble_common_api_definitions 1244 @{ 1245 */ 1246 /** Common error codes received as API result */ 1247 typedef enum 1248 { 1249 /** No Error occurred */ 1250 CY_BLE_SUCCESS = CY_PDL_STATUS_INFO, 1251 1252 /** Flash operation in progress*/ 1253 CY_BLE_INFO_FLASH_WRITE_IN_PROGRESS = CY_PDL_STATUS_INFO | CY_BLE_ID | 0x0001ul, 1254 1255 /** At least one of the input parameters is invalid */ 1256 CY_BLE_ERROR_INVALID_PARAMETER = CY_PDL_STATUS_ERROR | CY_BLE_ID | 0x0001ul, 1257 1258 /** Operation is not permitted */ 1259 CY_BLE_ERROR_INVALID_OPERATION, 1260 1261 /** An internal error occurred in the BLE Stack */ 1262 CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED, 1263 1264 /** Insufficient resources to perform requested operation */ 1265 CY_BLE_ERROR_INSUFFICIENT_RESOURCES, 1266 1267 /** OOB data not available */ 1268 CY_BLE_ERROR_OOB_NOT_AVAILABLE, 1269 1270 /** Connection is required to perform requested operation. Connection not 1271 present */ 1272 CY_BLE_ERROR_NO_CONNECTION, 1273 1274 /** No device entity to perform requested operation */ 1275 CY_BLE_ERROR_NO_DEVICE_ENTITY, 1276 1277 /** Device cannot be added to the White List as it has already been added */ 1278 CY_BLE_ERROR_DEVICE_ALREADY_EXISTS, 1279 1280 /** Attempted repeat operation is not allowed */ 1281 CY_BLE_ERROR_REPEATED_ATTEMPTS, 1282 1283 /** GAP role is incorrect */ 1284 CY_BLE_ERROR_GAP_ROLE, 1285 1286 /** Security operation failed */ 1287 CY_BLE_ERROR_SEC_FAILED, 1288 1289 /** L2CAP PSM encoding is incorrect */ 1290 CY_BLE_ERROR_L2CAP_PSM_WRONG_ENCODING, 1291 1292 /** L2CAP PSM has already been registered */ 1293 CY_BLE_ERROR_L2CAP_PSM_ALREADY_REGISTERED, 1294 1295 /** L2CAP PSM has not been registered */ 1296 CY_BLE_ERROR_L2CAP_PSM_NOT_REGISTERED, 1297 1298 /** L2CAP connection entity not found */ 1299 CY_BLE_ERROR_L2CAP_CONNECTION_ENTITY_NOT_FOUND, 1300 1301 /** Specified PSM is out of range */ 1302 CY_BLE_ERROR_L2CAP_PSM_NOT_IN_RANGE, 1303 1304 /** Unsupported feature or parameter value */ 1305 CY_BLE_ERROR_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE, 1306 1307 /** Write to Flash is not permitted */ 1308 CY_BLE_ERROR_FLASH_WRITE_NOT_PERMITED, 1309 1310 /** Error in Flash write */ 1311 CY_BLE_ERROR_FLASH_WRITE, 1312 1313 /** MIC Authentication failure */ 1314 CY_BLE_ERROR_MIC_AUTH_FAILED, 1315 1316 /** Hardware Failure */ 1317 /** Possible reason - BLE ECO failed to start due to one of the below: 1318 * - LFCLK (WCO, PILO, ILO) not present 1319 * - Radio bus failure 1320 */ 1321 CY_BLE_ERROR_HARDWARE_FAILURE, 1322 1323 /**GATT DB error codes*/ 1324 /** Invalid attribute handle */ 1325 CY_BLE_ERROR_GATT_DB_INVALID_ATTR_HANDLE, 1326 1327 /* Profile level API_RESULT codes */ 1328 /** Characteristic notifications disabled */ 1329 CY_BLE_ERROR_NTF_DISABLED, 1330 1331 /** Characteristic indications disabled */ 1332 CY_BLE_ERROR_IND_DISABLED, 1333 1334 /** \cond IGNORE */ 1335 CY_BLE_ERROR_CHAR_IS_NOT_DISCOVERED, 1336 /** \endcond */ 1337 1338 /** Controller Busy */ 1339 CY_BLE_ERROR_CONTROLLER_BUSY = CY_PDL_STATUS_ERROR | CY_BLE_ID | 0x00FEul, 1340 1341 /** The state is not valid for current operation */ 1342 CY_BLE_ERROR_INVALID_STATE, 1343 1344 /** All other errors not covered in the above list map to this error code */ 1345 CY_BLE_ERROR_MAX = CY_PDL_STATUS_ERROR | CY_BLE_ID | 0xFFFFul, 1346 1347 } cy_en_ble_api_result_t; 1348 1349 1350 /*************************************** 1351 ** Exported structures and unions 1352 ***************************************/ 1353 1354 /** Event callback function prototype to receive events from BLE Stack */ 1355 typedef void (*cy_ble_app_ev_cb_t)(cy_en_ble_event_t event, void* evParam); 1356 1357 1358 /** This structure is used to hold version information of the BLE Stack Library */ 1359 typedef struct 1360 { 1361 /** The major version of the library */ 1362 uint8_t majorVersion; 1363 1364 /** The minor version of the library */ 1365 uint8_t minorVersion; 1366 1367 /** The patch number of the library */ 1368 uint8_t patch; 1369 1370 /** The build number of the library */ 1371 uint16_t buildNumber; 1372 1373 } cy_stc_ble_stack_lib_version_t; 1374 1375 1376 /** Bluetooth Device Address type */ 1377 typedef struct 1378 { 1379 /** Bluetooth device address */ 1380 uint8_t bdAddr[CY_BLE_BD_ADDR_SIZE]; 1381 1382 /** public = 0, Random = 1 */ 1383 uint8_t type; 1384 1385 } cy_stc_ble_bd_addr_t; 1386 1387 1388 /** Configuration structure for Tx and Rx ACL Data Buffers required by the 1389 * BLE Stack. All the configurations specified are valid per 1390 * connection and all the supported LL connections will have same capability. 1391 */ 1392 typedef struct 1393 { 1394 /** 1395 * Tx buffer size configuration for the BLE Stack per the 1396 * LL Connection 1397 */ 1398 uint16_t dleMaxTxCapability; 1399 1400 /** 1401 * Rx buffer size configuration for the BLE Stack per the 1402 * LL Connection 1403 */ 1404 uint16_t dleMaxRxCapability; 1405 1406 /** 1407 * Total number of Tx buffer configuration per LL Connection for the 1408 * BLE Stack 1409 */ 1410 uint8_t dleNumTxBuffer; 1411 1412 /** 1413 * Total number of Rx buffer configuration per LL Connection for 1414 * BLE Stack 1415 */ 1416 uint8_t dleNumRxBuffer; 1417 1418 } cy_stc_ble_dle_config_param_t; 1419 1420 /** Configuration structure for the L2CAP buffer for data transmission */ 1421 typedef struct 1422 { 1423 /** 1424 * This specifies L2CAP stack queue depth per connection for data tx. 1425 * The application must provide heap memory based on the following calculation: 1426 * l2capBufferPerConn * maxBleConnections * CY_BLE_L2CAP_QUEUE_ELEMENT_SIZE 1427 */ 1428 uint8_t l2capBufferPerConn; 1429 1430 } cy_stc_ble_l2cap_config_param_t; 1431 1432 1433 /** Configuration structure for LL Privacy feature */ 1434 typedef struct 1435 { 1436 /** Maximum number of possible entries in Resolving List */ 1437 uint8_t resolvingListSize; 1438 1439 } cy_stc_ble_privacy_1_2_config_param_t; 1440 1441 /** Configuration parameter for Bonded Devices List */ 1442 typedef struct 1443 { 1444 /** Maximum number of possible entries in Bonded Devices List */ 1445 /* The application must provide Bonded Devices List memory as per bondlist size */ 1446 uint8_t bondListSize; 1447 1448 } cy_stc_ble_bonded_device_list_config_param_t; 1449 1450 /**Configuration parameter for the White List */ 1451 typedef struct 1452 { 1453 /** Maximum number of possible entries in the White List */ 1454 uint8_t whiteListSize; 1455 1456 } cy_stc_ble_white_list_config_param_t; 1457 1458 /** Configuration parameter for Radio PA calibration */ 1459 typedef struct 1460 { 1461 /** LOBUFF value Table 1462 * __________________________________ 1463 * | Parameter | Table Index | 1464 * |------------------|--------------| 1465 * | LOBUFF_5dBm | 0 | 1466 * | LOBUFF_4dBm | 1 | 1467 * | LOBUFF_0dBm | 2 | 1468 * | LOBUFF_n6dBm | 3 | 1469 * |------------------|--------------| 1470 * 1471 * Note: Non-zero entries to the below table will over-ride 1472 * the Cypress recommended radio PA settings. 1473 */ 1474 uint16_t lobuffTable[CY_BLE_MXD_PA_NUM_LOBUFF_VALS]; 1475 1476 /** Target Value Table 1477 * __________________________________ 1478 * | Parameter | Table Index | 1479 * |------------------|--------------| 1480 * | TARGET_5dBm | 0 | 1481 * | TARGET_4dBm | 1 | 1482 * | TARGET_0dBm | 2 | 1483 * | TARGET_n6dBm | 3 | 1484 * | TARGET_n12dBm | 4 | 1485 * | TARGET_n16dBm | 5 | 1486 * | TARGET_n20dBm | 6 | 1487 * |------------------|--------------| 1488 * 1489 * Note: Non-zero entries to the below table will over-ride 1490 * the Cypress recommended radio PA settings. 1491 */ 1492 1493 uint16_t targetTable[CY_BLE_MXD_PA_NUM_TARGET_VALS]; 1494 1495 /** Limit beyond which gain begins to rail. 1496 * Note: Non-zero entries to the below element will over-ride 1497 * the Cypress recommended radio PA settings. 1498 */ 1499 uint8_t lobuffLimit; 1500 1501 /** Calibration Ceiling. 1502 * Note: Non-zero entries to the below element will over-ride 1503 * the Cypress recommended radio PA settings. 1504 */ 1505 uint16_t calValLimit; 1506 1507 /** 1508 * __________________________________ 1509 * | Parameter | Table Index | 1510 * |-----------------|--------------| 1511 * | ACT LDO 0dBm | 0 | 1512 * | ACT LDO 4dBm | 1 | 1513 * | PA LDO 0dBm | 2 | 1514 * | PA LDO 4dBm | 3 | 1515 * |-----------------|--------------| 1516 * 1517 * Note: Non-zero entries to the below table will over-ride 1518 * the Cypress recommended radio PA settings. 1519 */ 1520 uint16_t ldoVoltageTable[CY_BLE_MXD_PA_NUM_LDO_SETTINGS]; 1521 1522 } cy_stc_ble_mxd_pa_cal_param_t; 1523 1524 /** 1525 * Configuration structure for enabling selective features 1526 * and passing associated parameters. 1527 */ 1528 typedef struct 1529 { 1530 /** Configuration parameter for DLE feature */ 1531 cy_stc_ble_dle_config_param_t dleConfig; 1532 1533 /** Configuration parameter for L2CAP buffer */ 1534 cy_stc_ble_l2cap_config_param_t l2capConfig; 1535 1536 /** Configuration parameter for privacy 1.2 feature */ 1537 cy_stc_ble_privacy_1_2_config_param_t privacyConfig; 1538 1539 /** Configuration parameter for Bonded Devices List */ 1540 cy_stc_ble_bonded_device_list_config_param_t bondListConfig; 1541 1542 /** Configuration parameter for White List */ 1543 cy_stc_ble_white_list_config_param_t whiteListConfig; 1544 1545 /** Configuration parameter for Radio PA calibration */ 1546 cy_stc_ble_mxd_pa_cal_param_t paCalConfig; 1547 1548 /** The feature set mask used to control usage of 1549 * specified feature in the BLE stack. If a feature is not selected, 1550 * then associated parameter pointer can be NULL. 1551 * Feature Mask Values : 1552 * B0 : DLE_FEATURE_MASK 1553 * B1 : PRIVACY_1_2_FEATURE_MASK 1554 * B2 : SECURE_CONN_FEATURE_MASK 1555 * B3 : PHY_UPDATE_FEATURE_MASK 1556 * B4 : PERSISTENT_STORE_BONDLIST 1557 * B5 : PERSISTENT_STORE_RESOLVING_LIST 1558 * B6 : PERSISTENT_STORE_WHITELIST 1559 * B7 : PERSISTENT_RADIO_CALIBRATION_MASK 1560 */ 1561 uint16_t featureMask; 1562 1563 /**Out parameter for returning memory requirement for selected features*/ 1564 uint16_t featureHeapReq; 1565 1566 1567 /** Configuration parameter for Maximum number of BLE Connection 1568 * Max possible value is 4 and Min configuration value is 1 1569 */ 1570 uint8_t maxBleConnections; 1571 1572 } cy_stc_ble_stack_config_param_t; 1573 1574 1575 /** Set of buffers to be allocated by BLE Stack for BLE Stack operation */ 1576 typedef struct 1577 { 1578 /** Size of the buffer chunk */ 1579 uint16_t bufferSize; 1580 1581 /** Number of the buffers units of 'bufferSize' */ 1582 uint16_t bufferUnits; 1583 1584 } cy_stc_ble_stk_app_data_buff_t; 1585 1586 /** Structure for passing the connection established 1587 * parameters 1588 */ 1589 typedef struct 1590 { 1591 /** bd handle of the device */ 1592 uint8_t bdHandle; 1593 1594 /** Link layer access address */ 1595 uint32_t accessAddr; 1596 1597 } cy_stc_ble_conn_estb_param_t; 1598 1599 /** BLE Stack Manager configuration structure for allocating memory pools 1600 * for host and controller operation. 1601 */ 1602 typedef struct 1603 { 1604 /** Memory Heap pointer */ 1605 uint8_t * memoryHeapPtr; 1606 1607 /** Set of buffers needed for BLE Stack operation */ 1608 cy_stc_ble_stk_app_data_buff_t * dataBuff; 1609 1610 /** Memory heap pointer size */ 1611 uint16_t totalHeapSz; 1612 1613 /** Total data buffer pools */ 1614 uint8_t totalDataBufferPools; 1615 1616 /** Pointer to an array of bytes to be allocated by the BLE Component for the storing the 1617 persistent data into the Flash. Pointer provided is should be aligned to the Flash boundary. */ 1618 const uint8_t * bleStackFlashPointer; 1619 1620 /** Size of the total Flash memory pointed by bleStackFlashPointer */ 1621 uint32_t bleStackFlashSize; 1622 1623 } cy_stc_ble_stack_mgr_mem_cfg_param_t; 1624 1625 1626 /** BLE Stack init parameter */ 1627 typedef struct 1628 { 1629 /** Application Callback Function Configuration **/ 1630 cy_ble_app_ev_cb_t CyBleAppCbFunc; 1631 1632 /** BLE Stack Manager Memory Configuration **/ 1633 cy_stc_ble_stack_mgr_mem_cfg_param_t memParam; 1634 1635 /** BLE Stack configuration parameter **/ 1636 cy_stc_ble_stack_config_param_t stackConfig; 1637 1638 } cy_stc_ble_stack_init_info_t; 1639 1640 /** 1641 * Structure containing the parameters required for AES CMAC Generation 1642 */ 1643 typedef struct 1644 { 1645 1646 /** pointer to message for which AES CMAC must be calculated, LSB should be first */ 1647 uint8_t *buffer; 1648 /** size of the message buffer */ 1649 uint16_t size; 1650 /** AES CMAC 128-bit Key, LSB should be first */ 1651 uint8_t *key; 1652 /** output-parameter, Buffer to hold generated MAC of 16 bytes. Output is LSB first */ 1653 uint8_t *mac; 1654 1655 }cy_stc_ble_aes_cmac_generate_param_t; 1656 1657 /** BLESS Power enum reflecting power level values supported by BLESS radio */ 1658 typedef enum 1659 { 1660 /** ABS PWR = -20 dBm */ 1661 CY_BLE_LL_PWR_LVL_NEG_20_DBM = -20, 1662 1663 /** ABS PWR = -16 dBm */ 1664 CY_BLE_LL_PWR_LVL_NEG_16_DBM = -16, 1665 1666 /** ABS PWR = -12 dBm */ 1667 CY_BLE_LL_PWR_LVL_NEG_12_DBM = -12, 1668 1669 /** ABS PWR = -6 dBm */ 1670 CY_BLE_LL_PWR_LVL_NEG_6_DBM = -6, 1671 1672 /** ABS PWR = 0 dBm */ 1673 CY_BLE_LL_PWR_LVL_0_DBM = 0, 1674 1675 /** ABS PWR = +4 dBm as per silicon */ 1676 CY_BLE_LL_PWR_LVL_MAX = 4 1677 1678 } cy_en_ble_bless_pwr_lvl_t; 1679 1680 /** BLE channel group ID */ 1681 typedef enum 1682 { 1683 /** Advertisement channel type */ 1684 CY_BLE_LL_ADV_CH_TYPE = 0x00u, 1685 1686 /** Connection channel type */ 1687 CY_BLE_LL_CONN_CH_TYPE, 1688 1689 /** Maximum value of the cy_en_ble_bless_phy_ch_grp_id_t type */ 1690 CY_BLE_LL_MAX_CH_TYPE 1691 1692 } cy_en_ble_bless_phy_ch_grp_id_t; 1693 1694 /** BLE WCO sleep clock accuracy configuration */ 1695 typedef enum 1696 { 1697 /** BLE WCO sleep clock accuracy 251 to 500 ppm */ 1698 CY_BLE_LL_SCA_251_TO_500_PPM = 0x00u, 1699 1700 /** BLE WCO sleep clock accuracy 151 to 250 ppm */ 1701 CY_BLE_LL_SCA_151_TO_250_PPM, 1702 1703 /** BLE WCO sleep clock accuracy 101 to 150 ppm */ 1704 CY_BLE_LL_SCA_101_TO_150_PPM, 1705 1706 /** BLE WCO sleep clock accuracy 76 to 100 ppm */ 1707 CY_BLE_LL_SCA_076_TO_100_PPM, 1708 1709 /** BLE WCO sleep clock accuracy 51 to 75 ppm */ 1710 CY_BLE_LL_SCA_051_TO_075_PPM, 1711 1712 /** BLE WCO sleep clock accuracy 31 to 50 ppm */ 1713 CY_BLE_LL_SCA_031_TO_050_PPM, 1714 1715 /** BLE WCO sleep clock accuracy 21 to 30 ppm */ 1716 CY_BLE_LL_SCA_021_TO_030_PPM, 1717 1718 /** BLE WCO sleep clock accuracy 0 to 20 ppm */ 1719 CY_BLE_LL_SCA_000_TO_020_PPM, 1720 1721 /** BLE WCO invalid sleep clock accuracy */ 1722 CY_BLE_LL_SCA_IN_PPM_INVALID 1723 } cy_en_ble_bless_wco_sca_cfg_t; 1724 1725 /** BLE ECO clock divider */ 1726 typedef enum 1727 { 1728 /** Link Layer clock divider = 1*/ 1729 CY_BLE_LL_ECO_CLK_DIV_1 = 0x00u, 1730 1731 /** Link Layer clock divider = 2*/ 1732 CY_BLE_LL_ECO_CLK_DIV_2, 1733 1734 /** Link Layer clock divider = 4*/ 1735 CY_BLE_LL_ECO_CLK_DIV_4, 1736 1737 /** Link Layer clock divider = 8*/ 1738 CY_BLE_LL_ECO_CLK_DIV_8, 1739 1740 /** Invalid Link Layer clock divider*/ 1741 CY_BLE_LL_ECO_CLK_DIV_INVALID 1742 1743 } cy_en_ble_bless_eco_clk_div_t; 1744 1745 /** BLE clock configuration parameters */ 1746 typedef struct 1747 { 1748 /** Sleep Clock accuracy in PPM, 32Khz Cycles */ 1749 cy_en_ble_bless_wco_sca_cfg_t bleLlSca; 1750 1751 /** Link Layer clock divider */ 1752 cy_en_ble_bless_eco_clk_div_t bleLlClockDiv; 1753 1754 } cy_stc_ble_bless_clk_cfg_params_t; 1755 1756 /** Standard HCI command/data packet */ 1757 typedef struct 1758 { 1759 /** Buffer to hold the HCI packet 1760 * HCI Command Packet guide: 1761 * 1762 * 0 4 8 12 16 20 24 28 32 1763 * Octet 0 Octet 1 Octet 2 Octet 3 1764 * +-----------+-----------+-----------+-----------+ 1765 * | Opcode | Parameter | | 1766 * ------------------------| Total |Parameter 0| 1767 * | OCF | OGF | Length | | 1768 * +-----------+-----------+-----------+-----------+ 1769 * |Parameter 1| | Parameter ... | 1770 * +-----------+-----------+-----------+-----------+ 1771 * | | 1772 * | * | 1773 * | * | 1774 * | * | 1775 * | | 1776 * +-----------+-----------+-----------+-----------+ 1777 * | Param N-1 | Parameter N | 1778 * +-----------+-----------+-----------+-----------+ 1779 * 1780 * HCI Event Packet guide: 1781 * 1782 * 0 4 8 12 16 20 24 28 32 1783 * Octet 0 Octet 1 Octet 2 Octet 3 1784 * +-----------+-----------+-----------+-----------+ 1785 * |Event Code | Parameter | | | 1786 * | | Total |Parameter 0|Parameter 1| 1787 * | | Length | | | 1788 * +-----------+-----------+-----------+-----------+ 1789 * |Parameter 1| Parameter ... | 1790 * +-----------+-----------+-----------+-----------+ 1791 * | | 1792 * | * | 1793 * | * | 1794 * | * | 1795 * | | 1796 * +-----------+-----------+-----------+-----------+ 1797 * | Param N-1 | Parameter N | 1798 * +-----------+-----------+-----------+-----------+ 1799 * 1800 * 1801 * HCI ACL Packet Guide: 1802 * 1803 * 0 4 8 1804 * +-----------------------+-----------+-------------+ 1805 * | HCI HEADER | L2CAP HEADER | 1806 * | |(only in Start of packet)| 1807 * |-----------------------|-------------------------| 1808 * |PDU Octet 1 |2 |3 |4 |5 |6 | ***** | 1809 * |-----------------------+-------------------------| 1810 * | * | 1811 * | * | 1812 * | * | 1813 * |-----------------------+-------------------------| 1814 * | ****|N-2 |N-1 |PDU Octet N (upto 247)| 1815 * +-----------------------+-------------------------+ 1816 * 1817 * The ACL Packet HCI Header contains the following 1818 * information: 1819 * +___________________________________________________+ 1820 * |--Conn Handle (12 bits)--|--Pkt Boundary (2 bits)--| 1821 * |-------------------------|-------------------------+ 1822 * |--HCI_LLID(2 bits)------ |--Length(16 bits)-- | 1823 * +-------------------------|-------------------------+ 1824 * 1825 * Note: 1826 * 1. Packet Boundary data indicates the following: 1827 * +-------------+------------------+------------------+ 1828 * | | Application to | Controller to | 1829 * | | Controller | Application | 1830 * +-------------|------------------|------------------| 1831 * | 0x0u | Start of PDU | RESERVED | 1832 * | 0x1u | Continuation PDU | RESERVED | 1833 * | 0x2u | RESERVED | Start of PDU | 1834 * | 0x3u | RESERVED | Continuation PDU | 1835 * +-------------+------------------+------------------+ 1836 * 1837 * 2. HCI_LLID data indicates the following: 1838 * +-------------+------------------| 1839 * | 0x0u | Start of PDU | 1840 * | 0x1u | Continuation PDU | 1841 * | 0x2u | RESERVED | 1842 * | 0x3u | RESERVED | 1843 * ---------------------------------| 1844 * 1845 * 3. The value in the Length field does NOT include 1846 * L2CAP header length (4 bytes). 1847 * 1848 */ 1849 uint8_t * data; 1850 1851 /** Length of the parameters in HCI packet buffer 1852 * in bytes. 1853 */ 1854 uint16_t dataLength; 1855 1856 /** HCI packet type : 1857 * +___________________________________________+ 1858 * | Packet Type | Value | 1859 * |_______________________________|___________| 1860 * | HCI Command packet type | 0x1 | 1861 * | HCI ACL data packet type | 0x2 | 1862 * | HCI Synchronous packet type | 0x3 | 1863 * | HCI Event packet type | 0x4 | 1864 * +-------------------------------|-----------+ 1865 * 1866 * Note: HCI Synchronous packet type (0x3) HCI packets 1867 * are not supported by PSoC 6 BLE 1868 */ 1869 uint8_t packetType; 1870 1871 }cy_stc_ble_hci_tx_packet_info_t; 1872 1873 /** \cond IGNORE */ 1874 1875 /** BLE power modes */ 1876 typedef enum 1877 { 1878 /** Link Layer engine and Digital modem clocked from ECO. 1879 * The CPU can access the BLE Sub-System (BLESS) registers. 1880 * This mode collectively denotes Tx Mode, Rx Mode, and 1881 * Idle mode of BLESS. 1882 */ 1883 CY_BLE_BLESS_ACTIVE = 0x01u, 1884 1885 /** The ECO is stopped and WCO is used to maintain link layer 1886 * timing. RF transceiver is turned off completely to reduce 1887 * leakage current. BLESS logic is kept powered ON from the 1888 * SRSS deep sleep regulator for retention. 1889 */ 1890 CY_BLE_BLESS_DEEPSLEEP, 1891 1892 /** Invalid mode */ 1893 CY_BLE_BLESS_INVALID = 0xFFu 1894 } cy_en_ble_lp_mode_t; 1895 1896 /** \endcond */ 1897 1898 /** BLESS Power enum reflecting power states supported by BLESS radio */ 1899 typedef enum 1900 { 1901 CY_BLE_BLESS_STATE_ACTIVE = 0x01, 1902 CY_BLE_BLESS_STATE_EVENT_CLOSE, 1903 CY_BLE_BLESS_STATE_ECO_ON, 1904 CY_BLE_BLESS_STATE_ECO_STABLE, 1905 CY_BLE_BLESS_STATE_DEEPSLEEP, 1906 CY_BLE_BLESS_STATE_STOPPED, 1907 CY_BLE_BLESS_STATE_INVALID = 0xFFu 1908 } cy_en_ble_bless_state_t; 1909 1910 /** Sleep mode which controller core is trying to enter */ 1911 typedef enum 1912 { 1913 CY_BLE_CONTROLLER_SLEEP_MODE_SLEEP = 0x01u, 1914 CY_BLE_CONTROLLER_SLEEP_MODE_DEEPSLEEP 1915 } cy_en_ble_controller_sleep_mode_t; 1916 1917 /** @} */ 1918 1919 /** 1920 \addtogroup group_ble_common_api_functions 1921 @{ 1922 */ 1923 /****************************************************************************** 1924 * Function Name: Cy_BLE_GetStackLibraryVersion 1925 ***************************************************************************//** 1926 * 1927 * This function retrieves the version information of the BLE Stack library. This 1928 * is a blocking function and no event is generated on calling it. 1929 * 1930 * \param param: Pointer to a variable of type cy_stc_ble_stack_lib_version_t. 1931 * 1932 * \return 1933 * cy_en_ble_api_result_t: Return value indicates whether the function succeeded or 1934 * failed. Following are the possible return codes. 1935 * 1936 * return codes | Description 1937 * ------------ | ----------- 1938 * CY_BLE_SUCCESS | On successful operation. 1939 * CY_BLE_ERROR_INVALID_PARAMETER | param is NULL. 1940 * 1941 ******************************************************************************/ 1942 cy_en_ble_api_result_t Cy_BLE_GetStackLibraryVersion 1943 ( 1944 cy_stc_ble_stack_lib_version_t * param 1945 ); 1946 1947 /** \cond IGNORE */ 1948 1949 /****************************************************************************** 1950 * Function Name: Cy_BLE_StackInit 1951 ***************************************************************************//** 1952 * 1953 * This function initializes the BLE Stack Manager and must be called from the higher 1954 * layer initialization routine only once before invoking any BLE Stack 1955 * functions. It includes initialization of the BLE Stack Manager, BLE Stack, and 1956 * BLE Host modules that make up the BLE Stack. 1957 * 1958 * For HCI-Mode of operation, this function will not initialize the BLE Host Stack 1959 * module. 1960 * 1961 * This is a non-blocking function and a call to this function results in the generation of the following events: 1962 * 1963 * | Event Name | Description | 1964 * | ------------------------------ |-------------------------------------------------------------------------- | 1965 * | CY_BLE_EVT_STACK_ON | Generated by BLE Stack on successful initialization | 1966 * | CY_BLE_EVT_HARDWARE_ERROR | Generated by BLE Stack if initialization fails in single CPU Configuration | 1967 * | CY_BLE_EVT_STACK_SHUTDOWN_COMPLETE | Generated by BLE Stack if initialization fails in dual CPU Configuration | 1968 * 1969 * \param param: parameter is of type 'cy_stc_ble_stack_init_info_t'. 1970 * param->CyBLEApplCbFunc: Event callback function to receive events from BLE Stack. 1971 * cy_ble_app_ev_cb_t is a function pointer type. The application is not expected to call 1972 * BLE Stack functions in the BLE Stack call back context. BLE Stack execution should be allowed to 1973 * return unless the BLE Stack function explicitly mentions otherwise. 1974 * 1975 * The following functions should not be called from the BLE Stack callback context but can be called from the 1976 * 'CY_BLE_EVT_GATTC_ERROR_RSP' or 'CY_BLE_EVT_GATTC_LONG_PROCEDURE_END' events 1977 * or any non long procedure events. 1978 * 1. Cy_BLE_GATTC_DiscoverPrimaryServices() 1979 * 2. Cy_BLE_GATTC_DiscoverPrimaryServiceByUuid() 1980 * 3. Cy_BLE_GATTC_FindIncludedServices() 1981 * 4. Cy_BLE_GATTC_DiscoverCharacteristics() 1982 * 5. Cy_BLE_GATTC_DiscoverCharacteristicByUuid() 1983 * 6. Cy_BLE_GATTC_DiscoverCharacteristicDescriptors() 1984 * 7. Cy_BLE_GATTC_ReadLongCharacteristicValues() 1985 * 8. Cy_BLE_GATTC_WriteLongCharacteristicValues() 1986 * 9. Cy_BLE_GATTC_ReliableWrites() 1987 * 10. Cy_BLE_GATTC_ReadLongCharacteristicDescriptors() 1988 * 11. Cy_BLE_GATTC_WriteLongCharacteristicDescriptors() 1989 * 12. Cy_BLE_GATTC_ReadByTypeReq() 1990 * 1991 * param->memParam.memoryHeapPtr: Pointer to an array of bytes to be allocated by the BLE Component 1992 * (or the application, if the BLE Component's initialization function 1993 * is not used). The size of the memory to be allocated is as 1994 * given below for non-HCI mode build of the BLE Stack. 1995 * 1996 * (CY_BLE_DEFAULT_HOST_RAM_SIZE 1997 * + Accumulative memory for all dataBuff units 1998 * + L2CAP heap requirement 1999 * + CY_BLE_RAM_SECURE_CONNECTIONS_SIZE (Only if Secure Connections feature is enabled) 2000 * + (CY_BLE_STACK_ONE_BONDED_DEVICE_SIZE + CY_BLE_STACK_ONE_DEVICE_Q_ENTITY_SIZE) 2001 * * (CY_BLE_MAX_CONNECTION_INSTANCES + param->bondListConfig.bondListSize) 2002 * + (CY_BLE_STACK_BUFFER_MGR_UTIL_RAM_SZ * totalDataBufferPools)) 2003 * 2004 * Where, CY_BLE_DEFAULT_HOST_RAM_SIZE is a define that is available from 2005 * the BLE Stack. The starting address of the memoryHeapPtr should be four bytes aligned and 2006 * the size of the total memory should be divisible by four. 2007 * 2008 * Accumulative memory for "single data buffer instance" = 2009 * (dataBuff.bufferSize * dataBuff.bufferUnits) 2010 * 2011 * L2CAP heap requirement = 2012 * (CY_BLE_L2CAP_QUEUE_ELEMENT_SIZE * BLE Stack queue depth per connection * 2013 * maxBleConnections ). 2014 * - CY_BLE_L2CAP_QUEUE_ELEMENT_SIZE is a define available in the BLE stack. 2015 * - BLE Stack queue depth per connection should be equal to or higher than 2016 * CY_BLE_L2CAP_STACK_Q_DEPTH_PER_CONN. 2017 * - maxBleConnections specifies number of connections supported. 2018 * 2019 * totalDataBufferPools is "numOfDataBuffSet" 2020 * 2021 * If HCI mode BLE stack is used, the memory to be allocated should 2022 * be of size 'CY_BLE_DEFAULT_RAM_SIZE_HCI'. 2023 * 2024 * param->memParam.totalHeapSz: Size of the total heap memory pointer by memoryHeapPtr. totalHeapSz shall be 2025 * the accumulated value of every dataBuff elements. To compute total size, each element's 2026 * size shall be rounded to next 4-byte boundary value. 2027 * 2028 * For example, a typical value can be computed in following manner: 2029 * 2030 * Size for buffer pool #1 to be added = 2031 * ((CY_BLE_ALIGN_TO_4(Size of GATT MTU) + CY_BLE_MEM_EXT_SZ + CY_BLE_L2CAP_HDR_SZ) * noOfBuffer) 2032 * 2033 * Note that the buffer pool size for each chunk may not be 4-byte boundary aligned, 2034 * and it should be as per user configuration. The BLE Stack's buffer management utility 2035 * internally aligns it to a higher 4-byte boundary. 2036 * 2037 * param->memParam.dataBuff: array of structures of type cy_stc_ble_stk_app_data_buff_t. Ignored in case of HCI mode. 2038 * 2039 * param->memParam.totalDataBufferPools: Number of data buffer sets in the array. Ignored in case of HCI mode. 2040 * 2041 * param->memParam.bleStackFlashPointer: Pointer to the Flash memory. Ignored in case of HCI mode. 2042 * The size of the memory to be allocated is as given below for a non-HCI mode build of the BLE Stack: 2043 * ( 2044 * (CY_BLE_STACK_ONE_BONDED_DEVICE_SIZE * User configured Bonded Devices List size) 2045 * + (CY_BLE_STACK_ONE_DEVICE_Q_ENTITY_SIZE * (CY_BLE_MAX_CONNECTION_INSTANCES + User configured bondlist size)) 2046 * + ((CY_BLE_LL_ONE_WHITELIST_HEAP_REQ * User Configured White List size) + 2047 * CY_BLE_LL_WHITELIST_RETENTION_HEAP_REQ) 2048 * + ((CY_BLE_LL_PRIVACY_HEAP_REQ * User Configured Resolving List size) + 2049 * CY_BLE_LL_PRIVACY_RETENTION_HEAP_REQ)Deterministic Random number generator 2050 * ) 2051 * 2052 * param->memParam.bleStackFlashSize: Size of the total Flash memory pointed by 'bleStackFlashPointer'. 2053 * Ignored in case of HCI mode. 2054 * 2055 * param->stackConfig: BLE Stack configuration parameters such as featuremask, Bonded Devices List, White List & Resolving List size 2056 * configuration, max number of connections, L2CAP configuration. 2057 * 2058 * Array dataBuff [totalDataBufferPools] shall provide the information to BLE Stack based on the below table - 2059 * 2060 * Index | Application config. param | bufferSize | noOfBuffer 2061 * ----- | ---------------------------------- | --------------------------------------------------------------------------------- | --------------- 2062 * 0 | GATT MTU | (GATT MTU + CY_BLE_MEM_EXT_SZ + CY_BLE_L2CAP_HDR_SZ) | 3 2063 * 1 | Num. of PSM supported | ((CY_BLE_L2CAP_PSM_SIZE + CY_BLE_MEM_EXT_SZ) * no of PSM supported) | No of PSM supported 2064 * 2 | Num. of L2CAP CBFC channels | ((CY_BLE_L2CAP_CBFC_CHANNEL_SIZE + CY_BLE_MEM_EXT_SZ) * No of L2CAP logical channels)| 2 * No of L2cap logical channels 2065 * 3 | L2CAP MTU (0x17 to 0xFFD0u) | (L2CAP MTU + CY_BLE_MEM_EXT_SZ + CY_BLE_L2CAP_HDR_SZ) | 2 * No of L2cap logical channels 2066 * 4 | GATT DB max entry (0x1 to 0xFFFFu) | (Max Entry / 8) + CY_BLE_MEM_EXT_SZ | 1 2067 * 2068 * Index position is fixed for each data buffer corresponding to configuration parameters. 2069 * First four buffers with valid size (shall be > 12) corresponding to each field are required 2070 * for single CPU mode operation. Otherwise, the BLE Stack will throw an error. 2071 * 2072 * 'dataBuff' will be modified by stack. If the application wants to reuse dataBuff, the application should keep a copy of it. 2073 * 2074 * *No of buffers should be increased from 3 to BLE Stack queue depth. if mtu>23. 2075 * BLE Stack queue depth = (stack queue depth per connection - 1) * maxBleConnection 2076 * 2077 * 2078 * \return 2079 * cy_en_ble_api_result_t : Return value indicates whether the function succeeded or 2080 * failed. Following are the possible error codes. 2081 * 2082 * Error codes | Description 2083 * ------------ | ----------- 2084 * CY_BLE_SUCCESS | On successful operation. 2085 * CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED | Memory allocation failed. 2086 * CY_BLE_ERROR_INVALID_PARAMETER | On passing a "NULL" for 'CyBLEApplCbFunc' parameter if the BLE stack is not built in HCI mode. On passing a "NULL" for 'memoryHeapPtr' parameter. If maxMtuSize is less than 23 or greater than 512 (only if BLE stack is not built in HCI mode). 2087 * CY_BLE_ERROR_REPEATED_ATTEMPTS | On invoking this function more than once without calling Cy_BLE_StackShutdown() function between calls to this function if the BLE stack is not built in HCI mode. 2088 * 2089 ******************************************************************************/ 2090 cy_en_ble_api_result_t Cy_BLE_StackInit 2091 ( 2092 cy_stc_ble_stack_init_info_t * param 2093 ); 2094 2095 /** \cond group_ble_common_HCI_api_functions */ 2096 2097 /****************************************************************************** 2098 * Function Name: Cy_BLE_ControllerStackInit 2099 ***************************************************************************//** 2100 * 2101 * This function initializes the BLE Stack Manager and must be called from the higher 2102 * layer initialization routine only once before invoking any BLE Stack 2103 * functions. It includes initialization of the BLE Stack Manager and BLE Controller Stack. 2104 * 2105 * For HCI-Mode of operation, this function will not initialize the BLE Host Stack 2106 * module. 2107 * 2108 * \param param: parameter is of type 'cy_stc_ble_stack_init_info_t'. 2109 * param->CyBLEApplCbFunc: Event callback function to receive events from BLE Stack. 2110 * cy_ble_app_ev_cb_t is a function pointer type. The application is not expected to call 2111 * BLE Stack functions in the BLE Stack call back context. BLE Stack execution should be allowed to 2112 * return unless the BLE Stack function explicitly mentions otherwise. 2113 * 2114 * param->memParam.memoryHeapPtr: Pointer to an array of bytes to be allocated by the BLE Component 2115 * (or the application, if the BLE Component's initialization function 2116 * is not used). The memory to be allocated should 2117 * be of size 'CY_BLE_DEFAULT_RAM_SIZE_HCI'. 2118 * 2119 * param->memParam.totalHeapSz: Size of the total heap memory pointer by memoryHeapPtr. totalHeapSz shall be 2120 * the accumulated value of every dataBuff elements. To compute total size, each element's 2121 * size shall be rounded to next 4-byte boundary value. 2122 * 2123 * For example, a typical value can be computed in following manner: 2124 * 2125 * Size for buffer pool #1 to be added = 2126 * ((CY_BLE_ALIGN_TO_4(Size of GATT MTU) + CY_BLE_MEM_EXT_SZ + CY_BLE_L2CAP_HDR_SZ) * noOfBuffer) 2127 * 2128 * Note that the buffer pool size for each chunk may not be 4-byte boundary aligned, 2129 * and it should be as per user configuration. The BLE Stack's buffer management utility 2130 * internally aligns it to a higher 4-byte boundary. 2131 * 2132 * param->memParam.dataBuff: Ignored for this API. This is used in Profile mode of the BLE Component. 2133 * 2134 * param->memParam.totalDataBufferPools: Ignored for this API. This is used in Profile mode of the BLE Component. 2135 * 2136 * param->memParam.bleStackFlashPointer: Ignored for this API. This is used in Profile mode of the BLE Component. 2137 * 2138 * param->memParam.bleStackFlashSize: Ignored for this API. This is used in Profile mode of the BLE Component. 2139 * 2140 * param->stackConfig: BLE Stack configuration parameters such as featuremask, Bonded Devices List, White List & Resolving List size 2141 * configuration, max number of connections, etc. 2142 * 2143 * \return 2144 * cy_en_ble_api_result_t : Return value indicates whether the function succeeded or 2145 * failed. Following are the possible error codes. 2146 * 2147 * Error codes | Description 2148 * ------------ | ----------- 2149 * CY_BLE_SUCCESS | On successful operation. 2150 * CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED | Memory allocation failed. 2151 * CY_BLE_ERROR_INVALID_PARAMETER | On passing a "NULL" for 'CyBLEApplCbFunc' parameter if the BLE stack is not built in HCI mode. On passing a "NULL" for 'memoryHeapPtr' parameter. If maxMtuSize is less than 23 or greater than 512 (only if BLE stack is not built in HCI mode). 2152 * CY_BLE_ERROR_REPEATED_ATTEMPTS | On invoking this function more than once without calling Cy_BLE_StackShutdown() function between calls to this function if the BLE stack is not built in HCI mode. 2153 * 2154 ******************************************************************************/ 2155 cy_en_ble_api_result_t Cy_BLE_ControllerStackInit 2156 ( 2157 cy_stc_ble_stack_init_info_t * param 2158 ); 2159 2160 /****************************************************************************** 2161 * Function Name: Cy_BLE_StackShutdown 2162 ***************************************************************************//** 2163 * This function stops any ongoing operation on the BLE Stack and forces the BLE 2164 * Stack to shut down. The only function that can be called after calling this 2165 * function is Cy_BLE_StackInit(). On calling this function, BLE Radio is turned 2166 * off; all the data loaded in Flash memory is retained and can be used on 2167 * re-initializing the BLE Stack. 2168 * 2169 * Shutdown complete is informed through 'CY_BLE_EVT_STACK_SHUTDOWN_COMPLETE' event. 2170 * Cy_BLE_ProcessEvents() function must be called to receive this event. 2171 * 2172 * For UART HCI mode: 2173 * This is a blocking function and no event is generated. 2174 * Only CY_BLE_SUCCESS will be returned and other error codes are not applicable. 2175 * The UART interface will be stopped and UART data will not be processed by the BLE Stack 2176 * until Cy_BLE_StackInit() function is invoked. 2177 * 2178 * \return 2179 * cy_en_ble_api_result_t : Return value indicates whether the function succeeded or 2180 * failed. Following are the possible error codes. 2181 * 2182 * Errors codes | Description 2183 * ------------ | ----------- 2184 * CY_BLE_SUCCESS | On successful operation. 2185 * CY_BLE_ERROR_INVALID_OPERATION | On calling shutdown even before calling Cy_BLE_StackInit() 2186 * 2187 ******************************************************************************/ 2188 cy_en_ble_api_result_t Cy_BLE_StackShutdown 2189 ( 2190 void 2191 ); 2192 2193 /** \endcond */ 2194 2195 /****************************************************************************** 2196 * Function Name: Cy_BLE_StackSoftReset 2197 ***************************************************************************//** 2198 * 2199 * This function resets the BLE Stack, including BLE sub-system hardware 2200 * registers. The BLE Stack transitions to idle mode. This function can be used to 2201 * reset the BLE Stack if the BLE Stack turns unresponsive. This function can be 2202 * used when the application wishes to keep the BLE ECO clock running. 2203 * 2204 * Reset complete is informed through 'CY_BLE_EVT_SOFT_RESET_COMPLETE event'. 2205 * 2206 * \return 2207 * cy_en_ble_api_result_t : Return value indicates whether the function succeeded or 2208 * failed. Following are the possible error codes. 2209 * 2210 * Errors codes | Description 2211 * ------------ | ----------- 2212 * CY_BLE_SUCCESS | On successful operation. 2213 * CY_BLE_ERROR_INVALID_OPERATION | On calling this function before calling Cy_BLE_StackInit() 2214 * 2215 ******************************************************************************/ 2216 cy_en_ble_api_result_t Cy_BLE_StackSoftReset 2217 ( 2218 void 2219 ); 2220 2221 2222 /****************************************************************************** 2223 * Function Name: Cy_BLE_ProcessEvents 2224 ***************************************************************************//** 2225 * 2226 * This function checks the internal task queue in the BLE Stack, and pending 2227 * operation of the BLE Stack, if any. This must be called at least once 2228 * every interval 't' where: 2229 * 1. 't' is equal to connection interval or scan interval, whichever is 2230 * smaller, if the device is in GAP Central mode of operation, or 2231 * 2. 't' is equal to connection interval or advertisement interval, 2232 * whichever is smaller, if the device is in GAP Peripheral mode 2233 * of operation. 2234 * 2235 * On calling at every interval 't', all pending operations of the BLE Stack are 2236 * processed. This is a blocking function and returns only after processing all 2237 * pending events of the BLE Stack. Care should be taken to prevent this call 2238 * from any kind of starvation; on starvation, events may be dropped by the 2239 * stack. All the events generated will be propagated to higher layers of the 2240 * BLE Stack and to the Application layer only after making a call to this 2241 * function. 2242 * 2243 * Calling this function can wake BLESS from deep sleep mode (DSM). In the process 2244 * of waking from BLESS DSM, the BLE Stack puts the CPU into sleep mode to 2245 * save power while polling for a wakeup indication from BLESS. BLESS Wakeup from DSM 2246 * can occur if the stack has pending data or control transactions to be performed. 2247 * 2248 * \return 2249 * None 2250 * 2251 ******************************************************************************/ 2252 void Cy_BLE_ProcessEvents 2253 ( 2254 void 2255 ); 2256 2257 /** \cond IGNORE */ 2258 2259 /****************************************************************************** 2260 * Function Name: Cy_BLE_StackSetFeatureConfig 2261 ***************************************************************************//** 2262 * 2263 * This function sets the configuration for Bluetooth 5.0 features in the BLE Stack to 2264 * initialize the corresponding data structures and data buffers to support 2265 * the features. The BLE Stack will create the data buffers for the Data length extension 2266 * feature, LE Privacy 1.2, and LE Secure connections as specified in the parameters, 2267 * during Stack initialization. This function should be called before Cy_BLE_StackInit(). 2268 * 2269 * This is a blocking function. No event is generated on calling this function. 2270 * 2271 * \param param: parameter of type 'CY_BLE_STACK_SET_CONFIG_PARAM_T' 2272 * param->configParam: parameter of type cy_stc_ble_stack_config_param_t. This structure contains 2273 * pointers to config params for individual features. Individual 2274 * feature configuration structures can be NULL if that feature is 2275 * not selected. 2276 * 2277 * param->featureHeapReq: parameter for returning memory requirement for selected features. 2278 * 2279 * 2280 * \return 2281 * cy_en_ble_api_result_t : Return value indicates if the function succeeded or 2282 * failed. Following are the possible error codes. 2283 * 2284 * Errors codes | Description 2285 * ------------ | ----------- 2286 * CY_BLE_SUCCESS | On successful operation. 2287 * CY_BLE_ERROR_INVALID_PARAMETER | Invalid configuration parameters passed or invalid combination of configParam and featureMask. 2288 * CY_BLE_ERROR_INVALID_OPERATION | Invoked after BLE Stack initialization. 2289 * 2290 ******************************************************************************/ 2291 cy_en_ble_api_result_t Cy_BLE_StackSetFeatureConfig 2292 ( 2293 cy_stc_ble_stack_config_param_t * param 2294 ); 2295 2296 /****************************************************************************** 2297 * Function Name: Cy_BLE_ControllerStackSetFeatureConfig 2298 ***************************************************************************//** 2299 * 2300 * This function sets the configuration for Bluetooth 5.0 features in the BLE Stack to 2301 * initialize the corresponding data structures and data buffers to support 2302 * the features. The BLE Stack will create the data buffers for the Data length extension 2303 * feature, LE Privacy 1.2, and LE Secure connections as specified in the parameters, 2304 * during Stack initialization. This function should be called before Cy_BLE_StackInit(). 2305 * 2306 * This is a blocking function. No event is generated on calling this function. 2307 * 2308 * \param param: parameter of type 'CY_BLE_STACK_SET_CONFIG_PARAM_T' 2309 * param->configParam: parameter of type cy_stc_ble_stack_config_param_t. This structure contains 2310 * pointers to config params for individual features. Individual 2311 * feature configuration structures can be NULL if that feature is 2312 * not selected. 2313 * 2314 * param->featureHeapReq: parameter for returning memory requirement for selected features. 2315 * 2316 * 2317 * \return 2318 * cy_en_ble_api_result_t : Return value indicates if the function succeeded or 2319 * failed. Following are the possible error codes. 2320 * 2321 * Errors codes | Description 2322 * ------------ | ----------- 2323 * CY_BLE_SUCCESS | On successful operation. 2324 * CY_BLE_ERROR_INVALID_PARAMETER | Invalid configuration parameters passed or invalid combination of configParam and featureMask. 2325 * CY_BLE_ERROR_INVALID_OPERATION | Invoked after BLE Stack initialization. 2326 * 2327 ******************************************************************************/ 2328 cy_en_ble_api_result_t Cy_BLE_ControllerStackSetFeatureConfig 2329 ( 2330 cy_stc_ble_stack_config_param_t * param 2331 ); 2332 2333 /******************************************************************************* 2334 * Function Name: Cy_BLE_StackGetFeatureConfig 2335 ****************************************************************************//** 2336 * 2337 * This function is used to get the status of Bluetooth 5.0 feature configuration made to the BLE Stack 2338 * during BLE Stack initialization. 2339 * 2340 * This is a blocking function. No event is generated on calling this function. 2341 * 2342 * \param param: pointer to cy_stc_ble_stack_config_param_t. This structure 2343 * contains pointers to config params for individual 2344 * features such as Data length extension feature, LE Privacy 1_2, 2345 * and LE Secure connections. Application shall provide memory for this 2346 * configuration structure. 2347 * 2348 * \return 2349 * cy_en_ble_api_result_t : Return value indicates whether the function succeeded or 2350 * failed. Following are the possible error codes. 2351 * 2352 * Errors codes | Description 2353 * ------------ | ----------- 2354 * CY_BLE_SUCCESS | On successful operation. 2355 * CY_BLE_ERROR_INVALID_PARAMETER | If param pointer is NULL. 2356 * 2357 ******************************************************************************/ 2358 cy_en_ble_api_result_t Cy_BLE_StackGetFeatureConfig 2359 ( 2360 cy_stc_ble_stack_config_param_t * param 2361 ); 2362 /** \endcond */ 2363 2364 /****************************************************************************** 2365 * Function Name: Cy_BLE_SetCustomEventMask 2366 ***************************************************************************//** 2367 * This function is used to set the mask that will enable/disable any custom/customer 2368 * specific events that are exposed by the Stack. 2369 * 2370 * This is a Non Blocking function and success is informed through the 2371 * 'CY_BLE_EVT_SET_EVENT_MASK_COMPLETE' event. 2372 * 2373 * \param mask: A variable of type UINT32, containing the mask bits. 2374 * Following are the supported Mask values 2375 * CY_BLE_DISABLE_ALL_EVENTS_MASK - Disables all custom events 2376 * CY_BLE_CONN_ESTB_EVENT_MASK - For connection establishment 2377 * events 2378 * CY_BLE_ADV_TX_EVENT_MASK - For advertisement packet sent 2379 * events 2380 * \return 2381 * cy_en_ble_api_result_t : Return value indicates whether the function succeeded or 2382 * failed. Following are the possible error codes. 2383 * 2384 * Errors codes | Description 2385 * ------------ | ----------- 2386 * CY_BLE_SUCCESS | On successful operation. 2387 * CY_BLE_ERROR_INVALID_PARAMETER | One of the input parameter is invalid. 2388 * CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED | If Memory allocation failed. 2389 * CY_BLE_ERROR_INSUFFICIENT_RESOURCES | If BLE Stack resources are unavailable. 2390 * 2391 ******************************************************************************/ 2392 2393 cy_en_ble_api_result_t Cy_BLE_SetCustomEventMask 2394 ( 2395 uint32_t mask 2396 ); 2397 2398 /** \cond IGNORE */ 2399 2400 /****************************************************************************** 2401 * Function Name: Cy_BLE_StackEnterLPM 2402 ***************************************************************************//** 2403 * 2404 * This function is used by BLE Component to request the BLE Sub-System (BLESS) to enter deep sleep mode. This function should not be 2405 * called by the application directly, instead application should use Cy_SysPm_DeepSleep function (which internally calls this function). 2406 * Based on the current state of the radio and the link layer timing, BLESS may fail to enter deep sleep mode. 2407 * The return value of this function should be used to check if the deep sleep entry request was successful or not. 2408 * Based on the return value, the CPU or the entire device can enter their respective low power modes. 2409 * 2410 * BLESS has following power modes: 2411 * 1. Active - BLESS, which includes the radio and the link layer, is active and CPU has access to all the BLESS registers in this mode 2412 * 2. Deep sleep (low power Mode) - All the high-frequency blocks in BLESS and the BLE ECO are shutdown and the BLE link layer timing is 2413 * maintained using low frequency clocks (WCO or ILO). CPU will not be able to access the BLESS registers in this mode. 2414 * 2415 * If the application is using the BLE ECO as source of HFCLK for higher clock accuracy, it must switch the HFCLK to non BLE ECO clock 2416 * before calling this (or Cy_SysPm_DeepSleep) function. 2417 * 2418 * The following table indicates the allowed power modes for the complete system 2419 * (BLE Sub-system and the micro-controller). Modes marked In 'X' are the allowed 2420 * combinations. The application layer should make sure that the invalid modes 2421 * are never entered into. 2422 * 2423 * \code 2424 * |-------------------------------------------------------------------------------| 2425 * | | MCU | 2426 * | BLESS |--------------|-------------|----------------|---------------| 2427 * | | CPU active | CPU sleep | CPU deep sleep | CPU hibernate | 2428 * |-----------------|--------------|-------------|----------------|---------------| 2429 * | Active | X | X | | | 2430 * | Deep sleep | X | X | X | | 2431 * |-------------------------------------------------------------------------------| 2432 * \endcode 2433 * 2434 * 2435 * This is a blocking function. In the process of entering into BLESS deep sleep mode, 2436 * the BLE Stack puts the CPU into sleep mode to save power while polling 2437 * for an entry indication to BLESS deep sleep mode. No event is generated on calling this function. 2438 * 2439 * \param pwrMode: The power mode that the BLE Stack is intended to 2440 * enter. The allowed value is CY_BLE_BLESS_DEEPSLEEP 2441 * 2442 * \return 2443 * cy_en_ble_lp_mode_t : The actual power mode to which the BLE Stack is now set. 2444 * 2445 ******************************************************************************/ 2446 2447 cy_en_ble_lp_mode_t Cy_BLE_StackEnterLPM(cy_en_ble_lp_mode_t pwrMode); 2448 2449 /** \endcond */ 2450 2451 /** \cond group_ble_common_HCI_api_functions */ 2452 2453 /****************************************************************************** 2454 * Function Name: Cy_BLE_ControllerEnterLPM 2455 ***************************************************************************//** 2456 * 2457 * This API requests BLE Controller to enter into low power mode. 2458 * It will put BLE controller firmware and BLE SS (BLE LL hardware & BLE radio) 2459 * into requested low power mode if following conditions meet: 2460 * 1) Sleep mode: Transmit or Receive operation is not active in BLE controller 2461 * or they are not scheduled in near future. 2462 * 2) Deep sleep mode: Transmit or Receive operation is not active in BLE 2463 * controller or they are not scheduled in near future. 2464 * Condition: curr_time_slot > DSM_THRESHOLD 2465 * DSM_THRESHOLD typically includes ECO -XTAL crystal stabilization time, radio, 2466 * LL hardware wake up time from accurate clock source. 2467 * 3) Hibernate Mode: This mode is only allowed if BLE controller is idle 2468 * and no other future activity (Tx/Rx) is scheduled such as BLE Connection, 2469 * BLE advertiser, BLE Scanner. 2470 * 2471 * This API returns the current operational mode of BLE Controller Stack after 2472 * processing request from the caller API. 2473 * 2474 * 2475 * Parameters: 2476 * CY_BLE_CONTROLLER_LP_MODE pwrMode: Enumeration containing value for 2477 * requested low power mode operation. 2478 * 2479 * Return: 2480 * CY_BLE_CONTROLLER_LP_MODE pwrMode: Current operational mode of BLE 2481 * Controller Stack after processing request from the caller API. 2482 2483 * 2484 ******************************************************************************/ 2485 2486 cy_en_ble_lp_mode_t Cy_BLE_ControllerEnterLPM(cy_en_ble_lp_mode_t pwrMode); 2487 2488 /** \endcond */ 2489 2490 2491 /****************************************************************************** 2492 * Function Name: Cy_BLE_StackGetBleSsState 2493 ***************************************************************************//** 2494 * 2495 * This function returns the BLE Subsystem's current operational mode. This state 2496 * can be used to manage system level power modes. 2497 * 2498 * \return: 2499 * cy_en_ble_bless_state_t : BLESS's operating mode has one of the following values 2500 * 2501 * BLE Stack Mode | Description 2502 * -------------- | ----------- 2503 * CY_BLE_BLESS_STATE_ACTIVE | BLE Sub System is in active mode, CPU can be in active mode or sleep mode. 2504 * CY_BLE_BLESS_STATE_EVENT_CLOSE| BLE Sub System radio and Link Layer hardware finished Tx/Rx. In this state, the application can try configuring the BLE stack to deep sleep mode. 2505 * CY_BLE_BLESS_STATE_ECO_STABLE | BLE Sub System is in the process of waking up from deep sleep mode and the BLE ECO is stable. The CPU can be configured in sleep mode. 2506 * CY_BLE_BLESS_STATE_DEEPSLEEP | BLE Sub System is in deep sleep mode. CPU can be configured in deep sleep mode. 2507 * 2508 ******************************************************************************/ 2509 cy_en_ble_bless_state_t Cy_BLE_StackGetBleSsState(void); 2510 2511 /** \cond IGNORE */ 2512 2513 /****************************************************************************** 2514 * Function Name: Cy_BLE_IsControllerActive 2515 ***************************************************************************//** 2516 * 2517 * This function checks whether any of the protocol engines of the BLE controller are 2518 * active. If either of ADV/SCAN/INIT/CONN engine is active, it returns CY_BLE_SUCCESS. 2519 * 2520 * \param checkForMode: Sleep mode which the Controller core is trying to enter 2521 * CY_BLE_CONTROLLER_SLEEP_MODE_SLEEP - Check whether controller core can enter sleep mode 2522 * CY_BLE_CONTROLLER_SLEEP_MODE_DEEPSLEEP - Check whether controller core can enter deep sleep mode 2523 * 2524 * \return 2525 * cy_en_ble_api_result_t : Returns whether the controller is active or not. 2526 * 2527 * Return value | Description 2528 * ------------ | ----------- 2529 * CY_BLE_SUCCESS | BLE Stack is active. 2530 * CY_BLE_ERROR_INVALID_OPERATION | BLE Stack is not active. 2531 * 2532 ******************************************************************************/ 2533 cy_en_ble_api_result_t Cy_BLE_IsControllerActive(cy_en_ble_controller_sleep_mode_t checkForMode); 2534 /** \endcond */ 2535 2536 /** @} */ 2537 2538 /** 2539 \addtogroup group_ble_common_Privacy_api_functions 2540 @{ 2541 */ 2542 2543 /****************************************************************************** 2544 * Function Name: Cy_BLE_EnablePrivacyFeature 2545 ***************************************************************************//** 2546 * 2547 * This function enables Link Layer (LL) Privacy feature in the 2548 * BLE Stack. LL privacy feature is disabled and memory space for the feature is not used by default. 2549 * This function is called by the BLE Component during BLE initialization if the 2550 * CY_BLE_CONFIG_ENABLE_LL_PRIVACY macro is set by the user. 2551 * 2552 * \return 2553 * None. 2554 * 2555 ******************************************************************************/ 2556 void Cy_BLE_EnablePrivacyFeature 2557 ( 2558 void 2559 ); 2560 2561 /** @} */ 2562 2563 /** 2564 \addtogroup group_ble_common_HCI_api_functions 2565 @{ 2566 */ 2567 /** \cond IGNORE */ 2568 /****************************************************************************** 2569 * Function Name: Cy_BLE_ControllerEnablePrivacyFeature 2570 ***************************************************************************//** 2571 * 2572 * This function Enables Privacy features in 2573 * controller. When this function is not called in the application, 2574 * Privacy features gets disabled and memory space used in the controller 2575 * is relenquished. 2576 * 2577 * \return 2578 * None. 2579 * 2580 ******************************************************************************/ 2581 void Cy_BLE_ControllerEnablePrivacyFeature 2582 ( 2583 void 2584 ); 2585 /** \endcond */ 2586 /** @} */ 2587 2588 /** 2589 \addtogroup group_ble_common_Data_length_extension_api_functions 2590 @{ 2591 */ 2592 /** \cond IGNORE */ 2593 2594 /****************************************************************************** 2595 * Function Name: Cy_BLE_EnableDleFeature 2596 ***************************************************************************//** 2597 * 2598 * This function Enables Data Length Extension (DLE) feature in the 2599 * BLE Stack. DLE features are disabled and memory space for the feature is not used by default. This 2600 * function is called by the BLE Component during BLE initialization if either of 2601 * CY_BLE_CONFIG_LL_MAX_TX_PAYLOAD_SIZE or CY_BLE_CONFIG_LL_MAX_RX_PAYLOAD_SIZE macro 2602 * is configured by the user to a value greater than 27 octets. 2603 * 2604 * \return 2605 * None. 2606 * 2607 ******************************************************************************/ 2608 void Cy_BLE_EnableDleFeature 2609 ( 2610 void 2611 ); 2612 2613 /** \endcond */ 2614 2615 /** @} */ 2616 2617 /** 2618 \addtogroup group_ble_common_HCI_api_functions 2619 @{ 2620 */ 2621 /** \cond IGNORE */ 2622 2623 /****************************************************************************** 2624 * Function Name: Cy_BLE_ControllerEnableDleFeature 2625 ***************************************************************************//** 2626 * 2627 * This function Enables Data Length Extension features in 2628 * controller. When this function is not called in the application, 2629 * DLE features gets disabled and memory space used in the controller 2630 * is relenquished. 2631 * 2632 * \return 2633 * None. 2634 * 2635 ******************************************************************************/ 2636 void Cy_BLE_ControllerEnableDleFeature 2637 ( 2638 void 2639 ); 2640 /** \endcond */ 2641 2642 2643 /** @} */ 2644 2645 /** 2646 \addtogroup group_ble_common_2MBPS_api_functions 2647 @{ 2648 */ 2649 /** \cond IGNORE */ 2650 /****************************************************************************** 2651 * Function Name: Cy_BLE_EnablePhyUpdateFeature 2652 ***************************************************************************//** 2653 * 2654 * This function Enables PHY Update (for 2 Mbps bitrate) feature in the 2655 * BLE Stack. The PHY Update feature is disabled and memory space for the feature is not used by default. 2656 * This function is called by the BLE Component during BLE initialization if the 2657 * CY_BLE_CONFIG_ENABLE_PHY_UPDATE macro. 2658 * 2659 * \return 2660 * None. 2661 * 2662 ******************************************************************************/ 2663 void Cy_BLE_EnablePhyUpdateFeature 2664 ( 2665 void 2666 ); 2667 /** \endcond */ 2668 2669 /** @} */ 2670 2671 /** 2672 \addtogroup group_ble_common_HCI_api_functions 2673 @{ 2674 */ 2675 /** \cond IGNORE */ 2676 2677 /****************************************************************************** 2678 * Function Name: Cy_BLE_ControllerEnablePhyUpdateFeature 2679 ***************************************************************************//** 2680 * 2681 * This function Enables PHY Update (2Mbps bitrate) feature in 2682 * controller. When this function is not called in the application, 2683 * PHY Update feature gets disabled and memory space used in the controller 2684 * is relenquished. This function is called by the BLE Component during BLE initialization if the 2685 * CY_BLE_CONFIG_ENABLE_PHY_UPDATE macro. 2686 * 2687 * \return 2688 * None. 2689 * 2690 ******************************************************************************/ 2691 void Cy_BLE_ControllerEnablePhyUpdateFeature 2692 ( 2693 void 2694 ); 2695 /** \endcond */ 2696 2697 /** @} */ 2698 2699 /** 2700 \addtogroup group_ble_common_HCI_api_functions 2701 @{ 2702 */ 2703 /****************************************************************************** 2704 * Function Name: Cy_BLE_SoftHciSendAppPkt 2705 ***************************************************************************//** 2706 * 2707 * This function sends a HCI packet to the BLE Stack's Controller when the Soft Transport feature is 2708 * enabled using the Cy_BLE_SoftHciTransportEnable() API. Application should allocate memory 2709 * for the buffer to hold the HCI packet passed as an input parameter. This API copies the 2710 * HCI packet into the controller's HCI buffer. Hence, the Application may deallocate the 2711 * memory buffer created to hold the HCI packet, once the API returns. 2712 * 2713 * \param HciPktParams: HCI packet which the application wants to push to the BLE Stack's Controller. 2714 * 2715 * 2716 * \return 2717 * cy_en_ble_api_result_t : Returns whether the controller is active or not. 2718 * 2719 * Return value | Description 2720 * ------------ | ----------- 2721 * CY_BLE_SUCCESS | On successful operation. 2722 * CYBLE_ERROR_INVALID_PARAMETER | HciPktParams Parameter is NULL. 2723 * CY_BLE_ERROR_INVALID_OPERATION | Operation not permitted. 2724 * CYBLE_ERROR_MEMORY_ALLOCATION_FAILED | Memory allocation failed. 2725 * 2726 ******************************************************************************/ 2727 cy_en_ble_api_result_t Cy_BLE_SoftHciSendAppPkt 2728 ( 2729 cy_stc_ble_hci_tx_packet_info_t *HciPktParams 2730 ); 2731 2732 /** @} */ 2733 2734 #ifdef __cplusplus 2735 } 2736 #endif /* __cplusplus */ 2737 2738 #endif //CY_BLE_STACK_H_ 2739
