docs: add Bluetooth troubleshooting guide with detection-stage caveats
This patch adds a new Bluetooth troubleshooting section to the Quick Docs sound troubleshooting article. It covers three key stages: - Device detection - Pairing - Profile switching The 'Device detection' section includes realistic notes about hardware incompatibility and unsupported devices, based on common Fedora user reports. Helps reduce confusion caused by generic forum suggestions when devices are never detected (no MAC address visible), which may not be solvable at the user level.
This commit is contained in:
parent
9b09ccd83d
commit
5668148239
1 changed files with 135 additions and 1 deletions
|
|
@ -220,8 +220,142 @@ Then reboot your system.
|
|||
|
||||
If you're using an external microphone, try reconnecting it or testing with a different device to rule out hardware issues.
|
||||
|
||||
== Diagnosing and Fixing Bluetooth Audio Problems
|
||||
|
||||
== Debugging options
|
||||
Bluetooth audio issues can often be categorized into one of three stages: device detection, pairing, or audio profile switching. This section provides a structured guide for identifying the stage where the issue occurs and how to resolve it.
|
||||
|
||||
Symptoms::
|
||||
|
||||
* Bluetooth audio device does not appear in `bluetoothctl` or GNOME Settings.
|
||||
* No MAC address shown even while device is in pairing mode.
|
||||
* `btmon` shows no HCI events.
|
||||
|
||||
This usually means the Linux Bluetooth stack never received an advertisement packet from the device. Common causes include:
|
||||
|
||||
- The Bluetooth adapter (HCI device) is not fully initialized or supported.
|
||||
- The device uses a newer Bluetooth version or chipset that requires kernel or firmware support not yet available.
|
||||
- The device requires special vendor-specific commands for pairing (common in Sony, Bose, etc.).
|
||||
- Signal interference or range issues (less likely if other devices are detected).
|
||||
|
||||
Check::
|
||||
|
||||
* Confirm HCI device status:
|
||||
+
|
||||
----
|
||||
hciconfig
|
||||
btmon
|
||||
lsusb | grep Bluetooth
|
||||
----
|
||||
|
||||
* Use `btmon` and watch for *LE Advertising Report* or *Inquiry Result* events. Absence of these while the device is in pairing mode strongly suggests a low-level compatibility issue.
|
||||
|
||||
Caution::
|
||||
|
||||
Some Bluetooth devices—especially newer models using Bluetooth 5.2+—may not be fully compatible with Linux unless the kernel and BlueZ stack support their advertisement mode and codec negotiation.
|
||||
|
||||
NOTE: If the device never appears in scans (no MAC shown), this is often **not solvable by user-level configuration or re-pairing**, and may indicate hardware or firmware-level incompatibility.
|
||||
|
||||
Recommendation::
|
||||
|
||||
- Test the device on other operating systems (Windows, macOS, Android) to confirm functionality.
|
||||
- Search bug trackers (e.g. kernel.org, Fedora Bugzilla, bluez mailing list) for known issues related to the specific device or chipset.
|
||||
- If no workaround exists, consider using another headset known to work well with Linux (some vendors like Jabra, Sennheiser, Logitech have better Linux track records).
|
||||
|
||||
Comment::
|
||||
|
||||
In community forums, it's helpful to distinguish device detection issues from pairing or profile switching problems. While many Bluetooth devices work well under Linux, some may not yet be fully supported due to hardware or firmware limitations. Acknowledging this distinction helps manage expectations and encourages contributions that improve clarity and troubleshooting effectiveness.
|
||||
|
||||
=== Stage 2: Pairing Fails or Is Incomplete
|
||||
|
||||
Symptoms::
|
||||
|
||||
* Device is visible but cannot be paired or consistently fails to connect.
|
||||
* Authorization timeouts or connection errors.
|
||||
|
||||
Check::
|
||||
|
||||
* Use `bluetoothctl` for manual steps:
|
||||
+
|
||||
----
|
||||
bluetoothctl
|
||||
power on
|
||||
agent on
|
||||
default-agent
|
||||
scan on
|
||||
pair <MAC>
|
||||
trust <MAC>
|
||||
connect <MAC>
|
||||
----
|
||||
|
||||
Fix::
|
||||
|
||||
* Remove device and retry pairing:
|
||||
+
|
||||
----
|
||||
bluetoothctl remove <MAC>
|
||||
----
|
||||
|
||||
* Restart Bluetooth service:
|
||||
+
|
||||
----
|
||||
sudo systemctl restart bluetooth
|
||||
----
|
||||
|
||||
* For some devices, make sure to hold the pairing button until rapid blinking starts.
|
||||
|
||||
=== Stage 3: Audio Profile Switching Fails
|
||||
|
||||
Symptoms::
|
||||
|
||||
* Device connects but no sound is played.
|
||||
* Only HSP/HFP is available, A2DP is missing.
|
||||
* Microphone works but stereo audio output does not.
|
||||
|
||||
Check::
|
||||
|
||||
* Confirm PipeWire is used:
|
||||
+
|
||||
----
|
||||
pactl info | grep Server
|
||||
----
|
||||
|
||||
* List available profiles:
|
||||
+
|
||||
----
|
||||
pactl list cards
|
||||
----
|
||||
|
||||
Fix::
|
||||
|
||||
* Manually switch to A2DP profile:
|
||||
+
|
||||
----
|
||||
pactl set-card-profile <card> a2dp-sink
|
||||
----
|
||||
|
||||
* Ensure required packages are installed:
|
||||
+
|
||||
----
|
||||
pipewire-pulse
|
||||
wireplumber
|
||||
bluez
|
||||
----
|
||||
|
||||
* Use `blueman` for profile selection if needed.
|
||||
|
||||
=== Notes
|
||||
|
||||
* Some Bluetooth 5.3+ headsets require newer kernel support.
|
||||
* High-quality codecs (e.g. AAC, aptX) may not be supported by default.
|
||||
* Diagnostic tools:
|
||||
+
|
||||
----
|
||||
btmon
|
||||
bluetoothctl
|
||||
journalctl -xeu bluetooth.service
|
||||
----
|
||||
|
||||
== Pipewire Debugging options
|
||||
|
||||
Debugging usually starts after the bug has been identified, and works best when users are very familiar with the circumstances surrounding the bug.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue