GAP Central Functions

group group_ble_common_api_gap_central_functions

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.

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:

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 |

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.

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:

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.

Returns

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

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.

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.

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.

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.

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.

Error Codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_STATE

On calling this function not in Connecting state.

Returns

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

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.

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.

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.

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).

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

On invalid bdHandle.

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.

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.

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.

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.