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 bt_host_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\rtl87x2g\bt_host_image\bt_host_A_B\bt_host_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\rtl87x2g\bt_host_image\readme.

Bluetooth Host Features Configurations

A bt_host_config.h file is provided in Bluetooth Host files for APP to use. The bt_host_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:

Supported Bluetooth Technology Feature

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_SUPPORT

LE Long Range

F_BT_LE_5_0_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

Angle of Arrival (AoA) and Angle of Departure (AoD)

F_BT_LE_5_1_AOA_AOD_SUPPORT

GATT Caching

Periodic Advertising Sync Transfer

F_BT_LE_5_1_PAST_SUPPORT

Bluetooth 5.2

LE Isochronous Channels

F_BT_LE_5_2_ISOC_SUPPORT

Enhanced Attribute Protocol

LE Power Control

F_BT_LE_5_2_POWER_CONTROL_SUPPORT

Bluetooth 5.3

LE Channel Classification

F_BT_LE_5_3_CHANNEL_CLASSIFICATION_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

bt_host_0_0 (default)

bin\\rtl87x2g\\bt_host_image\\bt_host_0_0

212K

3K

samples\\bluetooth\\xxx

bt_host_3_0

bin\\rtl87x2g\\bt_host_image\\bt_host_3_0

148K

3K

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

The bt_host_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 bt_host_config.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

bt_host_0_0 (default)

bin\\rtl87x2g\\bt_host_image\\bt_host_0_0\\bt_host_MP_xxxx.bin

bin\\rtl87x2g\\bt_host_image\\bt_host_0_0\\bt_host_config.h

subsys\\bluetooth\\gap_ext\\lib\\rtl87x2g\\bt_host_0_0\\mdk\\gap_utils.lib

subsys\\bluetooth\\gap_ext\\lib\\rtl87x2g\\bt_host_0_0\\gcc\\libgap_utils.a

bt_host_3_0

bin\\rtl87x2g\\bt_host_image\\bt_host_3_0\\bt_host_MP_xxxx.bin

bin\\rtl87x2g\\bt_host_image\\bt_host_3_0\\bt_host_config.h

subsys\\bluetooth\\gap_ext\\lib\\rtl87x2g\\bt_host_3_0\\mdk\\gap_utils.lib

subsys\\bluetooth\\gap_ext\\lib\\rtl87x2g\\bt_host_3_0\\gcc\\libgap_utils.a

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 bt_host_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 Configurations or the bin\rtl87x2g\bt_host_image\readme file.

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

/*================================================================*
 *                           bt_host_0_0                          *
 *================================================================*/
If Application uses bt_host_0_0, Application should configure NS_RAM_UPPERSTACK_SIZE as a value which is larger than or equal to (3 * 1024) in mem_config.h of Application.

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

The NS_RAM_UPPERSTACK_SIZE in mem_config.h file should be larger than or equal to 3K.

/** @brief data ram size for Bluetooth Host global variables and code */
#define NS_RAM_UPPERSTACK_SIZE         (3 * 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 subsys\bluetooth\gap_ext\inc\gap_vendor.h.

Usage of GAP LIB

APP shall add gap_utils.lib to the project. If APP uses bt_host_A_B, it shall also use the matching gap_utils.lib in the directory subsys\bluetooth\gap_ext\lib\rtl87x2g\bt_host_A_B.

For example, when APP uses the default Bluetooth Host image in directory bt_host_0_0, the matching gap_utils.lib directory is located in the directory subsys\bluetooth\gap_ext\lib\rtl87x2g\bt_host_0_0.

└── Project: broadcast
    └── secure_only_app
        └── Device
        ├── CMSE Library
        ├── Lib                      includes all binary symbol files that user APP is built on
            ├── ROM_NS.lib
            └── lowerstack.lib
            └── rtl87x2g_sdk.lib
            └── gap_utils.lib        includes gap_utils.lib
        ├── Peripheral
        ├── Profile
        └── 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 bt_host_3_0 to replace bt_host_0_0, follow the steps listed below:

  1. Download bin\rtl87x2g\bt_host_image\bt_host_3_0\bt_host_MP_xxxx.bin.

  2. Change the Bluetooth Host image Include Path in the APP project to bin\rtl87x2g\bt_host_image\bt_host_3_0.

  3. Change GAP LIB used in the APP project to subsys\bluetooth\gap_ext\lib\rtl87x2g\bt_host_3_0\mdk\gap_utils.lib.

  4. The NS_RAM_UPPERSTACK_SIZE in the mem_config.h file should be configured according to the bt_host_3_0 configuration in bin\rtl87x2g\bt_host_image\readme .