BLE Common Core Functions

group group_ble_common_api_functions

The common core API are used for general BLE configuration.

These include initialization, power management, and utilities.

Functions

cy_en_ble_api_result_t Cy_BLE_Init(const cy_stc_ble_config_t *config)

Initializes the PSoC 6 BLE Middleware.

Error codes

Description

CY_BLE_SUCCESS

The function completed successfully.

CY_BLE_ERROR_INVALID_PARAMETER

On specifying NULL as the input parameter.

Return

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

Parameters
  • config: The configuration structure for the PSoC 6 BLE Middleware.

cy_en_ble_api_result_t Cy_BLE_Enable(void)

Initializes and enable the BLE Stack.

Calling this function results in generation of a CY_BLE_EVT_STACK_ON event on successful initialization of the BLE Stack.

BLE Stack enables the BLE ECO clock automatically with the default parameters:

Parameter

Value

ECO Frequency

CY_BLE_DEFAULT_ECO_FREQ

Divider

CY_BLE_DEFAULT_ECO_DIV

Startup time

CY_BLE_DEFAULT_OSC_STARTUP_DELAY_LF

Load cap

CY_BLE_DEFAULT_CAP_TRIM_VALUE

If there is a need to start the BLE with non-default ECO parameters, call the Cy_BLE_EcoConfigure() function with the custom configuration each time before calling the

Cy_BLE_Enable() function.

This function initializes the BLE Stack which consists of the BLE Stack Manager, BLE Controller, and BLE Host modules. It takes care of initializing the Profile layer, schedulers, Timer and other platform-related resources required for the PSoC 6 BLE Middleware. It also registers the callback function for BLE events that will be registered in the BLE stack.

Note that this function does not reset the BLE Stack.

For the HCI-Mode of operation, this function will not initialize the BLE Host module.

Calling this function results in generation of a CY_BLE_EVT_STACK_ON event on successful initialization of the BLE Stack.

In the dual CPU mode, this function should be called on both cores in the following sequence:

  • call this function on CM0+ core to initialize the Controller.

  • start CM4 core by calling Cy_SysEnableCM4() function.

  • call this function on CM4 core to initialize the Host and Profiles.

NOTE: BLE requires a call to Cy_IPC_Sema_Init(), Cy_IPC_Pipe_Config(), Cy_IPC_Pipe_Init() functions before use. These functions are called in the SystemInit() function for proper flash write and erase operations. If the default startup file is not used, or the function SystemInit() is not called in your project, call the following functions:

  1. Cy_IPC_Sema_Init()

  2. Cy_IPC_Pipe_Config()

  3. Cy_IPC_Pipe_Init()

Error codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_REPEATED_ATTEMPTS

On invoking this function more than once without calling Cy_BLE_Disable() function between calls to this function.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

There is insufficient memory available.

Return

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

cy_en_ble_api_result_t Cy_BLE_Disable(void)

This function stops any ongoing operation in the BLE Stack and forces the BLE Stack to shut down.

Calling this function results in generation of a CY_BLE_EVT_STACK_SHUTDOWN_COMPLETE event on a successful stack shutdown.

For HCI mode: This is a blocking function and no event is generated. Only CY_BLE_SUCCESS will be returned and other error codes are not applicable. UART interface will be stopped and UART data will not be processed by stack until Cy_BLE_Enable() is invoked.

Error codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_OPERATION

On calling Cy_BLE_Disable before calling Cy_BLE_Enable() or on Controller core.

Return

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

void Cy_BLE_EnableLowPowerMode(void)

This function enables BLE low power mode.

void Cy_BLE_RegisterEventCallback(cy_ble_callback_t callbackFunc)

Registers a callback function to receive events from the PSoC 6 BLE Middleware.

Parameters
  • callbackFunc: An application layer event callback function to receive events from the PSoC 6 BLE Middleware. The definition of cy_ble_callback_t is:

    typedef void (* cy_ble_callback_t) (uint32_t eventCode, void *eventParam), where:

    • eventCode: Indicates the event that triggered this callback (e.g. CY_BLE_EVT_STACK_ON).

    • eventParam: Contains the parameters corresponding to the current event.

cy_en_ble_api_result_t Cy_BLE_RegisterAppHostCallback(cy_ble_app_notify_callback_t CallBack)

This function registers an application Host callback (BLE RTOS hook).

The user can trigger an RTOS BLE task if the application Host callback was called.

Theory of operation: The PSoC 6 BLE Middleware triggers this callback when the BLE Stack controller needs to process pending Stack events (by calling Cy_BLE_ProcessEvents()). This callback executes from within an ISR and must be very short.

note

The application Host callback is called from the context of a high- priority ISR. Some RTOS (e.g. FreeRTOS) have restrictions on calling the RTOS functions from a high-priority ISR. The user application is responsible for integration of the BLE RTOS hook and RTOS functions and must ensure that RTOS allows calling RTOS API from BLE interrupt context. If direct call is forbidden, one of the possible solutions is to trig a low-priority interrupt from the application Host callback and then call the RTOS functions from a low-priority interrupt. For detail, refer to specific RTOS documentation.

Return

Error Codes

Description

CY_BLE_SUCCESS

The callback registered successfully.

CY_BLE_ERROR_INVALID_PARAMETER

On specifying NULL as the input parameter.

Parameters
  • CallBack: The pointer to the application Host callback.

void Cy_BLE_UnRegisterAppHostCallback(void)

This function un-registers an application Host callback (BLE RTOS hook).

void Cy_BLE_BlessIsrHandler(void)

Process interrupt events generated by the BLE sub-system.

The interrupts are mandatory for BLE Device operation and this function must be called inside the user-defined interrupt service routine (ISR).

cy_en_ble_api_result_t Cy_BLE_StoreAppData(const cy_stc_ble_app_flash_param_t *param)

This function is used to back up application-specific data into the flash.

This function works in two Write modes: blocking or non-blocking:

param->destAddr - An array address to be defined in the application and aligned to the size of the device’s flash row.

Parameters
  • param: The parameter of type cy_stc_ble_app_flash_param_t.

    • param->srcBuff: The source buffer.

    • param->destAddr: The destination address. The destination buffer size should be greater than or equal to the source buffer.

    • param->buffLen: The length of srcData (in bytes).

    • param->writeMode: Blocking or non-blocking Write mode.

An example of a declaration of such an array (100 bytes):

  • CY_ALIGN(CY_FLASH_SIZEOF_ROW) const uint8_t appBuff[100u] = {0u};

    CY_ALIGN() - Aligns the array to the size of the device’s flash row. Even if the length of srcData is not a multiple of the flash row size,

    Cy_BLE_StoreAppData() forms whole rows, and programs them in sequence.

The approximate time to write one row - 16ms.

The following code snippet shows the usage of Cy_BLE_StoreAppData()

#define ARRAY_SIZE      (100u)    /* Bytes */

/* Allocates buffer (appFlashBuf) in the FLASH (aligned to the size of the device's flash row) */
CY_ALIGN(CY_FLASH_SIZEOF_ROW) static const uint8_t appFlashBuff[ARRAY_SIZE] = {0u};

/* Allocates buffer (appBuf) in the RAM */
uint8_t appBuff[ARRAY_SIZE] = {1u};

cy_en_ble_api_result_t apiResult;

cy_stc_ble_app_flash_param_t storeAppParam =
{
    .srcBuff   = appBuff,
    .destAddr  = appFlashBuff,
    .buffLen   = ARRAY_SIZE,
    .writeMode = CY_BLE_STORE_DATA_MODE_BLOCKING
};

/* Copies data from RAM buffer to FLASH buffer */
apiResult = Cy_BLE_StoreAppData(&storeAppParam);

if(apiResult != CY_BLE_SUCCESS)
{
    /* Error happens ... */
}

Error codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_INFO_FLASH_WRITE_IN_PROGRESS

Write operation is in progress.

CY_BLE_ERROR_INVALID_PARAMETER

An invalid input parameter.

CY_BLE_ERROR_FLASH_WRITE

An error in the flash Write.

CY_BLE_ERROR_FLASH_WRITE_NOT_PERMITED

Flash operation is not permitted (see Note)

note

: Flash operation is not permitted with protection context (PC) value > 0 and core voltage 0.9V, because of a preproduction hardware limitation.

Return

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_StoreBondingData(void)

This function writes the new bonding data from RAM to the dedicated flash location as defined by the PSoC 6 BLE Middleware.

It performs a data comparison between RAM and flash before writing to flash. If there is no change between RAM and flash data, then no write is performed. It writes one flash row in one call. The application should keep calling this function until it returns CY_BLE_SUCCESS. This function is available only when Bonding requirement is selected in Security settings.

Error Codes

Description

CY_BLE_SUCCESS

On successful operation

CY_BLE_INFO_FLASH_WRITE_IN_PROGRESS

Writing in progress

CY_BLE_ERROR_FLASH_WRITE

Error in flash write

CY_BLE_ERROR_FLASH_WRITE_NOT_PERMITED

Flash operation is not permitted (see Note)

note

: Flash operation is not permitted with protection context (PC) value > 0 and core voltage 0.9V, because of a preproduction hardware limitation.

Return

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

Global Variables

The cy_ble_pendingFlashWrite variable is used to detect status of pending write to flash operation for BLE Stack data and CCCD. This function automatically clears pending bits after the write operation completes.

cy_en_ble_api_result_t Cy_BLE_GAP_RemoveBondedDevice(cy_stc_ble_gap_bd_addr_t *bdAddr)

This function removes the bonding information of the device including CCCD values.

This function is available only when Bonding requirement is selected in Security settings.

Error 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

Whitelist is already in use or there is pending write to flash operation.

CY_BLE_ERROR_NO_DEVICE_ENTITY

Device does not exist in the bond list.

Return

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

Global Variables

The bdHandle is set in cy_ble_pendingFlashWrite variable to indicate that data should be stored to flash by Cy_BLE_StoreBondingData() afterwards.

Parameters

bool Cy_BLE_IsPeerConnected(uint8_t *bdAddr)

This function checks if the peer device represented by the bdAddr parameter is connected or not.

Return

  • true - The peer device is connected.

  • false - The peer device is not connected.

Parameters

bool Cy_BLE_IsDevicePaired(cy_stc_ble_conn_handle_t *connHandle)

The function is used to get the device pairing state.

Return

  • true - The peer device pairing is successful. A successful pairing is indicated when CY_BLE_EVT_GAP_AUTH_COMPLETE event is received.

  • false - The peer device is not yet paired.

Parameters
  • connHandle: Pointer to the connection handle of the peer device.

uint8_t Cy_BLE_GetDeviceRole(cy_stc_ble_conn_handle_t *connHandle)

The function returns the local link layer device role which is connected to peer device with connection handle indicated by connHandle parameter.

Return

  • CY_BLE_GAP_LL_ROLE_MASTER (0x00): The local device is connected as a master.

  • CY_BLE_GAP_LL_ROLE_SLAVE (0x01): The local device is connected as a slave.

  • CY_BLE_INVALID_CONN_HANDLE_VALUE (0xff): Invalid connection handle.

Parameters
  • connHandle: Pointer to the connection handle of the peer device.

cy_en_ble_api_result_t Cy_BLE_GetRssiPeer(uint8_t bdHandle)

Replacement for Cy_BLE_GetRssi() API where unused parameters are removed.

This function reads the recorded Received Signal Strength Indicator (RSSI) value of the last received packet on the specified connection. sub-system. The RSSI value is informed through CY_BLE_EVT_GET_RSSI_COMPLETE.

Deprecate the Cy_BLE_GetRssi() API in BLE_PDL v2_0.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_NO_DEVICE_ENTITY

If there is no connection for corresponding bdHandle.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

If Memory allocation failed.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

If BLE Stack resources are unavailable.

Information

Description

Range

-85 <= N <= 5

note

: The value is in dBm.

Return

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

Parameters
  • bdHandle: The bd handle of the peer device.

uint8_t Cy_BLE_GetNumOfActiveConn(void)

Used to get active number of connections.

Return

connNum - number of active connections

cy_stc_ble_conn_handle_t Cy_BLE_GetConnHandleByBdHandle(uint8_t bdHandle)

Used to get connection handle by bdHandle This function halts in debug mode if bdHandle does not exist in the connected device list.

Return

  • connHandle: Full connection handle.

  • connHandle.attId = CY_BLE_INVALID_CONN_HANDLE_VALUE: invalid bdHandle

Parameters
  • bdHandle: Peer device handle

__STATIC_INLINE cy_en_ble_state_t Cy_BLE_GetState (void)

This function is used to determine the current state of the PSoC 6 BLE Middleware state machine :

../../../../_images/ble_middleware_state_machine.png

The PSoC 6 BLE Middleware is in the state CY_BLE_STATE_INITIALIZING after the Cy_BLE_Enable() is called and until the CY_BLE_EVT_STACK_ON event is not received. After successful initialization the state is changed to CY_BLE_STATE_ON.

The PSoC 6 BLE Middleware is in the state CY_BLE_STATE_STOPPED when the CY_BLE_EVT_STACK_SHUTDOWN_COMPLETE event is received (after the Cy_BLE_Disable() is called).

For GAP Central role when the Cy_BLE_GAPC_ConnectDevice() is called, the state is changed to CY_BLE_STATE_CONNECTING. After successful connection indicated by CY_BLE_EVT_GAP_DEVICE_CONNECTED or CY_BLE_EVT_GAP_ENHANCE_CONN_COMPLETE event or the timeout indicated by CY_BLE_EVT_TIMEOUT event, the state is changed to CY_BLE_STATE_ON.

State

Description

CY_BLE_STATE_STOPPED

BLE is turned off.

CY_BLE_STATE_INITIALIZING

BLE is initializing (waiting for CY_BLE_EVT_STACK_ON event).

CY_BLE_STATE_ON

BLE is turned on.

CY_BLE_STATE_CONNECTING

BLE is connecting.

Return

cy_en_ble_state_t : The current PSoC 6 BLE Middleware state. The following are possible states:

__STATIC_INLINE cy_en_ble_adv_state_t Cy_BLE_GetAdvertisementState (void)

This function returns the state of the link layer hardware advertisement engine.

../../../../_images/ble_advertisement_state_machine.png

When Cy_BLE_GAPP_StartAdvertisement() is called, the state is set to CY_BLE_ADV_STATE_ADV_INITIATED. It automatically changes to CY_BLE_ADV_STATE_ADVERTISING when CY_BLE_EVT_GAPP_ADVERTISEMENT_START_STOP event is received. When Cy_BLE_GAPP_StopAdvertisement() is called, the state is set to CY_BLE_ADV_STATE_STOP_INITIATED. It automatically changes to CY_BLE_ADV_STATE_STOPPED when the CY_BLE_EVT_GAPP_ADVERTISEMENT_START_STOP event is received.

State

Description

CY_BLE_ADV_STATE_STOPPED

Advertising is stopped.

CY_BLE_ADV_STATE_ADV_INITIATED

Advertising is initiated.

CY_BLE_ADV_STATE_ADVERTISING

Advertising is initiated.

CY_BLE_ADV_STATE_STOP_INITIATED

Stop advertising is initiated.

Return

cy_en_ble_adv_state_t :The current advertising state. The following are possible states.

__STATIC_INLINE cy_en_ble_scan_state_t Cy_BLE_GetScanState (void)

This returns the state of the link layer hardware scan engine.

../../../../_images/ble_scanning_state_machine.png

When Cy_BLE_GAPC_StartScan() is called the state is set to CY_BLE_SCAN_STATE_SCAN_INITIATED. It automatically changes to CY_BLE_SCAN_STATE_SCANNING when the CY_BLE_EVT_GAPC_SCAN_START_STOP event is received. When Cy_BLE_GAPC_StopScan() is called, the state is set to CY_BLE_SCAN_STATE_STOP_INITIATED. It automatically changes to CY_BLE_SCAN_STATE_STOPPED when the CY_BLE_EVT_GAPC_SCAN_START_STOP event is received.

State

Description

CY_BLE_SCAN_STATE_STOPPED

Scanning is stopped.

CY_BLE_SCAN_STATE_SCAN_INITIATED

Scanning is initiated.

CY_BLE_SCAN_STATE_SCANNING

Scanning process.

CY_BLE_SCAN_STATE_STOP_INITIATED

Stop scanning is initiated.

Return

cy_en_ble_scan_state_t : The current scan state. The following are possible states.

__STATIC_INLINE cy_en_ble_conn_state_t Cy_BLE_GetConnectionState (cy_stc_ble_conn_handle_t connHandle)

This function returns the state of the BLE link for the specified connection handle.

The state is set to CY_BLE_CONN_STATE_CONNECTED when CY_BLE_EVT_GATT_CONNECT_IND event is received with the corresponding connection handle. The state is set to CY_BLE_CONN_STATE_DISCONNECTED when the CY_BLE_EVT_GATT_DISCONNECT_IND event is received.

For GATT Client role when Cy_BLE_GATTC_StartDiscovery() is called, the state indicates the current flow of the discovery procedure by CY_BLE_CONN_STATE_CLIENT_SRVC_DISCOVERING, CY_BLE_CONN_STATE_CLIENT_INCL_DISCOVERING, CY_BLE_CONN_STATE_CLIENT_CHAR_DISCOVERING, CY_BLE_CONN_STATE_CLIENT_DESCR_DISCOVERING and changes to CY_BLE_CONN_STATE_CLIENT_DISCOVERED when the procedure successfully completes.

The state changes from CY_BLE_CONN_STATE_CLIENT_DISCOVERED to CY_BLE_CONN_STATE_CLIENT_DISCONNECTED_DISCOVERED when the CY_BLE_EVT_GATT_DISCONNECT_IND event is received. The state comes backs to CY_BLE_CONN_STATE_CLIENT_DISCOVERED when CY_BLE_EVT_GATT_CONNECT_IND event is received and resolvable device address is not changed.

State

Description

CY_BLE_CONN_STATE_DISCONNECTED

Essentially idle state

CY_BLE_CONN_STATE_CLIENT_DISCONNECTED_DISCOVERED

Server is disconnected but discovered.

CY_BLE_CONN_STATE_CONNECTED

Peer device is connected for this and following states.

CY_BLE_CONN_STATE_CLIENT_SRVC_DISCOVERING

Server services are being discovered.

CY_BLE_CONN_STATE_CLIENT_INCL_DISCOVERING

Server included services are being discovered

CY_BLE_CONN_STATE_CLIENT_CHAR_DISCOVERING

Server Characteristics are being discovered

CY_BLE_CONN_STATE_CLIENT_DESCR_DISCOVERING

Server char. descriptors are being discovered

CY_BLE_CONN_STATE_CLIENT_DISCOVERED

Server is discovered

Return

cy_en_ble_conn_state_t : The current client state. The following are possible states.

Function Usage

/* Allocate the connection handle array. Macro CY_BLE_CONN_COUNT indicates the MAX number of supported connection. */
cy_stc_ble_conn_handle_t appConnHandle[CY_BLE_CONN_COUNT] = { {.attId = CY_BLE_INVALID_CONN_HANDLE_VALUE} };

/* ... */
uint32_t i;
for (i = 0; i < CY_BLE_CONN_COUNT; i++)
{
    if(Cy_BLE_GetConnectionState(appConnHandle[i]) >= CY_BLE_CONN_STATE_CONNECTED)
    {
     /* Do some action */
    }
}
/* ... */

Parameters
  • connHandle: The connection handle.

__STATIC_INLINE uint8_t Cy_BLE_GetFlashWritePendingStatus (void)

This function returns the flash Write pending status.

If this function returns a non-zero value, the application calls Cy_BLE_StoreBondingData() to store pending bonding data. Cy_BLE_StoreBondingData() automatically clears pending bits after the Write operation completes.

Flags

Description

CY_BLE_PENDING_STACK_FLASH_WRITE_BIT

the CY_BLE_EVT_PENDING_FLASH_WRITE event.

CY_BLE_PENDING_CCCD_FLASH_WRITE_BIT

a Write to the CCCD event when a peer device supports bonding.

CY_BLE_PENDING_CCCD_FLASH_CLEAR_BIT

a call to Cy_BLE_GAP_RemoveBondedDevice() with a request to clear CCCD for a particular device.

CY_BLE_PENDING_CCCD_FLASH_CLEAR_ALL_BIT

a call to Cy_BLE_GAP_RemoveBondedDevice() with a request to clear CCCD for all devices.

Return

cy_ble_pendingFlashWrite : The flash Write pending status. Possible flags are set after:

cy_en_ble_api_result_t Cy_BLE_SetLocalName(const char8 name[])

This function is used to set the local device name - a Characteristic of the GAP service.

If the characteristic length entered in the Component customizer is shorter than the string specified by the “name” parameter, the local device name will be cut to the length specified in the customizer.

Error Codes

Description

CY_BLE_SUCCESS

The function completed successfully.

CY_BLE_ERROR_INVALID_PARAMETER

On specifying NULL as input parameter.

Return

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

Parameters
  • name: The local device name string. The name string to be written as the local device name. It represents a UTF-8 encoded User Friendly Descriptive Name for the device. The length of the local device string is entered into the Component customizer and it can be set to a value from 0 to 248 bytes. If the name contained in the parameter is shorter than the length from the customizer, the end of the name is indicated by a NULL octet (0x00).

cy_en_ble_api_result_t Cy_BLE_GetLocalName(char8 name[])

This function is used to read the local device name - a Characteristic of the GAP service.

Error Codes

Description

CY_BLE_SUCCESS

The function completed successfully.

CY_BLE_ERROR_INVALID_PARAMETER

On specifying NULL as input parameter.

Return

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

Parameters
  • name: The local device name string. Used to read the local name to the given string array. It represents a UTF-8 encoded User Friendly Descriptive Name for the device. The length of the local device string is entered into the Component customizer and it can be set to a value from 0 to 248 bytes. If the name contained in the parameter is shorter than the length from the customizer, the end of the name is indicated by a NULL octet (0x00).

cy_en_ble_api_result_t Cy_BLE_GetStackLibraryVersion(cy_stc_ble_stack_lib_version_t *param)

This function retrieves the version information of the BLE Stack library.

This is a blocking function and no event is generated on calling it.

return codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

param is NULL.

Return

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

Parameters

cy_en_ble_api_result_t Cy_BLE_StackSoftReset(void)

This function resets the BLE Stack, including BLE sub-system hardware registers.

The BLE Stack transitions to idle mode. This function can be used to reset the BLE Stack if the BLE Stack turns unresponsive. This function can be used when the application wishes to keep the BLE ECO clock running.

Reset complete is informed through ‘CY_BLE_EVT_SOFT_RESET_COMPLETE event’.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_OPERATION

On calling this function before calling Cy_BLE_StackInit()

Return

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

void Cy_BLE_ProcessEvents(void)

This function checks the internal task queue in the BLE Stack, and pending operation of the BLE Stack, if any.

This must be called at least once every interval ‘t’ where:

  1. ’t’ is equal to connection interval or scan interval, whichever is smaller, if the device is in GAP Central mode of operation, or

  2. ’t’ is equal to connection interval or advertisement interval, whichever is smaller, if the device is in GAP Peripheral mode of operation.

On calling at every interval ‘t’, all pending operations of the BLE Stack are processed. This is a blocking function and returns only after processing all pending events of the BLE Stack. Care should be taken to prevent this call from any kind of starvation; on starvation, events may be dropped by the stack. All the events generated will be propagated to higher layers of the BLE Stack and to the Application layer only after making a call to this function.

Calling this function can wake BLESS from deep sleep mode (DSM). In the process of waking from BLESS DSM, the BLE Stack puts the CPU into sleep mode to save power while polling for a wakeup indication from BLESS. BLESS Wakeup from DSM can occur if the stack has pending data or control transactions to be performed.

Return

None

cy_en_ble_api_result_t Cy_BLE_SetCustomEventMask(uint32_t mask)

This function is used to set the mask that will enable/disable any custom/customer specific events that are exposed by the Stack.

This is a Non Blocking function and success is informed through the ‘CY_BLE_EVT_SET_EVENT_MASK_COMPLETE’ event.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

One of the input parameter is invalid.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

If Memory allocation failed.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

If 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
  • mask: A variable of type UINT32, containing the mask bits. Following are the supported Mask values CY_BLE_DISABLE_ALL_EVENTS_MASK - Disables all custom events CY_BLE_CONN_ESTB_EVENT_MASK - For connection establishment events CY_BLE_ADV_TX_EVENT_MASK - For advertisement packet sent events

cy_en_ble_bless_state_t Cy_BLE_StackGetBleSsState(void)

This function returns the BLE Subsystem’s current operational mode.

This state can be used to manage system level power modes.

BLE Stack Mode

Description

CY_BLE_BLESS_STATE_ACTIVE

BLE Sub System is in active mode, CPU can be in active mode or sleep mode.

CY_BLE_BLESS_STATE_EVENT_CLOSE

BLE Sub System radio and Link Layer hardware finished Tx/Rx. In this state, the application can try configuring the BLE stack to deep sleep mode.

CY_BLE_BLESS_STATE_ECO_STABLE

BLE Sub System is in the process of waking up from deep sleep mode and the BLE ECO is stable. The CPU can be configured in sleep mode.

CY_BLE_BLESS_STATE_DEEPSLEEP

BLE Sub System is in deep sleep mode. CPU can be configured in deep sleep mode.

Return

: cy_en_ble_bless_state_t : BLESS’s operating mode has one of the following values

cy_en_ble_api_result_t Cy_BLE_StartTimer(cy_stc_ble_timer_info_t *param)

This function starts a timer.

The BLE Application can use this timer for certain operations like deferring writing CCCD to flash. This function should not be used for generic purposes as the timer ticks are updated only when there is an LL activity. Maximum number of timers supported is 4.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

Timeout is set to zero.

CY_BLE_ERROR_INVALID_OPERATION

On failed operation.

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_StopTimer(cy_stc_ble_timer_info_t *param)

This function stops a timer that was started by Cy_BLE_StartTimer() function.

The BLE Application can use this timer for certain operations like deferring writing CCCD to flash. This function should not be used for generic purposes as the timer ticks are updated only when there is an LL activity.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_OPERATION

On failed operation (Timer is already stopped or expired).

Return

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

Parameters
  • param: parameter of type ‘cy_stc_ble_timer_info_t’ param->timeout: to be ignored. param->timerHandle: input parameter.

cy_en_ble_api_result_t Cy_BLE_GetRssi(cy_stc_ble_rssi_info_t *param)

This function reads the recorded Received Signal Strength Indicator (RSSI) value of the last received packet on the specified connection.

This is a non-blocking function. Successful operation is indicated through the ‘CY_BLE_EVT_GET_RSSI_COMPLETE’ event.

Information

Description

Range

-85 <= RSSI <= 5

note

: The value is in dBm.

param->bdHandle: Connection handle corresponding to the connection for which RSSI has to be read.

Parameters
  • param: Parameter is a pointer to a variable of type ‘cy_stc_ble_rssi_info_t’ param->rssi: No input value is required. The RSSI value will be returned in the cy_stc_ble_rssi_info_t parameter returned along with the CY_BLE_EVT_GET_RSSI_COMPLETE event.

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

If connection does not exist for corresponding 'bdHandle'.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

If Memory allocation failed.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

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

cy_en_ble_api_result_t Cy_BLE_GetTxPowerLevel(cy_stc_ble_tx_pwr_config_param_t *param)

This function reads the transmit power, in dBm, set for the Advertising channel operations or Data channel operations (per connection).

This is a non-blocking function. The Tx power level value is returned in the cy_stc_ble_tx_pwr_level_info_t parameter of the CY_BLE_EVT_GET_TX_PWR_COMPLETE event.

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

If connection does not exist for corresponding 'bdHandle'.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

If Memory allocation failed.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

If 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
  • param: Pointer to a variable of type ‘cy_stc_ble_tx_pwr_config_param_t’ where:

    • cy_stc_ble_tx_pwr_config_param_t -> bleSsChId indicates Channel group for which power level is to be read. The value can be Advertisement channel (CY_BLE_LL_ADV_CH_TYPE) or Data channel (CY_BLE_LL_CONN_CH_TYPE).

    • bdHandle indicates peer device handle. This is not applicable for advertisement channels (CY_BLE_LL_ADV_CH_TYPE).

cy_en_ble_api_result_t Cy_BLE_SetTxPowerLevel(cy_stc_ble_tx_pwr_lvl_info_t *param)

This function sets the transmit power for the advertising channel operations or data channel operations (per connection).

This is a non-blocking function. Successful operation is informed through ‘CY_BLE_EVT_SET_TX_PWR_COMPLETE’ event.

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

If connection does not exist for corresponding 'bdHandle'.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

If Memory allocation failed.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

If 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
  • param: Parameter is of type ‘cy_stc_ble_tx_pwr_lvl_info_t’ where,

    • blePwrLevel indicates Output Power level, in dBm, to be set by the function.

    • cy_stc_ble_tx_pwr_config_param_t -> bleSsChId indicates Channel group for which power level is to be set. The value can be Advertisement channel (CY_BLE_LL_ADV_CH_TYPE) or Data channel (CY_BLE_LL_CONN_CH_TYPE).

    • cy_stc_ble_tx_pwr_config_param_t -> bdHandle indicates peer device handle. This is not applicable for Advertisement channel (CY_BLE_LL_ADV_CH_TYPE). Set bdHandle to 0xFFu to set ‘blePwrLevel’ for ALL connections.

cy_en_ble_api_result_t Cy_BLE_GetBleClockCfgParam(void)

This function reads the clock configuration of the BLE sub-system.

This is a non-blocking function. BLE Clock configuration is informed through the (cy_stc_ble_bless_clk_cfg_params_t*) type parameter returned along with the ‘CY_BLE_EVT_GET_CLK_CONFIG_COMPLETE’ event.

The following parameters related to the BLE sub-system clock can be read by this function:

Sleep Clock accuracy

Sleep clock accuracy (SCA) in PPM. This parameter indicates the sleep clock accuracy in PPM as described in the following table. It is set in the BLE Stack and is used for BLE Connection operation while creating LE connection with the peer device.

Sleep Clock Accuracy Enum Field

PPM Range Translation (PPM)

CY_BLE_LL_SCA_251_TO_500_PPM

251 - 500

CY_BLE_LL_SCA_151_TO_250_PPM

151 - 250

CY_BLE_LL_SCA_101_TO_150_PPM

101 - 150

CY_BLE_LL_SCA_076_TO_100_PPM

76 - 100

CY_BLE_LL_SCA_051_TO_075_PPM

51 - 75

CY_BLE_LL_SCA_031_TO_050_PPM

31 - 50

CY_BLE_LL_SCA_021_TO_030_PPM

21 - 30

CY_BLE_LL_SCA_000_TO_020_PPM

0 - 20

Refer to Bluetooth Core Specification 5.0 Volume 6, Part B, Section 4.2.2 for more details on how the SCA is used.

Link Layer clock divider

This parameter decides the frequency of the clock to the link layer. A lower clock frequency results in lower power consumption. Default clock frequency for the operation is 24 MHz. BLESS supports 24 MHz, 12 MHz, and 8 MHz clock configurations. This parameter must be set based on the application requirement (Expected frequency of communication).

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_en_ble_api_result_t Cy_BLE_SetBleClockCfgParam(cy_stc_ble_bless_clk_cfg_params_t *param)

This function sets the clock configuration of the BLE sub-system.

This is a non-blocking function. Successful operation is informed through event ‘CY_BLE_EVT_SET_CLK_CONFIG_COMPLETE’. The following parameters related to the BLE sub-system clock are set by this function:

Sleep Clock accuracy

Sleep clock accuracy (SCA) in PPM. This parameter indicates the sleep clock accuracy in PPM as described in the following table. It is set in the BLE Stack and is used for BLE Connection operation while creating LE connection with the peer device.

Sleep Clock Accuracy Enum Field

PPM Range Translation (PPM)

CY_BLE_LL_SCA_251_TO_500_PPM

251 - 500

CY_BLE_LL_SCA_151_TO_250_PPM

151 - 250

CY_BLE_LL_SCA_101_TO_150_PPM

101 - 150

CY_BLE_LL_SCA_076_TO_100_PPM

76 - 100

CY_BLE_LL_SCA_051_TO_075_PPM

51 - 75

CY_BLE_LL_SCA_031_TO_050_PPM

31 - 50

CY_BLE_LL_SCA_021_TO_030_PPM

21 - 30

CY_BLE_LL_SCA_000_TO_020_PPM

0 - 20

Refer to Bluetooth Core Specification 5.0 Volume 6, Part B, Section 4.2.2 for more details on how the SCA is used.

Link Layer clock divider

This input decides the frequency of the clock to the link layer. A lower clock frequency results in lower power consumption. However, a lower clock frequency also lowers the throughput capability and may adversely affect the application’s functionality. Default clock frequency for the operation is 24 MHz. BLESS supports 24 MHz, 12 MHz, and 8 MHz clock configurations. This parameter must be set based on the application requirement (Expected frequency of communication).

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

If param pointer is NULL

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

If Memory allocation failed.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

If 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_SetSlaveLatencyMode(cy_stc_ble_slave_latency_info_t *param)

This function overrides the default BLE Stack Control Policy for an LE connection with non zero slave latency, hereafter referred to as the BLE Stack Policy.

This function is used only when the device is in Peripheral role to force the device to listen to all connection events, overriding the BLE Stack Policy. Command completion is informed through event ‘CY_BLE_EVT_SET_SLAVE_LATENCY_MODE_COMPLETE’

The BLE Stack Policy is as follows:

  • The BLE Stack enables quick transmission (listen to all connection events) whenever any data packet is queued in the link layer. The BLE Stack also enables quick transmit whenever any real time LL Control PDU is received.

  • Upon successful transmission of the data packet, or an acknowledgement that the real time LL PDU received earlier has been processed, the BLE Stack resets the quick transmit to enable latency for power saving.

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

If connection does not exist for corresponding 'bdHandle'.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

If Memory allocation failed.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

If 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
  • param: parameter is of type ‘cy_stc_ble_slave_latency_info_t’ param->setForceQuickTransmit: If this parameter is set to 1, the device will always respond to all the Connection Events (CE) ignoring the slave latency. To re-enable the BLE Stack Policy, the application should call this function with force quick transmit option set to zero. param->bdHandle: The connection handle corresponding to the connection for which the slave latency mode has to be changed.

cy_en_ble_api_result_t Cy_BLE_GetChannelMap(cy_stc_ble_channel_map_info_t *param)

This function can be used to read current channel map for the specified connection handle.

This is a non-blocking function. Current channel map is informed through the (cy_stc_ble_channel_map_info_t*) type parameter returned along with ‘CY_BLE_EVT_GET_CHANNEL_MAP_COMPLETE’ event.

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

If connection does not exist for corresponding 'bdHandle'.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

If Memory allocation failed.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

If 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_SetHostChannelClassification(cy_stc_ble_channel_map_info_t *param)

This function sets Channel Classification for the data channels.

This classification persists until it is overwritten by a subsequent call to this function or the controller is reset. The application must call this function within 10 seconds of knowing that the current channel classification must be updated. The interval between two successive calls to this function should be at least one second. This command should be used only when the local device supports the Master role.

Note: There is no direct event indicating completion of this function. The Cy_BLE_GetChannelMap() function must be called multiple times while handling the CY_BLE_EVT_GET_CHANNEL_MAP event until the parameter returned with the event indicates that channel map update procedure is complete.

For details, refer to Bluetooth 5.0 core specification, Volume 6, part B, section 4.5.8.

This is a non blocking function. Successful operation is informed through event ‘CY_BLE_EVT_SET_HOST_CHANNEL_COMPLETE’

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.

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_GetTemperature(void)

This function allows the application to read the current temperature from the temperature sensor in the BLE radio.

This is a non-blocking function. Temperature value is informed through ‘CY_BLE_EVT_RADIO_TEMPERATURE’ event in degreeC units

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.

Return

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_GetBatteryLevel(void)

This function allows the application to read the current supply voltage of the BLE radio (VDDR_HVL).

This is a non-blocking function. Voltage value is informed through ‘CY_BLE_EVT_RADIO_VOLTAGE_LEVEL’ event in milliVolts.

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.

Return

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