WARNING

If you're going to attach the log files mentioned below, be warned that they might include private information like phone numbers. If you're asked to share such log files, please redact any information you don't feel comfortable sharing and post the results to your bug report.

Reporting the bug on Launchpad

Ubuntu bluetooth bugs are tracked on Launchpad. When filing a report, please ensure one is using apport. For more on this, please see here.

The package to use with apport can be:

• bluez - Issues in the bluetooth protcol stack

• linux - Hardware dependent issues

• Issues could be caused by the desktop environment (GNOME, KDE, etc.), or its Bluetooth applications.
• If any doubts, feel free to file it under bluez and it will be rerouted as applicable.

Once one has reported the bug to Launchpad, it is vital to include the required information that will allow developers to address your issue.

Information required to include in a bug report

1. List the exact manufacturers, and model numbers of all devices involved.
2. Which Bluetooth version do all involved devices support

3. The bluez version of your Ubuntu based device:

   bluetoothctl --version

4. Bluetooth adapter information:

   hciconfig -a

5. List of paired devices:

   bluetoothctl
   [bluetooth]# show
   [bluetooth]# devices
   [bluetooth]# info <mac addr of any device you have problems with>

6. Post the results of the following terminal command:

   rfkill list

7. Necessary bluetooth log files in debug mode as per below

Capturing bluetooth logs files in debug mode

This section will cover the details of capturing the necessary log files to ease debugging of the Bluetooth related issues. It is divided into several sections and at the end of it you will know which log files are important, how to enable more verbose logging for Bluetooth and PulseAudio as well as how to sniff the HCI communication between the Bluetooth stack and the Bluetooth chip. Which log file depends on the device one is using:

On desktop:

• /var/log/syslog

On Ubuntu Touch based devices:

• /var/log/syslog
• /home/phablet/.cache/upstart/application-legacy-ubuntu-system-settings.log
• /home/phablet/.cache/upstart/dbus.log

Additionally:

• HCI trace captured with btmon

The table below summarizes what information these files carry:

Generating log files with debugging information

Under the normal circumstances the system log files just include warning and errors. This is a design decision to not pollute the system with big log files as the “debug logs” are very verbose.

In general, switching on the debugging information is as easy as adding the ‘-d’ switch to the exec line of the daemon for which this mode should be enabled. For Bluetooth there are, in general, three system components (thus daemons) to consider: bluetoothd, pulseaudio and ofonod.

The table below describes their role in detail:

Note that it is only required to enable debugging logs for bluetoothd and enabling it for the rest of these components depends on the issue that is to be debugged. For example the issues with pairing will not require any of them, the problems with music playback will require pulseaudio and problems with telephony will require ofonod and pulseaudio. The rule of thumb is that when you are unsure, enable more than less.

On Ubuntu Desktop

1. Enable verbose logging for bluetoothd:

   sudo sed -i 's/bluetoothd/bluetoothd \-d/g' /etc/init/bluetooth.conf

2. Enable verbose logging for pulseaudio:

   sudo sed -i 's/pulseaudio/pulseaudio \-d/g' /usr/lib/systemd/user/pulseaudio.service

On Ubuntu Touch based device (phone or tablet)

1. Log in to the device using adb (must enable developer mode in the settings) or ssh:

$ adb shell

1. Mount the system partition read / write (it is read only by default):

sudo mount -o remount,rw /

1. Enabling verbose logging for bluetoothd can be done in two ways. First for an already running daemon by sending SIGUSR2 to it. Second by adding the ‘-d’ switch to its exec line. If /etc/init/bluetooth.override exists do the following:

   sudo sed -i 's/exec \/usr\/sbin\/bluetoothd \-c \/etc\/bluetooth\/touch.conf/exec \/usr\/sbin\/bluetoothd \-c \/etc\/bluetooth\/touch.conf -d/g' /etc/init/bluetooth.override

Otherwise:

sudo sed -i 's/exec \/usr\/sbin\/bluetoothd/exec \/usr\/sbin\/bluetoothd -d/g' /etc/init/bluetooth.conf

1. Enable verbose logging for pulseaudio:

sudo sed -i 's/--start/--start --log-level=debug/g' /usr/share/upstart/sessions/pulseaudio.conf

1. Enable verbose logging for ofonod:

sudo sed -i 's/exec ofonod/exec ofonod \-d/g' /etc/init/bluetooth.override

Enable the Ubuntu Touch device automagically

The above steps are automated by the bt-device-enable.sh script available here.

How to use btmon to capture an HCI trace

The HCI trace is a snapshot of the communication between the Bluetooth host (software stack) and the Bluetooth controller (the chip). The ‘btmon’ tool can be used to capture such for both live debugging and saving it for later. Note that the HCI trace needs to be captured at the same time the Bluetooth issue occurs.

The ‘btmon’ executed without any parameters will offer live debugging which will print in a ‘tail -f’ fashion an ongoing exchange of the commands and events between the stack and the chip. It is possible however to make it save the data in the snoop format (https://tools.ietf.org/html/rfc1761) which can later be viewed using for example Wireshark (https://www.wireshark.org).

Live debugging:

sudo btmon

Saving it for later:

sudo btmon --write ~/hcitrace.snoop

Additionally, someone who would like to have a text version available for later too would execute it in a following way:

sudo btmon --write ~/hcitrace.snoop | tee ~/hcitrace.txt

The nice thing about btmon and how it works is that it is possible to have several versions of it executed simultaneously. This allows capturing logs as in the last example in one shell and viewing the live in another.

Script for automatic log collection

The bt-collect-logs.sh script available here: https://github.com/bergotorino/bt-debugging-tools can automatically fetch, pack and pull the logs from the device.

Working with log files

In this section you will read a few tips on how to make reading logs for Bluetooth debugging more productive.

syslog

The first thing to look at is the syslog and while it is a great source of knowledge it contains a lot of noise and usually happens to be long. I try to reboot my device (or check the output from the date command) before I start to capture logs and I do it to have a ‘marker’ in the syslog that I know of. This gives me the possibility to remove everything that has happened before with a single delete and focus only on the following lines.

It is also better to open the syslog file not in gedit because it happens to stall a bit when loading large files. Something like vim is preferable for that along with enabling syntax highlighting for syslog files.

:set filetype syslog

The last thing to do might be to remove the lines other than coming from bluetoothd, pulseaudio and ofonod so that there is less noise and there is no need for much scrolling.

grep ‘bluetoothd\|pulseaudio\|ofonod’ ./syslog > syslog-light

snoop files

Wireshark can open the snoop files and with its powerful abilities to filter out and colorize packets, it is a handy tool. Someone who knows a bit about Bluetooth might benefit a lot just by reading those logs.