GAP Peripheral Functions¶

group group_ble_common_api_gap_peripheral_functions

APIs unique to designs configured as a GAP Peripheral role.

A letter ‘P’ is appended to the API name: Cy_BLE_GAPP_

Functions

cy_en_ble_api_result_t Cy_BLE_GAPP_StartAdvertisement(uint8_t advertisingIntervalType, uint8_t advertisingParamIndex)¶

This function is used to start the advertisement using the advertisement data set in the BLE Component customizer’s GUI indicated by the advertisingParamIndex.

After invoking this function, the device will be available for connection by the devices configured for GAP central role. It is only included if the device is configured for GAP Peripheral or GAP Peripheral + Central role.

On start of advertisement, GAP Peripheral receives the CY_BLE_EVT_GAPP_ADVERTISEMENT_START_STOP event. The following events are possible on invoking this function:

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_TIMEOUT: If no device in GAP Central mode connects to this device within the specified timeout limit. BLE Stack automatically initiate stop advertising when Slow advertising was initiated, or starts Slow advertising after Fast advertising timeout occur.
CY_BLE_EVT_GAPP_ADVERTISEMENT_START_STOP: If device started or stopped advertising. Use Cy_BLE_GetAdvertisementState() to determine the state. Sequential advertising could be started when CY_BLE_ADV_STATE_STOPPED state is returned.

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	The operation is not permitted due to connection

| limit exceeded.

note

CY_BLE_EVT_GAPP_ADVERTISEMENT_START_STOP event is generated after calling Cy_BLE_GAPP_StartAdvertisement() and Cy_BLE_GAPP_StopAdvertisement() functions. Application should keep track of which function call resulted into this event

Parameters

advertisingIntervalType – Fast or slow advertising interval with timings entered in Advertising settings section of the BT Configurator.
- CY_BLE_ADVERTISING_FAST 0x00u
- CY_BLE_ADVERTISING_SLOW 0x01u
- CY_BLE_ADVERTISING_CUSTOM 0x02u
advertisingParamIndex – The index of the peripheral and broadcast configuration in BT Configurator. For example:
- CY_BLE_PERIPHERAL_CONFIGURATION_0_INDEX 0x00
- CY_BLE_BROADCASTER_CONFIGURATION_0_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_GAPP_StopAdvertisement(void)¶

This function can be used to exit from discovery mode.

After the execution of this function, there will no longer be any advertisements. On stopping advertising, GAP Peripheral receives CY_BLE_EVT_GAPP_ADVERTISEMENT_START_STOP event.

The following event occurs on invoking this function:

CY_BLE_EVT_GAPP_ADVERTISEMENT_START_STOP

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 Advertising state.

note

CY_BLE_EVT_GAPP_ADVERTISEMENT_START_STOP event is generated after calling Cy_BLE_GAPP_StartAdvertisement() and Cy_BLE_GAPP_StopAdvertisement() functions. Application should keep track of which function call resulted into this event.

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_GAPP_UpdateAdvScanData(cy_stc_ble_gapp_disc_mode_info_t *param)¶

This function is used by the GAP Peripheral application to set Advertisement and/or Scan Response data.

This function can be used during active advertisement as well. Application should ensure the validity of the data content. This is a non-blocking function.

On completion of this operation, GAP Peripheral application receives CY_BLE_EVT_GAPP_UPDATE_ADV_SCAN_DATA_COMPLETE event.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL for 'param' or if any of the elements of this structure is invalid.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.
CY_BLE_ERROR_INSUFFICIENT_RESOURCES	BLE Stack resources are unavailable.

Parameters: param – Structure of type cy_stc_ble_gapp_disc_mode_info_t, Only cy_stc_ble_gapp_disc_mode_info_t.advData and cy_stc_ble_gapp_disc_mode_info_t.scanRspData fields are used. Other fields in the structure are ignored.
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_GAPP_AuthReqReply(cy_stc_ble_gap_auth_info_t *param)¶

This function is used by the GAP Peripheral application to send Pairing Response in authentication/pairing procedure.

This function should be called after receiving CY_BLE_EVT_GAP_AUTH_REQ event.

If function call resulted in CY_BLE_SUCCESS, following events are expected to inform the application about the progress of the authentication procedure.

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.

Based on IO capabilities and security modes, following events can be generated during authentication procedure. Refer Bluetooth Core spec 5.0 volume 3 part - H section 2.3.5.1 to know more about Selecting Key Generation Method.

Event Name

CY_BLE_EVT_GAP_PASSKEY_DISPLAY_REQUEST

CY_BLE_EVT_GAP_KEYPRESS_NOTIFICATION

CY_BLE_EVT_GAP_NUMERIC_COMPARISON_REQUEST

Based on the authentication procedure result, following events will be generated.

Event Name	Description
CY_BLE_EVT_GAP_AUTH_COMPLETE	Pointer to structure of type 'cy_stc_ble_gap_auth_info_t' is returned as parameter to both the peer devices on successful authentication.
CY_BLE_EVT_GAP_AUTH_FAILED	Received by both GAP Central and Peripheral devices (peers) on authentication failure. Data is of type 'cy_en_ble_gap_auth_failed_reason_t'.

NOTE: If the param->bonding is set to CY_BLE_GAP_BONDING_NONE then, during authentication procedure, SMP keys will not be distributed even if the application has generated and set the keys explicitly.

Errors codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	On specifying NULL for 'param' or if any of the elements of this structure is invalid.
CY_BLE_ERROR_NO_DEVICE_ENTITY	Device identified using 'bdHandle' does not exist.
CY_BLE_ERROR_INVALID_OPERATION	Operation is not permitted.
CY_BLE_ERROR_INSUFFICIENT_RESOURCES	If application tries to initiate pairing with bonding enable, when the number of devices that can be bonded is exhausted.

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.
Returns: cy_en_ble_api_result_t: Return value indicates whether the function succeeded or failed. Following are the possible error codes.