Bluetooth
Bluetooth is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. BlueZ is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the bluez package.
This article describes the basic installation of Bluetooth controllers and devices.
Prerequisites
- Set up eudev
Installation
Basic installation requires the Installation of bluez package as follows:
# apk add bluez
Optionally install bluez-deprecated if you need deprecated tools like hcitool
File transfer
To enable bluetooth file transfer, Install the openobex package.
Front-ends
There are several front-ends available:
- The bluez comes with the
bluetoothctlfront-end - blueman: a full-featured Bluetooth manager
- bluedevil: the KDE Bluetooth manager
- bluetuith: simple text-based bluetooth management user interface
- gnome-bluetooth: the GNOME Bluetooth manager
Configuration
Set up the bluetooth hardware first before connecting it to other devices. The steps involved are as follows:
Load the btusb kernel module:
# modprobe btusb
Add user <username> to the lp group:
# adduser <username> lp
Service configuration
It is necessary to set up the bluetooth service before proceeding further.
Use standard start|stop|restart OpenRC command to start the bluetooth service immediately:
# rc-service bluetooth start
Add the bluetooth service to start during every boot:
# rc-update add bluetooth default
Verify the hardware
Now, check the state of the Bluetooth radio transmitter using rfkill:
$ 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:
# rfkill unblock bluetooth
Pairing with bluetoothctl
Begin by starting bluetoothctl and follow these basic steps:
$ 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
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 AutoEnable=false in /etc/bluetooth/main.conf in the [Policy] section:
Contents of /etc/bluetooth/main.conf
Battery Reporting
An experimental feature can be enabled in order to report device battery level:
Contents of /etc/bluetooth/main.conf
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 bluetoothctl 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:
# dmesg | grep -i bluetooth | grep -i firmware
There are many firmware packages available that could likely solve the this problem (see linux-firmware-*).
Another possible solution is to install hidapi and add load the module:
# apk add hidapi # modprobe uhid
It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:
cat <<EOF > /etc/modules-load.d/uhid.conf #Load uhid kernel module: uhid EOF
cat <<EOF > /etc/modules-load.d/btusb.conf #Load btusb kernel module: btusb EOF
The error br-connection-profile-unavailable is sometimes produced when trying to connect a Bluetooth HID device but the uhid 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 uhid kernel module is required for USB HID devices with drivers that are implemented in userspace, when userspace HID support is enabled.
Loading uhid with modprobe after encountering this error does not always fix the problem.
Try setting up uhid to load at boot, and then rebooting:
# 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 /etc/bluetooth/input.conf:
UserspaceHID=false
If running pipewire, you may also try installing 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 /etc/pulse/default.pa:
Contents of /etc/pulse/default.pa
Failed to connect: org.bluez.Error.NotReady br-connection-adapter-not-powered
The error code Failed to connect: org.bluez.Error.NotReady br-connection-adapter-not-powered may appear after resuming from suspend. This error can be resolved by issuing the command:
$ bluetoothctl power on