Bluetooth

2024-10-05T19:20:33Z

Rqpt: Suggest installing pipewire-spa-bluez to solve pairing failure issue - worked for me

{{Draft|work in progress}}

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites and Basic Installation ==

=== Prerequisites ===
{{todo|test bluetooth with [[mdev]]}}

{{Pkg|eudev}} should be installed and setup:

{{Cmd|# setup-devd udev}}

=== Basic Installation ===

Basic installation is as follows:

# Install {{Pkg|bluez}}
#* Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
# Load the <code>btusb</code> kernel module
# Add user to the <code>lp</code> group
# Start and enable the Bluetooth service

{{Cmd|# apk add bluez
# apk add bluez-deprecated
# modprobe btusb
# adduser $USER lp
# rc-service bluetooth start
# rc-update add bluetooth default}}

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:

{{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool:

{{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to restart the Bluetooth service before continuing.}}

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Pairing ==

=== Using <code>bluetoothctl</code> ===

Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# #trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

== Configuration ==

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section:

{{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level:

{{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue:

{{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module:

{{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a Bluetooth HID device but the <code>uhid</code> kernel module is not loaded. HID devices include keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace, when userspace HID support is enabled.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting:

{{Cmd|# cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF
# reboot}}

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>:

{{Cmd|1=UserspaceHID=false}}

If running pipewire, you may also try installing {{Pkg|pipewire-spa-bluez}} to see if that solves the issue.

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}:

{{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

== See Also ==

* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

Alpine Linux - User contributions [en]

Bluetooth