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:

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.

Return

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

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

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

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:

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.

Return

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.

Return

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

Parameters

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.

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.

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.

Return

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