问题速查

[English]

上报问题所需信息

在遇到问题时，请先收集以下信息：

• 使用的芯片

• IDF 版本

• 使用的协议栈

• 完整的日志

• 问题发生的时间和频率

• 问题发生时的操作步骤

如果产品尚且处于开发阶段，推荐升级当前 release 版本最新的 TAG 版本。

NimBLE 错误码

NimBLE 的错误码分为以下几类:

NimBLE 错误码类型

错误类型	说明	不同层的错误返回值
NimBLE Core	NimBLE 自己定义的错误码
ATT	属性协议层错误码	0x100+(X)
HCI	主机控制器接口层错误码	0x200+(X)
L2CAP	逻辑链路控制与适配层协议层错误码	0x300+(X)
Security manager (us)	安全管理层错误码（本地设备）	0x400+(X)
Security manager (peer)	安全管理层错误码（远端设备）	0x500+(X)
Hardware errors	硬件层的错误码	0x600+(X)

其中 X 代表具体的错误类型编号。例如，如果返回 0x102，表示是 ATT 层的错误码 0x02。 如果返回的错误码是十进制的则需要转换为十六进制。然后再检查对应的错误类型。

具体的错误码请参考 ble_hs.h

HCI 错误码

HCI 错误码是蓝牙主机控制器接口（Host Controller Interface）层返回的错误代码，用于指示操作失败的具体原因。以下是常见的 HCI 错误码及其说明：

常见 HCI 错误码

错误码	英文说明	说明	可能的原因
0x00	Success	成功	操作成功完成
0x01	Unknown HCI Command	未知 HCI 命令	控制器不理解主机发送的 HCI 命令数据包操作码
0x02	Unknown Connection Identifier	未知连接标识符	命令中指定的连接不存在或连接类型不正确
0x03	Hardware Failure	硬件故障	控制器中发生无法用其他错误码描述的故障
0x05	Authentication Failure	身份验证失败	配对或身份验证过程失败，可能是由于错误的密码或链接密钥
0x08	Connection Timeout	连接超时	链路监视超时或广播同步超时
0x0B	Connection Already Exists	连接已存在	尝试创建到已连接设备的新连接
0x0C	Command Disallowed	不允许命令	控制器当前状态无法处理该命令
0x0D	Connection Rejected due to Limited Resources	资源有限	由于控制器资源不足而拒绝连接
0x0E	Connection Rejected Due To Security Reasons	安全原因	由于未满足安全要求（如身份验证或配对）而拒绝连接
0x11	Unsupported Feature or Parameter Value	不支持的特性或参数值	HCI 命令中的特性或参数值不被支持
0x12	Invalid HCI Command Parameters	无效的 HCI 命令参数	至少有一个 HCI 命令参数无效
0x13	Remote User Terminated Connection	远程用户终止连接	远程设备上的用户终止了连接或停止了广播
0x16	Connection Terminated By Local Host	本地主机终止连接	本地设备终止了连接、同步或广播
0x1E	Invalid LMP Parameters / Invalid LL Parameters	无效的 LMP 参数/LL 参数	LMP PDU 或 LL 控制 PDU 参数无效
0x1F	Unspecified Error	未指定的错误	没有其他合适的错误代码
0x22	LMP Response Timeout / LL Response Timeout	LMP 响应超时/LL 响应超时	LMP 或 LL 事务未在超时时间内响应
0x2F	Insufficient Security	安全不足	命令或 PDU 需要在加密链路上执行
0x3B	Unacceptable Connection Parameters	不可接受的连接参数	远程设备因连接参数不可接受而终止连接
0x3C	Advertising Timeout	广播超时	固定时间的广播完成或定向广播未建立连接
0x3D	Connection Terminated due to MIC Failure	MIC 故障	由于消息完整性检查失败而终止连接
0x3E	Connection Failed to be Established / Synchronization Timeout	连接未能建立/同步超时	连接建立失败或未能与定期广播同步
0x3F	MAC Connection Failed	MAC 连接失败	连接建立过程中 MAC 层失败
0x40	Coarse Clock Adjustment Rejected but Will Try to Adjust Using Clock Dragging	粗时钟调整被拒绝，但将尝试使用时钟拖动	无法使用提供的参数对时钟进行粗调整，将尝试使用时钟拖动
0x41	Type0 Submap Not Defined	类型 0 子映射未定义	LMP PDU 被拒绝，因为类型 0 子映射当前未定义
0x42	Unknown Advertising Identifier	未知广播标识符	命令中指定的广播或同步句柄不存在
0x43	Limit Reached	达到限制	已达到请求的操作数量，活动已完成
0x44	Operation Cancelled by Host	被主机取消的操作	主机向控制器发出的且仍未完成的请求已成功取消
0x45	Packet Too Long	数据包太长	数据包长度超过允许的最大长度
0x46	Too Late	太晚	操作执行时间已过
0x47	Too Early	太早	操作执行时间未到
0x48	Insufficient Channels	通道不足	没有足够的通道来执行请求的操作

更多 HCI 错误码请参考 esp_bt_defs.h

BLE 抓包

BLE 广播包和普通连接抓包可以参考下述教程：

Windows 蓝牙抓包教程

抓取 BLE 加密连接的基本步骤与抓取普通连接类似，主要区别在于需要获取并输入连接的 LTK（Long Term Key）。获取 LTK 的方法如下：

1. 对于使用 Bluedroid 协议栈的设备：

   • 在 btsnd_hcic_ble_ltk_req_reply 函数中添加打印语句

2. 对于使用 NimBLE 协议栈的设备：

   • 将NimBLE 的日志等级设置为 DEBUG，然后重新编译固件

获取 LTK 后，在抓包工具中配置相应的 LTK 即可解密和查看加密连接的数据包。