Host Image

本篇文档用于对 Bluetooth Host 及 GAP LIB 做一个简要的概述。

  • Bluetooth Host 实现 Bluetooth 的 Host 部分，使用 Bluetooth Host image 方案，提供单独的 Bluetooth Host image 供烧录，Bluetooth Host 和 APP 的升级是互相独立的。更多信息参见 Image 版本管理 和 Bluetooth Host Image 的使用方法 。

  • GAP LIB 用于提供 Bluetooth Host 的入口函数。Bluetooth Host image 应与对应的 GAP LIB 配合使用。更多信息参见 GAP LIB。

Image 版本管理

Bluetooth Host image 提供不同配置的 Bluetooth Host，用 upperstack_A_B 来表示。 A 和 B 的含义如下：

  • A 表示支持的蓝牙技术功能。
    如果多版 Bluetooth Host 含有相同的 A 值，那么这些 Bluetooth Host 支持的蓝牙技术功能相同。
    具体支持的蓝牙技术功能请参考 bin\upperstack_img\upperstack_A_B\upperstack_config.h，该文件的使用将在章节 Bluetooth Host Features 配置 详细介绍。
  • B 表示 Bluetooth Host 的 flash size 和 RAM size 的配置。
    具体配置详情请参考 bin\upperstack_img\readme。

Bluetooth Host Features 配置

关于Bluetooth Host Features的更多信息，可以参考 功能支持。 每一版 Bluetooth Host 都会提供一份 upperstack_config.h 文件供 APP 使用。该文件给出支持的蓝牙技术功能对应的宏定义， 0 表示不支持该 feature， 1 表示支持。宏定义和蓝牙技术功能的对应关系可参考下方表格：

宏定义和蓝牙技术功能的对应关系

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

当 Bluetooth Host 支持某个 feature 时，APP 才可以调用相应的 API。

例如，Bluetooth Host 支持 F_BT_LE_READ_CHANN_MAP。

#define F_BT_LE_READ_CHANN_MAP                   (F_BT_LE_SUPPORT && 1)

APP 可以通过调用 le_read_chann_map() 接口获取到 channel 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 配置

Bluetooth Host image 配置如下表所示：

不同配置的 Bluetooth Host Image

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

bin\upperstack_img 路径下存放的 readme 文件对不同配置的 Bluetooth Host image 进行了说明。

upperstack_0_0 为默认版本的 Bluetooth Host image。Bluetooth Host 具体支持的蓝牙技术功能请参考 upperstack_config.h 文件。

Bluetooth Host Image的Flash start address由 flash_map.h 文件中的 BANK0_UPPERSTACK_ADDR / BANK1_UPPERSTACK_ADDR 项定义。

Bluetooth Host image 包含的具体文件和路径如下表所示：

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 和 Bluetooth Host image 的升级是互相独立的，更新 Bluetooth Host image，APP 不需要重新编译。

Bluetooth Host Image 的使用方法

当使用 Bluetooth Host image 方案时，需要在 APP 的 Include Paths 中添加对应 upperstack_config.h 文件的路径。这一步是必要的，因为不同配置的 Bluetooth Host image 对应的 RAM size 可能不一样。同时，APP 还需相应修改 mem_config.h 文件。

RAM size 参数请参考表-不同配置的 Image 或者 bin\upperstack_img\readme 文件。

例如：当 APP 使用 upperstack_0_0 时，从 readme 文件中得到 Bluetooth Host 的 RAM size 为 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)

APP 的 mem_config.h 文件中， UPPERSTACK_GLOBAL_SIZE 的值应设置为大于等于 2K。

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

APP 的 Include Paths 设置如下图所示：

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

Include Paths

GAP LIB

GAP LIB 用于提供 Bluetooth Host 的入口函数，为 APP 提供 GAP 扩展功能。

GAP 扩展功能

Vendor 功能模块

提供一些厂家自定义的扩展功能。 更多信息参见 inc\bluetooth\gap\gap_lib\gap_vendor.h。

GAP LIB 的使用方法

SDK中提供不同版本（ bt_host_A_B） 的Keil LIB 和默认版本（ bt_host_0_0）的 GCC LIB :

LIB file: bin\gcc\libgap_utils.a

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

下面以 Keil LIB 为例，介绍 GAP LIB 的使用方法。

APP 需要在工程中添加 gap_utils.lib。如果 APP 使用 upperstack_A_B，则还应使用位于目录 bin\upperstack_img\upperstack_A_B 中匹配的 gap_utils.lib。

比方说，当 APP 使用 upperstack_0_0 文件夹中的 image 时，应在工程中添加的对应 gap_utils.lib 位于路径 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

在使用扩展功能之前，APP 需要调用 gap_lib_init() 初始化 gap_utils.lib 。

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

替换 Bluetooth Host Image

如果 APP 需要使用不同的蓝牙技术功能，那么 APP 需要根据实际情况同步替换 Bluetooth Host image。

例如，如果 APP 要用 upperstack_findmy_0 替换 upperstack_0_0 ，应按以下步骤操作:

  1. 下载 bin\upperstack_img\upperstack_findmy_0\upperstack_MP_xxxx.bin。

  2. 将 APP 工程中 Bluetooth Host image 的 Include Path 改成 bin\upperstack_img\upperstack_findmy_0。

  3. 将 APP 工程中使用的 GAP LIB 替换成 bin\upperstack_img\upperstack_findmy_0\gap_utils.lib。

  4. mem_config.h 文件中， UPPERSTACK_GLOBAL_SIZE 的值需要参照 bin\upperstack_img\readme 中 upperstack_findmy_0 的配置配合修改。