做过BLE蓝牙开发的兄弟应该都有这种经历第一次用nRF Connect连上某个外设看到界面里Service、Characteristic一层层嵌套的数据结构心里既兴奋又有点发怵。兴奋的是终于能亲眼看到蓝牙设备内部的数据组织了发怵的是如果对GATT协议不熟悉面对这一堆属性、特征、描述符根本不知道从哪里下手。这篇文章是BLE系列的第六篇专门把GATT协议里的属性Attribute、特征Characteristic、描述符Descriptor这三层关系掰开揉碎讲清楚顺便把服务Service怎么把这三者串成一个树形结构也说透。适合正在做BLE开发、或者准备投蓝牙外设联调的新手也适合那些已经在用GATT但被各种报错折腾过、想彻底搞懂底层逻辑的老手。1. GATT到底是什么先理顺它在BLE协议栈里的位置1.1 从协议栈说起GATT和ATT、GAP的关系BLE协议栈从下往上分好几层物理层和链路层负责把射频信号变成可以传输的数据包再往上逻辑链路控制和适配协议L2CAP负责把数据包切成更小的块方便上层协议做分段和重组。真正和应用开发者打交道的是两个大块一个是GAPGeneric Access Profile负责广播、扫描、连接建立这些“怎么认识”的问题另一个就是GATTGeneric Attribute Profile负责连接建立之后“怎么交换数据”的问题。这里有一个很关键的点GATT并不是直接落在L2CAP上的它中间还隔着一层ATTAttribute Protocol。ATT协议定义了最底层的属性读写规则GATT则在ATT基础上封装出“服务-特征-描述符”这样有语义的结构。你可以把ATT理解成操作系统的文件系统底层读写接口GATT则相当于在这个文件系统上做出了目录和文件的组织方式。没有ATTGATT就没有落脚的载体。很多初学者会把GATT和ATT混在一起其实区分起来很简单ATT只管“属性”的读写操作比如Read Request、Write Request、Notification这些PDUGATT则定义了“这些属性怎么组织成服务和特征”。换句话说ATT是传输层语义GATT是应用层语义。你抓包的时候看到的一串串16进制PDU大部分是ATT层的报文而当你用调试工具看到“这个服务叫Heart Rate下面有心率测量特征”这样的结构化信息那是GATT层帮你解析出来的结果。1.2 GATT解决的问题靠“数据目录树”实现互操作GATT出现的核心动机是解决互操作性问题。BLE设备五花八门有手环、体重秤、温度计、门锁如果每家都用自己的一套私有数据格式手机端每对接一款设备就得单独适配体验会非常差。GATT把数据组织成统一的结构让任何支持BLE的客户端比如手机都能通过一套通用的“发现服务-读取特征-订阅通知”流程来理解设备能提供什么数据、怎么去读写。这也是BLE设备能实现“一机在手、随便连”的基础。从实际开发角度看GATT的树形结构非常像图书馆的图书分类系统。服务Service就是书架上的一个大分类比如“心率服务”“电量服务”特征Characteristic是分类下面的一本书表示一个具体的数据点比如“当前心率值”描述符Descriptor则是书里对某一页内容的注释或配套说明比如“这个特征是否允许通知”。三层结构层层嵌套每个服务有唯一的UUID服务下的特征有唯一的UUID特征下的描述符同样有UUID通过这种唯一标识体系任何客户端都能精确定位一个数据点。在开始写代码之前建议你先在脑子里建立这个“目录树”的概念因为后面所有操作——不管是Service Discovery、Read Characteristic还是Write Descriptor——本质上都是在这棵树上进行遍历和增删改查。我见过太多人一上来就照着示例代码写结果换个设备就报错原因就是他根本不了解设备端的GATT结构长什么样。2. 属性AttributeGATT一切数据的载体2.1 一个属性包含的四要素在GATT/ATT体系里最小不可分割的数据单元就是“属性”。表面上你是在和服务、特征打交道实际上所有操作落到ATT层都是对属性的读和写。一个属性包含四个部分属性句柄Attribute Handle16位整数唯一标识一个属性取值范围0x0000到0xFFFF。GATT数据库中属性的句柄是从0x0001开始依次递增的这个句柄就是客户端读写属性时用来指定“我要操作谁”的地址。属性类型Attribute Type一个UUID用来表示“这个属性是什么”。比如0x180D代表“心率服务”0x2A37代表“心率测量特征值”0x2902代表“客户端特征配置描述符”。属性值Attribute Value一个字节数组是属性真正携带的数据。值的长度可以从0到512字节不等具体取决于属性的类型和实现。属性权限Attribute Permissions规定谁可以对这个属性做什么。包括读权限Read Permission、写权限Write Permission、以及是否需要认证Authentication、授权Authorization或加密Encryption等更高层级的访问控制。这四个要素每一项都很关键。句柄是地址类型是身份证值是真数据权限是门禁。四者缺一不可共同决定了一个属性在GATT数据库中的行为。很多开发者在服务端注册属性时只关注UUID和值忽略了权限配置结果客户端读不到、写不进排查半天才发现是权限没开。2.2 属性句柄为什么重要属性句柄经常被新手忽略但它在调试和某些特殊场景里非常有用。因为同一个类型的属性比如“0x2A37心率特征值”在设备里可能只有一个但服务里其他类型的属性可能有好几个纯粹靠类型去定位属性很低效而且有些低层级的ATT命令比如“Read By Type”是按照类型范围来扫描的会返回一堆结果。而通过句柄客户端可以直接发出“Read Request with handle 0x0015”这样的指令精确读到对应属性的值。在调试抓包时句柄还能帮助定位GATT数据库的结构变化。比如你用wireshark抓取连接过程可以看到手机发出的Discover All Primary Services请求返回了一系列服务句柄范围这些句柄范围就是划分服务和特征边界的依据。如果设备的GATT数据库里有重复UUID的属性句柄更是唯一能区分它们的手段。所以我在联调时第一步永远是先看服务列表的句柄范围再根据句柄去读特征值这样即使看log也能快速定位问题出在哪个属性上。2.3 属性类型UUID不只是看起来像“0x180D”而已UUID在BLE里分两种16位的短UUID和128位的长UUID。短UUID是蓝牙SIG标准定义的比如服务UUID 0x180D心率、0x180F电池、0x180A设备信息特征UUID 0x2A37心率测量、0x2A19电池电量等。128位UUID则是自定义服务/特征时用的格式类似“0000ffe0-0000-1000-8000-00805f9b34fb”这样其中前96位通常是固定的Base UUID0000XXXX-0000-1000-8000-00805f9b34fb中间的XXXX替换成你要用的短UUID比如0xFFE0映射成完整UUID就是“0000ffe0-0000-1000-8000-00805f9b34fb”。为什么要分这两种核心原因是省电和兼容。短UUID只有2个字节在广播数据包和ATT协议里传输时能省一截字节对BLE这种小包为王的协议很重要长UUID虽然占空间但能提供几乎无限的扩展空间适合自定义私有数据。实际开发中只要不是SIG已经定义好的标准数据都建议用128位UUID避免和别人的私有服务撞车。我见过不少开发者图省事直接用0xFFxx这样的短UUID做自定义结果设备多了之后和其他厂家的服务冲突排查起来非常痛苦。3. 特征Characteristic真正能读写的数据单元3.1 特征声明一个特征是怎么告诉别人“我能干啥”的特征是GATT数据模型中真正有业务含义的数据点。比如一个温度计它的“当前温度”就是一个特征一个门锁它的“开关状态”也是一个特征。但特征并不是挂着一个名字就完了它需要在自己前面加上一个“声明”Declaration向外部说明三件事这个特征具备哪些属性Properties、特征值在哪个句柄、特征值对应什么类型UUID。在GATT数据库里特征声明本身也是一个属性它的属性类型固定为0x2803属性值包含三个部分特征属性Characteristic Properties1个字节用bit位表示这个特征支持的操作比如bit0表示Broadcastbit1表示Readbit2表示Write Without Responsebit3表示Writebit4表示Notifybit5表示Indicate等。特征值句柄Value Handle2个字节指向真正存储特征值的属性句柄。特征UUID2字节或16字节标识特征值的类型。换句话说客户端在发现特征时先读到的是0x2803这个声明属性再根据声明里给出的句柄去读特征值。如果没有这个声明客户端最多只能看到一堆“属性”不知道哪个属性是“可以被通知的读取数据”哪个是“必须通过写入来控制的命令”。声明就像一本书的目录告诉你“第几页有什么内容”方便客户端快速建立数据地图。3.2 特征值的格式与读写权限特征值是特征的核心存放的就是客户端想读想写的实际数据。和声明属性一样特征值本身也是一个属性它的UUID就是特征自己的UUID比如0x2A37它的属性值就是具体的数据字节。在定义特征值时需要同时考虑值的格式和读写权限。值的格式一般由UUID对应的规范决定比如心率测量特征0x2A37的格式是第一个字节是Flags表示心率值格式、是否包含能量消耗扩展等后面跟着心率值8位或16位再往后可能有能量消耗等扩展字段。这就意味着客户端读到数据后不能想当然地把所有字节当整数解析必须先解析Flags再按格式取值。我遇到不少同事在这个地方踩坑直接把两个字节当成16位心率值结果真实心率和解析值差了十万八千里。读写权限则在属性权限里配置。默认情况下GATT数据库里的属性都是“不可读不可写”的你需要根据业务明确开放权限温度传感器温度值需要可读控制点需要可写有些敏感数据还需要加密或配对后才允许访问。这个权限和特征声明里的Properties是两层概念Properties告诉客户端“这个特征支持读操作”Permissions才真正决定“读操作有没有权限执行”。很多初学者把两者混为一谈导致写了一个支持Notify的特征但值属性的权限没有配读权限结果手机端订阅通知后一直收不到数据。3.3 特征属性Properties的常见取值与选择特征属性Properties是特征声明里的第一个字节它决定了这个特征以什么方式对外服务。在实际项目中最常见的是下面几种Read0x02客户端可以主动读取特征值。适合状态类数据如设备型号、电量。Write0x08客户端可以写入特征值且设备会返回写响应。适合可靠命令下发。Write Without Response0x04客户端可以写入特征值但设备不返回响应。适合大量连续下发、丢一两包影响不大的场景比如OTA数据流。Notify0x10设备主动推送数据到客户端不需要客户端确认。适合高频数据如实时心率、运动步数。Indicate0x20设备主动推送数据到客户端并且要求客户端确认。适合需要可靠交付的告警数据。Broadcast0x01特征值可以在广播包里广播但广播包空间有限实际用的很少。选择这些属性时有一个核心原则能用Read解决的就不要用Notify能用Notify解决的就不要用Indicate。因为Notify和Indicate都需要客户端先配置CCCD多一步交互Indicate每个数据包都要等确认吞吐率明显低于Notify。反过来数据如果不要求实时性完全可以让客户端主动来读这样还能降低功耗。我之前调试一个低功耗传感设备开发者为了省事把所有特征都配成Notify结果设备一秒钟推几十包数据电池一周就耗光了后来改成客户端按需轮询读取续航直接拉长到两个月。4. 描述符Descriptor特征的说明书和遥控器4.1 描述符和特征是什么关系特征值本身只负责承载数据但很多场景下仅有数据还不够。比如“这个特征值的单位是什么”“这个特征值的有效范围是多少”“这个特征值要不要开启通知”这些额外信息就需要描述符来承载。描述符是附加在特征下面的属性一个特征可以有0个或多个描述符描述符的类型通过UUID标识。从属性角度看描述符和特征值一样也是GATT数据库里的一个普通属性有自己的句柄、UUID、值和权限。但从逻辑角度看描述符是特征的一部分它不能独立存在必须挂靠在某个特征下面。这就像一本书的附录它属于这本书不能单独出版。当手机端读取一个特征时会通过“Read All Descriptors”流程把该特征下面的所有描述符也一并拉出来用于判断这个特征的行为方式。在实现上描述符最常见的用途有两个一是配置特征的行为比如CCCD二是给客户端提供关于特征值的元信息比如单位、名称、格式。前者更像遥控器后者更像说明书。我调试过的很多设备里一个特征往往只挂一个CCCD其他描述符很少用但这不等于描述符不重要——恰恰相反一个没配CCCD的Notify特征等于摆设客户端想订阅通知都不知道往哪里写。4.2 最常见的CCCD为什么你要往0x2902写数据CCCD的全称是Client Characteristic Configuration Descriptor它的类型UUID固定为0x2902。这个描述符的值是2个字节用来告诉设备“客户端希望这个特征以什么方式上报数据”。bit0置1表示使能Notifybit1置1表示使能Indicate两者一般不能同时置1。客户端往CCCD写入0x0001设备就会在特征值变化时推送通知写入0x0000则关闭通知。CCCD的本质是客户端对设备的配置它在设备端通常默认值是0x0000即不通知。这带来一个很容易被忽视的坑如果你在手机端代码里只调用了setCharacteristicNotification(true)却没有往0x2902写入1那么设备永远不会下发通知。很多BLE开发的新手第一次做通知功能都是卡在这一步iOS的CoreBluetooth在设置Notification时内部会自动帮你写CCCD但Android的BluetoothGatt不会你得自己调用writeDescriptor往0x2902写值。这是两个平台一个非常典型的差异。在调试CCCD问题时还有一个经验值得分享如果你发现更新CCCD后仍然收不到通知先用nRF Connect手动写一下0x2902试试。如果能手动写入并收到通知说明问题出在客户端代码如果手动都写不进去那就要检查特征属性的Permissions或者服务端代码里有没有把CCCD当作普通只读属性来处理。4.3 其他常用描述符除了0x2902这个“遥控器”还有几个描述符在实际开发中也很常见0x2901Characteristic User Description。这是一个UTF-8字符串用于给特征起一个人类可读的名称比如“Temperature Sensor”。很多蓝牙调试工具在UI上显示的特征名实际上就是读取了这个描述符。0x2904Characteristic Presentation Format。用于描述特征值的格式包括格式类型如uint8、uint16、指数、单位、命名空间等。比如温度特征的值格式是uint16单位是0x272F摄氏度。客户端可以根据这个描述符自动决定如何解析和显示数值。0x2905Characteristic Aggregate Format。用于聚合多个特征值在实际设备中很少见。理解这些描述符的价值在于当你看到一个特征的值是一串看起来像乱码的字节时不要急着在代码里硬编码解析逻辑先看它有没有带0x2904描述符——如果有单位、格式类型都在里面直接照着解析就好。我自己做外部设备联调时凡是遇到“疑似单位不统一”的解析问题第一反应就是去抓0x2904的内容这是最高效的方法。5. 用一句话串起来Service-Characteristic-Descriptor的树形关系5.1 一个完整的自定义服务实例拆解理论说太多了我们用实际例子把所有概念串起来。假设我们要做一个温湿度传感器定义如下GATT结构服务房间传感器服务UUID 0000FFE0-0000-1000-8000-00805F9B34FB特征1温度TemperatureUUID 0000FFE1-0000-1000-8000-00805F9B34FB特征值uint16类型单位0.01°C属性Permissions为读特征PropertiesRead | Notify描述符CCCD0x2902用于开关通知描述符用户描述0x2901值“Temperature”描述符格式描述0x2904值表示uint16、单位°C特征2湿度HumidityUUID 0000FFE2-0000-1000-8000-00805F9B34FB特征值uint8类型单位0.5%属性Permissions为读特征PropertiesRead描述符用户描述0x2901值“Humidity”当手机连接上这个设备后它会按步骤发现所有服务和特征最终在客户端代码里构建出这样一个数据结构server服务下面有多个characteristic特征每个characteristic下面有多个descriptor描述符。你直接把特征名映射成“温度”两个字就得到一张完整的树形图。在服务端实现时这个树形结构会映射成一段GATT数据库初始化代码。Nordic的SoftDevice里就是通过SD_BLE_GATTS_ATTR_TAB_SIZE宏估算属性表大小再调用sd_ble_gatts_characteristic_add把特征和描述符一次性加进去。Espressif的ESP-IDF则提供了esp_ble_gatts_create_attr_tab接口来批量注册属性。虽然不同芯片厂商的API风格不同但底层都是构建属性表、分配句柄、设置权限这三件事。5.2 手机是怎么“发现”这些服务的理解树形结构之后再看手机端的“发现服务”流程就简单了。整个过程大致是客户端发送Discover All Primary Services请求ATT Read By Group Type Request类型为0x2800获取所有主服务的句柄范围和UUID。对每个服务客户端发送Discover All Characteristics请求ATT Read By Type Request类型为0x2803获取该服务下所有特征的声明信息和值句柄。对每个特征客户端发送Discover All Descriptors请求ATT Find Information Request获取特征值后面挂着的所有描述符UUID。这个流程在nRF Connect里点一下“Show Differences”或者重新连接时就会自动执行。我遇到的很多联调问题根源都在“发现流程”阶段有些设备没有正确处理Read By Type请求或者返回了错误的句柄范围导致手机端只能看到部分服务或看不到任何特征。调试这类问题时打开logcat或者Xcode的蓝牙调试日志看看到底是哪一步请求超时或返回异常比盲猜代码有效得多。6. 实操用nRF Connect一步步看懂GATT结构6.1 连接设备后如何快速定位服务与特征假设你手里有一块支持BLE的开发板烧录一个标准心率服务固件。打开nRF Connect for Mobile扫描到设备后点击Connect。连接成功后界面会刷新出服务的列表。这个列表看起来只是一个一个Service的UUID但点击某个服务进去就能看到该服务下的所有Characteristics以及每个Characteristic下的所有Descriptors。在这里有几个实操技巧观察句柄nRF Connect默认不显示句柄需要点击右上角的设置按钮把“Show handle”打开。句柄能帮你把界面显示的数据和底层抓包对应起来。查看属性值点击某个特征值能直接读取到原始字节。如果要按格式解析就对照特征UUID的规范或者看0x2904描述符里的格式定义。测试Read/Write/Notify在特征详情页可以直接执行Read、Write或者“Subscribe”操作。订阅时nRF Connect会自动写CCCD所以你不用手动往0x2902填值。如果订阅后能收到推送就说明服务端通知路径没问题。我个人习惯是用nRF Connect先快速“摸”一遍设备确定服务的结构、句柄范围、支持的属性和读写行为然后再开始写客户端代码。这一步能省掉后续至少一半的调试时间。尤其是对接别人家的设备时没有这套“摸底”流程你写出来的代码基本靠猜。6.2 实操中遇到的现象和踩坑记录这里分享几个我在实操中真实遇到过的现象给你做个参考。第一个是“连接后看不到任何服务”。有一次我拿到一块新的开发板扫描和连接都正常但点进设备详情页死活刷不出服务。后来查下来是板子固件里GATT初始化失败属性表创建不成功导致设备对外没有暴露任何服务。这种问题从手机端看就是“服务列表为空”但根本原因在设备端。用nRF Connect看log或者用wireshark抓包会看到Discover All Primary Services请求返回了错误码或者根本没有响应。第二个是“特征能读但通知收不到”。典型原因是CCCD没有正确配置。我上面说过Android上手动写CCCD是必须的很多新人要么只调了setCharacteristicNotification要么往错误的描述符UUID写了值结果通知就是不来。排查方法是先确认手机端写的描述符UUID确实是0x2902再确认写入的值是0x0001最后用nRF Connect对比验证。第三个是“写入特征值后设备没反应”。这里要检查特征声明里的Properties有没有配Write以及对应属性的Permissions有没有开放可写。有些开发者只改了UUID和值忘了给权限加WRITE标志导致手机端写入直接被拒绝。这类问题在nRF Connect里表现为写操作返回错误码0x03Write Not Permitted或0x05Insufficient Authentication。7. 常见问题与排查技巧一张速查表 经验总结7.1 问题速查表整理一张速查表遇到问题先对照一遍能省不少时间。现象可能原因排查手段扫描不到设备广播参数未开启或广播间隔过长检查advertising数据、广播间隔配置连接失败地址类型不对或设备不在广播状态确认public/random地址类型确认设备可连接连接成功但看不到服务GATT初始化失败/属性表为空抓包看Discover响应检查设备端属性表看不到某个特征服务端未注册该特征/句柄冲突用nRF Connect看完整属性表Read返回0x02属性权限未开放读检查Permissions配置Write返回0x03属性权限未开放写检查Permissions和Properties的Write位收不到通知CCCD未设置/Properties缺Notify手动写0x2902验证确认订阅流程通知收到但值不对值格式解析错误查0x2904格式描述符对照SIG规范写操作返回0x05需要认证或加密先配对或调整权限设置7.2 避坑经验最后聊几个我在实际项目里非常受用的经验。第一属性句柄从0x0001开始连续分配不要跳太大。有些开发者为了“对齐”或者“好记”故意把句柄设成0x0010、0x0020这样的值这在小内存芯片上非常浪费属性表空间严重时直接导致GATT初始化失败。BLE的GATT数据库不像普通内存地址那样需要对齐连续递增是最节省资源的方案。第二自定义服务UUID强烈建议直接用128位完整UUID不要想着用短UUID扩展。虽然有Base UUID这种映射规则但不是所有调试工具、协议栈都能正确处理你那个“看起来是短UUID、其实是私有服务”的属性。为了兼容性和后续可维护性直接全部用完整UUID客户端解析时也能少踩坑。第三做OTA这类大流量传输时不要用Indicate用Notify配合流控如果必须可靠宁可加上层校验和重传。Indicate的确认机制在BLE这种低吞吐环境下会严重拖慢速度我在一个项目里对比过用Indicate传一包固件要十几分钟换成Notify加超时重传后五分钟就搞定了。第四跨平台开发时把“写CCCD”这个动作封装成一个统一的接口内部判断iOS和Android的差异。iOS的CoreBluetooth会自动处理CCCD但Android需要手动调writeDescriptor。如果你在跨平台框架里直接复用同一套业务逻辑很容易出现“iOS能收到通知、Android收不到”这种诡异问题。封装好之后再遇到这种问题可以直接定位到平台适配层。最后再分享一点个人经验。GATT这套模型刚开始学的时候确实抽象尤其是属性、特征、描述符三个概念交织在一起总觉得绕。但你只要抓住一条主线去记属性是底层的基本单元特征是“能被业务读写的那个属性”以及它的声明和附属说明的集合描述符则是特征的补充说明和配置入口。把这条线理清之后再看任何BLE设备的GATT数据库其实都是在读一本目录清晰的说明书而已。我在实际项目中还养成了一个习惯每次新拿到一块BLE设备不管参数多复杂先不着急写应用代码而是用nRF Connect把服务、特征、描述符完整地“摸”一遍把句柄范围记下来再对照抓包确认一遍。这样做看起来多花了十分钟但后续写代码、排查问题的时候能省下好几个小时。这个习惯一直保持到现在也希望对你有用。