quick-docs/modules/ROOT/pages/troubleshooting-bluetooth-problems.adoc

= Troubleshooting Bluetooth problems
Dzickus; Hhlp; Devurandom
:revnumber: 37,38
:revdate: 2023-09-04 
:category: Troubleshooting 
:tags: How-to, Bluetooth

//:page-aliases:


Bluetooth is a short range wireless protocol that is used to connect to various low bandwidth I/O devices (like keyboards, mice, headsets).  Newer versions have a low-energy mode with a slightly higher bandwidth and range.

The Bluetooth solution is composed of a userspace daemon, bluetoothd, that communicates through a management port in the kernel to the hardware drivers.  Applications that want to communicate with the bluetoothd daemon do so over a d-bus api.  This includes the various GNOME bluetooth applets.


== Identifying Bluetooth Problems

=== Was the bluetooth hardware found?

* make sure bluetooth was found and enabled (note hci0: and 'UP RUNNING'):
+
[source,]
----
$ hciconfig
hci0:	Type: Primary  Bus: USB
	BD Address: xx:xx:xx:xx:xx:xx  ACL MTU: 1021:4  SCO MTU: 96:6
	UP RUNNING PSCAN 
	RX bytes:15047 acl:0 sco:0 events:2433 errors:0
	TX bytes:599323 acl:0 sco:0 commands:2431 errors:0
----

* If the command returns nothing (no hci: info), then there is a hardware issue
+
[source,]
----
$ lsusb -v | grep Bluetooth | grep DeviceProtocol
bDeviceProtocol         1 Bluetooth
----

* If the lsusb command returns nothing, there is no hardware, a dmesg output would be needed 

* If the lsusb commands returns Bluetooth, then check for attached driver
+
[source,]
----
$ lsusb -t | grep Wireless
    |__ Port 4: Dev 4, If 1, Class=Wireless, Driver=btusb, 12M
    |__ Port 4: Dev 4, If 0, Class=Wireless, Driver=btusb, 12M
----

* If Driver is empty, `lsusb -v` output would be needed to add ids

* If hciconfig shows output but not UP
+
[source,]
----
$ hciconfig up
----

* List of paired devices:
+
[source,]
----
$ bluetoothctl
[bluetooth]# show
[bluetooth]# devices
[bluetooth]# info <mac addr of any device you have problems with>
----

=== Is the bluetoothd daemon running? 

* Verify under systemd bluetooth is 'Active' and 'enabled'
+
[source,bash]
----
$ systemctl status bluetooth
● bluetooth.service - Bluetooth service
   Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; enabled; vendor preset: enabled)
   Active: active (running) since Wed 2017-10-04 16:07:40 EDT; 1 day 22h ago
     Docs: man:bluetoothd(8)
 Main PID: 27427 (bluetoothd)
   Status: "Running"
    Tasks: 1 (limit: 4915)
   CGroup: /system.slice/bluetooth.service
           └─27427 /usr/libexec/bluetooth/bluetoothd
----

* Verify obex is configured to run (to transfer files from phone)
+
[source,bash]
----
$ systemctl --global --user is-enabled obex
enabled
----

== Simple debugging 

Most bluetooth problems happen in the bluez package (bluetoothd), ie the userspace daemon.

* Enabling bluetoothd debugging
+
[source,bash]
----
$ \<edit\> /usr/lib/systemd/system/bluetooth.service
\<add '-d' to ExecStart line as option to bluetoothd\>
\<save and quit\>
$ systemctl daemon-reload
$ systemctl restart bluetooth
----
+
Debugging is enabled and can help pinpoint where some of the bluetooth problems are

* Capture the logs to put in bugzilla report
+
[source,bash]
----
$ journalctl -r -u bluetooth > /tmp/bluetoothd.out
----


== Resolving firmware problems

It happens that the firmware of bluetooth adapters enters a state where it is unable to pair with a certain (or all) bluetooth devices.  You might be able to resolve such problems by resetting your adapter.

In the case of a laptop with a built-in bluetooth adapter this might be achieved by:


1. Enter the laptop's firmware settings (BIOS) and disable the built-in adapter
2. Save settings and restart the laptop
3. Enter the firmware settings a second time and enable the bluetooth adapter again
4. Save and restart
5. Now try to pair the device again