Bluetooth

This article describes the configuration and usage of Bluetooth controllers and devices.

Prerequisites

This article assumes that udev and USB have been previously configured.

Installation

Kernel

In most cases enabling RFCOMM (CONFIG_BT_RFCOMM), HIDP (CONFIG_BT_HIDP), HCI USB (CONFIG_BT_HCIBTUSB) and/or HCI UART (CONFIG_BT_HCIUART) should be sufficient. The User-space I/O driver for HID input devices (CONFIG_UHID) should be enabled for Bluetooth keyboards and mice. CONFIG_INPUT_UINPUT is used also in some rare devices (^[1] ).

 Networking support Search for <code>CONFIG_NET</code> to find this item. --->
 [*] Bluetooth subsystem support Search for <code>CONFIG_BT</code> to find this item. --->
 [*] Bluetooth Classic (BR/EDR) features Search for <code>CONFIG_BT_BREDR</code> to find this item.
 <*> RFCOMM protocol support Search for <code>CONFIG_BT_RFCOMM</code> to find this item.
 [ ] RFCOMM TTY support Search for <code>CONFIG_BT_RFCOMM_TTY</code> to find this item.
 < > BNEP protocol support Search for <code>CONFIG_BT_BNEP</code> to find this item.
 [ ] Multicast filter support Search for <code>CONFIG_BT_BNEP_MC_FILTER</code> to find this item.
 [ ] Protocol filter support Search for <code>CONFIG_BT_BNEP_PROTO_FILTER</code> to find this item.
 <*> HIDP protocol support Search for <code>CONFIG_BT_HIDP</code> to find this item.
 [*] Bluetooth Low Energy (LE) features Search for <code>CONFIG_BT_LE</code> to find this item.
 Bluetooth device drivers --->
 <M> HCI USB driver Search for <code>CONFIG_BT_HCIBTUSB</code> to find this item.
 [*] Enable USB autosuspend for Bluetooth USB devices by default Search for <code>CONFIG_BT_HCIBTUSB_AUTOSUSPEND</code> to find this item.
 <M> HCI UART driver Search for <code>CONFIG_BT_HCIUART</code> to find this item.
 <*> RF switch subsystem support Search for <code>CONFIG_RFKILL</code> to find this item. --->
 Device Drivers --->
 Input device support --->
 [*] Miscellaneous devices Search for <code>CONFIG_INPUT_MISC</code> to find this item. --->
 [*] User level driver support Search for <code>CONFIG_INPUT_UINPUT</code> to find this item.
 [*] HID bus support Search for <code>CONFIG_HID_SUPPORT</code> to find this item. --->
 [*] User-space I/O driver support for HID subsystem Search for <code>CONFIG_UHID</code> to find this item.

Firmware

Most Bluetooth controllers need firmware to function. If the controller is supported by Linux, dmesg will usually indicate if firmware is needed. The sys-kernel/linux-firmware package should provide the needed firmware, although some devices may need firmware that is available in another package or obtainable only from the manufacturer.

USE flags

BlueZ is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the net-wireless/bluez package.

Bluetooth support can be enabled system-wide by setting the USE variable to bluetooth:

USE="bluetooth"

Alternatively, support can be enabled individually on important packages, for example, PulseAudio and PipeWire sound servers.

Emerge

The system needs to be updated if the USE variable was set to bluetooth:

Install BlueZ:

Configuration

Permissions

Permissions for Bluetooth devices is handled automatically by D-Bus, and access is granted to all users by default.

Services

OpenRC

Start bluetooth:

Start bluetooth at boot:

systemd

Start bluetooth:

Start bluetooth at boot:

Enabling experimental mode

Enable experimental mode:

[General]
Experimental=true

Restart bluetooth to apply the configuration changes:

Usage

Battery level

Bluez has a feature to report a device's battery level to upower. Upower should know the battery level of every device which supports sending its own battery level.

will dump all information of connected devices including battery details.

The D-Bus property can also be fetched directly via

or^[3]

Alternatively

will show the battery percentage of connected devices.

Controller setup

If, after following the steps described in the "Installation" and "Configuration" sections above, Bluetooth doesn't appear to be working, or an attempt to enable the controller results in a message such as:

Can't init device hci0: Operation not possible due to RF-kill

query the state of the Bluetooth radio transmitter with rfkill(8) :

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

rfkill is provided by util-linux.

Unblock the controller if rfkill indicates (with Soft blocked: yes) that the controller is blocked:

If rfkill indicates (with Hard blocked: yes) that the controller is blocked, unblock the controller by physical switch or keyboard function key.

Bluetooth controllers can be enabled automatically by setting AutoEnable=true in /etc/bluetooth/main.conf:

[Policy]
AutoEnable=true

In some instances Bluetooth controllers may have been soft-blocked by power management tools in udev. Make sure state is set to 1 in the corresponding rule file, or remove the following line entirely:

SUBSYSTEM=="rfkill", ATTR{type}=="bluetooth", ATTR{state}="1"

Device pairing

Bluetooth devices need to be paired with a Bluetooth controller before they can be used. This is done by entering a PIN (or other code) on both devices via an interaction agent. Certain devices such as headsets do not allow entering an arbitrary PIN. These devices use a static PIN, which is usually 0000, 1111, 1234 or 9999. There are also devices (e.g. Sony BD Remote Control) that do not require PIN entry, and attempting to enter a PIN when prompted will result in failure. Pairing can be skipped with such devices.

This article only covers device pairing with bluetoothctl, which is a command-line interaction agent provided by the net-wireless/bluez package. If a graphical desktop environment is being used, device paring can be done with a graphical interaction agent. For KDE use kde-plasma/bluedevil , for GNOME use net-wireless/gnome-bluetooth , and for GTK use net-wireless/blueman .

Start a bluetoothctl interactive session:

List the available controllers:

Display information about a controller:

Set the default controller:

Power on the controller:

Enable the agent and set it as default:

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

Scan for devices:

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:

Pair with the device:

Enter the PIN if prompted:

In case the pin is not prompted but needed, this command may need to be added before pairing with the device (see this post):

Allow the service authorization if requested:

Trust the device:

Connect to the device:

Display information about the device:

The device is now paired:

hciconfig

For information on hciconfig usage, refer to the Bluetooth/hciconfig page.

Wake from suspend

To enable Bluetooth devices to wake the system from suspend, the USB device corresponding to the controller first needs to be configured to allow triggering wakeup. This can be done with a udev rule.

To configure this for a specific controller, first find the idVendor and idProduct pair. Get the USB device syspath hosting the Bluetooth interface:

/sys/bus/usb/devices/3-10

This will produce multiple paths if multiple Bluetooth controllers are present. Details of each device can be viewed with udevadm info /sys/bus/usb/devices/3-10.

Get the current state and the ID pair:

disabled # The current value of the power/wakeup attribute
8087 # idVendor
0026 # idProduct

Then create the following udev rule, replacing the idVendor and idProduct values with those from above.

SUBSYSTEM=="usb", ATTRS{idVendor}=="8087", ATTRS{idProduct}=="0026", ACTION=="add", ATTR{power/wakeup}="enabled"

Conversely, a udev rule can be created to match and configure all Bluetooth controller devices:

SUBSYSTEM=="usb", ATTR{bDeviceClass}=="e0", ATTR{bDeviceSubClass}=="01", ACTION=="add", ATTR{power/wakeup}="enabled"

Test that the new rule applies to the USB device:

3-10: /etc/udev/rules.d/10-bluetooth-wake.rules:2 Running in test mode, skipping writing ATTR{/sys/devices/pci0000:00/0000:00:14.0/usb3/3-10/power/wakeup}="enabled".

If successful, trigger the new udev rules:

Each paired Bluetooth device which should be allowed to trigger wake needs to be configured so:

For testing on systemd systems, systemctl suspend will trigger an immediate suspend. The Bluetooth device should then trigger the system to wake up.

Disable Bluetooth

To disable Bluetooth at runtime, run the following command:

To disable Bluetooth automatically on every boot, choose one of the following options:

Using udev to disable Bluetooth

When using UDEV, just install the following rule which will disable Bluetooth:

SUBSYSTEM=="rfkill",ATTR{type}=="bluetooth",ATTR{state}="0"

Using OpenRC to disable Bluetooth

When using sys-apps/openrc , install the following script for local service and ensure it is executable:

#!/bin/sh
rfkillblockbluetooth

Disable Bluetooth at kernel level

When the kernel has modular Bluetooth support, disable loading of Bluetooth modules:

blacklist bnep
blacklist bluetooth
blacklist btusb

Utilities

btmon, provided by net-wireless/bluez , provides access to the Bluetooth subsystem monitor infrastructure for reading HCI traces. Refer to the output of btmon --help for usage details.

The net-wireless/bluez-tools package provides a number of utilities, including bt-obex(1) , for Bluetooth file transfers, and bt-network(1) , a Bluetooth network manager.

Troubleshooting

TLP and laptop_mode

If laptop-mode-tools is installed or TLP make sure they're not disabling Bluetooth to save power.

XBOX ONE controller pairing

It's a known issue that XBOX ONE wireless controllers will refuse to pair out of the box on most linux systems. To solve this issue ERTM needs to be disabled.

To disable it manually:

This will disable ERTM only until the system is rebooted. To disable it permanently, install the xpadneo kernel module.

In most cases, this will automatically solve the issue. If it doesn't, add this line into xpadneo config manually:

options bluetooth disable_ertm=Y

Notebook has a Synopsys DesignWare Controller

Bluetooth support for this controller needs also these options in kernel config^[4] :

Device Drivers --->
 Character devices --->
 Serial drivers --->
 [*] 8250/16550 and compatible serial support
 [*] Support for Synopsys DesignWare 8250 quirks

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. Resetting the adapter might solve such problems.

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

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

See also

• Bluetooth headset — describes the configuration of Bluetooth headsets within Gentoo Linux.
• Bluetooth input devices — describes the setup of Bluetooth input devices, for example a bluetooth mouse, on a Linux system.
• Bluetooth Network Aggregation Point — covers the setup of a Bluetooth Network Aggregation Point (NAP) on Gentoo Linux.
• Broadcom Bluetooth — details setup for Broadcom Bluetooth 4.x devices mostly based on BCM20702, BCM4354, and BCM4356 chipsets.

References

• Interfaces
• Networking