Baseband and Kernel Functions

To maximize the Bluetooth Low Energy connection stability, the stack must be provided sufficient processing time. We recommended that you:

  1. Set the stack interrupts to the highest priority to prevent preemption or ISR processing delays.
  2. Minimize the continuous time when interrupts are disabled
  3. Have the application call BLE_Kernel_Process() at least once per Bluetooth connection interval.

In the current sample code, all Bluetooth and non-Bluetooth interrupt priorities are set to 0 (highest priority). In future SDK updates, the priority of non-Bluetooth interrupts will be lowered. We recommend that customers make this change to their own code to lower the priority of all non-Bluetooth interrupts to maximize the Bluetooth Low Energy connection stability.

Use of the event kernel and baseband are primarily supported by the functions described in the "Event Kernel Support Functions" table. These functions initialize and execute these components, while supporting transitions between different power modes. Function prototypes for these functions are included through ble.h, and these prototypes are defined in ble/rwip.h.

Table: Event Kernel Support Functions

Function

Description

BLE_Initialize

Initialize the event kernel and Bluetooth baseband for use within an application.

BLE_Baseband_Sleep

Place the Bluetooth baseband to sleep if the current Bluetooth Low Energy stack and the event kernel state indicate it is safe.

BLE_Kernel_Process

Execute any pending events that have been scheduled with the event kernel.

BLE_Baseband_Is_Awake

Check if the Bluetooth baseband is awake.

BLE_Initialize

Prototype:

void BLE_Initialize(uint8_t * param_ptr)

Parameters:

Table: BLE_Initialize Parameters

Type

Parameters

Description

uint8_t *

param_ptr

Reserved for future use (input/output parameter)

Return:

None

Description:

Initializes the Bluetooth Low Energy stack and the event kernel for use within an application.

Example

/* Initialize the kernel and Bluetooth stack */

uint8_t param;

BLE_Initialize(&param);

BLE_Baseband_Sleep

Prototype:

uint8_t BLE_Baseband_Sleep(struct ble_sleep_api_param_tag *param_ptr)

Parameters:

Table: BLE_Baseband_Sleep Parameters

Type

Parameters

Description

struct ble_sleep_api_param_tag *

param_ptr

param_ptr->app_sleep_request

= Application sleep request; set to 1 if the Bluetooth baseband is intended to go to sleep when possible, 0 if the system is meant to stay awake

param_ptr->max_sleep_duration

= Requested maximum sleep duration in multiples of 312.5 μs (when this value is set to 0xFFFFFFFF, the maximum sleep duration is 36 hours and 16 minutes)

param_ptr->min_sleep_duration

= Requested minimum sleep duration in μs

param_ptr->calculated_sleep_duration

= Return value, in low power baseband clock cycles, providing the calculated sleep duration

NOTE: Minimum sleep duration that BLE_Baseband_Sleep() sets is the maximum value of min_sleep_duration and the BB_ENBPRESET_TWOSC bit field from the BB_ENBPRESET register.

Return:

Allowed sleep state.

  • RWIP_DEEP_SLEEP if the baseband controller has been put to sleep, the baseband timer is set, and the core can switch to Sleep Mode (after saving the baseband and RF registers) or Standby Mode.

  • RWIP_CPU_SLEEP if the core can be put to sleep, but the system is not meant to enter Sleep Mode or Standby Mode.

  • RWIP_ACTIVE otherwise.

Description:

A user application calls this function to put the system into Sleep Mode. This function performs the following operations:

  1. Checks the event kernel and Bluetooth Low Energy stack to decide whether it is the right time for the system to go into Sleep Mode
  2. Programs and starts the low-power BB timer (if requested)
  3. Puts the BB and RF hardware into Sleep Mode (if requested)
  4. Returns the calculated sleep duration and sleep decision to the application

The application uses input parameter param_ptr->app_sleep_request to indicate whether it requests this function to put the BB and RF hardware into Sleep Mode when possible (0x0: not requesting; 0x1: requesting). In detail:

When the application calls this function with param_ptr->app_sleep_request set to 0x0:

  • If Sleep Mode is possible, this function writes the expected baseband sleep duration (in low-power clock cycles) in the param_ptr->calculated_sleep_duration field, and returns RWIP_DEEP_SLEEP.

    NOTE: In this case, BLE_Baseband_Sleep() does not put the BB and RF hardware into Sleep Mode even if itis possible, because this has not been requested.

  • If Sleep Mode is not possible, this function returns RWIP_CPU_SLEEP or RWIP_ACTIVE.

When the application calls this function with param_ptr->app_sleep_request set to 0x1:

  • If Sleep Mode is possible, this function writes the expected baseband sleep duration (in low-power clock cycles) in the param_ptr->calculated_sleep_duration field, programs and starts the low-power BB timer, puts the BB and RF hardware into Sleep Mode, and finally returns RWIP_DEEP_SLEEP.
  • If Sleep Mode is not possible, this function returns RWIP_CPU_SLEEP or RWIP_ACTIVE.

In other words, the application calls BLE_Baseband_Sleep() with param_ptr->app_sleep_request set to 0x0 when it simply wants to check if Sleep Mode is possible and to get the expected baseband sleep duration. If Sleep Mode is possible, the application then might want to check the expected baseband sleep duration and other application-specific contexts to decide if it wants to enter Sleep Mode or not. If the application decides to enter Sleep Mode, it needs to call BLE_Baseband_Sleep() again with param_ptr->app_sleep_request set to 0x1.

Example:

/* Attempt to place the device to sleep */

struct ble_sleep_api_param_tag param;

param.app_sleep_request = 1;

param.max_sleep_duration = MAX_SLEEP_DURATION;

param.min_sleep_duration = MIN_SLEEP_DURATION;

 

switch(BLE_Baseband_Sleep(&param))

{

case RWIP_DEEP_SLEEP:

{

/* Save the baseband and RF registers, then go to sleep */

BB_Sleep(POWER_MODE);

break;

}

case RWIP_CPU_SLEEP:

{

/* Wait for interrupt */

__WFI();

break;

}

case RWIP_ACTIVE:

default:

{

}

}

BLE_Kernel_Process

Prototype:

void BLE_Kernel_Process(void)

Parameters:

None

Return:

None

Description:

Execute any pending events that have been scheduled with the event kernel.

Example:

/* Main application loop:

* - Run the kernel scheduler

* - Refresh the watchdog and wait for an interrupt before continuing */

while (1)

{

BLE_Kernel_Process();

/* Refresh the watchdog timer */

SYS_WATCHDOG_REFRESH();

/* Wait for an event before executing the scheduler again */

__WFI();

}

BLE_Baseband_Is_Awake

Prototype:

bool BLE_Baseband_Is_Awake(void)

Parameters:

None

Return:

True if the Bluetooth baseband is awake, false otherwise.

Description:

Check if the Bluetooth baseband is awake.

Example:

/* Check if the Bluetooth baseband is still awake */

if (BLE_Baseband_Is_Awake())

{

BLE_Baseband_Sleep(&param);

}