Bluetooth LE Host Stack Initialization and APIs

Initialization

The application developer is required to configure the Host Task as part of the Host Stack requirement. The task is the context for running all the Host layers (GAP, GATT, ATT, L2CAP, SM, GATTDB)

The prototype of the task function is located in the ble_host_tasks.h file:

void Host_TaskHandler(void * args);

It should be called with NULL as an argument in the task code from the application.

Application developers are required to define task events and queues as explained in RTOS Task Queues and Events.

If the Controller software runs on the same chip as the Host, the Controller task always has a higher priority than the Host task. The priority value of the Host Task can be configured through the gHost_TaskPriority_c define (by default set in ble_host_task_config.h). Note that changing this value can have a significant impact on the Bluetooth Low Energy stack.

Parent topic:Bluetooth LE Host Stack Initialization and APIs

Main function to initialize the Bluetooth LE Host Stack

This Figure provides an overview of Bluetooth Low Energy Host Stack. When using the existing application common files, the startup task uses BluetoothLEHost_AppInit(), which is defined in app_conn.h. The function initializes all components related to the Bluetooth Low Energy application. It has the following prototype:

void BluetoothLEHost_AppInit(void);

The BluetoothLEHost_AppInit() function must be implemented by each application. It should register its generic event callback using BluetoothLEHost_SetGenericCallback() and initialize the Bluetooth LE Host Stack layer by calling BluetoothLEHost_Init(). The prototype for the BluetoothLEHost_Init() function is found in app_conn.h and is implemented in app_conn.c.

void BluetoothLEHost_Init
(
    appBluetoothLEInitCompleteCallback_t pCallback
);

BluetoothLEHost_Init takes as parameter a function to be called at the end of Bluetooth LE Host Stack initialization. In this callback, the application can register its callbacks with the Host layer, allocate timers, start services, and perform similar tasks. The callback should have a prototype as follows:

static void BluetoothLEHost_Initialized(void);

BluetoothLEHost_Init() is responsible for initializing the Host.

Initialize the Bluetooth LE Host Stack after platform setup is complete and all RTOS tasks have been started. The function that should be called for this purpose is located in the ble_general.h file and has the following prototype:

bleResult_t Ble_HostInitialize
(
    gapGenericCallback_t            genericCallback,
    hciHostToControllerInterface_t  hostToControllerInterface
);

Parent topic:Bluetooth LE Host Stack Initialization and APIs

HCI entry and exit points

The HCI entry point of the Host Stack is the second function located in the ble_general.h file:

void Ble_HciRecv
(
    hciPacketType_t packetType,
    void* pHciPacket,
    uint16_t packetSize
);

This is the function that the application must call to insert an HCI message into the Host.

An equivalent exists, to be used in ISR context:

bleResult_t Ble_HciRecvFromIsr
(
    hciPacketType_t     packetType,
    void*               pHciPacket,
    uint16_t            packetSize
);

Therefore, the Ble_HciRecv function and the hostToControllerInterface parameter of the Ble_HostInitialize function represent the two points that need to be connected to the LE Controller (see Bluetooth Low Energy Host Stack overview), either directly (if the Controller software runs on the same chip as the Host) or through a physical interface (for example, UART).

Parent topic:Bluetooth LE Host Stack Initialization and APIs

Bluetooth LE Host Stack libraries and API availability

All the APIs referenced in this document are available in the Central and Peripheral libraries. The support for Bluetooth 5.3 optional features such as Advertising, Advertising Extensions, GATT Caching, and EATT are provided in separate host libraries. They are distributed in a similar process as the legacy ones using GAP/GATT role support, which is described as follows.

For example, below are listed the full-featured libraries with complete support for both Central and Peripheral APIs, at GAP level.

  • lib_ble_OPT_host_cm33_iar.a (for IAR projects)

  • lib_ble_OPT_host_cm33_gcc.a (for MCUX projects)

These libraries include optional features implemented by the Bluetooth LE Host. For applications that need to use only the mandatory 5.3 Bluetooth LE and below features, the lib_ble_host_cm33_iar.a or lib_ble_host_cm33_gcc.a libraries can be used instead.

However, some applications may be targeted to memory-constrained devices and do not need the full support. In the interest of reducing code size and RAM utilization, optimized libraries are provided:

  • lib_ble_host_peripheral_cm33_iar.a/ lib_ble_host_peripheral_cm33_gcc.a and

  • lib_ble_OPT_host_peripheral_cm33_iar.a / lib_ble_OPT_host_peripheral_cm33_gcc.a.

    • Support only APIs for the GAP Peripheral and GAP Broadcaster roles

    • Support only APIs for the GATT Server role

  • lib_ble_host_central_cm33_iar.a and lib_ble_OPT_host_central_cm33_iar.a

  • lib_ble_host_central_cm33_gcc.a and lib_ble_OPT_host_central_cm33_gcc.a

    • Support only APIs for the GAP Central and GAP Observer roles

    • Support only APIs for the GATT Client role

If one attempts to use an API that is not supported (for instance, calling Gap_Connect with the lib_ble_host_peripheral_cm33_iar.a and lib_ble_host_peripheral_cm33_gcc.a), then the API returns the gBleFeatureNotSupported_c error code.

Similarly, if the API for OPT is used with a host library that does not have support for optional features, then gBleFeatureNotSupported_c is returned. For instance, calling Gap_SetExtAdvertising parameters with the lib_ble_host_peripheral_cm33_iar.a and lib_ble_host_peripheral_cm33_gcc.a) returns the exit code gBleFeatureNotSupported_c.

Note: See the Bluetooth Low Energy Host Stack API Reference Manual for explicit information regarding API support. Each function documentation contains this information in the Remarks section.

Parent topic:Bluetooth LE Host Stack Initialization and APIs

Synchronous and asynchronous functions

The vast majority of the GAP and GATT APIs are executed asynchronously. Calling these functions generates a message and places it in the Host Task message queue.

Therefore, the actual result of these APIs is signaled in events triggered by specific callbacks installed by the application. See the Bluetooth Low Energy Host Stack API Reference Manual for specific information about the events that are triggered by each API.

However, there are a few APIs which are executed immediately (synchronously). This is explicitly mentioned in the Bluetooth Low Energy Host Stack API Reference Manual in the Remarks section of each function documentation.

If nothing is mentioned, then the API is asynchronous.

Parent topic:Bluetooth LE Host Stack Initialization and APIs

Radio TX Power level

The controller interface includes APIs that can be used to set the Radio TX Power to a different level than the default one.

The power level can be set differently for advertising and connection channels by calling the function Controller_SetTxPowerLevelDbm() with the channel parameter set to gAdvTxChannel_c or gConnTxChannel_c.

Parent topic:Bluetooth LE Host Stack Initialization and APIs