【RealMCU】瑞昱Simple BLE Service UUID 配置说明概述本文档详细说明在 Realtek BLE SDK 中如何将 Simple BLE Service 的 UUID 从默认的16位配置切换为128位配置。核心差异集中在simple_ble_service_tbl[]属性表中的各项配置。一、16位 UUID 配置默认方式1.1 头文件依赖16位 UUID 的具体数值通常定义在simple_ble_config.h中如GATT_UUID_SIMPLE_PROFILE、GATT_UUID_CHAR_SIMPLE_V1_READ等这些宏本质上就是纯数字如0xFFF0、0xFFF1等。1.2 Primary Service 声明服务UUID{(ATTRIB_FLAG_VALUE_INCL|ATTRIB_FLAG_LE),/* flags */{/* type_value */LO_WORD(GATT_UUID_PRIMARY_SERVICE),// 0x00HI_WORD(GATT_UUID_PRIMARY_SERVICE),// 0x28 → 组合为 0x2800LO_WORD(GATT_UUID_SIMPLE_PROFILE),// 服务UUID低字节16位数值拆分为2字节HI_WORD(GATT_UUID_SIMPLE_PROFILE)// 服务UUID高字节},UUID_16BIT_SIZE,/* bValueLen 2 */NULL,/* p_value_context */GATT_PERM_READ/* permissions */},关键点flags使用ATTRIB_FLAG_VALUE_INCL表示属性值16位UUID直接内嵌在 type_value 中type_value共4字节前2字节是 Primary Service 声明UUID0x2800后2字节是自定义服务UUIDbValueLenUUID_16BIT_SIZE即 2p_value_contextNULL因为值已内嵌在 type_value 中1.3 Characteristic 声明特征声明始终不变{ATTRIB_FLAG_VALUE_INCL,/* flags */{/* type_value */LO_WORD(GATT_UUID_CHARACTERISTIC),// 0x2803HI_WORD(GATT_UUID_CHARACTERISTIC),GATT_CHAR_PROP_READ/* characteristic properties */},1,/* bValueLen */NULL,GATT_PERM_READ/* permissions */},注意Characteristic 声明使用标准 GATT UUID0x2803始终是16位的16位和128位配置中此处完全相同。1.4 Characteristic Value 声明特征值UUID{ATTRIB_FLAG_VALUE_APPL,/* flags */{/* type_value */LO_WORD(GATT_UUID_CHAR_SIMPLE_V1_READ),// 16位特征UUID低字节HI_WORD(GATT_UUID_CHAR_SIMPLE_V1_READ)// 16位特征UUID高字节},0,/* bValueLen */NULL,GATT_PERM_READ/* permissions */},关键点flagsATTRIB_FLAG_VALUE_APPL仅此一个标志表示应用层负责读写该属性值type_value中直接填入LO_WORD/HI_WORD宏拆分的16位UUIDbValueLen0属性值由应用层动态提供不由表定义p_value_contextNULL1.5 CCCD 声明始终不变{ATTRIB_FLAG_VALUE_INCL|ATTRIB_FLAG_CCCD_APPL,/* flags */{/* type_value */LO_WORD(GATT_UUID_CHAR_CLIENT_CONFIG),// 0x2902HI_WORD(GATT_UUID_CHAR_CLIENT_CONFIG),LO_WORD(GATT_CLIENT_CHAR_CONFIG_DEFAULT),HI_WORD(GATT_CLIENT_CHAR_CONFIG_DEFAULT)},2,/* bValueLen */NULL,GATT_PERM_READ|GATT_PERM_WRITE/* permissions */},注意CCCD 使用标准 GATT 描述符UUID0x2902始终是16位的16位和128位配置中此处完全相同。二、128位 UUID 配置2.1 头文件中定义 128位 UUID 宏在simple_ble_service.h中使用宏定义 128位 UUID16字节格式为蓝牙标准的小端序#defineSIMP_UUID_BLE_BUFFER0xFB,0x34,0x9B,0x5F,0x80,0x00,0x00,0x80,#defineSIMP_READ_UUID_BLE_BUFFER0xFB,0x34,0x9B,0x5F,0x80,0x00,0x00,0x80,#defineSIMP_WRITE_UUID_BLE_BUFFER0xFB,0x34,0x9B,0x5F,0x80,0x00,0x00,0x80,#defineSIMP_NOTIFY_UUID_BLE_BUFFER0xFB,0x34,0x9B,0x5F,0x80,0x00,0x00,0x80,#defineSIMP_INDICATE_UUID_BLE_BUFFER0xFB,0x34,0x9B,0x5F,0x80,0x00,0x00,0x80,2.2 .c 文件中定义 128位 UUID 数组staticuint8_tsimple_uuid_ble[16]{SIMP_UUID_BLE_BUFFER};2.3 Primary Service 声明服务UUID → 128位{(ATTRIB_FLAG_LE|ATTRIB_FLAG_VOID),/* flags */{/* type_value */LO_WORD(GATT_UUID_PRIMARY_SERVICE),// 0x00HI_WORD(GATT_UUID_PRIMARY_SERVICE),// 0x28 → 组合为 0x2800},UUID_128BIT_SIZE,/* bValueLen 16 */simple_uuid_ble,/* p_value_context → 指向128位UUID数组 */GATT_PERM_READ/* permissions */},关键变化项目16位128位flagsATTRIB_FLAG_VALUE_INCL | ATTRIB_FLAG_LEATTRIB_FLAG_LE | ATTRIB_FLAG_VOIDtype_value4字节声明UUID 服务UUID2字节仅声明UUIDbValueLenUUID_16BIT_SIZE2UUID_128BIT_SIZE16p_value_contextNULLsimple_uuid_ble指向128位UUID数组的指针核心逻辑128位 UUID 无法像16位那样直接内嵌在type_value中type_value只有16字节空间因此改为通过p_value_context指针引用。相应地flags中去掉ATTRIB_FLAG_VALUE_INCL改用ATTRIB_FLAG_VOID。2.4 Characteristic Value 声明特征值UUID → 128位{(ATTRIB_FLAG_VALUE_APPL|ATTRIB_FLAG_UUID_128BIT),/* flags */{SIMP_READ_UUID_BLE_BUFFER},/* type_value → 128位UUID */UUID_128BIT_SIZE,/* bValueLen 16 */NULL,GATT_PERM_READ/* permissions */},关键变化项目16位128位flagsATTRIB_FLAG_VALUE_APPLATTRIB_FLAG_VALUE_APPL | ATTRIB_FLAG_UUID_128BITtype_valueLO_WORD(xx), HI_WORD(xx)2字节{SIMP_READ_UUID_BLE_BUFFER}16字节bValueLen0UUID_128BIT_SIZE16核心逻辑新增ATTRIB_FLAG_UUID_128BIT标志告知协议栈该属性使用的是128位UUID。type_value中直接展开16字节的UUID宏。三、gatt.h中关键标志位速查表以下是gatt.h中与 UUID 配置最相关的宏定义3.1 ATTRIB_FLAG 标志位宏定义值含义ATTRIB_FLAG_VOID0x0000属性值由p_value_context指向且不内嵌16位UUIDvalue_len需设为实际长度ATTRIB_FLAG_UUID_128BIT0x0001属性使用128位 UUID16字节ATTRIB_FLAG_VALUE_INCL0x0002属性值16位UUID直接内嵌在type_value字段中ATTRIB_FLAG_VALUE_APPL0x0004应用层负责提供该属性的读写值ATTRIB_FLAG_ASCII_Z0x0008属性值为 ASCII-Z 字符串ATTRIB_FLAG_CCCD_APPL0x0010应用层接收 CCCD 值变更通知ATTRIB_FLAG_CCCD_NO_FILTER0x0020CCCD 被写入时无条件通知应用层ATTRIB_FLAG_LE0x0800用于 Primary Service 声明表示 GATT over BLE3.2 UUID 尺寸宏定义值含义UUID_16BIT_SIZE216位 UUID 占用 2 字节UUID_128BIT_SIZE16128位 UUID 占用 16 字节3.3 T_ATTRIB_APPL 结构体typedefstruct{uint16_tflags;/* 属性标志位 ref GATT_ATTRIBUTE_FLAG */uint8_ttype_value[214];/* 16位UUID 内嵌值 或 128位UUID */uint16_tvalue_len;/* 值的长度 */void*p_value_context;/* 指向属性值的指针当 VALUE_INCL 和 VALUE_APPL 都未设置时使用 */uint32_tpermissions;/* 属性权限 ref GATT_ATTRIBUTE_PERMISSIONS */}T_ATTRIB_APPL;注意type_value字段固定为2 14 16字节。这个设计很巧妙16位模式前2字节放UUID后14字节可内嵌值如ATTRIB_FLAG_VALUE_INCL模式128位模式16字节全部放UUID配合ATTRIB_FLAG_UUID_128BIT标志四、完整对比总结4.1 需要修改的条目属性表条目16位配置128位配置Primary Serviceflags:VALUE_INCL | LEflags:LE | VOIDtype_value: 4字节声明服务UUIDtype_value: 2字节仅声明UUIDvalue_len:UUID_16BIT_SIZE(2)value_len:UUID_128BIT_SIZE(16)p_value_context:NULLp_value_context:simple_uuid_bleCharacteristic Valueflags:VALUE_APPLflags:VALUE_APPL | UUID_128BIT每个特征值各一个type_value:LO_WORD/HI_WORDtype_value:{SIMP_xxx_UUID_BLE_BUFFER}value_len:0value_len:UUID_128BIT_SIZE(16)4.2 不需要修改的条目属性表条目原因Characteristic 声明0x2803始终使用标准16位 GATT 声明UUIDCCCD0x2902始终使用标准16位 GATT 描述符UUIDUser Description0x2901始终使用标准16位 GATT 描述符UUID4.3 标志位组合逻辑16位模式的服务 UUID 内嵌流程 ATTRIB_FLAG_VALUE_INCL ATTRIB_FLAG_LE → 协议栈从 type_value[2..3] 读取16位服务UUID → value_len 2 128位模式的服务 UUID 指针引用流程 ATTRIB_FLAG_VOID ATTRIB_FLAG_LE → 协议栈从 p_value_context 读取128位UUID → value_len 16 16位模式的 Characteristic Value ATTRIB_FLAG_VALUE_APPL → 协议栈从 type_value[0..1] 读取16位UUID → value_len 0应用层动态提供 128位模式的 Characteristic Value ATTRIB_FLAG_VALUE_APPL ATTRIB_FLAG_UUID_128BIT → 协议栈从 type_value[0..15] 读取128位UUID → value_len 16五、从16位迁移到128位的操作步骤在simple_ble_service.h中定义5组128位UUID宏服务UUID 4个特征UUID每个16字节。在simple_ble_service.c中声明一个static uint8_t simple_uuid_ble[16]数组用于存放服务UUID。修改simple_ble_service_tbl[]中的 Primary Service 条目flags从(ATTRIB_FLAG_VALUE_INCL | ATTRIB_FLAG_LE)改为(ATTRIB_FLAG_LE | ATTRIB_FLAG_VOID)type_value中去掉服务UUID只保留LO_WORD/HI_WORD(GATT_UUID_PRIMARY_SERVICE)bValueLen从UUID_16BIT_SIZE改为UUID_128BIT_SIZEp_value_context从NULL改为simple_uuid_ble修改每个 Characteristic Value 条目共4个Read、Write、Notify、Indicateflags加上ATTRIB_FLAG_UUID_128BIT即从ATTRIB_FLAG_VALUE_APPL改为(ATTRIB_FLAG_VALUE_APPL | ATTRIB_FLAG_UUID_128BIT)type_value从LO_WORD/HI_WORD形式改为{SIMP_xxx_UUID_BLE_BUFFER}宏展开形式bValueLen从0改为UUID_128BIT_SIZECharacteristic 声明、CCCD、User Description 条目保持不变无需修改。