Bluetooth

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

Prerequisites
This article assumes that and  have been previously configured.

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.

Firmware
Most Bluetooth controllers need to function. If the controller is supported by Linux, will usually indicate if firmware is needed. The package should provide the needed firmware, although some devices may need firmware that available in other package or provided only from the manufacturer.

USE flags
BlueZ is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the package.

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

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

Install BlueZ:

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

OpenRC
Start bluetooth:

Start bluetooth at boot:

systemd
Start bluetooth:

Start bluetooth at boot:

Enabling battery reporting
has a feature to report a devices battery level to upower. This feature is currently experimental and not stable. Enable experimental mode:

Restart bluetooth to apply the configuration changes:

Now upower should know the battery level of every device which supports sending its own battery level.

Controller setup
Display controller information:

Where  is the name of the controller, and   (3rd line) indicates that the controller is enabled.

Enable the controller if indicates (with  ) (3rd line) that the controller is disabled:

In this case, query the state of the Bluetooth radio transmitter with :

is provided by >=-2.31. It can also be installed by the unmaintained package.

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

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

Bluetooth controllers can be enabled automatically by setting  in :

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

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, which is a command-line interaction agent provided by the package. If a graphical desktop environment is being used, device paring can be done with a graphical interaction agent. For use, for  use , and for GTK use  or.

Start :

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 if prompted:

In case the pin is not prompted but needed, you may need to add this command 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:

Disable Bluetooth
To disable Bluetooth at runtime, run the following command:

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

hciconfig

 * Open and initialize HCI device::
 * Close HCI device:
 * Reset HCI device:
 * Reset statistic counters:
 * Enable Authentication:
 * Disable Authentication:
 * Enable Encryption:
 * Disable Encryption:
 * Enable Page and Inquiry scan:
 * Disable scan:
 * Enable Inquiry scan:
 * Enable Page scan:
 * Get/Set default packet type:
 * Get/Set default link mode:
 * Get/Set default link policy:
 * Get/Set local name:
 * Get/Set class of device:
 * Get/Set voice setting:
 * Get/Set inquiry access code:
 * Get/Set inquiry transmit power level:
 * Get/Set inquiry mode:
 * Get/Set inquiry data:
 * Get/Set inquiry scan type:
 * Get/Set inquiry scan window and interval:
 * Get/Set page scan window and interval:
 * Get/Set page timeout:
 * Get/Set AFH mode:
 * Get/Set Simple Pairing Mode:
 * Set ACL MTU and number of packets:
 * Set SCO MTU and number of packets:
 * Delete link key from the device:
 * Get local OOB data:
 * Display supported commands:
 * Display device features:
 * Display version information:
 * Display revision information:
 * Add a device to the blacklist:
 * Remove a device from the blacklist:
 * Set LE Random Address:
 * Enable LE advertising:
 * Show all commands device has support for:

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

Using OpenRC to disable Bluetooth
When using, install the following script for local service and ensure it is executable:

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

TLP and laptop_mode
If 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 you need to disable ERTM.

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:

Notebook has a Synopsys DesignWare Controller
Bluetooth support for this controller needs also these options in kernel config :