Debug Bluetooth issues

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.

​

Debug BlueZ stack

Before you enable or collect logs, do the following:

1. Enable SSH to access your host device. For instructions, see Sign in using SSH.
2. Place the DUT and the remote device in the Bluetooth vicinity.
3. 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
   
4. Connect to the SSH by entering the following password:
   oelinux123
   

​

Enable BlueZ logs

To enable BlueZ logs, do the following in SSH:

1. Enable read and write permissions by running the following command:
   mount -o remount rw /
   
2. 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
   
3. Append -d option to the following line in the file:
   ExecStart=/usr/libexec/bluetooth/bluetoothd -d
   
4. Save the file.
5. Reload the Bluetooth daemon by running the following command:
   systemctl daemon-reload
   
6. 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:

1. Run the hcidump tool.
2. 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:

1. 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
   
2. Uncomment the log level and set it to 4 or 5.
   #log.level = 4
   
3. Save the file.
4. Reload the Bluetooth daemon by running the following command:
   systemctl daemon-reload
   
5. Restart PipeWire by running the following command:
   systemctl restart pipewire
   

​

Enable WirePlumber service logs

To enable WirePlumber service logs, do the following:

1. Verify the status of the WirePlumber service by running the following command:
   systemctl status wireplumber
   
2. 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
   
3. Add the the following debug variable to all the service sections in the file:
   Environment=WIREPLUMBER_DEBUG=T
   
4. Save the file.
5. Reload the Bluetooth daemon by running the following command:
   systemctl daemon-reload
   
6. Restart the WirePlumber service by running the following command:
   systemctl restart wireplumber
   
7. 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:

1. 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# |
   
2. 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
   
3. Append -d option to the following line in the file:
   ExecStart=/usr/sbin/ofonod -n -d
   
4. Save the file.
5. Reload the Bluetooth daemon by running the following command:
   systemctl daemon-reload
   
6. Restart the ofono service by running the following command:
   systemctl restart ofono
   
7. 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.
  1. Run the hcitool tool.
  2. 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
     
  3. Ensure that the BIN file is generated at the /var/spool/crash/ directory.