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.

Kernel
In most cases enabling RFCOMM, HIDP, HCI USB and/or HCI UART should be sufficient.

It is also a good idea to enable the UHID (Userspace Human Interface Device) driver for some bluetooth keyboards and mice to work.

Tallying up the options: CONFIG_BT, BT_BREDR , CONFIG_BT_RFCOMM , CONFIG_BT_HIDP , BT_LE , CONFIG_BT_HCIBTUSB , CONFIG_BT_HCIUART , CONFIG_RFKILL , CONFIG_UHID

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
Portage will by default install BlueZ 5. If the deprecated BlueZ 4 is required, mask BlueZ 5 to prevent it from being installed:

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

Install BlueZ:

Permissions
Permissions for Bluetooth devices will be handled automatically if the USE variable is set to, and ConsoleKit or systemd is being used.

Alternatively, adding a user to the group will allow that user to access Bluetooth devices:

OpenRC
Start bluetooth:

Start bluetooth at boot:

systemd
Start bluetooth:

Start bluetooth at boot:

Controller setup
Display controller information:

Where  is the name of the controller, and   indicates that the controller is enabled.

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

When attempting to enable the controller, the following message may be displayed:

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

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.

With BlueZ 4, the following udev rule will enable a controller before a graphical desktop environment is up and running:

With BlueZ 5, the controller will enable the controller automatically if you edit /etc/bluetooth/main.conf to uncomment/include:

It's important that the BlueZ 4 udev rule is not used, as it will disable some security features with BlueZ 5 if left as is, rendering devices that uses Bluetooth 4.0 features non-pairable.

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

This article only covers device pairing with a command-line interaction agent. If a graphical desktop environment is being used, device paring can be done with a graphical interaction agent. For KDE use, for GNOME use and for GTK+ use.

BlueZ 5
Device paring is done with, which is provided by the package.

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:

Allow the service authorization if requested:

Trust the device:

Connect to the device:

Display information about the device:

The device is now paired:

BlueZ 4
Device paring, which is done with, requires the USE flag  to be enabled for the  package.

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:

Where  is the MAC address of the device.

Pair with the device:

Enter a and press. Now enter the same on the device.

When attempting to pair with the device, the following message may be displayed if a graphical interaction agent is installed.

In this case, stop or disable the graphical interaction agent and attempt to pair with the device again.

Query the trust status of the device:

Where  indicates that the device is not trusted, and   would indicate that the device is trusted:

Trust the device so it can connect automatically:

Connect to the device. This only needs to be done once if the device is trusted:

The device is now paired.

External resources

 * Bluetooth for mobile phones