Apollo2 BLE自定义服务开发指南：GATT数据库配置与回调实现

1. 项目概述与核心价值最近在折腾一个基于Apollo2 Blue的低功耗蓝牙项目需要自定义一个服务Service来实现特定的数据交互功能。如果你也在用Ambiq Micro的Apollo2或Apollo3 Blue系列芯片做BLE开发大概率会遇到类似的需求官方SDK里提供的那些标准服务比如电池服务、设备信息服务往往不够用你得自己从头到尾定义一个全新的服务包括它的特征值Characteristic和描述符Descriptor。这个过程说简单也简单就是往GATT通用属性配置文件表里加几行“定义”说复杂也复杂涉及到UUID规划、属性权限设置、回调函数绑定、以及如何与你自己的应用逻辑无缝对接。我花了点时间把Apollo2 BLE SDK以AmbiqSuite SDK为例里添加自定义服务的完整流程走通并整理了出来。这篇文章就是一份手把手的实操指南适合已经对BLE基础概念GATT、Service、Characteristic有了解并且正在使用Ambiq SDK进行开发的工程师或爱好者。我会从最根本的GATT数据库结构讲起一步步带你完成从定义UUID、添加服务特征、实现读写回调到最终编译测试的全过程中间会穿插很多官方文档里不会提的配置细节和容易踩坑的地方。2. Apollo2 BLE服务架构与GATT数据库解析2.1 GATT数据库在Ambiq SDK中的存在形式在开始动手添加之前必须理解Apollo2 BLE SDK中GATT数据库是如何被构建和管理的。与一些其他BLE协议栈将数据库动态注册到内核不同Ambiq的SDK采用了一种静态定义为主的方式。整个GATT数据库的结构在编译前就已经通过一个特定的C源文件通常是gatt_db.c和对应的头文件gatt_db.h定义好了。这个gatt_db.c文件本质上是一个巨大的常量数组其内容遵循Bluetooth SIG定义的ATT属性协议格式。数组中的每一个元素都对应GATT数据库中的一个“属性句柄”Attribute Handle以及其关联的类型UUID、权限Permissions和值Value。SDK在初始化蓝牙协议栈时会直接将这个数组加载到内存的特定区域作为设备对外宣称的“服务清单”。这种静态定义的方式带来了两个关键特点高效与确定数据库在编译时确定运行时无需动态分配内存来构建节省了宝贵的RAM资源这对于Apollo2这类资源受限的MCU至关重要。修改需重新编译任何对服务或特征的增删改都必须修改gatt_db.c并重新编译固件无法在运行时动态变更数据库结构。你的核心任务就是正确地修改这个gatt_db.c文件在其中插入属于你自定义服务的那一段属性定义。2.2 自定义服务的核心组成UUID、特征值与权限一个完整的自定义服务Service在GATT数据库中表现为一个属性序列。这个序列通常以“服务声明”属性开始后面紧跟一个或多个“特征值声明”属性每个特征值声明后面还可能跟着“特征值描述符”属性如CCCD客户端特征配置描述符。1. UUID的选择与定义这是第一步也是容易出错的一步。UUID通用唯一识别码是区分不同服务和特征的身份证。16位UUID通常用于Bluetooth SIG官方认证的标准服务如0x180F是电池服务。使用短UUID可以节省数据库空间。128位UUID用于自定义的、厂商特定的服务。这是你添加自定义服务时必须使用的。在代码中你需要为你的服务和特征定义128位的UUID常量。SDK中通常有一个专门的头文件如gatt_uuid.h来存放这些定义。你需要按照SDK已有的格式添加。例如为你的自定义服务定义一个UUID// 在 gatt_uuid.h 中添加 #define UUID_SERVICE_CUSTOM AM_UUID128(0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc, 0xde, 0xf0, 0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc, 0xde, 0xf0) // 为这个服务下的一个特征定义UUID #define UUID_CHAR_CUSTOM_DATA AM_UUID128(0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc, 0xde, 0xf0, 0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc, 0xde, 0xf1)注意AM_UUID128是一个宏用于将16个字节的数组转换成SDK内部使用的UUID结构。你需要生成自己唯一的UUID可以使用在线UUID生成器但要确保在同一个项目中不冲突。2. 特征值Characteristic的属性与权限每个特征值都由至少两个属性构成特征声明Characteristic Declaration这是一个固定格式的属性其UUID为0x2803特征声明。它的值字段包含三个信息该特征的属性Properties如读、写、通知、该特征值句柄、以及该特征值的16/128位UUID。特征值Characteristic Value这是实际存放数据的属性。它的UUID就是你自定义的UUID_CHAR_CUSTOM_DATA。它的权限Permissions和属性Properties共同决定了客户端如何与之交互。权限Permissions和属性Properties必须正确匹配这是很多连接和读写失败问题的根源属性Properties在特征声明中指定通过位掩码表示例如GATT_PROP_READ | GATT_PROP_WRITE | GATT_PROP_NOTIFY。它告诉客户端“这个特征支持哪些操作”。权限Permissions在特征值属性中指定例如GATT_PERMIT_READ | GATT_PERMIT_WRITE。它告诉协议栈“服务器允许客户端进行哪些操作”。关键经验Properties是广告给客户端看的“能力清单”而Permissions是服务器端执行的“安全检查”。如果Properties包含了NOTIFY但你没有为该特征值添加CCCD描述符或者没有在权限中允许读/写CCCD通知功能就无法工作。同样如果Properties有WRITE但特征值的Permissions没有包含GATT_PERMIT_WRITE写请求会在协议栈层被直接拒绝根本到不了你的应用回调函数。3. 实操在gatt_db.c中插入自定义服务现在我们进入最核心的实操环节修改gatt_db.c。这个文件看起来可能很庞大且复杂但结构是有规律的。你需要找到现有服务定义的末尾在primary service的结束和下一个服务开始之前或者文件末尾的GATT_END宏之前插入你的服务。3.1 定位与插入点分析首先打开你的SDK中的gatt_db.c。你会看到类似下面的结构已大幅简化// gatt_db.c const uint8_t gatt_database[] { // ... 前面可能有很多其他服务的定义 ... // 假设这是最后一个现有服务例如设备信息服务的结尾 /* Characteristic User Description */ GATT_CHAR_DESC_UUID16 (HDLC_DEVICE_INFO_SERIAL_NUMBER_CHAR_USER_DESC, HDLC_DEVICE_INFO_SERIAL_NUMBER_CHAR_VAL, UUID_CHAR_DESC_CHAR_USER_DESC, GATT_PERMIT_READ, 0), // !! 注意这里就是插入新服务的理想位置 !! // 在最后一个特征的描述符之后下一个服务声明之前或直接放在GATT_END之前。 // 如果后面紧跟着另一个服务声明如 // GATT_PRIMARY_SERVICE_UUID128(HDL_CUSTOM_SERVICE, UUID_SERVICE_BATTERY), // 那么你就需要把自定义服务插在这个电池服务声明的前面。 // 更常见的是后面直接是数据库结束标记 GATT_END };你需要仔细查看插入点前后的代码。确保你的新服务定义被完整地包裹在一对GATT_PRIMARY_SERVICE_UUID128和后续的属性定义之间并且不会破坏现有属性的句柄Handle顺序。句柄通常是SDK宏自动生成的但你需要确保你引用的句柄名称如HDL_CUSTOM_SERVICE,HDL_CUSTOM_SERVICE_DATA_CHAR_VAL在gatt_db.h中有唯一定义。3.2 编写自定义服务属性序列假设我们要添加一个名为“Custom Data”的服务包含一个可读、可写、可通知的特征“Data”。以下是完整的属性序列示例// 1. 自定义主服务声明 GATT_PRIMARY_SERVICE_UUID128(HDL_CUSTOM_SERVICE, UUID_SERVICE_CUSTOM), // 2. “Data”特征的声明 GATT_CHARACTERISTIC_UUID128(HDL_CUSTOM_SERVICE_DATA_CHAR, HDL_CUSTOM_SERVICE_DATA_CHAR_VAL, UUID_CHAR_CUSTOM_DATA, GATT_PROP_READ | GATT_PROP_WRITE | GATT_PROP_NOTIFY, GATT_PERMIT_READ | GATT_PERMIT_WRITE), // 3. “Data”特征的值实际数据存储处 // 注意这里的权限必须与特征声明中的Properties匹配。NOTIFY属性不需要在这里设置权限但需要下面的CCCD。 GATT_CHAR_VALUE_UUID128(HDL_CUSTOM_SERVICE_DATA_CHAR_VAL, UUID_CHAR_CUSTOM_DATA, GATT_PERMIT_READ | GATT_PERMIT_WRITE), // 4. 客户端特征配置描述符CCCD用于启用/禁用通知 GATT_CHAR_DESC_UUID16(HDL_CUSTOM_SERVICE_DATA_CHAR_CCCD, HDL_CUSTOM_SERVICE_DATA_CHAR_VAL, UUID_CHAR_DESC_CLIENT_CHAR_CONFIG, GATT_PERMIT_READ | GATT_PERMIT_WRITE),代码解读与关键点GATT_PRIMARY_SERVICE_UUID128声明一个128位UUID的主服务。HDL_CUSTOM_SERVICE是这个服务声明的句柄名需要在gatt_db.h中定义。GATT_CHARACTERISTIC_UUID128声明一个特征。这里设置了该特征的属性可读、可写、可通知并关联了特征值句柄HDL_CUSTOM_SERVICE_DATA_CHAR_VAL和特征值UUID。GATT_CHAR_VALUE_UUID128定义特征值本身。这是客户端真正读写的数据所在。权限设置为可读可写。GATT_CHAR_DESC_UUID16定义CCCD描述符。它的UUID是标准的0x2902。客户端通过向这个描述符写入0x0001来启用通知写入0x0000来禁用。因此它的权限必须包含读和写。3.3 更新gatt_db.h中的句柄定义每使用一个新的句柄名如HDL_CUSTOM_SERVICE,HDL_CUSTOM_SERVICE_DATA_CHAR等都必须在gatt_db.h文件中为其分配一个唯一的句柄值。这个值通常是顺序递增的整数。打开gatt_db.h找到句柄枚举或宏定义的部分可能是一个enum或一系列#define。在列表的末尾添加你的新句柄。// gatt_db.h typedef enum { // ... 其他已有的句柄 ... HDL_DEVICE_INFO_SERIAL_NUMBER_CHAR_USER_DESC, // 假设这是最后一个已有句柄 // 自定义服务的句柄开始 HDL_CUSTOM_SERVICE, HDL_CUSTOM_SERVICE_DATA_CHAR, HDL_CUSTOM_SERVICE_DATA_CHAR_VAL, HDL_CUSTOM_SERVICE_DATA_CHAR_CCCD, // 务必更新这个最大值 HDL_GATT_MAX } gatt_db_handle_enum_t;重要提示HDL_GATT_MAX必须始终是列表中最大的那个值通常是最后一个枚举值。SDK可能用它来分配内存或做边界检查。添加新句柄后确保HDL_GATT_MAX被更新到最新有时SDK会自动计算有时需要手动修改请参考你的SDK版本说明。4. 实现应用层回调与数据交互GATT数据库定义好了但这只是“数据库表结构”。要让服务活起来能够响应客户端的读写请求你必须在应用层实现回调函数。4.1 注册自定义服务回调函数在Ambiq BLE SDK中通常有一个文件如app.c或ble_app.c负责应用逻辑的初始化和事件分发。你需要在这里找到并修改服务回调函数注册的部分。首先你需要编写一个自定义的服务回调函数其函数签名通常类似于static void custom_service_cb(uint16_t conn_id, uint32_t trans_id, gatt_event_t *p_event);然后在应用初始化函数例如app_init或ble_app_init中将这个回调函数注册到协议栈。你需要找到类似gatt_register_service_cb或gatt_register_callback的函数调用。在注册通用GATT回调的附近添加对你自定义服务回调的注册。void app_init(void) { // ... 其他初始化代码 ... // 注册通用GATT事件回调如果存在 gatt_register_callback(general_gatt_service_cb); // 注册自定义服务回调关键步骤 // 你需要将你的服务句柄范围从HDL_CUSTOM_SERVICE到HDL_CUSTOM_SERVICE_DATA_CHAR_CCCD // 与你的回调函数关联起来。 gatt_register_service_callback(HDL_CUSTOM_SERVICE, HDL_CUSTOM_SERVICE_DATA_CHAR_CCCD, custom_service_cb); // ... 后续代码 ... }注意具体的注册函数名和参数可能因SDK版本而异。你需要查阅SDK中的示例如heartrate示例来找到正确的注册方式。核心思想是告诉协议栈“当句柄在HDL_CUSTOM_SERVICE到HDL_CUSTOM_SERVICE_DATA_CHAR_CCCD这个范围内的属性发生事件时请调用custom_service_cb这个函数。”4.2 在回调函数中处理读写与通知事件你的custom_service_cb函数是整个自定义服务的大脑。它需要处理多种类型的事件最主要的是GATT_EVENT_READ和GATT_EVENT_WRITE。static void custom_service_cb(uint16_t conn_id, uint32_t trans_id, gatt_event_t *p_event) { uint16_t handle p_event-event_data.attribute_handle; switch (p_event-event_type) { case GATT_EVENT_READ: { // 客户端发起了读请求 if (handle HDL_CUSTOM_SERVICE_DATA_CHAR_VAL) { // 准备要返回的数据 uint8_t custom_data[] {0x01, 0x02, 0x03, 0x04}; // 调用API响应读请求 gatt_send_read_response(conn_id, trans_id, GATT_SUCCESS, custom_data, sizeof(custom_data)); } // 也可以处理对CCCD的读请求返回当前的订阅状态 else if (handle HDL_CUSTOM_SERVICE_DATA_CHAR_CCCD) { uint16_t cccd_value get_cccd_value(conn_id); // 你需要自己实现这个函数来管理每个连接的CCCD状态 gatt_send_read_response(conn_id, trans_id, GATT_SUCCESS, (uint8_t*)cccd_value, sizeof(cccd_value)); } break; } case GATT_EVENT_WRITE: { gatt_write_data_t *p_write p_event-event_data.write_data; if (handle HDL_CUSTOM_SERVICE_DATA_CHAR_VAL) { // 客户端写入了特征值 // p_write-p_val 指向写入的数据 p_write-len 是数据长度 process_custom_data(p_write-p_val, p_write-len); // 你的数据处理函数 // 发送写响应对于Write Request需要响应对于Write Command则不需要 if (p_write-type GATT_WRITE_REQ) { gatt_send_write_response(conn_id, trans_id, GATT_SUCCESS); } } else if (handle HDL_CUSTOM_SERVICE_DATA_CHAR_CCCD) { // 客户端写入CCCD启用或禁用通知 uint16_t cccd_value *(uint16_t*)(p_write-p_val); set_cccd_value(conn_id, cccd_value); // 保存这个连接的CCCD状态 if (cccd_value 0x0001) { // 通知已启用你可以在这里启动一个定时器或准备数据 } else { // 通知已禁用 } if (p_write-type GATT_WRITE_REQ) { gatt_send_write_response(conn_id, trans_id, GATT_SUCCESS); } } break; } // 可能还需要处理其他事件如连接断开时清理CCCD状态 case GATT_EVENT_DISCONNECT: { clear_cccd_value(conn_id); break; } default: break; } }4.3 主动发送通知Notification当CCCD被客户端设置为0x0001后服务器就可以在数据变化时主动发送通知。这是BLE应用中实现服务器向客户端推送数据的关键机制。void send_custom_notification(uint16_t conn_id, uint8_t *p_data, uint16_t len) { // 1. 检查该连接是否已启用通知 if (is_notification_enabled(conn_id) false) { return; // 未启用直接返回 } // 2. 构建并发送通知 gatt_notification_t notif; notif.conn_id conn_id; notif.handle HDL_CUSTOM_SERVICE_DATA_CHAR_VAL; // 通知是针对哪个特征值 notif.p_val p_data; notif.len len; gatt_send_notification(notif); }你需要自己实现is_notification_enabled函数该函数查询你为conn_id这个连接保存的CCCD状态。通常你需要一个数组或链表来为每个已连接的客户端存储其CCCD值。5. 编译、调试与常见问题排查5.1 编译配置与内存检查添加服务后编译前有两点必须检查GATT数据库大小gatt_db.c中的数组会占用Flash空间。有些SDK在gatt_db.h或配置文件中定义了GATT_DB_MAX_SIZE之类的宏。如果你的数据库变大了确保这个宏的值足够大否则可能导致编译错误或运行时数据库被截断。检查链接脚本.ld文件确保Flash空间充足。连接参数与MTU自定义服务可能传输更多数据。检查你的连接间隔Connection Interval是否满足数据吞吐要求。更重要的是协商一个足够大的MTU最大传输单元。默认MTU是23字节ATT有效载荷只有20字节。如果你的特征值数据大于20字节必须通过MTU交换来增大MTU例如到247字节否则长数据会被分包或截断。在SDK中你通常需要在连接事件中主动发起MTU交换请求。5.2 典型问题与排查技巧下表总结了添加自定义服务时最常见的问题及其排查思路问题现象可能原因排查步骤手机BLE扫描不到新服务1. 服务未成功添加到数据库。2. 数据库编译错误或句柄冲突。3. 服务UUID格式错误。1. 使用BLE调试工具如nRF Connect查看原始广播数据和GATT服务列表确认服务是否存在。2. 检查编译日志确认gatt_db.c无语法错误。单步调试查看GATT初始化是否成功。3. 核对gatt_db.c中UUID字节顺序小端序。能发现服务但无法读写特征1. 特征值的属性Properties与权限Permissions不匹配。2. 应用层回调函数未正确注册或未被调用。3. 回调函数中未正确发送响应。1. 用调试工具查看特征的Properties并与代码中GATT_CHARACTERISTIC_UUID128和GATT_CHAR_VALUE_UUID128的权限设置对比。2. 在回调函数入口加打印或断点确认事件是否触发。3. 对于Read Request必须调用gatt_send_read_response对于Write Request必须调用gatt_send_write_response。通知Notify无法启用或发送1. 未添加CCCD描述符或其权限未设置写。2. CCCD的UUID错误必须是0x2902。3. 应用层未保存和管理每个连接的CCCD状态。4. 发送通知时使用了错误的特征值句柄。1. 检查gatt_db.c中CCCD描述符的定义和权限。2. 在回调函数中打印CCCD写入事件确认客户端发送的值0x0001。3. 实现一个简单的数组uint16_t cccd_state[MAX_CONNECTIONS]来管理状态。4. 确认send_custom_notification中使用的句柄是特征值句柄HDL_..._CHAR_VAL不是特征声明句柄。写入数据后设备无响应或断开1. 写入的数据长度超过特征值定义的最大长度如果有定义。2. 回调函数处理写入时发生崩溃如数组越界。3. 未及时发送Write Response对于Write Request类型。1. 在特征值定义时可以指定一个最大长度。确保客户端写入的数据不超过此长度。2. 在写入回调中仔细检查指针p_write-p_val和长度p_write-len确保内存访问安全。3. 区分GATT_WRITE_REQ需响应和GATT_WRITE_CMD无响应。对前者必须发送响应。多连接下通知混乱1. CCCD状态未按连接IDconn_id区分管理。2. 向未启用通知的连接发送了通知。1. 确保你的CCCD状态数组或链表是以conn_id为索引的。2. 在send_custom_notification函数中先检查对应conn_id的CCCD状态是否为0x0001。5.3 调试工具与实战心得必备工具手机上的nRF Connect或LightBlue是绝佳的调试工具。它们可以直观地展示设备的所有服务、特征、描述符并允许你进行读写、订阅通知等操作是验证GATT数据库是否正确的第一步。日志输出在Apollo2上充分利用串口打印日志。在custom_service_cb函数的入口、每个事件分支内部都加上日志打印conn_id,handle,event_type等信息。这是定位问题最直接的方法。从简单开始先实现一个只有“读”属性的特征确保能通。然后再添加“写”最后再上“通知”。分步验证可以隔离问题。注意内存对齐如果你在特征值中传输结构体数据确保考虑MCU的内存对齐问题避免使用packed结构体导致访问异常。连接事件处理务必在GATT_EVENT_DISCONNECT事件中清理对应连接的CCCD等状态信息防止下一个连接复用旧状态。整个过程就像在MCU上定义一张静态的数据表然后写好这张表上每个“单元格”被访问时的处理程序。只要GATT数据库定义得正确无误回调函数注册到位事件处理逻辑清晰你的自定义服务就能稳定可靠地工作。Apollo2 BLE SDK的这套机制虽然初期理解起来需要花点功夫但一旦掌握为项目添加任何自定义的蓝牙功能都会变得非常高效。