GAP Central Functions

General Description

APIs unique to designs configured as a GAP Central role.

A letter 'C' is appended to the API name: Cy_BLE_GAPC_

Functions
cy_en_ble_api_result_t	Cy_BLE_GAPC_StartScan (uint8_t scanningIntervalType, uint8_t scanParamIndex)
	This function is used for discovering GAP peripheral devices that are available for connection. More...
cy_en_ble_api_result_t	Cy_BLE_GAPC_StopScan (void)
	This function used to stop the discovery of devices. More...
cy_en_ble_api_result_t	Cy_BLE_GAPC_ConnectDevice (const cy_stc_ble_gap_bd_addr_t *address, uint8_t centralParamIndex)
	This function is used to send a connection request to the remote device with the connection parameters set in the BLE Component customizer. More...
cy_en_ble_api_result_t	Cy_BLE_GAPC_CancelDeviceConnection (void)
	This function cancels a previously initiated connection with the remote device. More...
cy_en_ble_api_result_t	Cy_BLE_GAPC_ResolveDevice (cy_stc_ble_gapc_resolve_peer_info_t *param)
	This function enables the GAP Central application to start a address resolution procedure for a peer device that is connected using a resolvable private address. More...
cy_en_ble_api_result_t	Cy_BLE_GAPC_SetRemoteAddr (cy_stc_ble_gapc_peer_bd_addr_info_t *param)
	This function is used by GAP Central application to set the new address of peer device identified by bdHandle. More...
cy_en_ble_api_result_t	Cy_BLE_GAPC_ConnectionParamUpdateRequest (cy_stc_ble_gap_conn_update_param_info_t *param)
	This function is used by GAP Central application to initiate the Connection Parameter Update Procedure. More...

Function Documentation

Cy_BLE_GAPC_StartScan()

cy_en_ble_api_result_t Cy_BLE_GAPC_StartScan	(	uint8_t	scanningIntervalType,
		uint8_t	scanParamIndex
	)

This function is used for discovering GAP peripheral devices that are available for connection.

It performs the scanning routine using the parameters entered in the Component's customizer indicated by scanParamIndex parameter.

As soon as the discovery operation starts, CY_BLE_EVT_GAPC_SCAN_START_STOP event is generated. The CY_BLE_EVT_GAPC_SCAN_PROGRESS_RESULT event is generated when a GAP peripheral device is located. There are three discovery procedures can be selected in the customizer's GUI:

• Observation procedure: A device performing the observer role receives only advertisement data from devices irrespective of their discoverable mode settings. Advertisement data received is provided by the event, CY_BLE_EVT_GAPC_SCAN_PROGRESS_RESULT. This procedure requires the scanType sub parameter to be passive scanning.
• Discovery procedure: A device performing the discovery procedure receives the advertisement data and scan response data from devices in both limited discoverable mode and the general discoverable mode. Received data is provided by the event, CY_BLE_EVT_GAPC_SCAN_PROGRESS_RESULT. This procedure requires the scanType sub-parameter to be active scanning.

Every Advertisement / Scan response packet is received in a new event, CY_BLE_EVT_GAPC_SCAN_PROGRESS_RESULT. If 'scanTo' sub-parameter is a non-zero value, then upon commencement of discovery procedure and elapsed time = 'scanTo', CY_BLE_EVT_TIMEOUT event is generated with the event parameter indicating CY_BLE_GAP_SCAN_TO. Possible generated events are:

• CY_BLE_EVT_GAPC_SCAN_START_STOP: If a device started or stopped scanning. Use Cy_BLE_GetScanState() to determine the state. Sequential scanning could be started when CY_BLE_ADV_STATE_STOPPED state is returned.
• CY_BLE_EVT_GAPC_SCAN_PROGRESS_RESULT
• CY_BLE_EVT_TIMEOUT (CY_BLE_GAP_SCAN_TO)

Parameters

scanningIntervalType	Fast or slow scanning interval with timings entered in Scan settings section of the customizer. CY_BLE_SCANNING_FAST 0x00u CY_BLE_SCANNING_SLOW 0x01u CY_BLE_SCANNING_CUSTOM 0x02u
scanParamIndex	The index of the central and scan configuration in customizer.

Returns

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

Error Codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On passing an invalid parameter.
CY_BLE_ERROR_INVALID_STATE	On calling this function not in Stopped state.

CY_BLE_ERROR_INVALID_OPERATION |

Cy_BLE_GAPC_StopScan()

cy_en_ble_api_result_t Cy_BLE_GAPC_StopScan

(

void

)

This function used to stop the discovery of devices.

On stopping discovery operation, CY_BLE_EVT_GAPC_SCAN_START_STOP event is generated. Application layer needs to keep track of the function call made before receiving this event to associate this event with either the start or stop discovery function.

Possible events generated are:

• CY_BLE_EVT_GAPC_SCAN_START_STOP

Returns

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

Error Codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.
CY_BLE_ERROR_INVALID_STATE	On calling this function not in Scanning state.

Cy_BLE_GAPC_ConnectDevice()

cy_en_ble_api_result_t Cy_BLE_GAPC_ConnectDevice	(	const cy_stc_ble_gap_bd_addr_t *	address,
		uint8_t	centralParamIndex
	)

This function is used to send a connection request to the remote device with the connection parameters set in the BLE Component customizer.

This function needs to be called only once after the target device is discovered by Cy_BLE_GAPC_StartScan() and further scanning has stopped. Scanning is successfully stopped on invoking Cy_BLE_GAPC_StopScan() and then receiving the event CY_BLE_EVT_GAPC_SCAN_START_STOP with sub-parameter 'success' = 0x01u.

On successful connection, the following events are generated at the GAP Central device (as well as the GAP Peripheral device), in the following order.

• CY_BLE_EVT_GATT_CONNECT_IND
• CY_BLE_EVT_GAP_DEVICE_CONNECTED - If the device connects to a GAP Central and Link Layer Privacy is disabled.
• CY_BLE_EVT_GAP_ENHANCE_CONN_COMPLETE - If the device connects to a GAP Central and Link Layer Privacy is enabled.
• CY_BLE_EVT_GAP_DEVICE_CONNECTED

A procedure is considered to have timed out if a connection response packet is not received within time set by cy_ble_connectingTimeout global variable (30 seconds by default). CY_BLE_EVT_TIMEOUT event with CY_BLE_GENERIC_APP_TO parameter will indicate about connection procedure timeout. Connection will automatically be canceled and state will be changed to CY_BLE_STATE_ON.

Parameters

address	The device address of the remote device to connect to.
centralParamIndex	The index of the central configuration in customizer. For example: CY_BLE_CENTRAL_CONFIGURATION_0_INDEX 0x00 CY_BLE_CENTRAL_CONFIGURATION_1_INDEX 0x01

Returns

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

Error Codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On passing an invalid parameter.
CY_BLE_ERROR_INVALID_STATE	On calling this function not in Disconnected state.
CY_BLE_ERROR_INVALID_OPERATION	The operation is not permitted due to connection limit exceeded.

Note: Please refer the description of Cy_BLE_GAPC_InitConnection() for recommended Connection Interval values.

Cy_BLE_GAPC_CancelDeviceConnection()

cy_en_ble_api_result_t Cy_BLE_GAPC_CancelDeviceConnection

(

void

)

This function cancels a previously initiated connection with the remote device.

It is a blocking function. No event is generated on calling this function. If the devices are already connected then this function should not be used. If you intend to disconnect from an existing connection, the function Cy_BLE_GAP_Disconnect() should be used.

Returns

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

Error Codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_STATE	On calling this function not in Connecting state.

Cy_BLE_GAPC_ResolveDevice()

cy_en_ble_api_result_t Cy_BLE_GAPC_ResolveDevice

(

cy_stc_ble_gapc_resolve_peer_info_t *

param

)

This function enables the GAP Central application to start a address resolution procedure for a peer device that is connected using a resolvable private address.

This is a non-blocking function.

Refer to Bluetooth 5.0 Core specification, Volume 3, Part C, section 10.8.2.3 Resolvable Private Address Resolution Procedure to understand the usage of Private addresses.

'CY_BLE_EVT_GAP_RESOLVE_DEVICE_COMPLETE' event is generated to inform about the completion of address resolution procedure.

Parameters

param

Parameter is of type cy_stc_ble_gapc_resolve_peer_info_t param->bdAddr: Peer Bluetooth device address of 6 bytes length, not NULL terminated. param->peerIrk: 128-bit IRK to be used for resolving the peer's private resolvable address.

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 'param' or 'bdAddr'.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.
CY_BLE_ERROR_INSUFFICIENT_RESOURCES	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_RESOLVE_DEVICE_COMPLETE' event. Note2: If application is using White List filtering, update the White List with the new address using Cy_BLE_AddDeviceToWhiteList() function.

Cy_BLE_GAPC_SetRemoteAddr()

cy_en_ble_api_result_t Cy_BLE_GAPC_SetRemoteAddr

(

cy_stc_ble_gapc_peer_bd_addr_info_t *

param

)

This function is used by GAP Central application to set the new address of peer device identified by bdHandle.

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

This function should be used when:

1. A peer device bonded previously with a public address and changes its BD address to a resolvable private address. The application should first resolve the device address by calling the 'Cy_BLE_GAPC_ResolveDevice()' function. If address resolution is successful then set the new address using this function.
2. A peer device is previously bonded with a random address, then application should call this function to set the new address(public/random).

Parameters

param

Parameter of type 'cy_stc_ble_gapc_peer_bd_addr_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 invalid bdHandle.

Cy_BLE_GAPC_ConnectionParamUpdateRequest()

cy_en_ble_api_result_t Cy_BLE_GAPC_ConnectionParamUpdateRequest

(

cy_stc_ble_gap_conn_update_param_info_t *

param

)

This function is used by GAP Central application to initiate the Connection Parameter Update Procedure.

This function updates parameters to local BLE Controller. Local BLE Controller follows the connection update procedure as defined in Bluetooth Core Specification 4.0. This function does not perform parameter negotiation with peer device through LL topology as defined in Bluetooth Core Specification 4.1.

CY_BLE_EVT_GAP_CONNECTION_UPDATE_COMPLETE event is generated to inform about completion of Connection Parameter Update procedure.

Parameters

param

Parameter is of type 'cy_stc_ble_gap_conn_update_param_info_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 NULL for input parameter.
CY_BLE_ERROR_NO_DEVICE_ENTITY	If connection does not exist for corresponding 'bdHandle'.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.
CY_BLE_ERROR_INSUFFICIENT_RESOURCES	BLE Stack resources are unavailable.