Problem Quick Check

[中文]

Information Needed for Problem Reporting

When encountering a problem, please first collect the following information:

• The chip being used

• IDF version

• The protocol stack being used

• Complete logs

• The time and frequency of the problem occurrence

• The operation steps when the problem occurred

If the product is still in the development stage, it is recommended to upgrade to the latest TAG version of the current release.

NimBLE Error Codes

NimBLE error codes are divided into the following categories:

NimBLE Error Code Types

Error Type	Description	Error Return Values from Different Layers
NimBLE Core	Error codes defined by NimBLE itself
ATT	Attribute protocol layer error codes	0x100+(X)
HCI	Host Controller Interface layer error codes	0x200+(X)
L2CAP	Logical Link Control and Adaptation Layer Protocol error codes	0x300+(X)
Security manager (us)	Security management layer error codes (local device)	0x400+(X)
Security manager (peer)	Security management layer error codes (remote device)	0x500+(X)
Hardware errors	Hardware layer error codes	0x600+(X)

Where X represents the specific error type number. For example, if 0x102 is returned, it means the ATT layer error code 0x02. If the returned error code is in decimal, it needs to be converted to hexadecimal. Then check the corresponding error type.

For specific error codes, please refer to ble_hs.h

HCI Error Codes

HCI error codes are error codes returned by the Bluetooth Host Controller Interface (HCI) layer, indicating the specific reason for the operation failure. The following are common HCI error codes and their descriptions:

Common HCI Error Codes

Error Code	English Description	Description	Possible Causes
0x00	Success	Success	Operation successfully completed
0x01	Unknown HCI Command	Unknown HCI command	The controller does not understand the operation code of the HCI command packet sent by the host
0x02	Unknown Connection Identifier	Unknown connection identifier	The connection specified in the command does not exist or the connection type is incorrect
0x03	Hardware Failure	Hardware failure	A failure occurred in the controller that cannot be described by other error codes
0x05	Authentication Failure	Authentication failure	Pairing or authentication process failed, possibly due to incorrect password or link key
0x08	Connection Timeout	Connection timeout	Link supervision timeout or broadcast synchronization timeout
0x0B	Connection Already Exists	Connection already exists	Attempt to create a new connection to a device that is already connected
0x0C	Command Disallowed	Command disallowed	The controller cannot handle the command in its current state
0x0D	Connection Rejected due to Limited Resources	Limited resources	Connection rejected due to insufficient controller resources
0x0E	Connection Rejected Due To Security Reasons	Security reasons	Connection rejected due to unmet security requirements (such as authentication or pairing)
0x11	Unsupported Feature or Parameter Value	Unsupported feature or parameter value	The feature or parameter value in the HCI command is not supported
0x12	Invalid HCI Command Parameters	Invalid HCI command parameters	At least one HCI command parameter is invalid
0x13	Remote User Terminated Connection	Remote user terminated connection	The user on the remote device terminated the connection or stopped broadcasting
0x16	Connection Terminated By Local Host	Local host terminated connection	The local device terminated the connection, synchronization, or broadcast
0x1E	Invalid LMP Parameters / Invalid LL Parameters	Invalid LMP parameters/LL parameters	LMP PDU or LL control PDU parameters are invalid
0x1F	Unspecified Error	Unspecified error	No other suitable error codes
0x22	LMP Response Timeout / LL Response Timeout	LMP response timeout/LL response timeout	LMP or LL transaction did not respond within the timeout period
0x2F	Insufficient Security	Insufficient security	The command or PDU needs to be executed on an encrypted link
0x3B	Unacceptable Connection Parameters	Unacceptable connection parameters	The remote device terminated the connection due to unacceptable connection parameters
0x3C	Advertising Timeout	Advertising timeout	Fixed time broadcasting completed or directed broadcasting did not establish a connection
0x3D	Connection Terminated due to MIC Failure	MIC failure	Connection terminated due to message integrity check failure
0x3E	Connection Failed to be Established / Synchronization Timeout	Connection failed to be established/Synchronization timeout	Connection establishment failed or failed to synchronize with periodic broadcasting
0x3F	MAC Connection Failed	MAC connection failed	MAC layer failed during the connection establishment process
0x40	Coarse Clock Adjustment Rejected but Will Try to Adjust Using Clock Dragging	Coarse clock adjustment rejected, but will try using clock dragging	Unable to coarsely adjust the clock with the provided parameters, will try using clock dragging
0x41	Type0 Submap Not Defined	Type 0 submap not defined	LMP PDU was rejected because the type 0 submap is currently not defined
0x42	Unknown Advertising Identifier	Unknown advertising identifier	The broadcast or synchronization handle specified in the command does not exist
0x43	Limit Reached	达到限制	The number of requested operations has been reached, activity has been completed
0x44	Operation Cancelled by Host	Operation cancelled by the host	The request issued by the host to the controller that has not yet been completed has been successfully cancelled
0x45	Packet Too Long	Packet is too long	The length of the packet exceeds the maximum allowed length
0x46	Too Late	Too late	The operation execution time has passed
0x47	Too Early	Too early	The operation execution time has not yet arrived
0x48	Insufficient Channels	Insufficient channels	There are not enough channels to perform the requested operation

For more HCI error codes, please refer to esp_bt_defs.h

BLE Packet Capture

For capturing BLE broadcast packets and regular connection packets, you can refer to the following tutorial:

Windows Bluetooth Packet Capture Tutorial

The basic steps for capturing encrypted BLE connections are similar to capturing regular connections, with the main difference being the need to obtain and input the LTK (Long Term Key) of the connection. The method to obtain the LTK is as follows:

1. For devices using the Bluedroid protocol stack:

   • Add a print statement in the btsnd_hcic_ble_ltk_req_reply function

2. For devices using the NimBLE protocol stack:

   • Set the log level of NimBLE to DEBUG, then recompile the firmware

After obtaining the LTK, configure the corresponding LTK in the packet capture tool to decrypt and view the data packets of the encrypted connection.