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.

GATT Configurator 是 Simplicity Studio® 5 内置的可视化工具，提供直观的界面来访问 Bluetooth Specification 中定义的所有 Profiles、Services、Characteristics 和 Descriptors，并支持为 Bluetooth 应用创建、导入或导出自定义 GATT Profile，无需手动编辑 XML 文件。本指南适用于 Bluetooth SDK 3.x 和 Bluetooth Mesh SDK 2.x。

​
打开 GATT Configurator

在 Simplicity Studio 5 中打开 GATT Configurator 有以下方式：
  • 通过 Project Configurator → Configuration Tools 选项卡 → 点击 Open
  • 在 Project Explorer 中双击项目下的 config/btconfig/gatt_configuration.btconf 文件
gatt_configuration.btconf 是 GATT 数据库的主干文件，位于项目的 config/btconfig 目录中。可在同一目录中添加其他 XML 文件来扩展 GATT 数据库，附加 XML 文件的内容会在 GATT Configurator UI 中显示为 Contributed Items。

​
界面结构

GATT Configurator 由以下三个主要区域组成：
显示当前项目中的 Profiles/Services/Characteristics/Descriptors 层级列表。层级顺序反映了它们在 GATT 数据库中的存在顺序。顶部工具栏菜单功能：
  1. 添加项（Add Item）
  2. 复制所选项（Duplicate）
  3. 向上移动所选项
  4. 向下移动所选项
  5. 导入 GATT 数据库
  6. 添加预定义（打开 SIG Selector）
  7. 删除所选项
注意：Generic Attribute Service 不会显示在列表中，它是由协议栈维护的特殊 Service，可通过 Custom BLE GATT Profile 设置中的 Generic Attribute Service 滑动开关启用。
显示预定义的 Profiles、Services、Characteristics 和 Descriptors 列表，支持过滤和标签页切换。
  • 鼠标悬停在某项上，点击右侧 + 将其添加到 Custom GATT Editor
  • 右侧窗格显示所选项的详细文本信息
  • 点击 < BACK 返回 Settings Editor
配置所选项的 Properties，包括 Name、UUID、ID、Properties 和 Capabilities。所做更改会立即反映到所选项。一个 Service 的所有 Characteristics 包含在同一 Settings Editor 窗格中。

​
常见操作

​
添加标准 Service（Drag and Drop）

1

打开 SIG Selector

点击 Custom GATT Editor 顶部工具栏的 添加预定义（6） 按钮，打开 SIG Selector。
2

找到目标 Service

在 SIG Selector 中浏览 Profiles/Services 列表，或使用过滤器搜索。点击 Service 名称查看右侧的详细说明。
3

添加到 GATT 数据库

鼠标悬停在目标 Service 上，点击右侧 + 按钮，或直接将其从 Source Section 拖放到 Custom GATT Section。拖放 Profile 或 Service 时，其所有子级 Characteristics 和 Descriptors 会自动包含在内。

​
创建自定义 Service 和 Characteristic

1

添加自定义 Service

在 Custom GATT Editor 中选择 Profile (Custom BLE GATT)，点击工具栏中的 添加（1） → 选择 New Service。在 Settings Editor 中填写 Service 名称和 UUID（128-bit 或 16-bit）。
2

添加 Characteristic

选择刚创建的 Service，点击工具栏 添加（1） → 选择 New Characteristic。
3

配置 Characteristic

在 Settings Editor 右侧配置：
  • Name：Characteristic 的显示名称
  • ID：生成的 C 头文件中的宏名称（勾选 id 复选框后填写）
  • UUID：16-bit 或 128-bit UUID
  • Value Settings：选择数据类型（hex/utf-8/user）和长度
  • Properties：设置访问属性（Read、Write、Notify、Indicate 等）
4

保存并生成代码

点击 Save，GATT Configurator 会自动将数据库转换为 gatt_db.c 和 gatt_db.h，保存在 autogen 目录中。

​
配置访问权限（Permissions）

选中一个 Characteristic 后，在 Settings Editor 中可设置以下属性：
属性说明
Read允许远程设备读取该 Characteristic
Write允许远程设备写入该 Characteristic（带响应）
Write Without Response允许写入，无需 ATT 层确认
Notify服务端可向客户端发送无需确认的值变化通知
Indicate服务端可向客户端发送需要确认的值变化指示
Reliable Write允许使用 Reliable Write 过程修改 Attribute

​
添加 Capabilities（GATT 级可见性控制）

Capabilities 允许通过编程控制 Service 和 Characteristic 的可见性：
1

声明 Capabilities

在 Custom BLE GATT Profile 设置中添加 Capabilities 声明。最多支持 16 个 Capability。
2

为 Service/Characteristic 关联 Capabilities

在 Service 或 Characteristic 的设置中选择关联的 Capabilities。未声明任何 Capabilities 的 Service/Characteristic 将继承父级或全局的所有 Capabilities。
3

运行时控制可见性

当某 Service 的至少一个 Capability 被启用时，该 Service 及其所有 Characteristics 对远程 GATT Client 可见；当所有 Capabilities 被禁用时则不可见。

​
包含其他 Service（Service Includes）

Service Include 允许在一个 Service 中引用另一个 Service。在 Service 设置中使用 Service Includes 功能，通过 ID 引用已存在的 Service。

​
导入与导出 GATT 数据库

  • 导入：点击工具栏中的 导入（5） 按钮，可导入 .xml、.btconf 或 .bgproj 格式的 GATT 数据库文件。
  • 导出：在项目中保存后，GATT 数据库以 gatt_configuration.btconf 格式保存，可直接共享给其他项目。
如果通过 GATT Configurator 编辑 Contributed Items（来自其他组件的 Service），它们将从 Contributed Items 列表中移出并合并到 gatt_configuration.btconf 文件中。

​
生成的代码文件

保存 gatt_configuration.btconf 后，GATT 数据库会自动转换为以下文件（位于 autogen 目录）：
文件说明
gatt_db.cGATT 数据库的结构和内容定义
gatt_db.h本地 Characteristics 和 Services 的 Handle 宏定义
在代码中使用生成的句柄： 
// gatt_db.h 中自动生成的宏定义示例
#define gattdb_service_changed_char   3
#define gattdb_device_name            7
#define gattdb_ota_control           21
#define gattdb_custom_characteristic 24

// 使用句柄读取本地 Characteristic 值
sl_bt_gatt_server_read_attribute_value(gattdb_device_name, 0, sizeof(buf), &len, buf);

// 使用句柄写入本地 Characteristic 值
sl_bt_gatt_server_write_attribute_value(gattdb_custom_characteristic, 0, len, data);

// 发送 Notification
sl_bt_gatt_server_send_notification(connection, gattdb_custom_characteristic, len, data);

​
动态 GATT 数据库

除静态 GATT 数据库外，SDK 还支持在运行时动态构建 GATT 数据库，适用于 NCP 场景以避免每次修改都重新构建目标固件。

​
安装动态 GATT 组件

在 Project Configurator → Software Components 中搜索并安装 Dynamic GATT Database 组件。
NCP 模式下推荐使用动态 GATT 数据库。在 Host 端可将静态 GATT 数据库代码转换为动态 API 调用，通过 UART 传输数据库结构。详见 AN1259: Using the v3.x Silicon Labs Bluetooth® Stack in Network Co-Processor Mode。

​
动态 GATT API 示例

以下示例展示如何将 Health Thermometer Service 和 Temperature Measurement Characteristic 动态添加到数据库中： 
uint16_t session, service, characteristic;

// 开始新的 GATT 数据库编辑会话
sl_bt_gattdb_new_session(&session);

// 添加 Health Thermometer Service（UUID: 0x1809），作为广告的主 Service
sl_bt_gattdb_add_service(session,
                         sl_bt_gattdb_primary_service,
                         SL_BT_GATTDB_ADVERTISED_SERVICE,
                         2, uuid_service,
                         &service);

// 添加 Temperature Measurement Characteristic（UUID: 0x2A1C）
sl_bt_gattdb_add_uuid16_characteristic(session,
                                       service,
                                       SL_BT_GATTDB_CHARACTERISTIC_INDICATE,
                                       0, 0,
                                       uuid_characteristic,
                                       sl_bt_gattdb_fixed_length_value,
                                       1, 1, 0,
                                       &characteristic);

// 激活新 Service 和 Characteristic
sl_bt_gattdb_start_service(session, service);
sl_bt_gattdb_start_characteristic(session, characteristic);

// 提交更改并关闭编辑会话
sl_bt_gattdb_commit(session);

​
静态 vs 动态 GATT 对比

对比项静态 GATT（编译时）动态 GATT（运行时）
数据库存储位置ROMRAM
启动时间更快稍慢
内存占用更低更高
灵活性固定可动态变更
推荐场景SoC 应用NCP Host 应用

Build docs developers (and LLMs) love

Get started for freeTalk to us