Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dsyx/docs.silabs.com_zh/llms.txt

Use this file to discover all available pages before exploring further.

本文档是每位使用 Silicon Labs Bluetooth Stack 为 EFR32 Wireless Gecko 系列产品开发 C 应用程序的开发者的必备参考。本指南涵盖 Bluetooth Stack 的架构、应用开发流程、MCU 核心与外设的使用与限制、协议栈配置选项以及资源消耗分析，适用于 Silicon Labs Bluetooth SDK 3.0.x 及更高版本。
当前支持的编译器：GCC 10.3-2021.10 和 IAR 9.20.4；支持的 IDE：Simplicity Studio 5.2 或更高版本。

​
Bluetooth Stack 架构

下图展示了高级别的固件架构，开发者在协议栈之上创建应用程序： 
┌─────────────────────────────────────────┐
│           用户应用程序 (app.c)            │
├─────────────────────────────────────────┤
│      Bluetooth AppLoader (OTA DFU)       │
├─────────────────────────────────────────┤
│         Bluetooth Stack (libbluetooth.a) │
│  GAP │ SM │ ATT │ GATT │ L2CAP │ LL     │
├─────────────────────────────────────────┤
│    RAIL (libraile_efr32xgXX_xxx.a)       │
├─────────────────────────────────────────┤
│         EFR32 Hardware                   │
└─────────────────────────────────────────┘
主要组件说明：
  • Bluetooth Stack：包含 Link Layer、GAP、Security Manager、ATT 和 GATT，以预编译对象文件方式提供。
  • Bluetooth AppLoader：Bootloader 之后启动，验证用户应用是否有效；若无效则启动 OTA 流程接收新固件。从 SDK 4.0.x 起，EFR32[M|B]G2x 设备上的 AppLoader 已与 Gecko Bootloader 合并为通信插件。
  • RAIL：Radio Abstraction Interface Layer，Bluetooth Stack 通过 RAIL 访问无线电。

​
应用构建流程

1

定义 GATT Database

使用 Simplicity Studio 的 Visual GATT Editor（图形化）或编写 .xml/.bgproj 文件（IAR 项目），定义 Bluetooth Services 和 Characteristics。
2

编写应用代码

从 SDK 提供的示例或空模板开始，编写应用程序源码，实现事件处理逻辑。
3

编译生成对象文件

编译项目生成对象文件，Visual GATT Editor 自动生成 gatt_db.c 和 gatt_db.h。
4

链接库文件

将对象文件与 SDK 提供的预编译库链接，生成可烧录到 Wireless Gecko 设备的闪存映像。

​
项目文件结构

​
核心库文件

文件说明是否必选
libbluetooth.aBluetooth Stack 主库必选
librail_efr32xgXX_gcc/iar_release.a对应平台的 RAIL 库必选
libpsstore.aPS Store（EFR32[MB]G1x）Series 1 必选
libnvm3_CM33_gcc/iar.aNVM3（EFR32[MB]G2x）Series 2 必选
binapploader.oOTA AppLoader（G1x）可选

​
API 头文件

文件说明
sl_bt_api.h完整的 Bluetooth API 声明，SoC 和 NCP 模式的单一入口文件
sl_bt_stack_init.hSoC 上的 Bluetooth 特性和 API 初始化函数
sl_bt_types.hBluetooth API 数据类型定义
sl_bt_version.hBluetooth Stack 版本信息
sl_bt_ncp_host.h/.cHost 应用与 BGAPI 串行协议之间的适配层
sl_bt_rtos_adaptation.h/.c在 Micrium OS 上运行 Bluetooth 的适配层

​
RTOS 支持文件

当在 Micrium OS 或 FreeRTOS 上运行 Bluetooth Stack 时，需添加以下文件： 
// RTOS 适配层（使用 CMSIS-RTOS2 提供 IPC 任务）
sl_bt_rtos_adaptation.c
sl_bt_rtos_adaptation.h
// RTOS 任务优先级配置
sl_bt_rtos_config.h
RTOS 模式所需的配置结构字段： 
.config_flags = SL_BT_CONFIG_FLAG_RTOS,
.scheduler_callback = sli_bt_rtos_ll_callback,
.stack_schedule_callback = sli_bt_rtos_stack_callback,

​
配置 Bluetooth Stack

​
系统初始化

// 初始化系统（平台、驱动、服务、协议栈）
sl_system_init();

// 初始化应用特定特性
app_init();

​
Stack 配置示例

#define SL_BT_CONFIG_DEFAULT                                                       \
    {                                                                              \
        .config_flags = SL_BT_CONFIG_FLAGS,                                        \
        .bluetooth.max_connections = SL_BT_CONFIG_MAX_CONNECTIONS,                 \
        .bluetooth.max_advertisers = SL_BT_CONFIG_MAX_ADVERTISERS,                 \
        .bluetooth.max_periodic_sync = SL_BT_CONFIG_MAX_PERIODIC_ADVERTISING_SYNC, \
        .bluetooth.max_buffer_memory = SL_BT_CONFIG_BUFFER_SIZE,                   \
        .scheduler_callback = SL_BT_CONFIG_LL_CALLBACK,                            \
        .stack_schedule_callback = SL_BT_CONFIG_STACK_CALLBACK,                    \
        .gattdb = &bg_gattdb_data,                                                 \
        .max_timers = SL_BT_CONFIG_MAX_SOFTWARE_TIMERS,                            \
        .rf.tx_gain = SL_BT_CONFIG_RF_PATH_GAIN_TX,                                \
        .rf.rx_gain = SL_BT_CONFIG_RF_PATH_GAIN_RX,                                \
    }

​
关键配置参数说明

Bluetooth Stack 使用内存缓冲 API 事件及连接/广告/扫描中传输的数据。缓冲大小由 sl_bluetooth_config.h 中的 SL_BT_CONFIG_BUFFER_SIZE 定义。
static const sl_bt_configuration_t config = {
    .bluetooth.max_buffer_memory = SL_BT_CONFIG_BUFFER_SIZE,
};
如需提高吞吐量或使用长广告数据，可考虑增大此值。
同时进行的 Bluetooth 连接绝对最大数量为 32，内存分配进一步限制连接数：
#define SL_BT_CONFIG_MAX_CONNECTIONS 1  // 限制为 1 个连接
每个连接约需 RAM：约 120–200 字节（取决于协议配置）。
定义广告集的最大数量，同时也是定期广告的最大数量。每个广告上下文约占 60 字节 RAM：
.bluetooth.max_advertisers = SL_BT_CONFIG_USER_ADVERTISERS;
EM2（Energy Mode Two）深度睡眠由 Power Manager 组件自动管理。睡眠需要精确的 32 kHz LFCLK。在运行时禁用睡眠：
// 实现此函数以阻止设备进入睡眠状态
bool app_is_ok_to_sleep(void) {
    return false;  // 返回 false 则不进入睡眠
}
通过包含 bluetooth_on_demand_start 组件，允许应用按需启停 Bluetooth Stack：
sl_bt_system_start_bluetooth();   // 启动 Bluetooth Stack
sl_bt_system_stop_bluetooth();    // 优雅停止（断开连接、停止广告/扫描）
当协议栈停止时，已分配资源会被释放，适用于 DMP 场景。

​
时钟配置

用于无线电协议定时器（PROTIMER），精度要求 ±50 ppm，需外部晶振（HFXO）。注意：Bluetooth Stack 仅支持 38.4 MHz 的 HFXO 频率，不支持其他频率。

​
Bluetooth Stack 事件处理

​
非阻塞事件监听

// 检查是否有待处理事件
int sl_bt_event_pending(void);

// 从 Stack 请求 Bluetooth 事件（非阻塞）
sl_status_t sl_bt_pop_event(sl_bt_msg_t* evt);
典型的主循环结构： 
while (1) {
    sl_status_t status;
    sl_bt_msg_t evt;

    status = sl_bt_pop_event(&evt);
    if (status == SL_STATUS_OK) {
        sl_bt_on_event(&evt);
    }
    // 无事件时可进入低功耗睡眠
}

​
RTOS 环境下的事件监听

在 RTOS 环境中，事件处理被放在 Event Handler Task 中，该任务等待 SL_BT_RTOS_EVENT_FLAG_EVT_WAITING 标志被设置后调用 sl_bt_process_event() 处理事件。 BGAPI 命令的线程安全性通过互斥量（BluetoothMutex）保障，允许从多个 RTOS 任务中并发调用 BGAPI 命令。

​
多任务命令发送

// 辅助函数：准备命令并发送到协议栈（线程安全）
sli_bt_cmd_handler_rtos_delegate();
此函数通过互斥量确保可重入，任何 BGAPI 函数都会调用它，无需额外同步。

​
外设与中断处理

​
外部事件（External Event）

来自硬件中断的事件通过 sl_bt_external_signal() 发送到 Bluetooth Stack，在主循环中通过 sl_bt_evt_system_external_signal 事件处理： 
// 在中断处理函数中（ISR 上下文）
void GPIO_ODD_IRQHandler(void) {
    sl_bt_external_signal(BUTTON_PRESSED);
}

// 在事件处理函数中
case sl_bt_evt_system_external_signal_id:
    if (evt->data.evt_system_external_signal.extsignals & BUTTON_PRESSED) {
        // 处理按钮按下事件
    }
    break;
Sleep Timer 和其他驱动的回调是从中断上下文（ISR）中调用的，不能在回调中直接调用 BGAPI 函数。应使用 sl_bt_external_signal() 将事件传递到主循环处理，或使用支持从回调中调用 BGAPI 的 Simple Timer 组件。

​
中断优先级

Bluetooth Stack 使用特定的 NVIC 中断优先级。应用程序中断必须设置为低于 Bluetooth Stack 使用的优先级，否则可能导致协议栈不稳定。

​
Wireless Gecko 资源管理

​
Flash 资源

Dead Code Elimination：编译器和链接器通过消除未调用的代码减少 Flash 占用。选择性初始化：通过仅初始化所需的协议栈组件，避免包含不必要的代码。调用 sl_bt_init_stack() 后，必须分别初始化每个使用的协议栈组件：
// 初始化协议栈（必须）
sl_bt_init_stack(&config);

// 仅初始化需要的 BGAPI 类
sl_bt_class_system_init();
sl_bt_class_gap_init();
sl_bt_class_connection_init();
sl_bt_class_gatt_server_init();
// 其他按需添加...
绑定数据库存储在非易失性存储中（PS Store 或 NVM3）。最大绑定数量：
  • PS Store：最多 13 个绑定（Series 1 默认）
  • NVM3：最多 32 个绑定（Series 2 默认，Series 1 可选）
通过 sl_bt_sm_store_bonding_configuration() 设置最大绑定数量和满时策略。

​
RAM 资源

Bluetooth Stack 本身约需 10–20 KB RAM，具体取决于编译配置。
每个并发连接约需 RAM 120–200 字节。通过 SL_BT_CONFIG_MAX_CONNECTIONS 控制最大连接数以节省内存：
#define SL_BT_CONFIG_MAX_CONNECTIONS 4  // 仅允许 4 个并发连接
在 sl_bt_init_stack() 时从堆分配，大小由 SL_BT_CONFIG_BUFFER_SIZE 定义。支持多连接时的均衡调度：
// 使用均衡连接调度时推荐的缓冲和堆配置
SL_BT_CONFIG_BUFFER_SIZE 20160
SL_HEAP_SIZE 22520
静态 GATT 数据库存储在 ROM 中，启动更快、内存占用更低；动态 GATT 数据库存储在 RAM 中，灵活但占用更多内存。

​
NCP Host 端编程

开发 NCP Host 应用时，需在项目中定义 SL_BT_API_FULL 以包含所有 BGAPI 命令实现： 
// 防止链接器删除 BGAPI 命令实现
#define SL_BT_API_FULL
主要适配文件： 
// Host 应用与 BGAPI 串行协议之间的 API 定义和适配层
sl_bt_ncp_host_api.c
sl_bt_ncp_host.h / sl_bt_ncp_host.c
sl_bt_internal.h
基于 BGLIB 开发的 Host 代码可以与 EFR32 端代码共用同一套 BGAPI 接口，便于将应用代码在 EFR32 和独立 Host 之间移植。

​
多协议支持

在多协议环境（DMP）中使用 Bluetooth Stack 时，需启用多协议特性： 
sl_bt__init_multiprotocol();
同时需使用支持多协议的 RAIL 库（librail_multiprotocol_xxx.a）。 可通过自定义优先级配置优化多协议环境中的 Bluetooth 性能： 
sl_bt_bluetooth_ll_priorities custom_priorities;
static const sl_bt_configuration_t config = {
    .bluetooth.linklayer_priorities = &custom_priorities,
    // ...
};
sl_bt_bluetooth_ll_priorities 结构包含扫描、广告、连接和连接启动各操作的优先级范围（0 为最高优先级，0xFF 为最低优先级）。

Build docs developers (and LLMs) love

Get started for freeTalk to us