1. 蓝牙设备名称长度极限的探索背景1.1 一个看似无聊却暗藏玄机的实验蓝牙设备名称到底能有多长这个问题乍一看像是闲着没事干才会去琢磨的事但如果你恰好做过蓝牙协议栈开发、或者折腾过嵌入式蓝牙模块就会知道设备名称这块的水比想象中深得多。我最初注意到这个现象是因为在某次调试一个双设备配对场景时发现其中一台设备把名称改成了一个超长字符串之后另一台设备在可用设备列表里显示的名称末尾出现了一个方块符号。这个方块不是乱码也不是字体缺失而是一个明确的截断标记。这个现象背后涉及的东西其实挺多蓝牙协议对设备名称长度的规定、GAP层的广播数据包结构、不同操作系统对设备名称的解析策略、以及UI层面如何处理超长字符串的显示。我花了大概两周的碎片时间把从协议规范到实际设备行为这条链路完整地跑了一遍中间踩了不少坑也积累了一些在官方文档里找不到的经验。这篇文章就是把这些东西整理出来给同样在做蓝牙相关开发或者对底层协议感兴趣的同行参考。1.2 适合哪些人阅读如果你属于以下几类人这篇内容应该能给你省下不少查资料和试错的时间正在做蓝牙BLE或经典蓝牙开发的工程师尤其是涉及设备发现和配对流程的做嵌入式蓝牙模块固件、需要处理设备名称字段的开发者做跨平台蓝牙应用、需要兼容不同手机和电脑显示行为的移动端或桌面端开发者以及单纯对蓝牙协议底层细节好奇、想搞清楚广播包到底怎么组装的技术爱好者。阅读门槛方面我尽量把协议规范和实际代码结合起来讲不会一上来就甩一堆术语。但如果你对GAP、广播包、ATT这些概念完全没接触过建议先花十分钟了解一下蓝牙协议栈的基本分层不然有些地方可能会觉得跳跃。下面我会从整体设计思路开始一步步拆到具体实现和问题排查。2. 蓝牙设备名称的协议约束与设计考量2.1 GAP层对设备名称的规范定义蓝牙的GAPGeneric Access Profile是整个蓝牙协议栈里负责设备发现、连接建立和安全管理的基础层。设备名称这个东西在GAP里对应的是两个特征值一个是Device NameUUID是0x2A00属于GATT服务里的Generic Access服务另一个是Complete Local Name和Shortened Local Name出现在广播数据或者扫描响应数据里。这里有个关键区别很多人一开始会搞混GATT里的Device Name特征值理论上可以存很长的字符串规范里写的是最多248个字节。而广播包里的Complete Local Name受限于广播数据的总长度经典蓝牙的广播包其实是Inquiry Response和BLE的广播包限制不一样。BLE的广播数据最多31个字节扫描响应也是31个字节加起来62个字节这里面还要塞Flags、UUID、Tx Power Level这些东西留给名称的空间就更少了。所以当你把设备名称设成248字节的时候广播包里根本放不下完整的名称设备只能放Shortened Local Name或者在扫描响应里放一部分。另一台设备在扫描时拿到的名称就是不完整的具体显示成什么样取决于它怎么处理这个截断。2.2 为什么是248字节这个数字248这个数字不是随便定的。蓝牙核心规范里对Device Name特征值的长度限制是248个字节这个值来源于ATT协议的最大属性值长度。ATT_MTU默认是23字节但可以通过MTU交换协商到更大的值最大支持517字节。不过Device Name特征值本身在规范里被限制在248字节这个限制是为了保证在单个ATT读请求或者通知里能够完整传输不需要分片。另外UTF-8编码下一个中文字符通常占3个字节一个emoji可能占4个字节。所以248字节并不意味着能放248个英文字母如果你用中文或者特殊符号实际能放的字符数会少很多。这一点在做多语言支持的时候特别容易踩坑后面我会详细说。2.3 广播包与扫描响应的空间分配BLE设备在广播的时候广播数据包和扫描响应包各自最多31字节。广播数据里通常放Flags3字节、Local Name的一部分、Tx Power Level3字节、Service UUID等。扫描响应里可以放剩余的Local Name、Service Name、制造商自定义数据等。假设你把设备名称设成248字节广播数据里可能只放了前10个字节的Shortened Local Name扫描响应里再放20个字节加起来30个字节剩下的218字节根本没地方放。另一台设备扫描的时候如果只读了广播数据没读扫描响应拿到的名称就更短。如果读了扫描响应拿到的名称也是截断的。不同操作系统对这种情况的处理策略不一样。有的系统会把广播和扫描响应里的名称拼起来有的只取广播里的有的会在名称末尾加省略号或者特殊符号表示截断。你看到的那个方块符号大概率就是某个系统在名称被截断时加的标记。2.4 方案选型为什么选择248字节作为测试值做这个实验的时候我选择248字节作为测试值原因有几个。第一这是规范允许的最大值能覆盖极端情况第二248字节在UTF-8下如果全用ASCII字符刚好能放248个字符如果混入中文或emoji能观察到编码对长度的影响第三这个长度足够触发各种截断和显示异常方便观察不同平台的行为差异。实际测试中我还试了100字节、200字节、300字节超出规范等几个值发现248字节确实是最能暴露问题的临界点。300字节的时候有些协议栈会直接拒绝设置有些会静默截断到248字节行为不一致反而不好对比。3. 核心细节解析与实操要点3.1 设备名称的设置方式与底层实现设置蓝牙设备名称的方式取决于你用的平台和协议栈。在Android上你可以通过BluetoothAdapter的setName方法修改本地设备名称但这个API在不同Android版本上行为不一样。Android 8.0之前setName需要BLUETOOTH_ADMIN权限而且修改后需要重启蓝牙适配器才能生效。Android 8.0之后setName的行为更稳定一些但仍然受系统限制。在Linux上如果你用的是BlueZ协议栈可以通过hciconfig或者bluetoothctl来修改设备名称。命令行方式是这样的# 使用bluetoothctl修改设备名称 bluetoothctl [bluetooth]# system-alias MyVeryLongDeviceName...或者直接通过D-Bus接口调用org.bluez.Adapter1的Alias属性。注意Alias和Name是两个不同的属性Alias是用户友好的名称Name是硬件层面的名称。广播包里用的是Name还是Alias取决于协议栈的实现。在嵌入式平台上比如用某款常见的蓝牙SoC你通常需要在固件里调用厂商提供的API来设置设备名称。这些API的底层实现一般是往GAP服务的Device Name特征值里写数据同时更新广播数据里的Local Name字段。这里有个坑很多厂商的API对名称长度有限制比如只允许最多20个字节超过部分直接截断而且不报错。你需要查厂商的文档或者直接看固件源码才能确认。3.2 广播数据的组装过程广播数据的组装是蓝牙协议栈里比较核心的一块。以BLE为例广播数据由一系列AD Structure组成每个AD Structure包含长度字段1字节、类型字段1字节和数据字段长度-1字节。总长度不能超过31字节。假设你要放一个完整的设备名称类型是0x09Complete Local Name数据是名称的UTF-8编码。如果名称长度是248字节加上长度字段和类型字段总共250字节远远超过31字节的限制。所以协议栈必须做截断通常的做法是先放Flags类型0x01数据3字节再放Tx Power Level类型0x0A数据1字节剩下的空间放Shortened Local Name类型0x08数据长度根据剩余空间计算计算过程大概是31 - 3Flags的AD Structure总长 - 3Tx Power Level的AD Structure总长 25字节。这25字节里1字节是长度字段1字节是类型字段剩下23字节是名称数据。所以广播包里最多放23字节的名称。扫描响应包也是31字节可以放剩余的225字节吗不行扫描响应也只有31字节去掉长度和类型字段最多放29字节的名称。所以广播扫描响应最多放232952字节的名称剩下的196字节完全丢失。3.3 不同平台对截断名称的显示处理这是最有趣的部分。当另一台设备扫描到你的设备时它拿到的名称是截断的具体显示成什么样取决于操作系统的蓝牙UI实现。在Android上系统蓝牙设置界面显示设备名称时如果名称被截断通常会在末尾加省略号...。但有些定制ROM会加别的符号比如方块或者问号。我测试的几台设备里有一台在名称末尾显示了一个空心方块这个方块其实是Unicode字符U25A1WHITE SQUARE用来表示“此处有字符但无法显示”。在iOS上系统对设备名称的处理更保守通常只显示广播包里的Shortened Local Name不会去读扫描响应里的内容。所以iOS设备上看到的名称往往比Android上更短。在Windows上蓝牙设置界面显示的名称来自系统缓存的设备信息如果名称被截断Windows可能会显示完整的GATT Device Name如果已经连接过并读取了特征值也可能显示广播里的短名称。这个行为在不同Windows版本上不一致Windows 10和Windows 11就有差异。3.4 特殊符号方块的出现原因那个方块符号我一开始以为是乱码后来抓了HCI日志才发现它是系统UI在渲染名称时遇到无法显示的字符或者名称被截断时插入的占位符。具体来说有几种可能第一种可能是名称截断发生在UTF-8字符的中间。比如一个中文字符占3个字节如果截断发生在第2个字节剩下的字节序列就不是合法的UTF-8解码时会变成替换字符UFFFDREPLACEMENT CHARACTER显示出来就是一个方块或者问号。第二种可能是系统在名称末尾主动加了截断标记。有些蓝牙协议栈在组装广播数据时如果名称被截断会在最后一个AD Structure里加一个标记表示名称不完整。接收端解析到这个标记后在UI上显示一个方块表示“名称被截断”。第三种可能是字体问题。某些特殊字符在系统默认字体里没有对应的字形渲染时就会显示成方块。这种情况在跨平台显示时特别常见比如Android上能正常显示的emoji在Windows上可能就变成方块。我通过对比HCI日志和UI显示确认我遇到的情况是第一种和第二种的混合名称截断在了一个中文字符的中间同时系统在末尾加了截断标记。4. 实操过程与核心环节实现4.1 实验环境搭建为了复现这个问题我搭了一个简单的测试环境。硬件方面用了两块支持BLE的开发板一块作为被扫描的设备Peripheral一块作为扫描设备Central。开发板的具体型号就不说了反正都是市面上常见的支持BLE 5.0的模块。软件方面Peripheral端跑的是自己写的固件基于厂商提供的SDKCentral端用的是Android手机和Windows笔记本各一台方便对比不同平台的显示行为。Android手机的系统版本是Android 12Windows笔记本是Windows 11 22H2。两台设备都装了通用的蓝牙调试工具用来抓HCI日志和GATT通信记录。另外还准备了一个USB蓝牙适配器插在Linux虚拟机上用BlueZ的工具链做底层调试。4.2 设置248字节设备名称的完整步骤在Peripheral端设置设备名称的代码大概长这样基于某厂商SDK的伪代码// 定义248字节的名称 uint8_t device_name[248]; memset(device_name, A, 247); device_name[247] \0; // 字符串结束符 // 调用SDK API设置设备名称 ble_set_device_name(device_name, 248); // 更新广播数据 ble_adv_data_t adv_data; adv_data.flags BLE_GAP_ADV_FLAGS_LE_ONLY_GENERAL_DISC_MODE; adv_data.local_name device_name; adv_data.local_name_len 248; ble_set_adv_data(adv_data); // 开始广播 ble_start_advertising();这里有几个关键点。第一名称数组要留一个字节给字符串结束符所以实际能用的字符是247个。第二SDK的ble_set_device_name函数内部可能会对名称做截断你需要确认它到底存了多少字节到GATT特征值里。第三广播数据里的local_name_len如果设成248协议栈会自动截断到能放下的长度但不同协议栈的截断策略不一样。在Android端如果你想修改本地设备名称可以用这段代码BluetoothAdapter adapter BluetoothAdapter.getDefaultAdapter(); adapter.setName(AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA);注意Android的setName方法对名称长度也有限制具体限制取决于Android版本和硬件。我测试的Android 12设备上setName最多接受248字节超过部分会被截断。4.3 配对过程中的名称读取与显示配对过程是另一个关键环节。当Central端发起配对时它会先扫描到Peripheral的广播拿到截断的名称然后在UI上显示。用户点击配对后Central端会连接Peripheral读取GATT的Device Name特征值这时候拿到的才是完整的248字节名称。但问题是很多系统的蓝牙UI在配对成功后仍然显示扫描时拿到的短名称而不是重新读取GATT特征值。这就导致用户看到的名称和实际名称不一致。我在Android上测试的时候配对前显示的名称是“AAAA...AAA□”末尾方块配对后显示的名称还是这个没有更新。手动在设置里刷新设备信息后才显示完整的248字节名称。Windows上的行为更奇怪。配对前Windows显示的名称是广播里的短名称配对后Windows会缓存这个名称即使你后来改了设备名称Windows还是显示旧的。需要删除设备重新配对才能更新。4.4 抓包分析与数据验证为了确认名称到底被截断成什么样我用Ellisys的蓝牙分析仪抓了空口数据。抓包结果显示广播包里的Local Name确实是截断的只有23字节。扫描响应包里又放了29字节。加起来52字节剩下的196字节完全没有出现在空口数据里。然后我连接设备读取GATT的Device Name特征值读到的数据是完整的248字节。这说明设备本身存储了完整的名称只是广播的时候放不下。HCI日志里还能看到Central端在扫描时协议栈把广播包和扫描响应包里的名称拼起来了拼出来的名称是52字节然后在UI上显示。UI层在渲染这个52字节的名称时发现末尾是一个不完整的UTF-8字符就显示了一个方块。4.5 参数计算与选择过程这里补充一下名称长度的计算过程。假设你要放一个包含中文的设备名称比如“我的超长蓝牙设备名称测试”每个中文字符占3个字节总共12个字符占36个字节。加上字符串结束符总共37字节。这个长度在广播包里放不下只能放Shortened Local Name。如果你要计算广播包里最多能放多少个中文字符可以这样算广播包31字节减去Flags的3字节减去Tx Power Level的3字节剩下25字节。25字节里减去长度字段1字节减去类型字段1字节剩下23字节。23字节除以3等于7个中文字符还剩2字节。所以广播包里最多放7个中文字符第8个字符会被截断截断后的字节序列不完整显示时就会出问题。这个计算过程在实际开发中很有用你可以根据目标平台的显示行为反推应该把设备名称控制在多少字节以内避免出现截断和方块。5. 常见问题与排查技巧实录5.1 设备名称显示不全或显示方块这是最常见的问题。排查思路是这样的先确认设备名称的实际长度和编码用GATT读取Device Name特征值看看完整名称是什么。然后抓空口数据看广播包和扫描响应包里放了哪些字节。对比两者确认截断发生在哪里。最后看接收端的UI实现确认它是怎么处理截断名称的。如果方块出现在名称末尾大概率是UTF-8截断导致的。解决办法是把设备名称控制在广播包能放下的长度以内或者接受截断但在UI上做特殊处理。如果方块出现在名称中间可能是名称里包含了接收端字体不支持的字符需要换字符或者换字体。5.2 配对后名称不更新这个问题在Android和Windows上都遇到过。原因是系统缓存了扫描时拿到的名称配对后没有重新读取GATT特征值。解决办法有几个在应用层主动读取Device Name特征值并更新UI在系统设置里手动刷新设备信息或者删除设备重新配对。如果你在做应用开发建议在配对成功后主动读一次Device Name不要依赖系统UI的显示。5.3 不同平台显示不一致这是跨平台开发的经典问题。同一个设备Android上显示的名称和iOS上显示的不一样和Windows上也不一样。原因是各平台对广播数据的解析策略不同有的只读广播包有的读广播扫描响应有的会读GATT特征值。解决办法是在应用层统一处理不要依赖系统UI。你可以自己扫描、自己解析广播数据、自己读取GATT特征值然后在自己的UI上显示这样就能保证一致性。5.4 名称长度超出规范导致设置失败有些协议栈在设置超过248字节的名称时会直接报错有些会静默截断。如果你遇到设置失败的情况先检查名称长度是否超过248字节。如果没超过但还是失败可能是协议栈的内部缓冲区更小需要查厂商文档。另外注意UTF-8编码下中文字符和emoji占用的字节数不同计算长度时要按字节算不要按字符算。5.5 常见问题速查表问题现象可能原因排查方法解决方案名称末尾显示方块UTF-8截断或系统截断标记抓空口数据检查截断位置控制名称长度或UI层处理配对后名称不更新系统缓存了扫描时的名称对比扫描名称和GATT名称应用层主动读取GATT特征值不同平台显示不一致各平台解析策略不同在多平台对比测试应用层统一解析和显示设置名称失败超出协议栈限制检查名称字节数和协议栈文档缩短名称或换协议栈名称中间出现方块字体不支持某些字符检查名称里的特殊字符换字符或换字体5.6 独家避坑技巧第一个技巧在设置设备名称之前先算一下UTF-8编码后的字节数。不要用字符串长度函数那个返回的是字符数不是字节数。在C里可以用strlen在Java里可以用getBytes(UTF-8).length在Python里可以用len(name.encode(utf-8))。第二个技巧如果你必须用超长名称考虑把完整名称放在GATT特征值里广播包里只放一个短名称或者干脆不放名称。Central端连接后主动读取GATT特征值这样既能保证名称完整又能避免广播包截断的问题。第三个技巧在UI层处理名称显示时不要直接渲染原始字节先做UTF-8合法性检查。如果发现不完整的字节序列用替换字符或者省略号代替避免显示方块。很多UI框架有内置的UTF-8处理函数直接用就行。第四个技巧测试的时候不要只测一台设备。不同厂商的蓝牙芯片、不同版本的操作系统、不同型号的手机行为都可能不一样。我至少测了5台设备才把问题范围缩小到UTF-8截断和系统缓存这两个原因。第五个技巧抓包工具很重要。没有抓包工具的话你只能看到UI显示的结果看不到底层数据。有了抓包工具你能看到广播包里到底放了什么扫描响应里放了什么GATT特征值里存了什么排查起来事半功倍。6. 蓝牙设备名称长度问题的延伸思考6.1 协议规范与实现之间的鸿沟蓝牙核心规范写得很清楚Device Name特征值最多248字节广播包最多31字节。但规范没有规定协议栈必须怎么截断也没有规定UI必须怎么显示。这就导致不同厂商、不同平台的实现千差万别。做跨平台开发的时候你不能假设所有平台的行为一致必须自己做兼容处理。这个问题不只存在于设备名称上蓝牙协议栈里很多地方都有类似的情况。比如MTU交换、连接参数更新、服务发现规范只规定了基本流程具体实现细节各厂商自由发挥。你在开发中遇到的很多“奇怪”问题根源都在这里。6.2 对开发者的实际建议如果你正在做蓝牙相关的开发我的建议是第一不要依赖系统UI显示设备名称自己解析广播数据和GATT特征值自己控制显示逻辑。第二设备名称尽量控制在20字节以内避免截断问题。如果必须用长名称把完整名称放在GATT特征值里广播包里放短名称。第三测试覆盖要广至少覆盖Android、iOS、Windows三个平台每个平台至少测两个版本。第四抓包工具是必备的没有抓包工具等于闭着眼睛调试。6.3 这个实验的后续扩展方向这个实验还可以往几个方向扩展。一个是测试不同编码对名称长度的影响比如用emoji、用日文、用韩文看看截断行为有什么不同。另一个是测试不同蓝牙版本的行为差异比如BLE 4.2和BLE 5.0在广播数据组装上有没有区别。还有一个是测试多个设备同时广播时的名称显示看看系统怎么处理多个截断名称。我自己在实际项目中遇到这个问题之后把设备名称的长度限制写进了团队的开发规范里要求所有蓝牙设备的名称不超过16字节并且必须用ASCII字符。这个规范执行之后再也没有出现过名称显示异常的问题。有时候最简单的方案就是最可靠的方案没必要为了炫技去挑战协议极限。