UG136: Silicon Labs Bluetooth
®
C
Application Developer's Guide
本文档是使用
Silicon Labs Bluetooth 协议栈为 Silicon Labs
Wireless Gecko 产品开发基于 C 语言的应用的开发人员的必要参
考。本指南的内容涵盖 Bluetooth 协议栈体系结构、应用开发流
程、MCU 内核和外围设备使用和限制、协议栈配置选项以及协议
栈资源使用。该版本适用于 Silicon Labs Bluetooth SDK 2.13.x 及
更高版本。
本文档的目的是发现并弥补 Bluetooth 协议栈 API 参考、Gecko SDK API 参考和 Wireless Gecko
参考手册之间在开发 Wireless Gecko 所用 Bluetooth 应用方面的空白。本文档中呈现的细节可帮助
开发人员充分利用可用的硬件资源。
内容要点
• 项目结构和开发流程
• Bluetooth 协议栈和 Wireless Gecko 配置
• 中断处理
• 事件和睡眠管理
• 资源使用和可用资源
silabs.com | Building a more connected world. Rev. 1.7
目录
1. 介绍 ...................................4
1.1 关于此版本 ...............................4
1.2 必备条件 ................................4
2. 应用开发流程................................5
2.1 应用构建流程 ..............................6
3. 项目结构 .................................7
3.1
Bluetooth 文件 ..............................7
3.2 GATT 数据库 ..............................9
3.3 设备固件升级 ..............................9
3.4 RTOS 支持 ...............................9
3.5 多协议支持 ...............................9
3.6 硬件支持 ................................10
4. 配置 Bluetooth 协议栈和 Wireless Gecko 设备 ..................11
4.1 Wireless Gecko MCU 和外围设备配置 ......................11
4.1.1 自适应跳频 ..............................11
4.1.2 Bluetooth 时钟 ............................11
4.1.3 DC-DC 配置 .............................12
4.1.4 LNA ................................12
4.1.5 定期广播 ..............................13
4.1.6 PTI ................................13
4.1.7 发射功率 ..............................13
4.1.8 白名单 ...............................13
4.1.9 Wi-Fi 共存 ..............................14
4.2 使用 gecko_stack_init() 配置 Bluetooth ......................14
4.2.1 CONFIG_FLAGS............................14
4.2.2 Mbedtls ...............................14
4.2.3 多协议优先级配置 ...........................15
4.2.4 睡眠模式 ..............................15
4.2.5 Bluetooth 协议栈配置 ..........................16
4.2.6 OTA 配置 ..............................16
4.2.7 PA.................................17
4.2.8 软件定时器 ..............................17
4.2.9 RF 路径 ...............................17
5. Bluetooth 协议栈事件处理 ..........................18
5.1 阻塞事件侦听器..............................18
5.2 非阻塞事件侦听器 .............................18
5.2.1 睡眠和非阻塞事件侦听器 .........................19
5.2.2 更新事件侦听器的通知 ..........................19
5.3 用于 Micrium OS 的事件侦听器 ........................20
5.3.1 来自多个任务的命令...........................20
silabs.com | Building a more connected world. Rev. 1.7 | 2
6. 中断 ..................................21
6.1 外部事件 ................................21
6.2 优先级 .................................22
7. Wireless Gecko 资源 ...........................23
7.1 闪存 .................................24
7.1.1 优化闪存使用量 ............................24
7.2 链接 .................................25
7.3 RAM .................................25
7.3.1 Bluetooth 协议栈 ............................25
7.3.2 Bluetooth 连接池 ............................25
7.3.3 Bluetooth GATT 数据库 .........................25
7.3.4 调用协议栈 ..............................26
7.3.5 堆内存 ...............................26
7.4 RTCC .................................26
8. 应用 ELF 文件 ..............................27
9. 文档 ..................................28
silabs.com | Building a more connected world. Rev. 1.7 | 3
1. 介绍
本文档是 C 语言开发人员的 Silicon Labs Bluetooth 协议栈指南。
本文档的内容涵盖各种开发角度，是使用 Bluetooth 协议栈为 Wireless Gecko 产品开发基于 C 语言的应用的开发人员的重要参考。
本文档的内容涵盖以下主题：
• 章节 2. 应用开发流程 讨论了应用开发流程。
• 章节 3. 项目结构 论述了项目结构。
• 章节 4. 配置 Bluetooth 协议栈和 Wireless Gecko 设备 解释了项目，包括库和应用代码中的实际 Wireless Gecko 配置。
• 章节 5.
Bluetooth 协议栈事件处理 对使用 Silicon Labs Bluetooth 协议栈进行开发的每位开发人员都很重要，因为它解释了应用如何在一个基于事件的
体系结构中与协议栈同步运行。
• 章节 6. 中断 和章节 7. Wireless Gecko 资源 涉及的主题是外围设备和芯片组资源，内容涵盖为协议栈使用预留的资源、正确的中断处理方法，以及协
议栈的内存占用和应用的可用内存。
1.1 关于此版本
Silicon Labs Bluetooth SDK 的当前版本为 2.13.x。
当前支持的编译器和 IDE 版本为：
• IDE：Simplicity Studio 4.1.11 或更新版本
• 编译器：IAR v8.30.1 和 GCC 7.2.1
1.2 必备条件
本文档假设开发计算机（Windows、MAC OSX 或 Linux）上已正确安装 Silicon Labs 当前版本的 Bluetooth SDK，且读者熟悉快速入门指南和 SDK 示
例。此外，读者应对 Bluetooth 技术有基本的了解。有关更多信息，请参见
《
UG104.13
：
Bluetooth
技术基础知识》
。
有关在 Silicon Labs Simplicity Studio 开发环境中开始使用示例应用的说明，请参见
《
QSG139
：使用
Simplicity Studio
进行
Bluetooth
开发》
。
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
介绍
silabs.com | Building a more connected world. Rev. 1.7 | 4
2. 应用开发流程
下图描述了高级固件结构。开发人员在协议栈基础之上创建应用，该协议栈是
Silicon Labs 提供的预编译对象文件，可实现终端设备所需的 Bluetooth 连
接性。
Figure 2.1. Bluetooth 协议栈体系结构方框图
Bluetooth 协议栈包含以下块。
• Bootloader
- Gecko Bootloader 不是协议栈的一部分，但随 Bluetooth SDK 一起提供。请参阅
《
UG266
：
Gecko Bootloader
用户指南》
和
《
AN1086
：将
Gecko Bootloader
与
Silicon Labs Bluetooth
应用一起使用》
了解更多信息。有关引导装载的一般信息，请参阅
《
UG103.06
：引导装载
基础知识》
。
• Bluetooth 协议栈——Bluetooth 功能包括链路层、通用访问配置文件、安全管理器、属性协议和通用属性配置文件。
• Bluetooth AppLoader - 在引导装载程序之后启动的应用。它会检查用户应用是否有效，如果检查有效，AppLoader 便会启动应用。如果应用映像无
效，AppLoader 便会启动 OTA 进程以尝试接收有效的应用映像。这需要使用 Gecko Bootloader。
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
应用开发流程
silabs.com | Building a more connected world. Rev. 1.7 | 5
2.1 应用构建流程
Figure 2.2. Bluetooth 项目构建流程
要构建项目，首先必须定义
Bluetooth 服务和特性（GATT 定义），并通过 Silicon Labs 提供的示例或任何空项目模板编写应用源代码，如
《
QSG139
：
使用
Simplicity Studio
开发
Bluetooth
应用》
中所述。
SDK v2.1.0 和更新版本提供了两种 Bluetooth 服务和特性的定义方式。第一个选项是 Simplicity Studio 中的 Visual GATT Editor GUI。这是一个图形工
具，用于设计 GATT 和生成 gatt_db.c 与 gatt_db.h。此外，它可以导入 .xml 和 .bgproj GATT 定义文件。Visual GATT Editor 是 Simplicity Studio 项目中
的默认 GATT 定义和生成工具。
第二个选项是创建 .xml 或 .bgproj（根据
《
UG118
：
Blue Gecko Bluetooth® Profile Toolkit
开发人员指南》
），然后将 BGBuild 可执行文件用作预编译步
骤，以便将 GATT 定义文件转换为 .c 和 .h。IAR Embedded Workbench 项目使用的就是这种方法。
编译项目会生成一个对象文件，该文件随后会链接至 SDK 中提供的预编译库。该链接的输出是一个闪存映像，可以编程到支持的 Wireless Gecko 设备
中。
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
应用开发流程
silabs.com | Building a more connected world. Rev. 1.7 | 6
3. 项目结构
本节解释了应用项目结构以及必须包含在项目中的必要和可选资源。
3.1 Bluetooth 文件
库文件
Bluetooth 协议栈库是：
• binapploader.o：Bluetooth AppLoader 的二进制映像，提供可选的 OTA（无线）功能。
• binapploader_nvm3.o: 支持 NVM3 的系列 1 Bluetooth AppLoader 的二进制映像。
• libbluetooth.a：Bluetooth 协议栈库。
• libmbedtls.a：Bluetooth 协议栈的 mbed TLS 加密库。
• libpsstore.a: Bluetooth 协议栈的 PS 存储功能。EFR32BG2x 设备不提供此功能。请务必改用 NVM3。
RAIL
Bluetooth 协议栈使用
RAIL 访问无线电，RAIL 库需要与 Bluetooth 协议栈链接。RAIL 为每个设备产品系列以及单协议和多协议环境提供了单独的库。
Gecko SDK 中提供了 RAIL 库。有关更多信息，请参阅
《
UG103.13
：
RAIL
基础知识》
和其他 RAIL 文档。
Note: 为确保无线电模块的合规性，无线电模块的 Bluetooth 协议栈需要链接到无线电模块的 RAIL 库和配置库。这些库是 librail_module_<soc
family><compiler>_release.a 和 librail_config<modulename>.a。
EMLIB 和 EMDRV
Bluetooth 协议栈使用 EMLIB 和 EMDRV 库访问 EFR32 硬件。源代码中提供了 EMLIB 和 EMDRV 外围设备库，必须将这些库包含到项目中。EMLIB 和
EMDRV 是 Gecko SDK 的一部分。有关 EMLIB 和 EMDRV 的更多信息，请参阅<Simplicity Studio Gecko SDK> \platform\bootloader\documentation
\Gecko_Bootloader_API_Reference\index.html 中的 Gecko Bootloader API 参考信息，以及 <Simplicity Studio Gecko SDK>\platform\ 下相应文件夹中的
文档。
睡眠定时器
睡眠定时器是一个提供单次定时器和周期定时器的平台组件。Bluetooth 协议栈将它用于深度睡眠，而且必须包含在项目中。定时器分频器
(SL_SLEEPTIMER_FREQ_DIVIDER in sl_sleeptimer_config.h) 必须配置为 1。
头文件
bg_version.h
该文件包含 Bluetooth 协议栈版本。
API 头文件
这些文件定义了 Bluetooth 协议栈 API。有三个用于不同使用案例的不同文件。只须包括其中一个文件。native_gecko.h 与裸机 Bluetooth 应用一起使用。
ncp_gecko.h 在构建用于支持 NCP 的 SoC 应用时使用。rtos_gecko.h 与 Micrium RTOS 一起使用。
这些文件有两个用途：第一，它们包含实际的 Bluetooth 协议栈 API 以及该协议栈的命令和事件；第二，它们向 Bluetooth 协议栈提供配置、事件和睡眠
管理 API。
配置、事件和睡眠管理 API 在下文中有介绍。
errorcode_t gecko_init(const gecko_configuration_t*config)
此函数需要单一参数，即指向 gecko_configuration_t 结构体的指针。它的目的在于使用结构体中提供的参数配置和初始化 Bluetooth 协议栈。第 4.2 使用
gecko_stack_init() 配置 Bluetooth 节中更详细地讨论了配置选项和 gecko_init() 的使用方法。应用必须调用 gecko_init() 以初始化 Bluetooth 协议栈。
此函数是出于方便目的而提供。它初始化 Bluetooth 协议栈中的所有功能。要更细致地进行配置，请使用 gecko_stack_init()，如下所述。
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
项目结构
silabs.com | Building a more connected world. Rev. 1.7 | 7
errorcode_t gecko_stack_init(const gecko_configuration_t*config)
此函数需要单一参数，即指向 gecko_configuration_t 结构体的指针。它的目的在于使用结构体中提供的参数配置和初始化
Bluetooth 协议栈。一旦调用函
数 gecko_stack_init()，就必须单独初始化使用的各个协议栈组件。这种单独初始化不包含那些不必要的协议栈组件，从而可实现内存优化。
可以使用以下 API 来单独初始化协议栈组件：
• gecko_bgapi_class_dfu_init();
• gecko_bgapi_class_system_init();
• gecko_bgapi_class_le_gap_init();
• gecko_bgapi_class_le_connection_init();
• gecko_bgapi_class_gatt_init();
• gecko_bgapi_class_gatt_server_init();
• gecko_bgapi_class_endpoint_init();
• gecko_bgapi_class_hardware_init();
• gecko_bgapi_class_flash_init();
• gecko_bgapi_class_test_init();
• gecko_bgapi_class_sm_init();
struct gecko_cmd_packet*gecko_wait_event(void)
这是一个阻塞函数，等待 Bluetooth 协议栈发出事件并进行阻塞，直至收到事件。一旦收到事件，将返回指向 gecko_cmd_packet 结构体的指针。
如果已在 Bluetooth 协议栈配置中启用 EM 睡眠模式，当未收到 Bluetooth 协议栈发出的任何事件时，设备将自动进入 EM1 或 EM2 模式。要确保设备只
要有可能就进入功耗最低的睡眠模式，最简单的方法就是使用 gecko_wait_event()。
章节 5. Bluetooth 协议栈事件处理 详细讨论了 Bluetooth 协议栈的事件处理。
struct gecko_cmd_packet* gecko_peek_event(void)
这是一个非阻塞函数，用于请求 Bluetooth 协议栈发出 Bluetooth 事件。当请求了事件且事件队列不为空时，将返回指向 gecko_cmd_packet 结构体的指针。
如果事件队列中没有任何事件，则返回 NULL。
当使用此非阻塞事件侦听器时，必须由应用代码管理 EM 睡眠模式，因为 Bluetooth 协议栈不会自动管理它们。睡眠模式管理是使用 gecko_can_sleep_ms()
和 gecko_sleep_for_ms() 函数实现的，稍后会有对这两个函数的讨论。
章节 5. Bluetooth 协议栈事件处理 详细讨论了协议栈的事件处理。
int gecko_event_pending(void)
此函数可检查事件队列中是否有任何待处理
Bluetooth 协议栈事件。如果发现待处理 Bluetooth 事件，此函数会返回一个非零值，表明事件应由
gecko_peek_event() 或 gecko_wait_event() 处理。如果未发现任何事件，则返回零。
uint32 gecko_can_sleep_ms(void)
此函数用于确定
Bluetooth 协议栈可以进入睡眠模式的时长。返回值是协议栈可在下一次 Bluetooth 操作必须出现之前进入睡眠模式的毫秒数。如果无法
进入睡眠模式，则返回零。此函数只能与非阻塞 gecko_peek_event() 事件处理一起使用。
uint32 gecko_sleep_for_ms(uint32 max)
此函数用于使协议栈进入 EM 睡眠模式，持续时间为此函数的单一参数中设置的最大毫秒数。返回值为实际处于睡眠模式的毫秒数。协议栈可能会因为外
部事件而被唤醒。此函数只能与非阻塞 gecko_peek_event() 事件处理一起使用。
native_gecko.h
该文件用于不具有 RTOS 的应用中。它使用直接函数调用向 Bluetooth 协议栈提供 IPC（进程间通信）。
ncp_gecko.h
此文件在为主机提供 NCP 功能的应用中使用。 它使用 NCP 头作为函数调用来向 Bluetooth 协议栈提供 IPC。
host_gecko.h 和 gecko_bglib.h
这些文件可用于开发适用于外部主机的应用程序。host_gecko.h 拥有 API 定义，而 gecko_bglib.h 包含主机应用程序和 BGAPI 串行协议之间的适配层。
rtos_gecko.h
当为
Micrium OS 构建应用时，使用 rtos_gecko.h。Bluetooth 协议栈是 Micrium OS 的独立任务，并使用其电源、睡眠和内存管理。rtos_gecko.h 通过
Micrium OS 中任何任务的 Bluetooth 协议栈为 IPC 提供封装程序。该文件包含 Bluetooth 协议栈 API 及该协议栈的命令和事件，以及一个 Bluetooth 协议
栈配置 API。
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
项目结构
silabs.com | Building a more connected world. Rev. 1.7 | 8
3.2 GATT 数据库
GATT（通用属性配置文件）数据库是一个描述
Bluetooth 设备的 Bluetooth 配置文件、服务和特性的标准化方法。借助 Silicon Labs Bluetooth 协议栈，
GATT 定义可以直接在 Simplicity Studio 中的 Visual GATT Editor GUI 中编辑或以 XML 格式编写，并作为预构建任务传递至 BGBuild 可执行文件。有关
如何创建 GATT 数据库和语法的更多信息，请参阅
《
UG118
：
Blue Gecko Bluetooth® Smart Profile Toolkit
开发人员指南》
。
gatt_db.c 和 gatt_db.h
gatt_db.c 由 BGBuild.exe 或 Visual GATT 编辑器自动生成，用于定义 GATT 数据库的结构和内容。gatt_db.h 包含此数据库以及本地特性和服务的句柄。
从 gatt_db_def.h 至 gatt_db.h，GATT 的类型定义将自动包含在内。
3.3 设备固件升级
设备固件升级 (DFU) 是指通过串行链路或无线链路 (OTA) 升级应用的过程。在这两种情况下，应用都需要添加以下文件来启用对 DFU 的支持。
application_properties.c
该文件包含应用属性结构体，其中包含有关应用映像的信息，如类型、版本和安全性。该结构体在 Gecko Bootloader API 中的 application_properties.h
中进行定义（请参见 <Simplicity Studio Gecko SDK>\platform\bootloader\documentation\Gecko_Bootloader_API_Reference\index.html 中的 Gecko
Bootloader API 参考）。Simplicity Studio 项目中包含一个预生成文件，可对其进行修改以包含应用特定属性。可使用 Gecko Bootloader API 访问这些应
用属性。通过更改 define 语句，可以更新以下成员：
// Version number for this application (uint32_t)
#define BG_APP_PROPERTIES_VERSION
// Capabilities of this application (uint32_t)
#define BG_APP_PROPERTIES_CAPABILITIES
// Unique ID (e.g. UUID or GUID) for the product this application is built for (uint8_t[16])
#define BG_APP_PROPERTIES_ID
在 Bluetooth AppLoader 中使用 OTA 进程时，应用属性结构体需要驻留在紧跟应用矢量表后的位置。使用 Bluetooth 协议栈提供的链接器文件时，将自动
启用此对象。
3.4 RTOS 支持
Bluetooth 协议栈也可以在
Micrium RTOS 上运行。在这种情况下，native_gecko.h 被替换为 rtos_gecko.h ，并且将以下文件添加到项目：
rtos_bluetooth.c 和 rtos_bluetooth.h。
rtos_bluetooth.c 和 rtos_bluetooth.h
rtos_bluetooth.c 和 rtos_bluetooth.h 用于 Micrium OS 任务与 Bluetooth 协议栈及其他 Micrium OS 任务之间的 IPC（进程间通信）。使用 Micrium OS
时，还需要包括在下面介绍的 rtos_gecko.h 头文件。它提供了从任何 Micrium OS 任务使用 Bluetooth 协议栈的 API IPC 封装。
需要在 gecko_configuration_t 结构体中为 Bluetooth 协议栈配置 RTOS 支持。config_flags 字段需要有 GECKO_CONFIG_FLAG_RTOS 集。这导致 Bluetooth 协议
栈需要依靠 Micrium OS 进入睡眠模式，而不是直接睡眠。应合理配置 scheduler_callback 和 stack_schedule_callback，以调用正确的函数。这些回调函数
用于唤醒对应的任务。
与 Micrium OS 一同使用的 Bluetooth 协议栈配置如下：
.config_flags = GECKO_CONFIG_FLAG_RTOS, .scheduler_callback = BluetoothLLCallback, .stack_schedule_callback = BluetoothUpdate,
调用 gecko_stack_init() 后可以调用 bluetooth_start_task()。
void bluetooth_start_task(OS_PRIO ll_priority, OS_PRIO stack_priority)；
它将任务优先级当作参数。ll_priority 用于链路层，stack_priority 用于
Bluetooth 协议栈。链路层优先级必须为系统中的最高优先级，其及时执行对系
统性能至关重要。
3.5 多协议支持
在多协议环境中使用 Bluetooth 协议栈时，必须通过以下函数启用 Bluetooth 协议栈中的多协议功能：
gecko_init_multiprotocol(const void *config)；
config 参数目前始终设置为 NULL，它被保留为用于将来的扩展。
此外，要在多协议环境中使用 Bluetooth，还必须使用支持多协议的 RAIL 库。
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
项目结构
silabs.com | Building a more connected world. Rev. 1.7 | 9
3.6 硬件支持
以下文件是 Gecko SDK 的一部分，它们添加了对硬件特定功能的支持。
hal-config.h
此头文件包含
MCU 外围设备的初始化设置，例如时钟和电源管理以及外围设备（例如 UART、SPI 等）的初始化设置。请注意，此文件仅包含外围设备
的非板特定设置，例如 UART 的波特率，不包含板特定设置，例如 UART 的输入/输出引脚等。
init_mcu.c 和 init_mcu.h
这些文件包含用于初始化 MCU 的内部设置（如时钟和电源管理）的设备初始化函数。
init_board.c 和 init_board.h
这些文件包含用于初始化板上的外部部件的板初始化函数。例如，它启用 GPIO，并初始化无线电板上的外部闪存。
init_app.c 和 init_app.h
这些文件包含根据应用初始化 WSTK 上的外部部件的应用初始化函数。例如，它启用 WSTK 上的 VCOM、传感器和 LCD 显示器。
pti.c 和 pti.h
这些文件包含用于启用数据包追踪接口的 PTI 初始化函数。
hal-config-board.h
此头文件包含板初始化设置，例如按钮和 LED 引脚、UART 和 SPI 引脚等等。在为 Silicon Labs 的无线电板开发应用时，这些设置在 SDK 中提供的示例
中进行了正确设置，但为自定义硬件设计创建应用的开发人员需要相应地配置这些设置。
bspconfig.h / bsphalconfig.h
BSP（板支持包）头包括无线电板特定配置，这些配置被用作 WSTK 特定函数的参数，如在 WSTK 上切换 IO，或在入门套件上驱动 LCD 显示屏。如果
使用硬件配置器工具，那么示例使用 bsphalconfig.h。否则，使用 bspconfig.h。
mx25flash_spi.h
该头文件包含用于将某些无线电板（例如，BRD4100A）上的 SPI 闪存芯片配置为低功耗模式的函数。例如，这在测量睡眠电流时很有用，因为若 SPI 闪
存未处于低功耗模式，则达不到最小的 EM2、EM3 或 EM4 电流。
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
项目结构
silabs.com | Building a more connected world. Rev. 1.7 | 10
4. 配置 Bluetooth 协议栈和 Wireless Gecko 设备
要在
Wireless Gecko 上运行 Bluetooth 协议栈和应用，必须正确配置 MCU 及其外围设备。一旦硬件完成初始化，还必须使用 gecko_init() 函数对协议栈
进行初始化。
4.1 Wireless Gecko MCU 和外围设备配置
initMcu()
initMCU() 函数用于初始化 MCU 内核。此函数启动振荡器并配置设备的能量模式。可将独立于板设置的外围设备初始化（例如，定时器初始化）添加到此
函数中。必须在 main() 刚开始时调用此函数。
initBoard()
initBoard() 函数用于初始化板功能，例如初始化外部闪存。可将取决于板设计的外围设备初始化（例如，GPIO 初始化或 UART 初始化）添加到此函数
中。必须在 initMcu() 后调用该函数。
initApp()
initApp() 函数用于初始化应用特定功能，例如启用 WSTK 上的 SPI 显示。必须在 initBoard() 后调用此函数。
4.1.1 自适应跳频
Bluetooth 协议栈根据 ETSI EN 300 328 标准实现自适应跳频 (AFH)。使用 +10 dBm 及以上的发射功率时需要 AFH。AFH 还可以避免信道拥塞，从而提
高性能。
要启用 Bluetooth 协议栈中的 AFH，必须调用以下初始化函数：
void gecko_init_afh();
在主从连接中，两端均可以独立使用 AFH。主机可以是非自适应性的，但从机可能仍然需要是自适应性的。该标准允许在阻塞的信道上使用控制传输。出
于合规性方面的原因，如果从机检测到阻塞的信道正在使用中，它将只在该信道上发送一个数据包以避免连接超时。
Note: 传统广播不使用自适应跳频。传统广播使用
3 个信道，而 AFH 至少需要 15 个信道才能符合 ETSI 标准的要求。为 AFH 启用广播时必须使用扩展
广播。
4.1.2 Bluetooth 时钟
时钟设置在 initMcu_clocks() 函数中初始化。时钟设置包括使用参数（例如，调谐）初始化振荡器（HFXO、LFXO 和 LFRCO）、初始化时钟（HFCLK、
LFCLK、LFA、LFB、LFE）以及向振荡器分配时钟。注意：此函数中不启用外围设备时钟（如 GPIO 时钟、定时器时钟）。这些时钟必须在初始化外围
设备时启用。
HFCLK
HFCLK 用于无线电协议定时器 (PROTIMER)。HFCLK 是高频时钟，精度必须为至少 ±50 ppm。此时钟要求外部晶体足够精确 (HFXO)。
HFXO 初始化会配置外部晶体以实现时间关键型连接和睡眠管理。HFXO 必须被设置为高频时钟 (HFCLK)，且必须与 Wireless Gecko 的 HFXO 输入引脚
物理连接。
LFCLK
LFCLK 用于两个目的。在 Bluetooth 协议栈中，它用于 Bluetooth 协议定时。在睡眠模式期间跟踪时间时也需要使用它。
当设备进入睡眠模式时，会保存 PROTIMER 的当前状态。当设备被唤醒时，它会计算睡眠时钟发出滴答声的次数，并相应地调整 PROTIMER。至于无线
电，PROTIMER 似乎持续不断地发出滴答声。
该时钟的精度取决于设备的运行模式。当广播或扫描时，精度并不是那么重要，但当连接打开时，精度必须至少达到 ±500 ppm。此时钟可由 LFXO 或
LFRCO 驱动，具体取决于精度要求。
时钟精度在 Bluetooth 协议栈配置结构体中定义，请参阅 4.2.5 Bluetooth 协议栈配置。
默认配置是，LFXO 连接到 Wireless Gecko，并被设置为低频时钟 (LFCLK)。如果设计不支持连接 LFXO，则必须明确禁用应用的睡眠模式，且 LFRCO
必须被设置为用作时钟源。如章节 4.2.4 睡眠模式 中所述，如果 LFCLK 不够精确，则必须禁用 Bluetooth 协议栈的睡眠模式以便正确运行。
HFRCODPLL
HFRCODPLL 是一个高频时钟，可用作系统时钟，与 Bluetooth 协议栈一起用于系列 2 设备。在 EFR32xG21x 中，HFRCODPLL 需要配置为 80 MHz，
并设置为系统时钟源。
CMU_HFRCODPLLBandSet(cmuHFRCODPLLFreq_80M0Hz)；CMU_ClockSelectSet(cmuClock_SYSCLK, cmuSelect_HFRCODPLL)；
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
配置 Bluetooth 协议栈和 Wireless Gecko 设备
silabs.com | Building a more connected world. Rev. 1.7 | 11
CTUNE
在示例中，HFXO 和 LFXO 的晶体调谐 (CTUNE) 设置是默认值，以与所有 Silicon Labs 的 Bluetooth 模块、参考设计和无线电板搭配使用。不过，在某
些情况下，最终产品设计需要特定的晶体校准，要么在每个设备上进行，要么在每个设计上进行。可根据设计使用 initMcu_clocks() 函数中的
hfxoInit.ctuneSteadyState 和 lfxoInit.ctune 设置来调整 CTUNE 值。
// Initialize HFXO
CMU_HFXOInit_TypeDef hfxoInit = BSP_CLK_HFXO_INIT;
hfxoInit.ctuneStartup = BSP_CLK_HFXO_CTUNE;
hfxoInit.ctuneSteadyState = BSP_CLK_HFXO_CTUNE;
CMU_HFXOInit(&hfxoInit);
有关配置 HFXO 和 LFXO 的更多信息，请参见《EFR32 参考手册》。
HFXO CTUNE 默认值
系统会使用以下逻辑顺序检查多个来源中的 HFXO CTUNE 默认值：
1. 设置
CTUNE PSKEY 。该密钥具有 ID 50 （16 进制中为 32 ）且包含 2 字节数据，用于 16 位 CTUNE 值。该过程可以使用 BGAPI 命令
cmd_flash_ps_save 编程
2. DEVINFO 中存在校准值。部分模块的 DEVINFO 页面中包含由工厂编程的值。
3. 用户数据页面中存在制造令牌。这一过程由开发人员编程，如果 EEPROM 板中包含该值，也可以由 Simplicity Studio 自动设置。该令牌由 2 个字节组
成，位于自用户数据页面（若是 EFR32xG1x 设备）或最后一个闪存页面（若是 EFR32xG21 设备）的起始地址偏移 0x0100 的位置。有关您的特定 EFR
变体的完整闪存映射，请参见《EFR32 参考手册》。
4. 如果生成项目时选择了无线电板，则使用电路板头文件中的默认值
5. 如果未发现其他信息，请使用 CMU 头文件中的默认值。
注意：Bluetooth 协议栈仅支持 38.4 MHz HFXO 频率；不支持任何其他 HFXO 频率。
4.1.3 DC-DC 配置
在拥有 DC-DC 的设备上，该配置可在 initMCU() 函数中设置。在 SDK 中的示例中，DC-DC 配置被设置为与 Silicon Labs 的 Bluetooth 模块、无线电板和
参考设计搭配使用，但自定义设计可能需要特定的 DC-DC 设置。这些自定义设置可在 hal-config-board.h 中设置。
#define BSP_DCDC_INIT \
{ \
emuPowerConfig_DcdcToDvdd, /* DCDC to DVDD */ \
emuDcdcMode_LowNoise, /* Low-noise mode in EM0 */ \
1800, /* Nominal output voltage for DVDD mode, 1.8V */ \
15, /* Nominal EM0/1 load current of less than 15mA */ \
10, /* Nominal EM2/3/4 load current less than 10uA */ \
200, /* Maximum average current of 200mA
(assume strong battery or other power source) */ \
emuDcdcAnaPeripheralPower_DCDC,/* Select DCDC as analog power supply (lower power) */ \
160, /* Maximum reverse current of 160mA */ \
emuDcdcLnCompCtrl_1u0F, /* 1uF DCDC capacitor */ \
}
有关配置 DC-DC 的更多信息，请参见《EFR32 参考手册》第 11 章和
《
AN0948
：电源配置和
DC-DC
》
。
4.1.4 LNA
低噪声放大器 (LNA) 是一种电子放大器，可放大极低功耗信号，同时不会显著降低信噪比。LNA 可提高 RF 灵敏度。
某些 MGM12P 模块的前端模块 (FEM) 中具有板载 LNA。要在这些模块中使用 LNA，需正确配置并启用 FEM。在 hal-config-board.h 中使用前缀 BSP_FEM_
配置 FEM。
如果板支持 FEM，则 FEM 在 initBoard() 函数的 initFem() 中初始化。
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
配置 Bluetooth 协议栈和 Wireless Gecko 设备
silabs.com | Building a more connected world. Rev. 1.7 | 12
4.1.5 定期广播
定期广播支持多个侦听器与单个广播设备同步，因此，它是一种多播形式。
每个侦听器在接收数据前，需要与该广播设备同步。定期广播使用侦听设备的扫描仪建立与该广播设备的同步，同步后即可停止扫描仪。这种做法比全程
使用扫描仪侦听广播节能得多。
定期广播由 2 个部分组成：定期播发器角色和侦听端的定期广播同步。这两个部分互不干涉，需要分别进行初始化。
定期播发器
Bluetooth 配置中的 max_advertisers 还配置定期播发器的最大数量。
要在 Bluetooth 协议栈中启用定期播发器，必须在调用 gecko_init 函数之后调用以下初始化函数：
void gecko_init_periodic_advertising()；
定期广播同步
Bluetooth 配置中的 max_periodic_sync 可用于配置 Bluetooth 协议栈需要支持的最大同步数。
要在 Bluetooth 协议栈中启用定期广播同步，必须在调用 gecko_init 函数之后调用以下初始化函数：
void gecko_bgapi_class_sync_init()；
该命令还会初始化 BGAPI 同步类，使其变得可用。
4.1.6 PTI
PTI（数据包追踪接口）是
Wireless Gecko SoC 中的内置块，用于将传入和传出无线电数据包作为元数据路由至调试接口。Simplicity Studio 的 Network
Analyzer 随后会捕捉并显示这些数据包。Network Analyzer 配备一个适用于 Bluetooth 数据包的解码器，可用于调试、分析和测量 Bluetooth 网络。
PTI 在 initApp() 函数的 configEnablePti() 中初始化。可使用 HAL_PTI_BAUD_RATE 定义在 hal-config.h 中设置波特率，而使用带有 BSP_PTI_ 前缀的
定义在 hal-config-board.h 中配置引脚。
从 Bluetooth 2.6.x 版本开始，使用 RAIL 提供的函数配置 PTI。
4.1.7 发射功率
Bluetooth 的发射功率取决于无线电允许的最大功率、软件配置、RF 路径增益补偿、以及自适应跳频 (AFH) 的使用。
ETSI EN 300 328 标准要求发射机功率为 +10 dBm 及以上时要使用 AFH。
如果受自适应性要求的限制，最大允许功率限制为 +10 dBm 以下。ETSI 标准要求至少有 15 个通道用于 AFH。在以下情况下，此要求禁止使用 +10 dBm
及以上：传统广播、扫描响应、和连接中 - 没有足够的信道可用时。
4.1.8 白名单
白名单可用于过滤设备。目前，仅在发现设备时支持使用白名单。远程设备在广播期间发出的连接请求、扫描请求和连接初始化不受白名单限制。
白名单大小与绑定设备的最大数量配置相匹配。如果使用白名单时绑定设备的最大数量发生更改，则需要重置设备以使新设置生效。
绑定设备会自动添加到白名单中。或者，您也可以使用 BGAPI 命令 gecko_cmd_sm_add_to_whitelist() 执行手动添加。
不支持随机地址解析。使用可解析随机地址的设备在扫描期间将不可见。鉴于大多数 Android 和 iOS 手机 使用可解析随机地址，白名单功能将在发现设
备期间有效拦截这些设备。
要在 Bluetooth 协议栈中启用白名单，必须在调用 gecko_init 函数之后调用以下初始化函数：
void gecko_init_whitelisting()；
该函数启用后，可以通过 BGAPI 命令 gecko_cmd_le_gap_enable_whitelisting() 在运行时启用或禁用白名单。
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
配置 Bluetooth 协议栈和 Wireless Gecko 设备
silabs.com | Building a more connected world. Rev. 1.7 | 13
4.1.9 Wi-Fi 共存
Wi-Fi 共存
(COEX) 是一种协议，由 Bluetooth 和 Wi-Fi 仲裁哪个协议可使用无线传输。启用后，它可以提高 Wi-Fi 和 Bluetooth 的性能。在 hal-config-
board.h 中使用带有前缀 BSP_COEX_ 和 HAL_COEX_ 的定义配置 COEX。
为启用 COEX，在调用 gecko_stack_init() 后调用以下函数：
gecko_initCoexHAL();
COEX 为 Wi-Fi IC 实现 GPIO 接口。它依赖于 EMLIB em_gpio.c 和 EMDRV gpiointerrupt.c，需要在项目中包含这两个文件。
4.2 使用 gecko_stack_init() 配置 Bluetooth
gecko_stack_init() 函数用于配置
Bluetooth 协议栈，包括睡眠模式配置、分配给连接的内存、OTA 配置等。没有一个 Bluetooth 协议栈函数可在
Bluetooth 协议栈配置好之前使用。
Bluetooth 协议栈配置示例：
uint8_t bluetooth_stack_heap[DEFAULT_BLUETOOTH_HEAP(MAX_CONNECTIONS)];
static const gecko_configuration_t config = {
.config_flags=0,
.sleep.flags=SLEEP_FLAGS_DEEP_SLEEP_ENABLE,
.bluetooth.max_connections=MAX_CONNECTIONS,
.bluetooth.heap=bluetooth_stack_heap,
.bluetooth.heap_size=sizeof(bluetooth_stack_heap),
.bluetooth.sleep_clock_accuracy = 100, // ppm
.gattdb=&bg_gattdb_data,
.ota.flags=0,
.ota.device_name_len=3,
.ota.device_name_ptr="OTA",
.max_timers=4
};
gecko_stack_init() 函数中的配置选项是：睡眠启用/禁用、Bluetooth 连接计数、堆大小、睡眠时钟准确度、GATT 数据库、OTA 配置和 PA 配置。
一旦调用函数 gecko_stack_init()，就必须单独初始化使用的各个协议栈组件。这种单独初始化不包含不必要的协议栈组件，从而可实现内存优化。
可以使用以下 API 来单独初始化协议栈组件：
gecko_bgapi_class_dfu_init() 启用设备固件升级 (dfu) API。
gecko_bgapi_class_system_init() 启用本地设备（系统）API。
gecko_bgapi_class_le_gap_init() 启用通用访问配置文件 (gap) API。
gecko_bgapi_class_le_connection_init() 允许通过连接 API 管理连接建立、参数设置和断开程序。
gecko_bgapi_class_gatt_init() 有助于通过 gatt API 浏览和管理远程 GATT 服务器中的属性。
gecko_bgapi_class_gatt_server_init() 有助于通过 gatt_server API 浏览和管理本地 GATT 数据库中的属性。
gecko_bgapi_class_hardware_init() 支持访问和配置软件定时器。
gecko_bgapi_class_flash_init() 启用可用于管理闪存中的用户数据的永久性存储命令（闪存）API。
gecko_bgapi_class_test_init() 启用 DTM 测试 API。
gecko_bgapi_class_sm_init() 启用安全管理器 (sm) API。
gecko_bgapi_class_util_init() 启用效用函数 API，如 atoi 和 itoa。
4.2.1 CONFIG_FLAGS
当前标志：
GECKO_CONFIG_FLAG_RTOS 1 = 应用使用 RTOS。协议栈并不配置时钟、矢量、TEMPDRV 或睡眠，因为它们是由 RTOS 提供的。
4.2.2 Mbedtls
协议栈使用的
Mbedtls 加密库通过一个配置文件配置，该配置文件定义支持哪些算法以及该实现是使用硬件加速还是在软件上完成。Mbedtls 配置文件路
径使用 #define MBEDTLS_CONFIG_FILE 给出。默认配置文件 mbedtls_config.h 在 SDK 中，且应当用作更改配置时的模板。
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
配置 Bluetooth 协议栈和 Wireless Gecko 设备
silabs.com | Building a more connected world. Rev. 1.7 | 14
4.2.3 多协议优先级配置
Bluetooth 协议栈和多协议环境中的其他协议一起使用时，可能需要更改 RAIL 的 Bluetooth 优先级设置以优化部分使用情况。
应用需要分配配置结构并将其提供给 Bluetooth 协议栈：
gecko_bluetooth_ll_priorities custom_priorities; static const gecko_configuration_t config = { // .bluetooth.linklayer_priorities =
&custom_priorities, // };
gecko_bluetooth_ll_priorities 结构必须由 GECKO_BLUETOOTH_PRIORITIES_DEFAULT 常数初始化为默认状态。
gecko_bluetooth_ll_priorities 结构含有以下字段：
• scan_min & scan_max - 扫描操作的优先级范围。
• adv_min & adv_max - 广播操作的优先级范围。
• conn_min & conn_max - 连接包的优先级范围。
• init_min & init_max - 连接初始化的优先级范围。
• threshold_coex - 提高优先级信号时的阈值级别，仅在启用 coex 时使用。
• rail_mapping_offset - Bluetooth 优先级所在的 RAIL 优先级。
• rail_mapping_range - Bluetooth 优先级所在的 RAIL 优先级范围。
对于每个优先级范围，0 是最大优先级，0xff 是最小优先级。Bluetooth 优先级与 RAIL 优先级不同。也就是说，在 0 到 0xff 之间的所有 Bluetooth 优先级
中，Bluetooth 有它自己的空间。要将
Bluetooth 优先级与 RAIL 优先级映射，则必须使用字段 rail_mapping_offset 和 rail_mapping_range 中的值形成单度
方程：
RAIL_priority=(BT_priority/0xFF)*rail_mapping_range+rail_mapping_offset
4.2.4 睡眠模式
必须在 gecko_init() 函数中启用
Wireless Gecko 的睡眠模式 EM2（能源模式 2）。睡眠标志是 gecko_configuration_t 结构体的一部分。必须设置
SLEEP_FLAGS_DEEP_SLEEP_ENABLED 标志以启用睡眠模式。如果出现阻塞事件，协议栈会自动处理睡眠模式，如章节 5. Bluetooth 协议栈事件处理 中所述。
在 gecko_configuration_t 结构体 (main.c) 中启用睡眠模式的示例：
.sleep.flags = SLEEP_FLAGS_DEEP_SLEEP_ENABLE // EM sleeps enabled
睡眠模式要求硬件中存在精准的
32 kHz 低频时钟 (LFCLK)。如果 Bluetooth 协议栈没有精准的睡眠时钟可用，则无法进入低功耗睡眠模式。对于不需要
低功耗睡眠模式的应用，可以忽视 LFXO，但必须如下所示设置 Gecko 配置结构体中的睡眠标志：
.sleep.flags = 0, // Sleeps disabled
运行时禁用睡眠模式
如果在运行时需要禁用睡眠模式，您可以调用睡眠模式驱动器函数 SLEEP_SleepBlockBegin(sleepEM2) 。要重新启用
EM2 深度睡眠模式，请使用
SLEEP_SleepBlockEnd(sleepEM2)。EM2 被禁用 (/blocked) 时，该协议栈将在 EM0 和 EM1 之间切换。有关更多信息，请参见知识库文章将能量模式与
Bluetooth 协议栈搭配使用。
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
配置 Bluetooth 协议栈和 Wireless Gecko 设备
silabs.com | Building a more connected world. Rev. 1.7 | 15
4.2.5 Bluetooth 协议栈配置
协议栈内存
Bluetooth 协议栈使用内存管理程序为每个连接和内部数据缓冲区分配内存。此内存需要由应用分配并传递给 Bluetooth 协议栈。内存大小取决于连接数。
C 宏 DEFAULT_BLUETOOTH_HEAP() 计算所需内存的默认大小（以字节为单位）。
分配 bluetooth_stack_heap 数组并将其传递给 Bluetooth 协议栈的示例：
uint8_t bluetooth_stack_heap[DEFAULT_BLUETOOTH_HEAP(MAX_CONNECTIONS)]; static const
gecko_configuration_t config = { // .bluetooth.heap = bluetooth_stack_heap,
.bluetooth.heap_size = sizeof(bluetooth_stack_heap), // };
连接数
同步 Bluetooth 连接数的绝对最大值为 8。分配给连接管理的内存大小会进一步限制连接的数量。在 gecko_init() 中进行初始化期间分配内存。可定义 C-
define MAX_CONNECTIONS 来设置连接数。然后使用相同的定义来计算 Bluetooth 协议栈的内存大小，如上所述。然后，在配置结构体
的 .bluetooth.max_connections 字段中将 MAX_CONNECTIONS 进一步传递给 Bluetooth 协议栈。
将 Bluetooth 连接限制为一 (1) 个的示例。
#define MAX_CONNECTIONS 1
有关连接 RAM 使用情况的更多信息，请参阅 7.3.2 Bluetooth 连接池。
睡眠时钟精度
Bluetooth 协议栈使用 .sleep_clock_accuracy 来优化从睡眠中唤醒的时间。单位是 ppm（百万分之一）。如果该值太大，则 Bluetooth 协议栈会过早从睡
眠状态中唤醒以等待实际事件，从而导致耗电过多。如果该值太小，则 Bluetooth 协议栈唤醒太晚并错过连接事件，从而导致连接断开。
如果不定义该值或将其设置为 0，则使用默认值 250 ppm。
设置睡眠时钟精度的示例：
.bluetooth.sleep_clock_accuracy = 100, // ppm
播发器
最大广播组数可以通过该配置选项进行定义。这些广播组可用于启动多个播发器。该配置选项还可以配置最大定期广播数。每个广播上下文分配约 60 字
节的 RAM。
.bluetooth.max_advertisers = 5; //!< Maximum number of advertisers to support, if 0 defaults to 1
Note: 最大可连接广播数受限于 MAX_CONNECTIONS。
同步广播
支持的最大同步广播数需要进行配置。每个上下文分配约 40 字节的 RAM。
.bluetooth.max_periodic_sync = 5; //! <要支持的最大同步播发器数。默认为 0，不支持任何播发器
4.2.6 OTA 配置
支持 Bluetooth 无线 (OTA) 固件升级，因为固件升级的一部分是由 Bluetooth AppLoader 应用处理的。
OTA 模式使用 .ota.flags 配置字段。它目前有一个选项，即 GECKO_OTA_FLAGS_RANDOM_ADDRESS，此选项将 OTA 设置为使用静态随机地址而不是公共地址。
当 Wireless Gecko 处于 AppLoader 的 OTA 模式时，可通过 Gecko 配置结构体配置其设备名称和设备名称长度。
.ota.device_name_len = 3, // OTA name length
.ota.device_name_ptr = "OTA", // OTA Device Name
最后，应确保将设备设置为 OTA DFU 模式，以便仅可信设备才具备该能力。
有关
OTA 固件更新的更多信息，请参阅
《
UG266
：
Silicon Labs Gecko Booloader
用户指南》
和
《
AN1086
：将
Gecko Bootloader
与
Silicon Labs
Bluetooth
应用一起使用》
。
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
配置 Bluetooth 协议栈和 Wireless Gecko 设备
silabs.com | Building a more connected world. Rev. 1.7 | 16
4.2.7 PA
在基于 EFR32 SoC 的设计上，PAVDD（功率放大器稳压器 VDD 输入）可由 DC/DC 输出供电或直接由 3.3 V 电源供电。
Bluetooth 协议栈配置默认使用 DC/DC 作为 PAVDD 输入。如果 PAVDD 由 3.3 V 电源供电，则需要定义 .pa.input 字段。
Bluetooth 协议栈自动选择高功率 PA（如可用）。pa_mode 配置中的设置 1 会将 Bluetooth 协议栈配置为始终使用低功率 PA。
.pa.config_enable = 1, // PA 配置已启用 .pa.input = GECKO_RADIO_PA_INPUT_VBAT, // PAVDD 由 3.3 V 电源供电 .pa.pa_mode=0 // 选择高功率 PA（如可用）
4.2.8 软件定时器
可配置最多可用的软件定时器数量。各定时器需要协议栈资源才能运行。在某些使用案例中，增加软定时器的数量可能会导致性能下降。
.max_timers = 4; // 软件定时器的最大数量，最多 16 个，默认值：4
4.2.9 RF 路径
增益
应用可以分别为 RX 和 TX 定义 RF 路径增益值。
调整发射机功率时，Bluetooth 协议栈会将 TX RF 路径增益考虑在内。然后天线辐射的功率与应用请求匹配。例如，如果应用请求的最大功率为 +10
dBm，路径损耗为 -1 dBm，则该引脚的实际功率为 +11 dBm。
使用 RX RF 路径增益补偿来自 Bluetooth 协议栈的 RSSI 报告。
.rf.tx_gain = -20; // RF TX 路径增益单位 0.1 dBm .rf.rx_gain = -18; // RF RX 路径增益单位 0.1 dBm
输出选择
在基于 EFR32XG21 SoC 的设计中，可以选择 RF 输出。
.rf.flags = GECKO_RF_CONFIG_ANTENNA; // 启用输出配置 .rf.antenna = 0; // 所需输出，
要了解正确的值，请参考 RAIL 头文件 rail_chip_specific.h 中的天线路径选择。
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
配置 Bluetooth 协议栈和 Wireless Gecko 设备
silabs.com | Building a more connected world. Rev. 1.7 | 17
5. Bluetooth 协议栈事件处理
Wireless Gecko 所用的 Bluetooth 协议栈是一个事件驱动型体系结构，其中事件在主 while 循环中得到处理。
5.1 阻塞事件侦听器
gecko_wait_event() 是阻塞等待函数的实现，该函数会等待事件出现在事件队列中，并将它们返回至事件处理程序。这是一种推荐的 Bluetooth 协议栈运行
模式，因为它可以最高效且自动地管理睡眠，同时让设备和连接保持同步。
• gecko_wait_event() 函数会处理内部消息队列，直至收到事件。
• 如果没有任何待处理事件或待处理消息，设备会进入 EM1 或 EM2 睡眠模式。
• 该函数会返回指向保留接收的事件的 gecko_cmd_packet 结构的指针。
下面的代码片段显示了使用 gecko_wait_event() 的 iBeacon 示例中的简单主 while 循环，该循环会在启动后设置广播。
/* Main loop */
while (1) {
struct gecko_cmd_packet* evt;
/* Wait (blocking) for a Bluetooth stack event. */
evt = gecko_wait_event();
/* Run application and event handler. */
switch (BGLIB_MSG_ID(evt->header))
{
/* This boot event is generated when the system is turned on or reset. */
case gecko_evt_system_boot_id:
/* Initialize iBeacon ADV data */
bcnSetupAdvBeaconing();
break;
/* Ignore other events */
default:
break;
}
5.2 非阻塞事件侦听器
该运行模式需要更多手动调整，例如，睡眠管理需要由应用完成。在某些使用案例中，非阻塞运行是必需的。
• gecko_peek_event() 函数会处理内部消息队列，直至收到事件或所有消息都得到处理。
• 该函数会返回指向保留接收的事件的 gecko_cmd_packet 结构的指针，如果队列中没有任何事件，则返回 NULL。
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
Bluetooth 协议栈事件处理
silabs.com | Building a more connected world. Rev. 1.7 | 18
5.2.1 睡眠和非阻塞事件侦听器
当应用使用非阻塞 gecko_peek_event() 函数创建事件处理程序时，睡眠实现也会有所不同。应用必须使用 gecko_can_sleep_ms() 询问协议栈设备可以进入睡
眠模式多久，然后使用 gecko_sleep_for_ms() 函数将睡眠时长设为该值。在调用 gecko_can_sleep_ms() 或 gecko_sleep_for_ms() 函数前，必须禁用中断；一
旦执行了函数，则必须立即启用中断。
Note: 推荐的做法是不向该关键部分添加额外功能。这将增加中断的延迟，导致性能下降。
下面的示例显示了如何在使用非阻塞事件处理时实现睡眠管理。
/* Main loop */
while (1) {
struct gecko_cmd_packet* evt;
CORE_DECLARE_IRQ_STATE;
/* Poll (non-blocking) for a Bluetooth stack event. */
evt = gecko_peek_event();
/* Run application and event handler. */
if(evt != NULL){
switch (BGLIB_MSG_ID(evt->header))
{
/* This boot event is generated when the system is turned on or reset. */
case gecko_evt_system_boot_id:
/* Initialize iBeacon ADV data */
bcnSetupAdvBeaconing();
break;
/* Ignore other events */
default:
break;
}
}
CORE_ENTER_ATOMIC(); // Disable interrupts
/* Check how long the stack can sleep */
uint32_t durationMs = gecko_can_sleep_ms();
/* Go to sleep. Sleeping will be avoided if there isn't enough time to sleep */
gecko_sleep_for_ms(durationMs);
CORE_EXIT_ATOMIC(); // Enable interrupts
}
5.2.2 更新事件侦听器的通知
在某些情况下，可能需要在应用程序的另一个事件循环内运行
Bluetooth 事件循环。Bluetooth 协议栈拥有回调机制，用于通知应用程序需要更新
Bluetooth 协议栈事件侦听器。这一过程可以通过在 Bluetooth 配置结构中定义回调函数实现。
Note: stack_schedule_callback 可从中断上下文中调用。切勿从该上下文中调用 gecko_peek_event 或 gecko_wait_event。应用程序必须设置标志或利用其它
机制启用应用程序主循环，以更新 Bluetooth 协议栈。
static const gecko_configuration_t config = { // .stack_schedule_callback = bluetooth_update // }; void bluetooth_update() { //set notification for
application }
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
Bluetooth 协议栈事件处理
silabs.com | Building a more connected world. Rev. 1.7 | 19
5.3 用于 Micrium OS 的事件侦听器
该应用在
Micrium OS 下运行，使用一个不同的程序来接收事件。该应用需要等待 Micrium OS 标志，而不是调用函数来接收事件。仅可接收单一任务的
事件。
bluetooth_event_flags 中的 Micrium OS 标志用于向不同的任务通知 Bluetooth 协议栈的状态。该应用仅使用 BLUETOOTH_EVENT_FLAG_EVT_WAITING 和
BLUETOOTH_EVENT_FLAG_EVT_HANDLED。
该应用事件处理程序需要等待 BLUETOOTH_EVENT_FLAG_EVT_WAITING。
OSFlagPend(&bluetooth_event_flags, (OS_FLAGS)BLUETOOTH_EVENT_FLAG_EVT_WAITING 0,OS_OPT_PEND_BLOCKING + OS_OPT_PEND_FLAG_CONSUME, NULL,&os_err);
输入事件随后添加至 bluetooth_evt。
switch
(BGLIB_MSG_ID(bluetooth_evt->header)) { ... }
事件得到处理后，应释放该事件以接收下一个事件。此过程通过发布以下标志通知 Bluetooth 任务完成：BLUETOOTH_EVENT_FLAG_EVT_HANDLED。
OSFlagPost(&bluetooth_event_flags, (OS_FLAGS)BLUETOOTH_EVENT_FLAG_EVT_HANDLED, OS_OPT_POST_FLAG_SET, &os_err);
Note: 当应用挂起时，睡眠和电源管理自动由 Micrium OS 代替应用处理。
5.3.1 来自多个任务的命令
可以从多个 Micrium OS 任务发送 Bluetooth 命令。这要求各个任务在发送和释放命令之前获得排他性。
为了方便起见，Bluetooth 协议栈提供了两种函数。BluetoothPend 用于获得 Micrium OS 互斥量，BluetoothPost 用于释放互斥量。
以下代码块在 Bluetooth 命令前获得 Bluetooth 互斥量，之后又将其释放。
BluetoothPend(&err); //acquire mutex for Bluetooth stack gecko_cmd_gatt_server_send_characteristic_notification(0xff, gattdb_temp_measurement, 5,
temp_buffer); BluetoothPost(&err);//release mutex
UG136: Silicon Labs Bluetooth
®
C Application Developer's Guide
Bluetooth 协议栈事件处理
silabs.com | Building a more connected world. Rev. 1.7 | 20
ページが読み込まれています...
ページが読み込まれています...
ページが読み込まれています...
ページが読み込まれています...
ページが読み込まれています...
ページが読み込まれています...
ページが読み込まれています...
ページが読み込まれています...
ページが読み込まれています...
-
1
-
2
-
3
-
4
-
5
-
6
-
7
-
8
-
9
-
10
-
11
-
12
-
13
-
14
-
15
-
16
-
17
-
18
-
19
-
20
-
21
-
22
-
23
-
24
-
25
-
26
-
27
-
28
-
29
Silicon Labs UG136 ユーザーガイド
- タイプ
- ユーザーガイド
- このマニュアルも適しています
関連論文
-
Silicon Labs UG136： Bluetooth ® C アプリケーション開発者ガイド（SDK v2.x用） ユーザーガイド
-
-
-
-
-