Bluetooth: Difference between revisions

Latest revision as of 15:57, 19 July 2025

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 bluetoothctl front-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

Note: It may be necessary to restart the Bluetooth service before continuing.

Pairing with `bluetoothctl`

bluetoothctl tool can be run both in interactive and non-interactive mode. The non-interactive commands can be issued from the shell by suffixing bluetoothctl like $ bluetoothctl list or $ bluetoothctl power on.

The example below shows step-by-step procedure to configure a bluetooth adapter in interactive mode. 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

[Policy]
...
AutoEnable=false
...

Battery Reporting

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

Contents of /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 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

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

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

...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect

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

Failed to connect: org.bluez.Error.Failed br-connection-unknown

When trying to connect to a bluetooth speaker, If you receive the following error message

$ bluetoothctl connect 88:C6:26:0A:7D:F1 Attempting to connect to 88:C6:26:0A:7D:F1 Failed to connect: org.bluez.Error.Failed br-connection-unknown

Check the following

$ bluetoothctl info Missing device address argument DeviceSet (null) not available

The above errors may appear after resuming from suspend. In such cases, resolve it by restarting bluetooth service:

$ doas service bluetooth restart

dbus-daemon[2431]: [system] Rejected send message error name="org.bluez.Profile1.Error.NotImplemented"

Jul 19 20:54:59 homepc2 auth.notice dbus-daemon[2431]: [system] Rejected send message, 0 matched rules; type="error", sender=":1.119" (uid=1000 pid=10213 comm="/usr/bin/wireplumber") interface="(unset)" member="(unset)" error name="org.bluez.Profile1.Error.NotImplemented" requested_reply="0" destination=":1.661" (uid=0 pid=11828 comm="/usr/lib/bluetooth/bluetoothd")

To make the above error message in /var/log/message to disappear, enable the following

Contents of /etc/bluethooth/main.conf

[General]
...
# Enables D-Bus experimental interfaces
# Possible values: true or false
Experimental = true
...

@@ Line 1: / Line 1: @@
-{{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 ==
+* Set up [[Include:Setup Device Manager|eudev]]
+== Installation ==
-=== Prerequisites ===
+Basic installation requires the Installation of {{Pkg|bluez}} package as follows:{{Cmd|# apk add {{Pkg|bluez}}}}
-{{todo|test bluetooth with [[mdev]]}}
+Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
+=== File transfer ===
+To enable bluetooth file transfer, [[Install]] the {{Pkg|openobex}} package.
+=== 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
-{{Pkg|eudev}} should be installed and setup:
+== Configuration ==
-{{Cmd|# setup-devd udev}}
+Set up the bluetooth hardware first before connecting it to other devices. The steps involved are as follows:
-=== Basic Installation ===
+Load the <code>btusb</code> kernel module: {{Cmd|# modprobe btusb}}
+Add user <username> to the <code>lp</code> group: {{Cmd|# adduser <username> lp}}
-Basic installation is as follows:
+=== Service configuration ===
-# Install {{Pkg|bluez}}
+It is necessary to set up the {{ic|bluetooth}} service before proceeding further.
-#* 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
+Use standard '''start|stop|restart''' [[OpenRC]] command to start the {{ic|bluetooth}} service immediately: {{Cmd|# rc-service bluetooth start}}
-&#35; apk add bluez-deprecated
+Add the {{ic|bluetooth}} service to start during every boot: {{Cmd|# rc-update add bluetooth default}}
-&#35; modprobe btusb
-&#35; adduser $USER lp
-&#35; rc-service bluetooth start
-&#35; rc-update add bluetooth default}}
-Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:
+=== Verify the hardware ===
-{{Cmd|$ rfkill list bluetooth}}
+Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>: {{Cmd|$ rfkill list bluetooth}}
 It should return something similar to:
@@ Line 41: / Line 51: @@
           Hard blocked: no
-If the device is listed as blocked, it can be unblocked using the same tool:
+If the device is listed as blocked, it can be unblocked using the same tool: {{Cmd|# rfkill unblock bluetooth}}
-{{Cmd|# rfkill unblock bluetooth}}
+{{Note|It may be necessary to [[OpenRC|restart]] the Bluetooth service before continuing.}}
-{{Note|It may be necessary to restart the Bluetooth service before continuing.}}
+=== Pairing with <code>bluetoothctl</code> ===
-=== Front-ends ===
+<code>bluetoothctl</code> tool can be run both in interactive and non-interactive mode. The non-interactive commands can be issued from the shell by suffixing <Code>bluetoothctl</Code> like {{ic|$ bluetoothctl list}} or {{ic|$ bluetoothctl power on}}.
-There are several front-ends available:
+The example below shows step-by-step procedure to configure a bluetooth adapter in interactive mode. Begin by starting <code>bluetoothctl</code> and follow these basic steps:
-* 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}}
@@ Line 115: / Line 113: @@
 Trust the device:
-  <span style="color:blue;">[bluetooth]</span># #trust ''device_mac_address''
+  <span style="color:blue;">[bluetooth]</span># trust ''device_mac_address''
 Connect to the device:
@@ Line 128: / Line 126: @@
   <span style="color:blue;">[bluetooth]</span># 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:
+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]
-{{Cat|/etc/bluetooth/main.conf|[Policy]
 ...
 AutoEnable&#61;false
@@ Line 143: / Line 136: @@
 === Battery Reporting ===
-An experimental feature can be enabled in order to report device battery level:
+An experimental feature can be enabled in order to report device battery level: {{Cat|/etc/bluetooth/main.conf|[General]
-{{Cat|/etc/bluetooth/main.conf|[General]
 ...
 Experimental&#61;true
@@ Line 165: / Line 155: @@
 One possible solution is that you are missing firmware drivers.
-Try running the following command to discover the source of the issue:
+Try running the following command to discover the source of the issue: {{Cmd|# dmesg &#124; grep -i bluetooth &#124; grep -i firmware}}
-{{Cmd|# dmesg &#124; grep -i bluetooth &#124; 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:
+Another possible solution is to install {{Pkg|hidapi}} and add load the module: {{Cmd|# apk add hidapi
-{{Cmd|# apk add hidapi
 &#35; modprobe uhid}}
-It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:
+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
-{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
 &#35;Load uhid kernel module:
 uhid
@@ Line 190: / Line 174: @@
 === "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 when userspace HID support is enabled but the <code>uhid</code> kernel module is not loaded.
+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.
-This includes 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:
+Try setting up <code>uhid</code> to load at boot, and then rebooting: {{Cmd|# cat <<EOF > /etc/modules-load.d/uhid.conf
-{{Cmd|# cat <<EOF > /etc/modules-load.d/uhid.conf
 &#35;Load uhid kernel module:
 uhid
@@ Line 204: / Line 186: @@
 &#35; reboot}}
-The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace.
+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}}
-Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>:
+If running pipewire, you may also try installing {{Pkg|pipewire-spa-bluez}} to see if that solves the issue.
-<code>UserspaceHID=false</code>
 === Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===
@@ Line 216: / Line 196: @@
 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}}:
+Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}: {{Cat|/etc/pulse/default.pa|...
+&#35;##Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
+load-module module-switch-on-connect}}
+=== Failed to connect: org.bluez.Error.NotReady br-connection-adapter-not-powered ===
+The error code <code>Failed to connect: org.bluez.Error.NotReady br-connection-adapter-not-powered</code> may appear after resuming from suspend. This error can be resolved by issuing the command:{{Cmd|$ bluetoothctl power on}}
+=== Failed to connect: org.bluez.Error.Failed br-connection-unknown ===
+When trying to connect to a bluetooth speaker, If you receive the following error message {{Cmd|$ bluetoothctl connect 88:C6:26:0A:7D:F1
+Attempting to connect to 88:C6:26:0A:7D:F1
+Failed to connect: org.bluez.Error.Failed br-connection-unknown}}
+Check the following {{Cmd|<nowiki>$ bluetoothctl info
+Missing device address argument
+DeviceSet (null) not available</nowiki>}}
+The above errors may appear after resuming from suspend. In such cases, resolve it by restarting {{ic|bluetooth}} service: {{Cmd|$ doas service bluetooth restart}}
+=== dbus-daemon[2431]: [system] Rejected send message error name="org.bluez.Profile1.Error.NotImplemented" ===
-{{Cat|/etc/pulse/default.pa|...
+ Jul 19 20:54:59 homepc2 auth.notice dbus-daemon[2431]: [system] Rejected send message, 0 matched rules; type="error", sender=":1.119" (uid=1000 pid=10213 comm="/usr/bin/wireplumber") interface="(unset)" member="(unset)" error name="org.bluez.Profile1.Error.NotImplemented" requested_reply="0" destination=":1.661" (uid=0 pid=11828 comm="/usr/lib/bluetooth/bluetoothd")
-&#35;##Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
-load-module module-switch-on-connect}}
+To make the above error message in {{path|/var/log/message}} to disappear, enable the following {{Cat|/etc/bluethooth/main.conf|<nowiki>
+[General]
+...
+# Enables D-Bus experimental interfaces
+# Possible values: true or false
+Experimental = true
+...
+</nowiki>}}
-== See Also ==
+== See also ==
 * [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
 * [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]