Bluetooth

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

Prerequisites
This article assumes that udev, USB and/or PC-Card have been previously configured.

Kernel
Use the table below to determine which Bluetooth options you need to enable. In most cases enabling RFCOMM, HIDP, HCI USB and/or HCI UART should be sufficient.

Software
Bluetooth user space support is provided by. Portage has ebuilds for BlueZ 4 (deprecated) and BlueZ 5.

You can enable Bluetooth support system-wide by adding  to the USE variable.

If you require BlueZ 4 you can mask BlueZ 5 to prevent it from being installed.

If you enabled the  USE flag system-wide you will need to update your system.

Install BlueZ.

Permissions
If you have the  USE flag enabled system-wide and are using ConsoleKit or systemd, permissions for Bluetooth devices will be handled automatically.

An alternative is to add the user you want to be able to access Bluetooth devices to the plugdev group.

Starting
OpenRC
 * Start Bluetooth.


 * Start Bluetooth at boot.

systemd
 * Start Bluetooth.


 * Start Bluetooth at boot.

Controller setup

 * Display Bluetooth controller information.

Where hci0 is the name of the first controller and UP indicates that the controller is enabled.


 * If hciconfig indicates that the controller is disabled with DOWN, you will need to enable the controller.


 * You may receive the following message when attempting to enable the controller.

In this case you will need to query the controllers rfkill state with.


 * If rfkill indicates that the controller is blocked with Soft blocked: yes, you will need to unblock the controller.


 * If rfkill indicates that the controller is blocked with Hard blocked: yes, you will need to unblock the controller by physical switch or keyboard function key.


 * If you need to use trusted Bluetooth devices before a graphical environment is up and running, you can use the following udev rule.

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 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. You can skip the pairing step with these devices.

This article only covers device pairing with a command-line interaction agent. If you have a graphical desktop environment you can perform device paring with a graphical interaction agent. You can use for KDE,  for GNOME and  for GTK+.

BlueZ 4
Device paring which is done with simple-agent, requires that you enable the  USE flag for.


 * 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 00:1F:20:1D:1B:4B is the MAC address of the device.


 * Pair with the device.

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


 * If you have a graphical interaction agent installed (BlueDevil, GNOME Bluetooth etc.), you may receive the following message when attempting to pair with the device.

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


 * Query the trust status of the device.

Where 0 is not trusted and 1 is trusted.


 * Trust the device so it can connect automatically.


 * Connect to the device. If the device is trusted you only need to do this once.


 * The device is now paired.

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


 * Start bluetoothctl.


 * 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.


 * Discover the device MAC address.


 * Pair with the device.


 * If prompted enter the PIN code.


 * If prompted allow the service authorization request.


 * Trust the device.


 * Connect to the device.


 * Display information about the device.


 * The device is now paired.