BLE GATT服务与特性自定义：Adafruit Bluefruit LE AT命令实战指南

1. 项目概述与GATT核心概念解析

如果你正在捣鼓蓝牙低功耗（BLE）设备，尤其是像Adafruit Bluefruit LE这样的模块，那你肯定绕不开一个核心概念：GATT。这东西听起来有点玄乎，但说白了，它就是蓝牙世界里一套约定俗成的“数据组织与交换协议”。想象一下，你的BLE设备就像一个提供多种服务的智能小店，GATT就是这家小店的“服务菜单”和“商品清单”的编排规则。

GATT的全称是通用属性配置文件（Generic Attribute Profile），它是建立在ATT（属性协议）之上的一层抽象。其核心架构非常清晰，是一个三层树状结构：配置文件（Profile） -> 服务（Service） -> 特性（Characteristic）。对于我们开发者而言，最常打交道的后两层。一个服务（Service）代表设备提供的一项独立功能，比如电池电量监测、心率测量或者自定义的数据传输。每个服务下面包含一个或多个特性（Characteristic），这才是真正存放数据的地方，比如电池服务的“电量百分比”特性，心率服务的“心率测量值”特性。

每个特性不仅仅是一个数据值，它更像一个带有完整“元数据”的数据点。这些元数据包括：

• UUID：全球唯一标识符，相当于特性的身份证号。蓝牙技术联盟（SIG）定义了一批标准的16位UUID（如0x2A19代表电池电量），对于自定义功能，我们可以使用128位的UUID。
• 属性（Properties）：定义了客户端（比如手机App）能对这个特性做什么。常见的有：读（Read）、写（Write）、通知（Notify）、指示（Indicate）。Notify和Indicate都允许服务器（你的设备）主动向客户端推送数据，区别在于Indicate需要客户端确认，更可靠但稍慢。
• 值（Value）：特性实际承载的数据，长度可变。
• 描述符（Descriptor）：对特性进行进一步描述的附加信息，比如“特性用户描述”（Characteristic User Description）就是一个可读的字符串，告诉你这个特性是干嘛的。

为什么我们要大费周章地自定义GATT服务呢？因为标准服务（如电池、设备信息）虽然通用，但远远不够。当你想让设备传输特定的传感器数据、控制指令或任何非标准信息时，就必须创建自己的服务和特性。这就是AT+GATTADDCHAR等命令大显身手的地方。通过Adafruit Bluefruit LE模块提供的AT命令集，我们可以直接通过串口指令，动态构建一个完全符合我们业务逻辑的GATT数据模型，而无需深入底层复杂的蓝牙协议栈编程。这对于快速原型开发、功能验证以及特定应用的设备开发来说，效率提升不是一点半点。

2. Bluefruit LE GATT AT命令体系深度拆解

Bluefruit LE的AT命令为管理GATT提供了一套完整的工具箱。理解这个工具箱里每件工具的用途和先后顺序，是成功配置的关键。整个流程遵循“先搭建框架，再填充内容”的逻辑。

2.1 命令执行顺序与状态管理

在开始添加任何特性之前，必须理解GATT配置的“上下文”概念。Bluefruit LE模块内部维护着一个自定义GATT表。所有AT+GATTADDCHAR（添加特性）的操作，其目标都是最近一次通过AT+GATTADDSERVICE添加的那个服务。这就像你打开了一个文档进行编辑，所有输入的文字都会出现在当前光标所在的位置。因此，一个典型的配置流程必须是线性的、有序的：

1. 清理现场：使用AT+GATTCLEAR。这是一个好习惯，尤其是在开发和调试阶段。这条命令会清空模块内所有之前定义的自定义服务和特性，确保你从一个干净的状态开始，避免旧配置的干扰。
2. 创建服务：使用AT+GATTADDSERVICE。这是搭建框架的第一步。你需要指定服务的UUID。执行成功后，模块会返回一个服务索引ID（通常是1，2，3...递增），并且将“当前编辑的服务”指向这个新创建的服务。
3. 添加特性：使用AT+GATTADDCHAR。现在，所有对AT+GATTADDCHAR的调用，都会将特性添加到上一步创建的服务中。你可以连续添加多个特性到这个服务下。
4. 重复或新建：如果你想创建另一个服务，必须再次使用AT+GATTADDSERVICE。这会将“当前编辑的服务”切换到新的服务上，随后添加的特性就会归属于这个新服务。

踩坑提醒：一个非常常见的错误是，连续调用两次AT+GATTADDCHAR而中间没有用AT+GATTADDSERVICE指定新的服务，结果就是两个特性都被加到了同一个服务里。如果你本意是创建两个独立服务，这就会导致结构错误。务必在逻辑上区分服务时，显式地使用AT+GATTADDSERVICE。

2.2 核心命令参数精讲

AT+GATTADDCHAR是配置的灵魂，它的参数决定了特性的所有行为。这些参数以逗号分隔的键=值对形式提供，且不区分大小写。

• UUID：这是特性的核心标识。

  • 16位UUID：最常用的形式，例如UUID=0x2A19。这里有一个至关重要的细节：当父服务使用的是128位UUID时（通过UUID128参数指定），你提供的这个16位UUID会被插入到父服务UUID的第3和第4个字节。因此，你必须确保自定义的16位UUID不会与父服务128位UUID的这两个字节冲突，否则会产生歧义。
  • 128位UUID（固件>=0.6.6）：使用UUID128参数，后跟一个完整的128位UUID，格式如00-11-22-33-...-FF。这给了你完全的自主权，无需考虑与父服务UUID的拼接关系，适合需要绝对唯一标识的场景。

• PROPERTIES：定义特性的操作权限，使用8位掩码（十六进制）。你可以通过“或”运算组合多个属性（在AT命令中直接写计算后的十六进制值即可）。

  • 0x02-Read：允许客户端读取该特性的值。
  • 0x04-Write Without Response：客户端写入数据，服务器不回复确认。速度快，但不保证送达。
  • 0x08-Write：客户端写入数据，服务器需要回复确认。更可靠。
  • 0x10-Notify：服务器可以主动向启用了通知（Notification）的客户端发送更新。这是实现数据推送（如传感器实时流）最常用的属性。
  • 0x20-Indicate：与Notify类似，但客户端必须回复确认。数据可靠性更高，但吞吐量略低于Notify。

• MIN_LEN 与 MAX_LEN：定义特性值长度的合法范围（单位：字节）。MIN_LEN默认为1，MAX_LEN在早期固件中最大为20，0.7.0之后增至32。这不仅是限制，也是一种约定，帮助通信双方预知数据大小。

• VALUE：特性的初始值。支持多种格式：

  • 十进制整数：VALUE=100
  • 十六进制数：VALUE=0x64
  • 字节数组（十六进制，以短横线连接）：VALUE=AA-BB-CC-DD
  • 字符串：VALUE=Hello设置合理的初始值有助于客户端在连接后立即获取到一个有效状态。

• DATATYPE（固件>=0.7.0）：指明VALUE的数据类型，用于辅助系统正确解析和处理数据。这是一个非常实用的增强。

  • AUTO (0)：自动检测（默认）。
  • STRING (1)：字符串类型。
  • BYTEARRAY (2)：字节数组类型。
  • INTEGER (3)：整数类型。 明确数据类型可以避免一些边界情况下的解析错误。

• DESCRIPTION 与 PRESENTATION（固件>=0.7.0）：这两个参数用于添加标准的GATT描述符，极大地提升了特性的可读性和互操作性。

  • DESCRIPTION：对应“特性用户描述描述符”。你可以提供一个人类可读的字符串，例如DESCRIPTION="Battery Level"。一些专业的蓝牙调试工具（如Nordic的nRF Connect）会显示这个描述，让调试者一目了然。
  • PRESENTATION：对应“特性展示格式描述符”。这是一个7字节的特定格式数据，用于标准化地描述特性值的格式、单位和精度。例如，对于一个温度值，你可以指定它是浮点数、单位是摄氏度、小数点后一位。这需要参考蓝牙SIG的定义来组装这7个字节。

2.3 配套命令：查询与管理

配置好后，我们还需要工具来验证和管理。

• AT+GATTCHAR：这是与特性交互的瑞士军刀。
  • 读模式：AT+GATTCHAR=<索引>。返回该特性的当前值。索引是AT+GATTADDCHAR成功时返回的数字。
  • 写模式：AT+GATTCHAR=<索引>,<新值>。更新特性的值。新值必须符合创建时定义的MIN_LEN和MAX_LEN限制。
• AT+GATTLIST：你的“配置清单”。执行后，模块会列出所有已定义的自定义服务和其下的特性，包括UUID、属性、长度限制和当前值。这是调试时验证GATT结构是否按预期构建的必备命令。
• AT+GATTCHARRAW（固件>=0.7.0）：一个为库开发者或高效数据传输设计的命令。它直接返回特性的二进制原始数据，而不是可打印的ASCII格式，减少了解析开销。注意，此命令输出后没有标准的OK\r\n结尾，使用时需要特别处理。

3. 从零构建自定义GATT服务：实战演练

理论说得再多，不如动手操作一遍。下面我们通过两个完整的例子，演示如何构建一个包含标准服务和完全自定义服务的GATT配置。

3.1 案例一：创建标准电池服务

这个例子演示如何实现一个蓝牙SIG标准的电池服务。这是一个非常常见且实用的功能。

# 步骤1：清空之前的自定义配置，确保起点干净 AT+GATTCLEAR # 预期响应: OK # 步骤2：添加电池服务。UUID 0x180F 是蓝牙SIG为电池服务分配的标准标识。 AT+GATTADDSERVICE=UUID=0x180F # 预期响应: 1 (服务索引ID) # OK # 步骤3：为电池服务添加“电量等级”特性。 # UUID 0x2A19 是标准电池电量特性标识。 # PROPERTIES=0x10 表示启用Notify，允许设备主动上报电量变化。 # MIN_LEN=1, MAX_LEN=1 表示电量值是一个1字节的无符号整数（范围0-100%）。 # VALUE=100 设置初始电量为100%。 AT+GATTADDCHAR=UUID=0x2A19,PROPERTIES=0x10,MIN_LEN=1,MAX_LEN=1,VALUE=100 # 预期响应: 1 (特性索引ID) # OK

完成上述步骤后，你的设备就对外暴露了一个标准的电池服务。手机上的蓝牙调试App（如nRF Connect）扫描并连接后，应该能看到一个名为“Battery Service”的服务，里面有一个“Battery Level”特性，其属性包含“Read”和“Notify”，当前值为0x64（即十进制的100）。

交互测试：

# 读取当前电量值 AT+GATTCHAR=1 # 预期响应: 0x64 # OK # 模拟电量更新为50%（0x32） AT+GATTCHAR=1,50 # 预期响应: OK # 再次读取验证 AT+GATTCHAR=1 # 预期响应: 0x32 # OK

3.2 案例二：创建完全自定义的环境监测服务

现在我们来点更复杂的：创建一个自定义的“环境监测服务”，包含温度、湿度和开关状态三个特性，并使用0.7.0固件的新功能。

# 步骤1：清空配置 AT+GATTCLEAR OK # 步骤2：创建一个使用128位UUID的自定义服务。 # 这里使用一个随机生成的UUID作为服务基础。 AT+GATTADDSERVICE=UUID128=DE-AD-BE-EF-00-00-11-11-22-22-33-33-44-44-55-55 1 OK # 步骤3：添加温度特性。 # 使用16位UUID 0x0001。注意，它会被插入到父服务UUID的3、4字节。 # 属性：可读、可通知（0x02 | 0x10 = 0x12） # 长度：2字节（假设用16位整数表示，单位0.1摄氏度，范围-400~8500，即-40.0°C ~ 85.0°C） # 初始值：250 (代表25.0°C) # 数据类型：整数 # 描述：“Temperature” # 展示格式：0x17-00-27-AC-01-00-00 (IEEE 11073 32位浮点，单位：华氏度，命名空间1) # 注意：PRESENTATION格式需要根据蓝牙规范仔细计算，此处为示例。 AT+GATTADDCHAR=UUID=0x0001,PROPERTIES=0x12,MIN_LEN=2,MAX_LEN=2,VALUE=250,DATATYPE=3,DESCRIPTION="Temperature",PRESENTATION=17-00-AC-27-01-00-00 1 OK # 步骤4：添加湿度特性。 # UUID: 0x0002 # 属性：可读、可通知 # 长度：1字节（0-100%） # 初始值：60 (60%) # 描述：“Humidity” AT+GATTADDCHAR=UUID=0x0002,PROPERTIES=0x12,MIN_LEN=1,MAX_LEN=1,VALUE=60,DATATYPE=3,DESCRIPTION="Humidity" 2 OK # 步骤5：添加开关控制特性。 # UUID: 0x0003 # 属性：可读、可写（0x02 | 0x08 = 0x0A） # 长度：1字节（0=关，1=开） # 初始值：0 (关) # 描述：“LED Switch” AT+GATTADDCHAR=UUID=0x0003,PROPERTIES=0x0A,MIN_LEN=1,MAX_LEN=1,VALUE=0,DATATYPE=3,DESCRIPTION="LED Switch" 3 OK

使用AT+GATTLIST验证配置：执行AT+GATTLIST，你会得到一个清晰的树状结构输出，类似于：

ID=01,UUID=0xDEAD, UUID128=DE-AD-BE-EF-00-00-11-11-22-22-33-33-44-44-55-55 ID=01,UUID=0x0001,PROPERTIES=0x12,MIN_LEN=2,MAX_LEN=2,VALUE=0xFA,DATATYPE=INTEGER,DESC="Temperature",PRES-FMT=17-00-AC-27-01-00-00 ID=02,UUID=0x0002,PROPERTIES=0x12,MIN_LEN=1,MAX_LEN=1,VALUE=0x3C,DATATYPE=INTEGER,DESC="Humidity" ID=03,UUID=0x0003,PROPERTIES=0x0A,MIN_LEN=1,MAX_LEN=1,VALUE=0x00,DATATYPE=INTEGER,DESC="LED Switch" OK

这个输出完美地展示了我们刚刚构建的整个自定义GATT结构。

4. 高级特性与固件版本适配

Bluefruit LE的固件在持续更新，带来了更多强大功能。了解这些特性，能让你的项目更上一层楼。

4.1 128位UUID的灵活运用（固件>=0.6.6）

在0.6.6版本之前，自定义特性的UUID受到父服务UUID的限制。0.6.6版本引入的UUID128参数彻底解决了这个问题。它允许你为特性指定一个完全独立的、完整的128位UUID。

应用场景：当你需要确保特性的UUID在全球范围内绝对唯一，或者需要遵循某个特定厂商或组织的私有UUID规范时，就必须使用128位UUID。例如，苹果的iBeacon、谷歌的Eddystone都使用特定的128位UUID。

示例：

# 添加一个使用独立128位UUID的特性 AT+GATTADDCHAR=UUID128=12-34-56-78-9A-BC-DE-F0-12-34-56-78-9A-BC-DE-F0,PROPERTIES=0x02,MIN_LEN=4,VALUE=0xDEADBEEF

这样定义的特性，其UUID与父服务无关，提供了最大的灵活性。

4.2 描述符的威力：DESCRIPTION与PRESENTATION（固件>=0.7.0）

DESCRIPTION和PRESENTATION这两个参数极大地提升了GATT配置的专业性和互操作性。

• DESCRIPTION：这相当于给特性加了一个“标签”。在复杂的自定义服务中，有一堆UUID为0x0001、0x0002的特性，光看数字根本记不住谁是谁。加上DESCRIPTION="Temperature Sensor"这样的描述，在任何支持显示该描述符的蓝牙调试工具上，可读性瞬间提升，极大降低调试和维护成本。

• PRESENTATION：这是为了标准化数据解释。它告诉客户端：“我这个特性的值，是一个IEEE 754浮点数，单位是摄氏度，指数是-1（即代表0.1°C的精度）”。客户端应用（尤其是通用型的数据采集App）可以依据这个描述符，正确地将接收到的原始字节（例如0x00 0xFA）解析并显示为有意义的数值（25.0°C），而无需在App里硬编码解析规则。

组装PRESENTATION值： 这需要参考蓝牙SIG的“特性展示格式”描述符定义。它是一个7字节的数组：

1. 格式 (1字节)：如0x17代表IEEE-11073 32-bit SFLOAT。
2. 指数 (1字节)：有符号整数，表示10的幂次。例如，值250（0xFA）若指数为-1，则实际值为25.0。
3. 单位 (2字节)：蓝牙SIG定义的单元UUID，如0x27AC代表华氏度。
4. 命名空间 (1字节)：0x01代表蓝牙SIG分配号。
5. 描述 (2字节)：0x0000通常表示无额外描述。

虽然手动计算有些繁琐，但一旦配置好，数据的交换就变得非常规范。

4.3 特性值的动态读写与通知机制

创建特性只是第一步，让数据流动起来才是目的。

• 写入与业务逻辑挂钩：当你通过手机App向一个具有Write属性的特性（如我们例子中的LED开关）写入新值（如0x01）时，Bluefruit LE模块会通过串口发送一个特定格式的报文（通常是+GATTCHAR=<索引>,<值>）来通知你的主控MCU（如Arduino）。你的MCU代码需要解析这个报文，并执行相应的操作（如点亮LED）。这就是实现“手机控制硬件”的关键链路。

• 通知的启用与数据推送：对于具有Notify属性的特性（如温度），客户端（手机App）需要先向该特性的“客户端特性配置描述符”（CCCD）写入0x0001来启用通知。启用后，你的MCU就可以在传感器数据更新时，使用AT+GATTCHAR=<索引>,<新值>命令更新特性值。模块会自动将新值通过BLE通知推送给所有已启用的客户端，实现数据的实时上传。这是“硬件上报数据给手机”的主要方式。

实战经验：在编写MCU端代码处理+GATTCHAR输入时，一定要做好错误处理和超时机制。蓝牙连接可能不稳定，写入的值也可能超出范围。稳健的代码应该能忽略无效报文，并在关键操作失败时有恢复策略。

5. 调试技巧、常见问题与故障排除

即使按照指南操作，也难免会遇到问题。下面是我在多年项目中积累的一些实战调试经验和常见坑位。

5.1 基础检查清单

遇到GATT配置不生效时，首先按以下顺序排查：

1. 固件版本：使用ATI命令确认固件版本。许多高级功能（如128位UUID、DESCRIPTION）需要特定版本以上。
2. 命令顺序：是否在AT+GATTADDCHAR之前正确执行了AT+GATTADDSERVICE？可以用AT+GATTLIST检查当前有哪些服务。
3. 参数格式：检查键=值对的拼写是否正确，逗号是英文逗号，十六进制是否有0x前缀，128位UUID的连字符格式是否正确。
4. 连接与发现：手机App是否已经断开并重新连接？许多App在连接后缓存服务列表，设备GATT表更改后，必须重连才能发现新服务。
5. 供电与复位：确保模块供电稳定。在完成一系列GATT配置后，有时执行一次ATZ（软复位）能让配置更彻底地生效。

5.2 典型错误与解决方案

5.3 高效调试工具链

1. AT命令终端：一个支持发送回车换行（\r\n）的串口工具是基础。我推荐使用Arduino IDE的串口监视器（需设置“新行”或“回车换行”），或者功能更强大的CoolTerm、Putty。
2. 蓝牙调试App：这是可视化验证GATT配置的利器。
   • nRF Connect (Nordic)：功能最强大、最专业的免费工具，支持所有平台（iOS/Android/Windows/macOS/Linux）。它能清晰展示完整的GATT层次结构，方便地读写特性、启用通知，并且能显示DESCRIPTION和PRESENTATION描述符。
   • LightBlue (iOS/macOS)：界面简洁直观，适合快速测试基本读写和通知功能。
   • BLE Scanner (Android)：另一款流行的Android端调试工具。
3. 逻辑分析仪：如果遇到极其诡异的通信问题（如AT命令无响应），一个廉价的逻辑分析仪（如Saleae Logic 8或其克隆版）可以帮助你抓取UART线上的实际波形，确认MCU发送给Bluefruit LE模块的命令字节完全正确，排查硬件通信问题。

5.4 性能与内存考量

• 特性数量限制：虽然理论上可以添加多个服务/特性，但受限于nRF51822的内存和Bluefruit LE固件的设计，实际可添加的数量是有限的。过多的自定义GATT项目可能导致系统不稳定或连接失败。对于复杂应用，建议将相关数据合并到更少的特性中，或者通过一个“命令/数据”特性进行多路复用。
• 通知频率：高频发送Notify（如每秒几十次）可能会消耗较多功耗，并给蓝牙链路带来压力。需要根据连接间隔（Connection Interval）合理设置数据更新频率。Bluefruit LE的AT+GAPINTERVALS命令可以调整连接参数以平衡速度和功耗。
• 数据长度：单个特性值最大长度从20字节提升到32字节（0.7.0+），但对于传输大量数据（如图片、长日志），仍然需要设计分包协议。常见的做法是：定义一个“数据通道”特性用于传输分包后的数据，再定义一个“控制”特性用于同步包序号、长度等信息。

最后，我的个人体会是，GATT配置就像在蓝牙世界里定义一套双方都能理解的“数据语言”。AT+GATTADDCHAR等命令给了我们定义词汇（特性）和语法（属性）的能力。一开始可能会被UUID、属性这些细节困扰，但一旦你成功配置出第一个自定义服务并实现手机与设备的双向通信，那种成就感会驱使你探索更多可能。多动手实验，善用AT+GATTLIST来验证你的每一步操作，遇到问题时按照从基础到复杂的顺序耐心排查，你就能越来越熟练地驾驭Bluefruit LE，让它成为你物联网项目中可靠的无线通信核心。