# Bluetooth Stack Supporting API Functions

## Device_BLE_Param_Get

#### Prototype:

uint8_t Device_BLE_Param_Get(uint8_t param_id, uint8_t *lengthPtr, uint8_t *buf)

This is a callback function that is called by the Bluetooth stack whenever the associated data is required. If the application returns PARAM_OK, it means that requested parameter is provided by the application; if it returns PARAM_FAIL, it means the stack can use the default settings/parameters.

In this function there is a switch/case, described below:

- PARAM_ID_BD_ADDRESS: the global public address of the device
- PARAM_ID_LPCLK_DRIFT: the clock accuracy in ppm for the low power clock. There are three clock sources: XTAL32, RC OSC 32, and clock input from a GPIO[0- 3]. By default it is 500 ppm, but the application can provide another value based on the clock accuracy used. For the central role it is not expected to be bigger than 500.
- PARAM_ID_ACTCLK_DRIFT: the clock accuracy of XTAL 48 MHz in ppm that depends on the XTAL component used in PCB. If it is not provided by application maximum, 50 ppm will be used.
- PARAM_ID_OSC_WAKEUP_TIME: the time that, after wakeup from a low power mode, XTAL48 and other blocks of need time to power up and be ready. The value is in μs.
- PARAM_ID_CH_ASS_EN: can be used in a central role to indicate if the channel assessment mechanism needs to be executed by the stack or not. It has True and False values.
- PARAM_ID_LPCLK_NO_XTAL32K: determines if a XTAL 32768 Hz is used as the low power clock source or another option of clock source/value is used. If 32768 Hz with maximum 500 ppm is not used, then the actual clock value can be provided by calling LPCLK_PeriodValue_Set(LPCLK_PERIOD_VALUE); refer to sample application code.
- PARAM_ID_LE_PRIVATE_KEY_P256 and PARAM_ID_LE_PUBLIC_KEY_P256: if ECC public and private keys are provided by the application, this can be used for debugging purposes or for use cases where an application needs to generate the keys by itself (using the Arm CryptoCell-312 hardware accelerator or any other way) rather than having them generated by the Bluetooth stack.
- PARAM_ID_LE_DBG_FIXED_P256_KEY: values are True or False, indicating if the stack should use forced keys provided by application or not.
- PARAM_ID_CH_ASSESS_PARAMS: when a channel assessment algorithm is enabled by the application, the related parameters can be provided through this case that need to follow struct channel_map_assess_tag.
- PARAM_ID_DTM_ANT_ID_TO_PTRN_PARAMS: for antenna-switching use cases, the antennal pattern table can be provided through this case.
- PARAM_ID_CUSTOMIZED_HEAP_SIZE: if an application needs to control and define the memory size used by the Bluetooth stack (stack heap), the four heap sizes values can be provided; otherwise the stack will use default sizes. (Refer to Introduction for details).
- PARAM_ID_DFT_SLAVE_MD: When a peripheral device sends a packet, it sets the MD bit to make sure that an acknowledge can be received from the central peer device in the same connection event. It has true and false values. By default, it is set to true, which means that the MD bit is set.
- PARAM_ID_ACTIVITY_MOVE_CONFIG: When there is more than one Bluetooth Low Energy connection, events anchor points might overlap and a peripheral device can send a connection parameter update request to peer central devices asking for an anchor point move. By default, it is enabled (true). It can be disabled if the application sets it to false.
- PARAM_ID_LE_CODED_PHY_500: In the RSL15 peripheral_server sample project, setting ADV_EXTENSION =1 causes the application to use GAPM_PHY_TYPE_LE_CODED for advertising at a default rate of 250 Kbps. But if 500 Kbps is required instead, then this case is used.

## platform_reset

#### Prototype:

void platform_reset(uint32_t error)

This function is called whenever the stack memory is full, so that the application can be notified of the situation and handle it accordingly.

## srand_func

#### Prototype:

void srand_func(uint32_t seed)

This provides a seed value for the rand() function used in the stack.

## rand_func

#### Prototype:

int rand_func(void)

Instead of the C rand function, the application can provide its own implementation or use the TRNG accelerator from the Arm CryptoCell-312.

## Device_RF_RSSI_Convert

#### Prototype:

int8_t Device_RF_RSSI_Convert(uint8_t rssi_reg)

This function can be used by application to convert or readthe RF RSSI register to an actual dBm value. A general function is provided, but RSSI needs calibration for use cases that need an more accurate RSSI.

## Device_RF_TxPwr_Get_dBm

#### Prototype:

int8_t Device_RF_TxPwr_Get_dBm(uint8_t txpwr_idx)

This callback function is called whenever the stack needs to convert the RF0_REG1A_PA_PWR_PA_PWR_BYTE field of register RF0_REG1A to a dBm value.

## Device_RF_TxPwr_Get_Idx

#### Prototype:

uint8_t Device_RF_TxPwr_Get_Idx(int8_t txpwr_dbm)

This callback function is used whenever the stack is converting output power in dBm to a value used to set the RF0_REG1A_PA_PWR_PA_PWR_BYTE field of register RF0_REG1A.

## BLE_Set_RxStatusCallBack

#### Prototype:

void App_RxStatus_Callback(uint8_t *actidx, uint16_t *status, uint8_t *rssi, uint8_t *chnl, uint16_t *length)

#### Parameters:

- *actidx
- *status
- *rssi
- *chnl
- *length

#### Return:

The returned RSSI is a raw RSSI register read value and needs to be converted to dBm.

#### Description:

This API can register an application callback function, so that whenever a packet is received, the Bluetooth Low Energy stack calls that callback function and returns the listed parameters as arguments of that function.

#### Examples:

/* registering a callback function any time in application after Bluetooth Low Energy initialization */

BLE_Set_RxStatusCallBack(App_RxStatus_Callback);

/*callback function:*/

void App_RxStatus_Callback(uint8_t *actidx, uint16_t *status, uint8_t *rssi, uint8_t *chnl, uint16_t *length)

{

int8_t calculated_rssi = ((0.328 * (*rssi)) - 108);

if(*status == 0)

{ swmTrace_printf("\n\r actidx = %d, status = %d, rssi = %d, chnl= %d, length = %d", *actidx, *status, calculated_rssi, *chnl, *length); }

}

/* When this functionality is required another API needs to be called before BLE_Initialize() is called, as shown below: */

BLE_Set_RFOffSeqMode(1);

uint8_t param_ptr;

BLE_Initialize(&param_ptr);

This information is only valid if the status of the received packet is zero (no error). The callback function does not consume a great deal of processing time, as it is called in the Bluetooth Low Energy RX ISR.

A rough estimation formula can be used as shown below, but in general the RSSI needs to be calibrated to take into account sample-to-sample variation, and channel variation that depends on PCB, XTAL48 trimming, and antenna/matching circuit design. Changes in temperature can also cause variation.

## Device_RF_SetMaxPwrIdx

#### Prototype:

uint8_t Device_RF_SetMaxPwrIdx(void)

This API/callback function is called by the Bluetooth Low Energy stack to set a maximum power index, which is later used for non-advertisement activities powered by TX output.

The return value is based on the format that function Device_RF_TxPwr_Get_Idx(desired dBm value) returns.

Setting adv_param.max_tx_pwr to any value between -127 and 126 causes the stack to call Device_RF_TxPwr_Get_Idx(), and the return index to this function determines the actual ADV TX power.

However, for connections, scan response, and initiating activities, the stack uses the value that is provided in advance by the application during the stack initialization when Device_RF_SetMaxPwrIdx() is called.

Thus, applications can control ADV TX powers through adv_param.max_tx_pwr, and output power levels for connections are controlled by Device_RF_SetMaxPwrIdx().

## BLE_Set_ScanConIndStatusCallBack

#### Prototype:

BLE_Set_ScanConIndStatusCallBack(App_ScanConIndStatus_Callback);

#### Parameters:

none

#### Return:

The returned RSSI is a raw RSSI register read value and needs to be converted to dBm.

#### Description:

Through this function, it is possible to register an application callback function to access the channel number and RSSI for any successfully received scan request and connection indication. It requires that BLE_Set_RFOffSeqMode(1) be called in advance.

#### Example:

BLE_Set_ScanConIndStatusCallBack(App_ScanConIndStatus_Callback);

void App_ScanConIndStatus_Callback(uint8_t *type, uint8_t *rssi, uint8_t *chnl)

{

int8_t calculated_rssi = ((0.328 * (*rssi)) - 108);

if(*type == BLE_SCAN_REQ)

{ swmTrace_printf("\n\r SCAN_REQ, rssi = %d, chnl= %d", calculated_rssi, *chnl); }

else if(*type == BLE_CONNECT_IND)

{ swmTrace_printf("\n\r CONNECT_IND, rssi = %d, chnl= %d", calculated_rssi, *chnl); }

}

## Hci_Vs_Cmd_App_Func

#### Prototype:

uint8_t Hci_Vs_Cmd_App_Func(uint8_t cmd_code, uint8_t length, uint8_t *data_buf, uint8_t *result_length, uint8_t *result_data)

#### Parameters:

- cmd_code
- length
- *data_buf
- *result_length
- *result_data

#### Return:

Status.

#### Description:

When running an hci application that uses the HCI variant of the Bluetooth Low Energy stack to support HCI commands over UART, HCI_DBG_VS_APP_CMD_OPCODE needs to be implemented in the application. This allows users to develop any desired vendor-specific command. The format of the message is handled by the stack, and the application needs to have a function implemented such that it can interpret the command code, input parameters length, and data, and sends a response with the status, length and data. Some of the command codes are used by RF tools, so users can add unused command codes.

#### Example:

uint8_t Hci_Vs_Cmd_App_Func(uint8_t cmd_code,

uint8_t length, uint8_t *data_buf,

uint8_t *result_length, uint8_t *result_data)

{

uint8_t status = CO_ERROR_NO_ERROR;

*result_length = 0;

uint16_t freq_Mhz;

int8_t pwr_dBm, txOrRx; /* 0: Tx, 1:Tx */

switch(cmd_code)

{ case HCI_VS_RF_CW_ENABLE_CMD_CODE: txOrRx = data_buf[0]; freq_Mhz = (data_buf[1] + (data_buf[2] << 8)); //TODO break;

case HCI_VS_RF_CW_DISABLE_CMD_CODE: //TODO break; case HCI_VS_RF_OUTPUT_PWR_CMD_CODE: pwr_dBm =

(int8_t)data_buf[0]; //TODO To be replace with HAL RF set output power function break; default: status =

CO_ERROR_INVALID_HCI_PARAM; break; }

return(status);

}

The above commands are implemented and can be found in the hci sample code.

## BLE_Set_MaxRFConnectionPwr

#### Prototype:

void BLE_Set_MaxRFConnectionPwr(void)

#### Parameters:

None

#### Return:

None

#### Description:

This API can be used by an application to set the maximum RF transmission output power for Bluetooth Low Energy connections. It must be invoked before a connection is established (RF transmission power cannot be changed during a connection and therefore calling this API during a connection does not change the power). This API calls Device_RF_SetMaxPwrIdx(), where it uses the rf_tx_power_dbm field of the ble_dev_params data structure; therefore, this rf_tx_power_dbm field must be set to the desired output power (dBm value) in advance by the application before a new connection is made.

NOTE: Setting the VDDPA Enable or Disable configuration is the application's responsibility The effect that the RF0_REG1A_PA_PWR_PA_PWR_BYTE field of the RF0_REG1A register has on output power is this API's responsibility.

#### Example:

/* Before a new Bluetooth Low Energy connection is established */

/* Set RF TX power to -5 dBm */

ble_dev_params.rf_tx_power_dbm = -5;

BLE_Set_MaxRFConnectionPwr();

## uint32_t ke_get_max_mem_usage

#### Prototype:

uint32_t ke_get_max_mem_usage(void)

#### Parameters:

None

#### Return:

Maximum memory used by the Bluetooth stack in the application

#### Description:

The maximum memory that the Bluetooth stack has used in the application at any time can be returned using this API.

#### Example:

/* Get the Maximum memory used by the Bluetooth stack in the application */

uint32_t max_mem_usage_stack = ke_get_max_mem_usage();

## uint16_t ke_get_mem_usage

#### Prototype:

uint32_t ke_get_max_mem_usage(void)

#### Parameters:

type : Kernel memory heap type which can be set using one of the following arguments

- KE_MEM_ENV: Memory allocated for environment variables
- KE_MEM_ATT_DB: Memory allocated for Attribute database
- KE_MEM_KE_MSG: Memory allocated for kernel messages
- KE_MEM_NON_RETENTION: Non-retention memory block

#### Return:

The amount of memory allocated for the specified Bluetooth stack heap type at the time of calling this API

#### Description:

The amount of memory that is allocated for the Bluetooth stack heap type of environment variables, attribute database, kernel messages, or non-retention memory block can be returned using this API.

#### Example:

/* Memory heap allocated for environment variables */

Uint32_t mem_env = ke_get_mem_usage(KE_MEM_ENV);

/* Memory heap allocated for Attribute database */

Uint32_t mem_env = ke_get_mem_usage(KE_MEM_ATT_DB);

/* Memory heap allocated for kernel messages*/

Uint32_t mem_env = ke_get_mem_usage(KE_MEM_KE_MSG);

/* Memory heap allocated for non-retention memory block */

Uint32_t mem_env = ke_get_mem_usage(KE_MEM_NON_RETENTION);

## BLE_Set_PhyReqMode

#### Prototype:

void BLE_Set_PhyReqMode(bool send_enable)

#### Parameters:

Send_enable: Set to true to enable passing the PHY request in any scenario; set to false to pass the PHY request only if the value is changed compared to the previous value.

#### Return:

None

#### Description:

By default, when an application sends a PHY request using the GAPC_SET_PHY_CMD message, the request is not sent if there is no difference between the ongoing PHY of the link and the PHY requested by the application. However, the request can be sent over the air, by calling BLE_Set_PhyReqMode and passing a true parameter to enable this behavior.

This API can be used to enable or disable the passing of PHY requests (even if the newly requested value is the same as before).

NOTE: BLE_Initialize() must be called before an application calls BLE_Set_PhyReqMode.

#### Example:

/* Make sure BLE_Initialize is called before calling this API */

BLE_Initialize(&param_ptr);

...

/* Enable sending PHY requests even if the PHY value is unchanged */

BLE_Set_PhyReqMode(true);

...