General Description

These are APIs common to both GAP Central role and GAP Peripheral role.

You may use them in either roles.

No letter is appended to the API name: Cy_BLE_GAP_

Functions
cy_en_ble_api_result_t	Cy_BLE_GAP_SetIoCap (const cy_en_ble_gap_iocap_t *param)
	This function sets the IO capability that is used during pairing procedure. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_SetSecurityRequirements (cy_stc_ble_gap_sec_req_t *param)
	This function sets the security requirements of local device and encryption key size requirement of the local device. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_SetOobData (cy_stc_ble_gap_oob_info_t *param)
	This function is used to set the Out of Band (OOB) presence flag and Out of Band (OOB) data received from peer device. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_GenerateBdAddress (cy_stc_ble_gap_bd_addr_info_t *param)
	This function generates either public or random address based on 'type' specified by param->'addrType'. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_Disconnect (cy_stc_ble_gap_disconnect_info_t *param)
	This function is used to terminate the LE connection with specified peer device. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_GetPeerBdAddr (cy_stc_ble_gap_peer_addr_info_t *param)
	This function reads the peer Bluetooth device address identified by 'bdHandle'. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_GetPeerBdHandle (cy_stc_ble_gap_peer_addr_info_t *param)
	This function reads the bdHandle of the peer device (identified by its BD address). More...

cy_en_ble_api_result_t	Cy_BLE_GAP_GetPeerDevSecurity (cy_stc_ble_gap_auth_info_t *param)
	This function enables the application to get the peer device security information identified by 'bdHandle', when the peer device is in bonded list. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_GetPeerDevSecurityKeyInfo (cy_stc_ble_gap_sec_key_info_t *param)
	This function enables the application to know the key shared during the bonding procedure by a peer device upon completion of the bonding procedure. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_GetLocalDevSecurityKeyInfo (cy_stc_ble_gap_sec_key_info_t *param)
	This function gets the local device's keys and key flags. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_SetSecurityKeys (cy_stc_ble_gap_sec_key_info_t *param)
	This function sets the security keys that are to be exchanged with a peer device during key exchange stage of the authentication procedure and sets it in the BLE Stack. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_GenerateKeys (cy_stc_ble_gap_sec_key_info_t *param)
	This function generates the security keys as per application requirement. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_AuthReq (cy_stc_ble_gap_auth_info_t *param)
	This function starts authentication/pairing procedure with the peer device. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_AuthPassKeyReply (cy_stc_ble_gap_auth_pk_info_t *param)
	This function sends a passkey for authentication. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_FixAuthPassKey (cy_stc_ble_gap_auth_fix_pk_info_t *param)
	This function Sets or clears a fixed passkey to be used during authenticated pairing procedure. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_SetSecureConnectionsOnlyMode (cy_stc_ble_gap_sc_mode_info_t *param)
	This function sets the BLE Stack to use Secure Connection Only mode for pairing. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_GenerateSetLocalP256Keys (void)
	This function is used to generate and set P-256 Public-Private key pair to be used during LE Secure connection pairing procedure. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_SetLocalP256Keys (cy_stc_ble_gap_smp_local_p256_keys_t *param)
	This function is used to set a application provided P-256 Public-Private key pair to be used during the LE Secure connection pairing procedure. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_AuthSendKeyPress (cy_stc_ble_gap_sc_kp_notif_info_t *param)
	This function is used to send the LE Secure connection key press notification to a peer device during secure connection pairing. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_GenerateOobData (cy_stc_ble_gap_sc_oob_info_t *param)
	This function is used to generate OOB information to be used by the peer device. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_SetBdAddress (cy_stc_ble_gap_bd_addr_t *param)
	This function informs Bluetooth device address to BLE Stack for its operation. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_GetBdAddress (void)
	This function reads the Bluetooth device address currently used by BLE Stack. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_SetIdAddress (const cy_stc_ble_gap_bd_addr_t *param)
	This function sets the device's identity address in the BLE Stack. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_GetBondList (cy_stc_ble_gap_bonded_device_list_info_t *param)
	This function returns the count of bonded devices and the list of bonded devices with their BD address and bdHandle. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_RemoveDeviceFromBondList (cy_stc_ble_gap_bd_addr_t *param)
	This function removes the specified device from the bond list. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_RemoveOldestDeviceFromBondedList (void)
	This function removes the oldest device from the bond List. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_SetCeLengthParam (cy_stc_ble_gap_ce_length_param_info_t *param)
	This function sets the connection event length to be used for a specific connection. More...

cy_en_ble_api_result_t	Cy_BLE_GAP_SetConnectionPriority (cy_stc_ble_gap_set_conn_priority_param_t *param)
	This function sets the Controller connection priority to be used for a connection during arbitration. More...

Function Documentation

◆ Cy_BLE_GAP_SetIoCap()

cy_en_ble_api_result_t Cy_BLE_GAP_SetIoCap ( const cy_en_ble_gap_iocap_t * param )

This function sets the IO capability that is used during pairing procedure.

This is a blocking function. No event is generated on calling this function.

The input capabilities are described in the following table:

Capability	Description
No input	Device does not have the ability to indicate "yes" or "no".
Yes/No	Device has at least two buttons that can be easily mapped to "yes" and "no" or the device has a mechanism whereby the user can indicate either "yes" or "no".
Keyboard	Device has a numeric keyboard that can input the numbers "0" through "9" and a confirmation. Device also has at least two buttons that can be easily mapped to "yes" and "no" or the device has a mechanism whereby the user can indicate either "yes" or "no".

The output capabilities are described in the following table:

Capability	Description
No output	Device does not have the ability to display or communicate a 6-digit decimal number.
Numeric output	Device has the ability to display or communicate a 6-digit decimal number.

The combined capability is defined in the following table:

Input Capability	No Output	Numeric Output
No input	NoInputNoOutput	DisplayOnly
Yes/No	NoInputNoOutput	DisplayYesNo
Keyboard	KeyboardOnly	KeyboardDisplay

For more details, refer to Bluetooth Core Spec 5.0, Vol 3, Part C, 5.2.2.4

Parameters

param IO parameter is of type cy_en_ble_gap_iocap_t.

Returns: cy_en_ble_api_result_t : Return value indicates if the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation
CY_BLE_ERROR_INVALID_PARAMETER	On specifying invalid input parameter

◆ Cy_BLE_GAP_SetSecurityRequirements()

cy_en_ble_api_result_t Cy_BLE_GAP_SetSecurityRequirements ( cy_stc_ble_gap_sec_req_t * param )

This function sets the security requirements of local device and encryption key size requirement of the local device.

This is a blocking function. No event is generated on calling this function. Application should call this function on receiving 'CY_BLE_EVT_STACK_ON' event. The Security requirements are defined in the following table:

Security Requirement	Description
CY_BLE_GAP_NO_SECURITY_REQUIREMENTS	Default:Security requirement specifies there are no security requirements
CY_BLE_GAP_SEC_UNAUTH_PAIRING	Bit 0: Legacy pairing with NO MITM protection
CY_BLE_GAP_SEC_AUTH_PAIRING	Bit 1: Legacy pairing with MITM protection
CY_BLE_GAP_SEC_SC_PAIRING_WITH_NO_MITM	Bit 2: Secured Connection pairing with NO MITM protection
CY_BLE_GAP_SEC_SC_PAIRING_WITH_MITM	Bit 3: Secured Connection pairing with MITM protection
CY_BLE_GAP_SEC_OOB_IN_LEGACY_PAIRING	Bit 4: Legacy pairing with OOB method
CY_BLE_GAP_SEC_OOB_IN_SC_PAIRING	Bit 5: Secured Connection pairing with OOB method

The BLE Stack will check the received security request against the set security requirements during the pairing procedure. If the security requirements are not met, then pairing is rejected by the BLE Stack.

For example: Cy_BLE_GAP_SetSecurityRequirements() is called with secReq as CY_BLE_GAP_SEC_SC_PAIRING_WITH_MITM. If the BLE Stack receives any pairing request with Secured Connection (SC) bit and MITM bit not set, then that pairing request will be rejected by the BLE stack.

Note: If the 'Secured Connection (SC) Only' mode is set, then these security requirements are not considered during pairing procedure. This is to maintain Backward Compatibility for SC Only mode.

Parameters

param Parameter is a pointer to type cy_stc_ble_gap_sec_req_t.

secReq: The application can set multiple security requirements by ORing them in this parameter. For example: If secReq is (CY_BLE_GAP_SEC_UNAUTH_PAIRING | CY_BLE_GAP_SEC_SC_PAIRING_WITH_NO_MITM), then the BLE Stack allows pairing only if the received pairing request is either Legacy pairing with NO MITM or Secured Connection pairing with NO MITM.

encKeySize: Encryption key size requirement of the local device. This parameter does not affect pairing procedure on the central side. At the peripheral side, if the negotiated key size is less than the key size set by this function, then the BLE Stack will reject the pairing request.

Returns: cy_en_ble_api_result_t : Return value indicates if the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation
CY_BLE_ERROR_INVALID_PARAMETER	On specifying invalid input parameter

◆ Cy_BLE_GAP_SetOobData()

cy_en_ble_api_result_t Cy_BLE_GAP_SetOobData ( cy_stc_ble_gap_oob_info_t * param )

This function is used to set the Out of Band (OOB) presence flag and Out of Band (OOB) data received from peer device.

This function should be used by the application layer to enable Out Of Band bonding procedure for the specified device identified by 'bdHandle' This function should be called before initiating authentication or before responding to an authentication request to set OOB flag and data.

This is a blocking function. No event is generated on calling this function. Cy_BLE_GAP_GenerateOobData() function can be called to generate OOB data.

Parameters

param parameter is of type cy_stc_ble_gap_oob_info_t. param->oobData is ignored in case of the Legacy Pairing procedure.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL as input parameter
CY_BLE_ERROR_NO_DEVICE_ENTITY	'bdHandle' does not represent known device entity

◆ Cy_BLE_GAP_GenerateBdAddress()

cy_en_ble_api_result_t Cy_BLE_GAP_GenerateBdAddress ( cy_stc_ble_gap_bd_addr_info_t * param )

This function generates either public or random address based on 'type' specified by param->'addrType'.

This function uses BLE Controller's random number generator to generate the random part of the Bluetooth device address.

Cy_BLE_GAP_GenerateKeys() function can be called by application to generate IRK. Same IRK can be used in this function to generate Resolvable Private Address.

This is non-blocking function. Generated address is informed through 'CY_BLE_EVT_GAP_DEVICE_ADDR_GEN_COMPLETE' event.

Application should call Cy_BLE_GAP_SetBdAddress() function to set the generated address with BLE Stack.

Parameters

param Buffer is of type cy_stc_ble_gap_bd_addr_info_t. param->irk: Buffer containing 128-bit 'IRK' data. This parameter is used only when param->addrType is set to CY_BLE_GAP_RANDOM_PRIV_RESOLVABLE_ADDR. param->addrType'. type of address to be generated.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL as input parameter.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	If Memory allocation failed.
CY_BLE_ERROR_INSUFFICIENT_RESOURCES	If BLE Stack resources are unavailable.

Note: : Note1: param should point to valid memory location until completion of function is indicated via the CY_BLE_EVT_GAP_DEVICE_ADDR_GEN_COMPLETE event. Note2: To guarantees that this function generate different addresses every time, Cy_BLE_GenerateRandomNumber() should be called first with unique seeds.

◆ Cy_BLE_GAP_Disconnect()

cy_en_ble_api_result_t Cy_BLE_GAP_Disconnect ( cy_stc_ble_gap_disconnect_info_t * param )

This function is used to terminate the LE connection with specified peer device.

This function can be used by application in both GAP Central and GAP Peripheral role to send disconnect request to the peer device. This is a non-blocking function.

On disconnection, the following events are generated in order.

CY_BLE_EVT_GATT_DISCONNECT_IND
CY_BLE_EVT_GAP_DEVICE_DISCONNECTED

Parameters

param parameter is of type 'cy_stc_ble_gap_disconnect_info_t *' param->reason: Reason for Disconnection Note: The application shall preferably use CY_BLE_HCI_ERROR_OTHER_END_TERMINATED_USER (0x13) error code as the reason for disconnection when using the Cy_BLE_GAP_Disconnect API.

param->bdHandle: bd Handle of the remote device to be disconnected

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation
CY_BLE_ERROR_INVALID_PARAMETER	If 'param' pointer is NULL
CY_BLE_ERROR_NO_DEVICE_ENTITY	Device identified using 'bdHandle' does not exist
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed
CY_BLE_ERROR_INSUFFICIENT_RESOURCES	BLE Stack resources are unavailable

◆ Cy_BLE_GAP_GetPeerBdAddr()

cy_en_ble_api_result_t Cy_BLE_GAP_GetPeerBdAddr ( cy_stc_ble_gap_peer_addr_info_t * param )

This function reads the peer Bluetooth device address identified by 'bdHandle'.

This is a blocking function. No event is generated on calling this function.

Parameters

param parameter is of type cy_stc_ble_gap_peer_addr_info_t, where param->bdHandle: Peer bdHandle param->bdAddr: Empty buffer where the peer Bluetooth device address will be stored.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL as input parameter for 'peerBdAddr'.
CY_BLE_ERROR_NO_DEVICE_ENTITY	Specified bdHandle does not map to any bdHandle entry in the BLE Stack.

◆ Cy_BLE_GAP_GetPeerBdHandle()

cy_en_ble_api_result_t Cy_BLE_GAP_GetPeerBdHandle ( cy_stc_ble_gap_peer_addr_info_t * param )

This function reads the bdHandle of the peer device (identified by its BD address).

This is a blocking function. No event is generated on calling this function.

Parameters

param parameter is of type cy_stc_ble_gap_peer_addr_info_t, where param->bdHandle: buffer where peer bdHandle will be stored, output parameter param->bdAddr: Peer Bluetooth device address will be stored.

Returns: cy_en_ble_api_result_t : Return value indicates if the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL as input parameter for 'peerBdAddr' or 'bdHandle'.
CY_BLE_ERROR_NO_DEVICE_ENTITY	Specified device address does not map to any entry in BLE Stack.

◆ Cy_BLE_GAP_GetPeerDevSecurity()

cy_en_ble_api_result_t Cy_BLE_GAP_GetPeerDevSecurity ( cy_stc_ble_gap_auth_info_t * param )

This function enables the application to get the peer device security information identified by 'bdHandle', when the peer device is in bonded list.

This is a blocking function. No event is generated on calling this function.

Parameters

param Pointer to a buffer of type 'cy_stc_ble_gap_auth_info_t' into which security information will be written. param->security (output parameter): It ignores LE Security mode. Security should be interpreted as MITM and no MITM as encryption is always supported if pairing is performed between two devices.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL as input parameter for 'authInfo'.
CY_BLE_ERROR_INVALID_OPERATION	An error occurred in the BLE Stack.
CY_BLE_ERROR_NO_DEVICE_ENTITY	Specified bdHandle does not map to any bdHandle entry in the BLE Stack.

◆ Cy_BLE_GAP_GetPeerDevSecurityKeyInfo()

cy_en_ble_api_result_t Cy_BLE_GAP_GetPeerDevSecurityKeyInfo ( cy_stc_ble_gap_sec_key_info_t * param )

This function enables the application to know the key shared during the bonding procedure by a peer device upon completion of the bonding procedure.

This is a blocking function. No event is generated on calling this function.

Parameters

param buffer is of type cy_stc_ble_gap_sec_key_info_t, where peer device security information will be stored. param->SecKeyParam.bdHandle param->localKeysFlag : ignored param->exchangeKeysFlag : Keys exchanged by peer (output parameter)

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL as input parameter for 'keyInfo'.
CY_BLE_ERROR_INVALID_OPERATION	An error occurred in BLE Stack.
CY_BLE_ERROR_NO_DEVICE_ENTITY	Device identified using 'bdHandle' does not exist.

◆ Cy_BLE_GAP_GetLocalDevSecurityKeyInfo()

cy_en_ble_api_result_t Cy_BLE_GAP_GetLocalDevSecurityKeyInfo ( cy_stc_ble_gap_sec_key_info_t * param )

This function gets the local device's keys and key flags.

The IRK received from this function should be used as the input IRK for the function 'Cy_BLE_GAP_GenerateBdAddress()' to generate Random Private Resolvable address. This is a blocking function. No event is generated on calling this function.

Parameters

param buffer is of type cy_stc_ble_gap_sec_key_info_t, where local device security information will be stored. param->SecKeyParam.bdHandle: keys corresponding to peer device param->localKeysFlag : ignored param->exchangeKeysFlag : Indicates the types of the keys exchanged with the peer

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL as input parameters
CY_BLE_ERROR_NO_DEVICE_ENTITY	Device identified using 'bdHandle' does not exist.

◆ Cy_BLE_GAP_SetSecurityKeys()

cy_en_ble_api_result_t Cy_BLE_GAP_SetSecurityKeys ( cy_stc_ble_gap_sec_key_info_t * param )

This function sets the security keys that are to be exchanged with a peer device during key exchange stage of the authentication procedure and sets it in the BLE Stack.

The application is expected to set new keys for new connections. By default, BLE Stack will use 'ZEROs' for the keys if not set by the application. The last set keys will be used by the BLE Stack during the pairing procedure.

This is a blocking function. No event is generated on calling this function. This function should be called before the pairing process begins, preferably after the event 'CY_BLE_EVT_GAP_DEVICE_CONNECTED or CY_BLE_EVT_GAP_ENHANCE_CONN_COMPLETE' is received.

Parameters

param buffer is of type cy_stc_ble_gap_sec_key_info_t, which contains the security keys information to be set to BLE Stack.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL as input parameter for 'keyInfo'
CY_BLE_ERROR_NO_DEVICE_ENTITY	Device identified using 'bdHandle' does not exist.

Note: : Note1: idAddrInfo is ignored as it is device level information. Use Cy_BLE_GAP_SetIdAddress() to set the ID address for the device. Note2: 'exchangeKeysFlag' flags will automatically be ignored if this does not match with the exchange key flag received for a peer during pairing process.

◆ Cy_BLE_GAP_GenerateKeys()

cy_en_ble_api_result_t Cy_BLE_GAP_GenerateKeys ( cy_stc_ble_gap_sec_key_info_t * param )

This function generates the security keys as per application requirement.

Generated Keys are informed through 'CY_BLE_EVT_GAP_KEYS_GEN_COMPLETE' This function does not generate identity address (keyInfo->idAddrInfo)

Parameters

param buffer is of type cy_stc_ble_gap_sec_key_info_t, where generated keys are store. param->SecKeyParam.bdHandle: parameter ignored param->exchangeKeysFlag : parameters ignored

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL as input parameter for 'param'
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	If Memory allocation failed.
CY_BLE_ERROR_INSUFFICIENT_RESOURCES	If BLE Stack resources are unavailable.

Note: Note1: param should point to a valid memory location until completion of function is indicated via CY_BLE_EVT_GAP_KEYS_GEN_COMPLETE event. Note2: Cy_BLE_GenerateRandomNumber() should be called every time with unique seeds before calling this function to guarantee different keys,

◆ Cy_BLE_GAP_AuthReq()

cy_en_ble_api_result_t Cy_BLE_GAP_AuthReq ( cy_stc_ble_gap_auth_info_t * param )

This function starts authentication/pairing procedure with the peer device.

It is a non-blocking function.

If the local device is a GAP Central, the pairing request is sent to the GAP Peripheral device. On receiving CY_BLE_EVT_GAP_AUTH_REQ event, GAP Peripheral is expected to respond by invoking the Cy_BLE_GAPP_AuthReqReply() function.

If the local device is GAP Peripheral, a Security Request is sent to GAP Central device to initiate pairing. On receiving CY_BLE_EVT_GAP_AUTH_REQ event, the GAP Central device should initiate pairing by invoking 'Cy_BLE_GAP_AuthReq()' function.

Following events may occur during pairing procedure, if the function call resulted in CY_BLE_SUCCESS:

Event Name	Description
CY_BLE_EVT_GAP_SMP_NEGOTIATED_AUTH_INFO	SMP has completed pairing properties (feature exchange) negotiation.
CY_BLE_EVT_GAP_KEYINFO_EXCHNGE_CMPLT	SMP keys exchange with peer device is completed.
CY_BLE_EVT_GAP_ENCRYPT_CHANGE	When there is a change in encryption after pairing procedure.
CY_BLE_EVT_GAP_AUTH_COMPLETE	Received by both GAP Central and Peripheral devices (peers) on successful authentication. Data of type 'cy_stc_ble_gap_auth_info_t' is returned as event parameter.
CY_BLE_EVT_GAP_AUTH_FAILED	Received by both GAP Central and Peripheral devices (peers) on authentication failure. Data of type 'cy_en_ble_gap_auth_failed_reason_t' is returned as event parameter.

Based on IO capabilities and security modes, following events may occur during pairing procedure.

Event Name
CY_BLE_EVT_GAP_PASSKEY_DISPLAY_REQUEST
CY_BLE_EVT_GAP_KEYPRESS_NOTIFICATION
CY_BLE_EVT_GAP_NUMERIC_COMPARISON_REQUEST

Parameters

param Pointer to a variable of type 'cy_stc_ble_gap_auth_info_t'. Param->security can take the value from enum cy_en_ble_gap_sec_level_t. NOTE: If the bonding flag in param is set to CY_BLE_GAP_BONDING_NONE, then SMP keys will not be distributed even if the application has generated and set the keys explicitly.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Error codes	Description
CY_BLE_SUCCESS	On successful operation
CY_BLE_ERROR_INVALID_PARAMETER	If 'param' pointer is NULL or if any of the element of this structure is invalid
CY_BLE_ERROR_NO_DEVICE_ENTITY	Device identified using 'bdHandle' does not exist
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed
CY_BLE_ERROR_INSUFFICIENT_RESOURCES	Number of devices that can be bonded is exhausted

◆ Cy_BLE_GAP_AuthPassKeyReply()

cy_en_ble_api_result_t Cy_BLE_GAP_AuthPassKeyReply ( cy_stc_ble_gap_auth_pk_info_t * param )

This function sends a passkey for authentication.

It is a non-blocking function.

This function should be called to pass 6 digit passkey in reply to passkey entry request event CY_BLE_EVT_GAP_PASSKEY_ENTRY_REQUEST received by the BLE Stack. This function is used to accept the passkey request and send the passkey or reject the passkey request.

If the authentication operation succeeds, the CY_BLE_EVT_GAP_AUTH_COMPLETE is generated. If the authentication process times out, the CY_BLE_EVT_TIMEOUT event is generated.
If the authentication fails, the CY_BLE_EVT_GAP_AUTH_FAILED event is generated.

Parameters

param Pointer to security information of the device, of type cy_stc_ble_gap_auth_pk_info_t.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Error codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	If param pointer is NULL
CY_BLE_ERROR_NO_DEVICE_ENTITY	Device identified using 'bdHandle' does not exist.
CY_BLE_ERROR_INVALID_OPERATION	If CY_BLE_EVT_GAP_PASSKEY_ENTRY_REQUEST event is not received before this function call

◆ Cy_BLE_GAP_FixAuthPassKey()

cy_en_ble_api_result_t Cy_BLE_GAP_FixAuthPassKey ( cy_stc_ble_gap_auth_fix_pk_info_t * param )

This function Sets or clears a fixed passkey to be used during authenticated pairing procedure.

This is a blocking function. No event is generated on calling this function.

Note: : Note1: The fixed passkey will work only if local device has IO capability as display only and peer device's IO capability is keyboard only.

Note2: The fixed passkey is not persistent across power cycle. Note3: This function should not be called during an ongoing pairing procedure. This function should preferably be called on CY_BLE_EVT_STACK_ON event.

Parameters

param Parameter is of type 'cy_stc_ble_gap_auth_fix_pk_info_t'

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Error codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	If any of input parameters is invalid.

◆ Cy_BLE_GAP_SetSecureConnectionsOnlyMode()

cy_en_ble_api_result_t Cy_BLE_GAP_SetSecureConnectionsOnlyMode ( cy_stc_ble_gap_sc_mode_info_t * param )

This function sets the BLE Stack to use Secure Connection Only mode for pairing.

If device is in Secure Connection Only mode, it will allow pairing to complete only with Secure Connection Security mode. Non Secure Connection Security pairing will lead to pairing failure with reason "Authentication requirement not met".

This function should be called after CY_BLE_EVT_STACK_ON event, before making LE connection. Secure Connection Only mode is not persistent across power cycles. However it is persistent across BLE Stack shutdown-init cycles.

Parameters

param Parameter is of type 'cy_stc_ble_gap_sc_mode_info_t' bdHandle should be ignored.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Error codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_OPERATION	Secure connections feature mask is not set through Cy_BLE_StackSetFeatureConfig().
CY_BLE_ERROR_INVALID_PARAMETER	If 'param' is NULL or 'state' value is invalid.

Note: This is device level policy and does not depend on bdHandle.

◆ Cy_BLE_GAP_GenerateSetLocalP256Keys()

cy_en_ble_api_result_t Cy_BLE_GAP_GenerateSetLocalP256Keys ( void )

This function is used to generate and set P-256 Public-Private key pair to be used during LE Secure connection pairing procedure.

Application may choose to generate a P-256 public-private key pair before pairing process starts. If this function is not called before pairing process starts, the BLE Stack will use a debug public-private key pair defined in Bluetooth Core specification. Successful completion is informed by CY_BLE_EVT_GAP_GEN_SET_LOCAL_P256_KEYS_COMPLETE event. Event parameter contains the keys that are generated and set for LE Secure connection pairing procedure.

For robust security Cypress recommends that, the application may change the local public-private key pair after:

Every pairing (successful or failed) attempt, OR
After any of the following: a. Three failed attempts to pair from a BD_ADDR b. Ten successful attempts to pair from a BD_ADDR c. Any combination of the above such that three successful pairing attempts count as one failed pairing attempt.

For details, refer to Bluetooth core specification 4.2, Volume 3, part H, section 2.3.6.

It is a non-blocking function.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_OPERATION	Pairing is in progress or Secure Connections feature is not enabled.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.
CY_BLE_ERROR_INSUFFICIENT_RESOURCES	BLE Stack resources are unavailable.

◆ Cy_BLE_GAP_SetLocalP256Keys()

cy_en_ble_api_result_t Cy_BLE_GAP_SetLocalP256Keys ( cy_stc_ble_gap_smp_local_p256_keys_t * param )

This function is used to set a application provided P-256 Public-Private key pair to be used during the LE Secure connection pairing procedure.

The application may choose to set a P-256 public-private key pair before the pairing process starts. If this function is not called before the pairing process starts, the BLE Stack will use a debug public-private key pair defined in Bluetooth Core specification. This function is not expected to be called when a pairing procedure is in progress.

For robust security Cypress recommends that, the application may change the local public-private key pair after:

Every pairing (successful or failed) attempt, OR
After any of the following: a. Three failed attempts to pair from a BD_ADDR b. Ten successful attempts to pair from a BD_ADDR c. Any combination of the above such that three successful pairing attempts count as one failed pairing attempt.

For details, refer to Bluetooth core specification 4.2, Volume 3, part H, section 2.3.6.

Parameters

param Pointer to structure cy_stc_ble_gap_smp_local_p256_keys_t, that has fields for local P-256 public-private key pair.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	Parameter is NULL Or Public key is not valid
CY_BLE_ERROR_INVALID_OPERATION	Pairing is in progress.

◆ Cy_BLE_GAP_AuthSendKeyPress()

cy_en_ble_api_result_t Cy_BLE_GAP_AuthSendKeyPress ( cy_stc_ble_gap_sc_kp_notif_info_t * param )

This function is used to send the LE Secure connection key press notification to a peer device during secure connection pairing.

This function should be called by the application to inform the BLE Stack about the passkey entry process started for each digit: Started (0), entered (1), erased (2), cleared (3). Once all the digits are entered, application needs to call 'Cy_BLE_GAP_AuthPassKeyReply()'to inform the BLE Stack for passkey enter completed. An error will be returned if key press entry bit was not set in 'pairingProperties' of cy_stc_ble_gap_auth_info_t during the authentication procedure and this function is called.

Parameters

param Parameter is of type 'cy_stc_ble_gap_sc_kp_notif_info_t'

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	If 'param' is NULL or notificationType is invalid.
CY_BLE_ERROR_INVALID_OPERATION	If keypress was not negotiated or Secured Connection is not enabled or passkey entry procedure or pairing procedure is not in progress.

◆ Cy_BLE_GAP_GenerateOobData()

cy_en_ble_api_result_t Cy_BLE_GAP_GenerateOobData ( cy_stc_ble_gap_sc_oob_info_t * param )

This function is used to generate OOB information to be used by the peer device.

This function uses a 16-byte random number input to generate the OOB information. The application should share generated OOB information with the peer device using Out Of Band Mechanism.

function completion is informed through 'CY_BLE_EVT_GAP_OOB_GENERATED_NOTIFICATION' event. Note: This function must be used only during LE Secured Connection pairing.

The application should use Cy_BLE_GAP_SetOobData function to set the OOB data of peer device in the BLE Stack.

Parameters

param parameter is of type 'cy_stc_ble_gap_sc_oob_info_t'. If 'param->rand' is NULL, BLE Stack will generate 16 Bytes random number and then will generate OOB data.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	If 'param' is NULL.
CY_BLE_ERROR_INSUFFICIENT_RESOURCES	BLE Stack resources are unavailable.
CY_BLE_ERROR_NO_DEVICE_ENTITY	Device identified using 'bdHandle' does not exist.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Sufficient memory is not available to handle this request.

◆ Cy_BLE_GAP_SetBdAddress()

cy_en_ble_api_result_t Cy_BLE_GAP_SetBdAddress ( cy_stc_ble_gap_bd_addr_t * param )

This function informs Bluetooth device address to BLE Stack for its operation.

This address shall be used for all BLE procedures unless changed by the application. The application layer must call this function every time an address change is required. Application can change its private address periodically, with the period being decided by the application, there are no limits specified on this period. The application layer should maintain its own timers in order to do this.

The application should first generate public or random address using Cy_BLE_GAP_GenerateBdAddress() function and then should call Cy_BLE_GAP_SetBdAddress() function to set the generated address.

If the application sets a public or random static address using this function, then the application should set the same address as the Identity address by calling Cy_BLE_GAP_SetIdAddress function.

This is a non blocking function and completion is informed through the 'CY_BLE_EVT_SET_DEVICE_ADDR_COMPLETE' event

Parameters

param Pointer to type cy_stc_ble_bd_addr_t.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL as input parameter.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	If Memory allocation failed.
CY_BLE_ERROR_INSUFFICIENT_RESOURCES	If BLE Stack resources are unavailable.

◆ Cy_BLE_GAP_GetBdAddress()

cy_en_ble_api_result_t Cy_BLE_GAP_GetBdAddress ( void )

This function reads the Bluetooth device address currently used by BLE Stack.

This is non-blocking function.

The BD Address is informed through 'CY_BLE_EVT_GET_DEVICE_ADDR_COMPLETE' event.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	If Memory allocation failed.
CY_BLE_ERROR_INSUFFICIENT_RESOURCES	If BLE Stack resources are unavailable.

◆ Cy_BLE_GAP_SetIdAddress()

cy_en_ble_api_result_t Cy_BLE_GAP_SetIdAddress ( const cy_stc_ble_gap_bd_addr_t * param )

This function sets the device's identity address in the BLE Stack.

Calling this function will change only the identity address of the device. If the identity address is changed by user, this function needs to be called again to update the address in the BLE Stack.

If the public address or static random address is changed by the user, this function must be called to set the changed public address or static random address as the identity address.

This is a blocking function. No event is generated on calling this function.

Parameters

param

Pointer to the cy_stc_ble_gap_bd_addr_t structure variable. It has two fields where,

param.addr: Bluetooth Device address buffer that is populated with the device address data.
param.type: Caller function should fill the "address type" to set appropriate address.

Caller function should use param.type = 0x00 to set the "Public Device Address" as identity address.
Caller function use param.type = 0x01 to set the "Static Random Device Address" as identity address.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL as input parameter.

◆ Cy_BLE_GAP_GetBondList()

cy_en_ble_api_result_t Cy_BLE_GAP_GetBondList ( cy_stc_ble_gap_bonded_device_list_info_t * param )

This function returns the count of bonded devices and the list of bonded devices with their BD address and bdHandle.

This is a blocking function. No event is generated on calling this function.

Note: The newest bonded device will be at the index 0 in the list.

Parameters

param Pointer to buffer to which list of bonded devices will be stored of type cy_stc_ble_gap_bonded_device_list_info_t.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL as input parameter.

Note : Provide sufficient memory for 'param->bdHandleAddrList' based on 'bondListSize' parameter that is passed during BLE Stack Initialization otherwise provided memory might be corrupted if memory is not sufficient to store all bonded device information.

◆ Cy_BLE_GAP_RemoveDeviceFromBondList()

cy_en_ble_api_result_t Cy_BLE_GAP_RemoveDeviceFromBondList ( cy_stc_ble_gap_bd_addr_t * param )

This function removes the specified device from the bond list.

Successful operation is informed through 'CY_BLE_EVT_PENDING_FLASH_WRITE' event

Parameters

param Pointer to peer device address, of type cy_stc_ble_gap_bd_addr_t. If the device address is set to 0, then all devices shall be removed from trusted white list.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL as input parameter for 'bdAddr'.
CY_BLE_ERROR_INVALID_OPERATION	Operation is not permitted when device is in connected state.

◆ Cy_BLE_GAP_RemoveOldestDeviceFromBondedList()

cy_en_ble_api_result_t Cy_BLE_GAP_RemoveOldestDeviceFromBondedList ( void )

This function removes the oldest device from the bond List.

If the device is connected to the oldest device and this function is called, it will remove the device that is oldest and not connected.

Successful operation is informed through 'CY_BLE_EVT_PENDING_FLASH_WRITE' event

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded (0x0000) or failed. Following are the possible error codes returned.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_MAX	On failure operation.

◆ Cy_BLE_GAP_SetCeLengthParam()

cy_en_ble_api_result_t Cy_BLE_GAP_SetCeLengthParam ( cy_stc_ble_gap_ce_length_param_info_t * param )

This function sets the connection event length to be used for a specific connection.

function completion is informed through the 'CY_BLE_EVT_SET_CE_LENGTH_COMPLETE' event.

Parameters

param Pointer to type cy_stc_ble_gap_ce_length_param_info_t.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded (0x0000) or failed. Following are the possible error codes returned.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL for input parameter.
CY_BLE_ERROR_NO_DEVICE_ENTITY	Incorrect bdHandle.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	If Memory allocation failed.
CY_BLE_ERROR_INSUFFICIENT_RESOURCES	If BLE Stack resources are unavailable.

Note1: The primary usage of this function is to allow application to control bandwidth by setting connection event lengths for specific connections. Note2: Application shall set ceLength to 0xFFFF to allow BLE Stack to internally use maximum possible bandwidth for this connection.

◆ Cy_BLE_GAP_SetConnectionPriority()

cy_en_ble_api_result_t Cy_BLE_GAP_SetConnectionPriority ( cy_stc_ble_gap_set_conn_priority_param_t * param )

This function sets the Controller connection priority to be used for a connection during arbitration.

Controller arbiter resolves radio contention based on the priority level of the contending connections. If one or more contending connections have the same priority level (default configuration), then a round-robin scheme is used to resolve contention. Priority value of 0x00 corresponds to highest priority and 0xFF is the lowest and default priority setting for a connection.

function completion is informed through the 'CY_BLE_EVT_SET_CONN_PRIORITY_COMPLETE' event.

Parameters

param Pointer to type cy_stc_ble_gap_set_conn_priority_param_t.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded (0x0000) or failed. Following are the possible error codes returned.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL for input parameter.
CY_BLE_ERROR_NO_DEVICE_ENTITY	Incorrect bdHandle.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	If Memory allocation failed.
CY_BLE_ERROR_INSUFFICIENT_RESOURCES	If BLE Stack resources are unavailable.

General Description

Functions

Function Documentation

◆ Cy_BLE_GAP_SetIoCap()

◆ Cy_BLE_GAP_SetSecurityRequirements()

◆ Cy_BLE_GAP_SetOobData()

◆ Cy_BLE_GAP_GenerateBdAddress()

◆ Cy_BLE_GAP_Disconnect()

◆ Cy_BLE_GAP_GetPeerBdAddr()

◆ Cy_BLE_GAP_GetPeerBdHandle()

◆ Cy_BLE_GAP_GetPeerDevSecurity()

◆ Cy_BLE_GAP_GetPeerDevSecurityKeyInfo()

◆ Cy_BLE_GAP_GetLocalDevSecurityKeyInfo()

◆ Cy_BLE_GAP_SetSecurityKeys()

◆ Cy_BLE_GAP_GenerateKeys()

◆ Cy_BLE_GAP_AuthReq()

◆ Cy_BLE_GAP_AuthPassKeyReply()

◆ Cy_BLE_GAP_FixAuthPassKey()

◆ Cy_BLE_GAP_SetSecureConnectionsOnlyMode()

◆ Cy_BLE_GAP_GenerateSetLocalP256Keys()

◆ Cy_BLE_GAP_SetLocalP256Keys()

◆ Cy_BLE_GAP_AuthSendKeyPress()

◆ Cy_BLE_GAP_GenerateOobData()

◆ Cy_BLE_GAP_SetBdAddress()

◆ Cy_BLE_GAP_GetBdAddress()

◆ Cy_BLE_GAP_SetIdAddress()

◆ Cy_BLE_GAP_GetBondList()

◆ Cy_BLE_GAP_RemoveDeviceFromBondList()

◆ Cy_BLE_GAP_RemoveOldestDeviceFromBondedList()

◆ Cy_BLE_GAP_SetCeLengthParam()

◆ Cy_BLE_GAP_SetConnectionPriority()