# Use of the Event Kernel and Bluetooth Stack

Applications using the event kernel and Bluetooth Stack make use of both the custom API, described in Baseband and Kernel Functions, and standard event kernel and Bluetooth Stack APIs, as described in the provided CEVA/RivieraWaves documentation.

IMPORTANT: To ensure Bluetooth connection stability, the Event Kernel and Bluetooth stack require that their interrupts be handled in a timely manner. For maximum Bluetooth stability, their interrupts must remain enabled throughout a connection interval and must be configured as the highest priority interrupts in the system to avoid preemption. For more information, see Baseband and Kernel Functions.

To assist in understanding the event kernel and Bluetooth stack, the following sections outline the customary usage of these components within the context of a typical application use case.

## The Kernel Scheduler

The kernel scheduler is responsible for constantly checking messages communicated by different tasks. Applications might use as few as one task, although more complex applications typically include several tasks. Additionally, applications can contain multiple instances of the same task.

Different application tasks control different Bluetooth Low Energy functionalities. An application sometimes needs to communicate with different tasks, such as GAPM, GAPC, GATTM, GATTC, and different standard and custom profiles (services). The kernel scheduler is responsible for handling these messages.

When the application needs to send a message, it allocates memory in the kernel buffer, fills in the message with any parameter that it wants to send, and then fills in the source address and destination address as the message identifier. The application calls a function from the kernel asking to send this message to the destination. The kernel scheduler checks that buffer. If it is filled, the scheduler sends the message to the destination task by automatically calling a pre-defined message handler. The kernel scheduler also handles all timers used by the stack, services, or application. When a timer expires, the kernel scheduler automatically calls a function or message handler allocated to the timer’s identifier.

## Message Handlers

Coordinating with the event scheduler, the message handlers manage any request or command associated with a scheduled event.

For example, any message, request or command sent from the application to the GAPM has an associated GAPM_COMPLETE event. This event message is sent from the stack to the application. Based on its message identifier, this message is called automatically by the kernel.

NOTE: We recommend that users read the CEVA documentation for GATT and GAP before attempting to add their own message handler for a specific API or message.

To add a message handler, you first need to add DEFINE_MESSAGE_HANDLER in the corresponding .h file, and define a function in the corresponding file, which can be ble_standard.h, application.h, or standard_profile.h.

To add a message handler, users must:

1. Add a task message ID for the handler to the message enumeration used by the application.

2. Add a callback function and function prototype that executes when an event with the task message ID added in step 1 occurs.

3. Register the task message ID and callback function using:

   MsgHandler_Add(ke_msg_id_t const msg_id, MsgHandlerCallback_t callback);

## Core Bluetooth Profiles

Core Bluetooth profiles provide the standard communications structures needed to communicate between devices and to organize Bluetooth data. These core profiles are listed here:

- The Generic Access Profile (GAP) contains standard compliant implementations of the broadcasting and connecting mechanisms by which a Bluetooth Low Energy device can communicate with the outside world. The GAP implementation is divided into GAPM (GAP Manager) and GAPC (GAP Controller) services, and is described in the GAP Interface Specification.
- The Generic Attribute Profile (GATT) contains rules for how attributes (data) are formatted, packaged, and sent between Bluetooth Low Energy devices once they have a dedicated connection. The GATT implementation is divided into GATTM (GATT Manager) and GATTC (GATT Controller) services, and is described in CEVA’s GATT Interface Specification.

## Standard Profiles and Services

Standard services are pre-defined data structures and methods, which Bluetooth Low Energy devices can use to communicate Bluetooth-specific data between devices in a standardized way. Standard profiles define how a group of one or more services interact and are used.

The attributes of standard services are already recognized by the Bluetooth Low Energy stack, so you do not need to list the attributes when adding standard services to an application. Each standard service has a 16-bit UUID (unique numeric identifier).

## Custom Profiles and Services

Custom services, like standard services, are data structures, and the methods which Bluetooth Low Energy devices can use to communicate with, and work with, your Bluetooth Low Energy applications to add functionality. Unlike standard services, custom services are not pre-defined. Users control what custom services do, creating them to meet the needs of their own applications. For custom services, a list all of the attributes needed for the service must be provided to the stack, because the stack cannot automatically tell which attributes to add. Each custom service needs a 128-bit UUID.

Custom profiles can be defined that use both standard and custom services in similar ways to standard profiles.

## Event Kernel and Bluetooth Low Energy Library Initialization and Execution

When using the event kernel and Bluetooth stack in a user application, the application must:

- Initialize the event kernel and Bluetooth stack using the BLE_Initialize() function, described in Baseband and Kernel Functions.
- Periodically execute the kernel scheduler using the BLE_Kernel_Process() function, described in Scheduler.
  - For proper operation, this function must be called in the application’s main loop prior to placing the core into a state waiting for an interrupt.
  - If using low power modes, the BLE_Baseband_Sleep() function needs to be called after running the event scheduler before going to sleep. Only transition the device to Sleep Mode or Standby Mode if this function returns RWIP_DEEP_SLEEP.

NOTE: While connected to a remote device, the application must allow Bluetooth- and RF-related interrupts to be handled regularly, by not disabling and blocking interrupts for multiple Bluetooth connection periods.