# Introduction

## Include and Object Files

The Bluetooth stack is accessed through the ble.h header file. This header is supported by a set of include files located in the include\ble folder of the installation.

The stack is extended by a number of GATT-based profiles and services. The headers for these profiles are located in the include\ble\profiles folder, and a list of the available supporting objects is provided in the "Bluetooth GATT-Based Profile and Service Object Files" table.

Table: Bluetooth GATT-Based Profile and Service Object Files
Profile Name | Profile | Profile Library Name | Profile Description
--- | --- | --- | ---
Battery Service | BAS | libbasc libbass | The Battery Service exposes the state of a battery within a device, or it reads the battery state of a peer device.
Device Information Service | DIS | libdisc libdiss | This service exposes manufacturer and/or vendor information about their own device or discovers peer device information.
Glucose Service | GLS | libglps | This service exposes glucose and other data from a personal glucose sensor for use in consumer healthcare applications.

All of the individual profile libraries use the Bluetooth Low Energy stack through the profile’s specified interfaces. These interfaces are documented in the interface specifications. Because the Bluetooth Low Energy stack itself requires a reciprocal link in order to find all of the profile components, the stack library has been built with an object factory that instantiates calls to each of the profiles. If a profile is used by an application, the Bluetooth stack needs to use the specified profile library.

## Bluetooth Stack

The RSL15 device supports a Bluetooth stack through a combination of hardware and firmware resources. The hardware components of the Bluetooth stack are described in the RSL15 Hardware Reference. The firmware components of the Bluetooth stack are accessible through a Bluetooth library and associated header files.

The Bluetooth stack is optionally accessible through HCI over UART or through the host (GAP, GATT, L2CAP) and profile APIs.

The "Bluetooth Stack and Kernel Object Files" table describes the Bluetooth stacks provided with RSL15 and their associated object files.

Table: Bluetooth Stack and Kernel Object Files
Stack Type | Library Name | Description
--- | --- | ---
Standard stack | \lib\ble_core\Release \lib\ble_profiles\Release | These libraries provide the complete standard stack and support for all RSL15 Bluetooth features.
HCI stack | \lib\ble_core\Release_HCI \lib\ble_profiles\Release_HCI | These libraries can be used with an HCI interface over UART.

## Stack Support Functions

The Bluetooth stack library includes a set of support functions that augment the stack firmware, as described in Bluetooth and Kernel Library. All other stack APIs are described in their reference documentation, with support for specific Bluetooth layers described in the following documents:

GAP

RW-BLE-GAP-IS.pdf

GATT

RW-BLE-GATT-IS.pdf

L2CAP

RW-BLE-L2C-IS.pdf

Profiles

RW-BLE-PRF-*-IS.pdf

## Managing Bluetooth Low Energy Stack RAM Usage

The Bluetooth Low Energy stack is provided as a complied library and cannot be modified by the user. However, some of the stack variables are defined at the application level, and the user has some control over the size of these variables. This is a guide to optimizing stack RAM memory usage by adjusting the application level variable defines as dependent upon the application use case.

The application level variables are defined to support the maximum number of connections and activities, which is 10 and 11 respectively, as described in the CEVA documentation provided with RSL15. If the application use case does not require the maximum number of connections and activities, application level variable sizes can be reduced to save memory.

NOTE: It is not recommended to adjust application level variable sizes in the HCI stack, as this can adversely affect Bluetooth certification.

The simplest method and recommended starting point to reduce stack memory usage is to reduce the value of APP_MAX_NB_CON. This scales most of the other application level variables as well, resulting in a reduction of memory usage. This is usually sufficient for most users. If you are an advanced user requiring further optimization, read on.

The memory allocated by the stack is divided into different parts. The first part comprises the required environment and global variables that are independent of the number of connections or activities. This part cannot be changed by developers.

The second part is heap memory, which the kernel takes as a global variable (.bss section), and later the kernel and the Bluetooth Low Energy stack use it as the heap memory for their procedures. It is divided into four parts:

- Environment variables
- Message heap memory
- Data base memory
- Non-retention memory

By default, all parameters are set to address the maximum number of connections and activities, which are 10 and 11 respectively. If definition APP_HEAP_SIZE_DEFINED is defined in the app.h file of any Bluetooth Low Energy application, then the heap sizes can be customized in the ble_protocol_support.c file (where they are defined and allocated). The following code example shows how the required memory sizes can be calculated (defined in ble_protocol_support.c).

/// Memory allocated for environment variables

uint32_t rwip_heap_env[RWIP_CALC_HEAP_LEN(APP_RWIP_HEAP_ENV_SIZE)];

/// Memory allocated for Attribute database

uint32_t rwip_heap_db[RWIP_CALC_HEAP_LEN(APP_RWIP_HEAP_DB_SIZE)];

/// Memory allocated for kernel messages

uint32_t rwip_heap_msg[RWIP_CALC_HEAP_LEN(APP_RWIP_HEAP_MSG_SIZE)];

/// Non Retention memory block

uint32_t rwip_heap_non_ret[RWIP_CALC_HEAP_LEN(APP_RWIP_HEAP_NON_RET_SIZE)];

We assume:

APP_MAX_NB_ACTIVITY and APP_MAX_NB_CON are defined in the application, based on the application’s use case. Please note that PP_BLE_CONNECTION_MAX needs to be at least one value bigger than APP_MAX_NB_CON.

APP_RWIP_HEAP_ENV_SIZE =

(600 + (APP_MAX_NB_ACTIVITY) * 230)

+ APP_MAX_NB_CON * ((sizeof(struct gapc_env_tag)

+ KE_HEAP_MEM_RESERVED)

+ (sizeof(struct gattc_env_tag) + KE_HEAP_MEM_RESERVED)

+ (sizeof(struct l2cc_env_tag) + KE_HEAP_MEM_RESERVED))

+ ((APP_MAX_NB_ACTIVITY ) * (sizeof(struct gapm_actv_scan_tag)

+ KE_HEAP_MEM_RESERVED))

APP_RWIP_HEAP_DB_SIZE: This depends on how much data base memory (GATT services) is added. The default value is 3072 bytes, but developers can choose a smaller value based on their use case (see Managing Bluetooth Low Energy Stack RAM Usage for more information).

APP_RWIP_HEAP_MSG_SIZE =

(1650 + 2 * ((16 + (APP_MAX_NB_ACTIVITY - 1) * 56)

+ (58 + (APP_MAX_NB_ACTIVITY - 1) * 26)

+ ((APP_MAX_NB_ACTIVITY) * 66)

+ ((APP_MAX_NB_ACTIVITY) * 100)

+((APP_MAX_NB_ACTIVITY) * 12)))

+(((BLEHL_HEAP_MSG_SIZE_PER_CON * APP_MAX_NB_CON) > BLEHL_HEAP_DATA_THP_SIZE)

?

(BLEHL_HEAP_MSG_SIZE_PER_CON * APP_MAX_NB_CON) : BLEHL_HEAP_DATA_THP_SIZE)

APP_RWIP_HEAP_NON_RET_SIZE: By default, this is set to 656 bytes. It is used for security algorithm calculations. This part of memory does not need to be in retention mode when the use case calls for keeping the Bluetooth Low Energy link active and going to sleep with VDDM in retention. If enough memory is allocated — for example, in the database — the kernel can allocate this part of memory from another heap. Developers need to make sure that this default amount of memory is available, in non-ret heap or in another heap.

In this way, users can set their own APP_MAX_NB_CON and APP_MAX_NB_ACTIVITY values, and decrease the memory size allocated by default settings.