Host Image

The purpose of this document is to give an overview of the Bluetooth Host and GAP LIB.

  • Bluetooth Host implements the Host part of Bluetooth, using the Bluetooth Host image solution, providing a separate Bluetooth Host image for downloading. Bluetooth Host and APP update independently. Bluetooth Host image will be introduced in detail in the chapter Image Version Management and Usage of Bluetooth Host Image.

  • GAP LIB provides the entry functions for Bluetooth Host. Bluetooth Host image shall be used in conjunction with the matching GAP LIB. More information can be found in the chapter GAP LIB.

Image Version Management

Bluetooth Host image provides Bluetooth Host with different configurations. The different configurations of Bluetooth Host files are represented by upperstack_A_B, where A and B have the following meanings:

  • A indicates the supported Bluetooth technology features in Bluetooth Host files.
    If Bluetooth Host configurations contain the same A value, it means that Bluetooth Host files with these configurations support the same Bluetooth technology features.
    For details about the specific Bluetooth technology features supported by Bluetooth Host, please refer to the bin\upperstack_img\upperstack_A_B\upperstack_config.h, which will be introduced in detail in the chapter Bluetooth Host Features Configurations.
  • B indicates the configuration of flash size and RAM size of Bluetooth Host.
    For specific configurations of Bluetooth Host files, please refer to bin\upperstack_img\readme.

Bluetooth Host Features Configurations

For more information about Bluetooth Host Features, please refer to Supported Features. A upperstack_config.h file is provided in Bluetooth Host files for APP to use. The upperstack_config.h file contains macro definitions that correspond to the supported Bluetooth technology features. In these macro definitions, 0 indicates that the feature is not supported, while 1 indicates that the feature is supported. For more information about the relationship between the macro definitions and Bluetooth technology features, please refer to the table below:

The Relationship Between Macro Definitions and Bluetooth Technology Features

Spec Version

Bluetooth Technology

Macro Definition

Bluetooth 4.0

Advertiser

Scanner

F_BT_LE_GAP_SCAN_SUPPORT

Initiator

Central

F_BT_LE_GAP_CENTRAL_SUPPORT

Peripheral

F_BT_LE_GAP_PERIPHERAL_SUPPORT

Bluetooth 4.1

Low Duty Cycle Directed Advertising

LE L2CAP Connection Oriented Channel

LE Scatternet

LE Ping

Bluetooth 4.2

LE Data Packet Length Extension

F_BT_LE_4_2_DATA_LEN_EXT_SUPPORT

LE Secure Connections

F_BT_LE_4_2_SC_SUPPORT

Link Layer Privacy (Privacy1.2)

F_BT_LE_PRIVACY_SUPPORT

Link Layer Extended Filter Policies

F_BT_LE_PRIVACY_SUPPORT

Bluetooth 5

2 Msym/s PHY for LE

F_BT_LE_5_0_SET_PHYS_SUPPORT

LE Long Range

F_BT_LE_5_0_SET_PHYS_SUPPORT

High Duty Cycle Non-Connectable Advertising

LE Advertising Extensions

F_BT_LE_5_0_AE_ADV_SUPPORT

F_BT_LE_5_0_AE_SCAN_SUPPORT

Bluetooth 5.1

AoA and AoD

F_BT_LE_5_1_AOA_AOD_SUPPORT

GATT Caching

Periodic Advertising Sync Transfer

F_BT_LE_5_1_PAST_SUPPORT

When the Bluetooth Host supports a feature, APP can invoke the reference API.

For example, if Bluetooth Host supports F_BT_LE_READ_CHANN_MAP.

#define F_BT_LE_READ_CHANN_MAP                   (F_BT_LE_SUPPORT && 1)

APP can read channel map by invoking le_read_chann_map().

/**
* @brief   Read the used channel map of the connection. Channel map value will be returned by
*          @ref app_gap_callback with cb_type @ref GAP_MSG_LE_READ_CHANN_MAP.
*
* @param[in] conn_id Connection ID.
* @return  Read request result.
* @retval  GAP_CAUSE_SUCCESS: Read request sent success.
* @retval  GAP_CAUSE_NON_CONN: Read request sent fail.
*/
T_GAP_CAUSE le_read_chann_map(uint8_t conn_id);

Bluetooth Host Image Configurations

The configurations of Bluetooth Host image are shown in the following table:

Bluetooth Host Image with Different Configurations

Bluetooth Host Image

Image Directory

Flash Size

RAM Size

Reference Project

upperstack_0_0 (default)

bin\upperstack_img\upperstack_0_0

144K

2K

board\evb\ble_xxx

upperstack_findmy_0

bin\upperstack_img\upperstack_findmy_0

100K

2K

The readme file located in bin\upperstack_img directory introduces Bluetooth Host images with different configurations.

The upperstack_0_0 is the default configuration of Bluetooth Host image. For the details of specific Bluetooth technology features supported by Bluetooth Host, please refer to the upperstack_config.h file.

The Flash start address of the Bluetooth Host Image is defined by the BANK0_UPPERSTACK_ADDR / BANK1_UPPERSTACK_ADDR in flash_map.h file.

The specific files contained in the Bluetooth Host image and the directory are described in the following table:

Files List of Bluetooth Host Image

Bluetooth Host Configuration

Files of Bluetooth Host

upperstack_0_0 (default)

bin\upperstack_img\upperstack_0_0\upperstack_MP_xxxx.bin

bin\upperstack_img\upperstack_0_0\upperstack_config.h

bin\upperstack_img\upperstack_0_0\gap_utils.lib

upperstack_findmy_0

bin\upperstack_img\upperstack_findmy_0\upperstack_MP_xxxx.bin

bin\upperstack_img\upperstack_findmy_0\upperstack_config.h

bin\upperstack_img\upperstack_findmy_0\gap_utils.lib

APP image and Bluetooth Host image are upgraded independently. To update Bluetooth Host image, there is no need to recompile the APP.

Usage of Bluetooth Host Image

When using the Bluetooth Host image, the APP should add the directory of the corresponding upperstack_config.h file to the Include Paths. This is necessary because the RAM size may vary depending on the configuration of the Bluetooth Host image. Additionally, the APP needs to modify the mem_config.h file. For the RAM size parameter, please refer to Table-Bluetooth Host Image with Different Configuration or the bin\upperstack_img\readme file.

For example, when APP uses upperstack_0_0, the RAM size of Bluetooth Host that is obtained from readme file is 2K.

/*============================================================================*
*                          upperstack_0_0                                    *
*============================================================================*/
If Application uses upperstack_0_0, Application should configure UPPERSTACK_GLOBAL_SIZE
as value which is larger than or equal to (2 * 1024) in mem_config.h of Application.

/** @brief data ram size for upperstack global variables and code */
#define UPPERSTACK_GLOBAL_SIZE        (2*1024)

The UPPERSTACK_GLOBAL_SIZE in mem_config.h file should be larger than or equal to 2K.

/** @brief data ram size for Bluetooth Host global variables and code */
#define UPPERSTACK_GLOBAL_SIZE         (2 * 1024)

The Include Paths configuration in the APP is shown in the following figure:

../../../../_images/include_path.png

Include Paths

GAP LIB

GAP LIB provides the entry functions for Bluetooth Host and extension functions for APP.

GAP Extension Function

Vendor Function module

Vendor function module provides vendor-specific functions. For more information, please refer to inc\bluetooth\gap\gap_lib\gap_vendor.h.

Usage of GAP LIB

The SDK provides different versions ( bt_host_A_B) of Keil LIB and the default version ( bt_host_0_0) of GCC LIB:

LIB file: bin\gcc\libgap_utils.a

LIB file: bin\upperstack_img\upperstack_A_B\gap_utils.lib

Below, the usage of GAP LIB is introduced using the Keil LIB as an example.

APP shall add gap_utils.lib to the project. If APP uses upperstack_A_B, it shall also use the matching gap_utils.lib in the directory bin\upperstack_img\upperstack_A_B.

For example, when APP uses the default Bluetooth Host image in directory upperstack_0_0, the matching gap_utils.lib directory is located in the directory bin\upperstack_img\upperstack_0_0.

└── Project: broadcaster
    └── broadcaster
        └── include
        ├── lib                      Includes all binary symbol files that user application is built on.
            ├── ROM.lib
            ├── gap_utils.lib        Includes gap_utils.lib.
            ├── lowerstack.lib
            └── rtl8752h_sdk.lib
        ├── cmsis
        ├── peripheral
        └── app

And it is necessary to initialize gap_utils.lib with the gap_lib_init() function before using extension functions.

int main(void)
{
   ......
   gap_lib_init();
   ......
   task_init();
   os_sched_start();
   return 0;
}

Replace Bluetooth Host Image

If APP requires different Bluetooth technology features, then APP shall replace the Bluetooth Host image according to actual needs.

For example, if APP needs to use upperstack_findmy_0 to replace upperstack_0_0, follow the steps listed below:

  1. Download bin\upperstack_img\upperstack_findmy_0\upperstack_MP_xxxx.bin.

  2. Change the Bluetooth Host image Include Path in the APP project to bin\upperstack_img\upperstack_findmy_0.

  3. Change GAP LIB used in the APP project to bin\upperstack_img\upperstack_findmy_0\gap_utils.lib.

  4. The UPPERSTACK_GLOBAL_SIZE in the mem_config.h file should be configured according to the upperstack_findmy_0 configuration in bin\upperstack_img\readme .