This page is part of the debugging series — pages with debugging details for a variety of Ubuntu packages. |
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
- List the exact manufacturers, and model numbers of all devices involved.
- Which Bluetooth version do all involved devices support
The bluez version of your Ubuntu based device:
bluetoothctl --version
Bluetooth adapter information:
hciconfig -a
List of paired devices:
bluetoothctl [bluetooth]# show [bluetooth]# devices [bluetooth]# info <mac addr of any device you have problems with>
Post the results of the following terminal command:
rfkill list
- 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:
Log file |
What it contains |
syslog |
The bluetooth daemon (bluetoothd), pulseaudio and ofono daemons output their verbose logging to syslog when enabled. It is the source of the state of the Bluetooth stack and other involved components used to understand what has happened on the Bluetooth stack level. |
ubuntu-system-settings-log |
The Ubuntu System Settings on the Ubuntu Touch devices (phone, tablet) logs here. It is useful for knowing what is happening on the level above the Bluetooth stack itself. |
dbus.log |
DBus is the IPC communication layer between the Ubuntu System Settings and the Bluetooth stack. DBus saves its debug information to this log file which can be useful to tell if both of the parties are able to communicate. |
HCI trace |
In general the term “HCI trace” refers to the sniffed communication between the Bluetooth host (which means the software stack) and the Bluetooth controller (which means the chip). It contains the full communication between these two and thus can be used to retrace the exact chain of commands / events. In many cases, it is extremely helpful. However, reading and understanding the trace requires Bluetooth knowledge. |
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:
daemon |
role |
bluetoothd |
This is the Bluetooth daemon (i.e. the stack). It provides the core operations (search for devices, pair, etc.) and Bluetooth profiles such as A2DP (music streaming), HID (human interface devices), etc. and exposes a DBus API for the applications to talk to it. |
pulseaudio |
PulseAudio is the sound server and bluetoothd uses it to correctly route the audio streams so that the music finds its way to the Bluetooth-connected headset rather than through the speakers (unless selected explicitly to do so). In general every Bluetooth-connected headset appears to PulseAudio as an independent sound card and is managed by it as any other sound card. |
ofonod |
oFono is responsible for the mobile telephony part andbluetoothd uses it to place and answer phone calls. It is not, however, involved in call audio (the HFP audio) at all as this is usually routed, for efficiency, through PCM and completely bypasses the Bluetooth software stack. |
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
Enable verbose logging for bluetoothd:
sudo sed -i 's/bluetoothd/bluetoothd \-d/g' /lib/systemd/system/bluetooth.service
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)
- Log in to the device using adb (must enable developer mode in the settings) or ssh:
$ adb shell
- Mount the system partition read / write (it is read only by default):
sudo mount -o remount,rw /
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
- Enable verbose logging for pulseaudio:
sudo sed -i 's/--start/--start --log-level=debug/g' /usr/share/upstart/sessions/pulseaudio.conf
- 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.