Debug Bluetooth issues - Qualcomm Dragonwing Documentation

To debug Bluetooth issues, use host logs or over-the-air (OTA) logs. Host logs include Logcat and BTSnoop (stack)/HCI logs. You can use these logs for initial debugging. The following table lists the logs required to debug different Bluetooth issues.

Issue type	Logcat	BTSnoop/HCI	Kernel logs	OTA	PipeWire	Subsystem restart (SSR) logs
General	Required	Required	Not required	Recommended	Not required	Not required
Bluetooth controller	Not required	Recommended	Not required	Required	Not required	Required
Bluetooth on/off	Required	Not required	Not required	Not required	Not required	Required
Crash	Required	Not required	Required	Not required	Not required	Required
Audio	Not required	Required	Not required	Required	Required	Not required

Debug BlueZ stack

Before you enable or collect logs, do the following:

Enable SSH to access your host device. For instructions, see Sign in using SSH.
Place the DUT and the remote device in the Bluetooth vicinity.
Run the SSH in command prompt using the following command:
```
ssh root@<device_IP_address>
```
Example If the IP address of the device is 10.92.160.222, run the following command:
```
ssh root@10.92.160.222
```
Connect to the SSH by entering the following password:
```
oelinux123
```

Enable BlueZ logs

To enable BlueZ logs, do the following in SSH:

Enable read and write permissions by running the following command:
```
mount -o remount rw /
```
Open the Bluetooth service file in a text editor. Example To open the bluetooth.service file in a VI editor, run the following command:
```
vi /lib/systemd/system/bluetooth.service
```
Append -d option to the following line in the file:
```
ExecStart=/usr/libexec/bluetooth/bluetoothd -d
```
Save the file.
Reload the Bluetooth daemon by running the following command:
```
systemctl daemon-reload
```
Restart Bluetooth by running the following command:
```
systemctl restart bluetooth
```

Collect BlueZ logs

To collect BlueZ user space logs, run the following command in SSH:
```
journalctl -f -u bluetooth.service > /var/log/bluetooth.log
```
To collect all logs, run the following command in SSH:
```
journalctl -f > /var/log/full.log
```

Collect snoop logs

To collect snoop logs, do the following in SSH:

Run the hcidump tool.

Save the file by running the following command:

hcidump --save-dump=<filename.log>

Example To save the snoop logs to snoop.log file, run the following command:

hcidump --save-dump=/var/log/snoop.log

If the device has multiple HCI interfaces, specify the target interface with the -i option when capturing the snoop log. Run hciconfig first to identify the available interfaces. Sample output

sh-5.2# hciconfig
hci1:   Type: Primary  Bus: USB
        BD Address: 8C:FD:F0:96:54:42  ACL MTU: 1024:7  SCO MTU: 240:8
        UP RUNNING
        RX bytes:5782304 acl:27596 sco:0 events:29481 errors:0
        TX bytes:13229664 acl:18315 sco:0 commands:8760 errors:0

hci0:   Type: Primary  Bus: UART
        BD Address: 00:00:00:00:00:00  ACL MTU: 0:0  SCO MTU: 0:0
        DOWN
        RX bytes:0 acl:0 sco:0 events:0 errors:0
        TX bytes:20 acl:0 sco:0 commands:4 errors:0

To capture the snoop log on hci1, run the following command:

hcidump -i hci1 --save-dump=/var/log/snoop.log

Sample output

sh-5.2# hcidump -i hci1 --save-dump=/var/log/snoop.log
HCI sniffer - Bluetooth packet analyzer ver 5.72
btsnoop version: 1 datalink type: 1002
device: hci1 snap_len: 1500 filter: 0x0

Enable PipeWire logs

To enable PipeWire logs, do the following in SSH:

Open the PipeWire configuration file in a text editor. Example To open the pipewire.conf file in a VI editor, run the following command:
```
vi /usr/share/pipewire/pipewire.conf
```
Uncomment the log level and set it to 4 or 5.
```
#log.level = 4
```
Save the file.
Reload the Bluetooth daemon by running the following command:
```
systemctl daemon-reload
```
Restart PipeWire by running the following command:
```
systemctl restart pipewire
```

Enable WirePlumber service logs

To enable WirePlumber service logs, do the following:

Verify the status of the WirePlumber service by running the following command:
```
systemctl status wireplumber
```
Open the WirePlumber service file in a text editor. Example To open the wireplumber.service file in a VI editor, run the following command:
```
vi /usr/lib/systemd/system/wireplumber.service
```
Add the the following debug variable to all the service sections in the file:
```
Environment=WIREPLUMBER_DEBUG=T
```
Save the file.
Reload the Bluetooth daemon by running the following command:
```
systemctl daemon-reload
```
Restart the WirePlumber service by running the following command:
```
systemctl restart wireplumber
```
Validate the status of the service to verify if it’s running with the specified flags.

Enable logs of ofono service

To enable logs of ofono service, do the following in SSH:

Verify the status of the ofono service by running the following command:

systemctl status ofono

Sample output

sh-5.1# systemctl status ofono
* ofono.service - Telephony service
   Loaded: loaded (/lib/systemd/system/ofono.service; enabled; vendor preset: enabled)
   Active: active (running) since Sun 1980-01-06 00:00:00 UTC; 30min ago
   Main PID: 990 (ofonod)
   Tasks: 1 (limit: 6234)
   Memory: 3.8M
   CGroup: /system.slice/ofono.service
            `- 990 /usr/sbin/ofonod -n

Jan 06 00:00:00 qcm6490 systemd[1]: Started Telephony service.
sh-5.1# |

Open the ofono service file in a text editor. Example To open the ofono.service file in a VI editor, run the following command:
```
vi /lib/systemd/system/ofono.service
```
Append -d option to the following line in the file:
```
ExecStart=/usr/sbin/ofonod -n -d
```
Save the file.
Reload the Bluetooth daemon by running the following command:
```
systemctl daemon-reload
```
Restart the ofono service by running the following command:
```
systemctl restart ofono
```
Validate the status of the service to verify if it’s running with the specified flags.

Collect SSR dump logs

In Qualcomm Linux software, if any Bluetooth subsystem module crashes, the SSR functionality collects the required firmware crash dumps in the Bluetooth driver. It then restarts the Bluetooth subsystem. The crash dump file is at the /var/spool/crash/ directory. Consider the following points about SSR logging:

To verify if SSR logs are enabled or disabled, run the following command:
```
cat /sys/class/devcoredump/disabled
```
Return:
- 1: SSR logging is disabled.
- 0: SSR logging is enabled.
To enable SSR logs, run the following command:
```
echo 0 > /sys/class/devcoredump/disabled
```

To collect SSR logs manually, do the following:

To collect the SSR crash dump manually, ensure that the device Bluetooth is on.

Run the hcitool tool.

Send the crash command to the controller by running the following command:

hcitool cmd 0x3f 0c 26

Sample output

hcitool cmd 0x3f 0c 26
< HCI Command: ogf 0x3f, ocf 0x000c, plen 1
   26
> HCI Event: 0xff plen 246
   01 09 A5 7A 01 02 84 BD 4C 00 00 00 00 7C 0C 01 10 0C 8B 00
   00 00 02 00 61 0C 8B 00 00 0C FC 00 00 AC 08 02 00 B8 04 02
   00 08 08 08 08 09 09 09 09 10 10 10 10 11 11 11 11 04 00 00
   00 80 FF 06 00 CC DE 06 00 67 0C 01 10 4A 0F 01 10 00 00 00
   00 02 00 00 00 A0 E8 DE 06 00 0C 8B 00 00 0C FC 00 00 AC 08
   02 00 84 16 02 00 3F 42 01 10 04 00 00 00 06 00 00 00 0C 8B
   00 00 0C FC 00 00 3F 00 00 00 BD AE 02 00 04 00 00 00 FF FF
   00 00 0C 8B 00 00 0C FC 00 00 3F 00 00 00 B1 BB 0D 10 90 FD
   01 00 90 2B 01 00 10 36 01 00 4C 09 02 00 90 FD 01 00 15 C6
   0D 10 90 2B 01 00 49 E2 02 10 00 00 00 00 00 00 00 10 35 D5
   A5 2D 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02
   02 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02
   02 02 02 02 02 02

The crash triggered generates a BIN file at the /var/spool/crash/ directory. Sample output

ls -l /var/spool/crash/
total 904
-r--------. 1 root root 458888 Jan  1 00:53 hci0_1970-01-01_00-53-36.bin
-r--------. 1 root root 458888 Jan  1 00:58 hci0_1970-01-01_00-58-18.bin

Ensure that the BIN file is generated at the /var/spool/crash/ directory.

A userspace dump collection tool isn’t installed by default. Install or configure a tool (for example, systemd-coredump or kdump-tools) to save the dump to /var/spool/crash/.If you observe any timeout or Bluetooth hardware error, contact Qualcomm and share the BIN file.

SSR limitation on IQ-9075 and IQ-8275On IQ-9075 and IQ-8275 platforms, SSR has a known limitation: If the crash is caused by corrupted RAM patch data in memory, SSR alone can’t fully recover the Bluetooth subsystem. A platform reboot is required to restore normal operation.

​Debug BlueZ stack

​Enable BlueZ logs

​Collect BlueZ logs

​Collect snoop logs

​Enable PipeWire logs

​Enable WirePlumber service logs

​Enable logs of ofono service

​Collect SSR dump logs

Debug BlueZ stack

Enable BlueZ logs

Collect BlueZ logs

Collect snoop logs

Enable PipeWire logs

Enable WirePlumber service logs

Enable logs of ofono service

Collect SSR dump logs