From Gentoo Wiki
Jump to:navigation Jump to:search

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


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



In most cases enabling RFCOMM (CONFIG_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.

KERNEL Enabling Bluetooth support
[*] Networking support --->
      <M>   Bluetooth subsystem support --->
              [*]   Bluetooth Classic (BR/EDR) features
              <*>     RFCOMM protocol support
              [ ]       RFCOMM TTY support
              < >     BNEP protocol support
              [ ]       Multicast filter support
              [ ]       Protocol filter support
              <*>     HIDP protocol support
              [*]     Bluetooth High Speed (HS) features
              [*]   Bluetooth Low Energy (LE) features
                    Bluetooth device drivers --->
                      <M> HCI USB driver
                      <M> HCI UART driver
      <*>   RF switch subsystem support --->
    Device Drivers --->
          HID support --->
            <*>   User-space I/O driver support for HID subsystem


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 only available from the manufacturer.

root #emerge --ask --noreplace sys-kernel/linux-firmware

USE flags

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

USE flags for net-wireless/bluez Bluetooth Tools and System Daemons for Linux

btpclient Enable BTP client
cups Add support for CUPS (Common Unix Printing System)
debug Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see
deprecated Build deprecated plugins
doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
experimental Build experimental plugins
extra-tools Install tools that upstream doesn't install on purpose by default. All this tools shouldn't be used. Then, please notify upstream about you still need them to let them know the situation.
mesh Add support for Bluetooth Mesh control application and advertising bearer.
midi Enable MIDI support
obex Enable OBEX transfer support
readline Enable support for libreadline, a GNU line-editing library that almost everyone wants
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
systemd Enable use of systemd-specific libraries and features like socket activation or session tracking
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
test-programs Install tools for testing of various Bluetooth functions
udev Enable virtual/udev integration (device discovery, power and storage device support, etc)

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

FILE /etc/portage/make.conf


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

root #emerge --ask --changed-use --deep @world

Install BlueZ:

root #emerge --ask --noreplace net-wireless/bluez



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



Start bluetooth:

root #rc-service bluetooth start

Start bluetooth at boot:

root #rc-update add bluetooth default


Start bluetooth:

root #systemctl start bluetooth

Start bluetooth at boot:

root #systemctl enable bluetooth


Controller setup

Display controller information:

hciconfig and other utilities are only available if net-wireless/bluez is installed with the deprecated USE flag enabled.
root #hciconfig -a
hci0:   Type: BR/EDR  Bus: USB
        BD Address: 00:02:72:2F:A9:33  ACL MTU: 1021:8  SCO MTU: 64:1
        RX bytes:1166 acl:0 sco:0 events:43 errors:0
        TX bytes:960 acl:0 sco:0 commands:43 errors:0
        Features: 0xbf 0xfe 0xcf 0xfe 0xdb 0xff 0x7b 0x87
        Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3 
        Link policy: RSWITCH SNIFF 
        Link mode: SLAVE ACCEPT 
        Name: 'BlueZ 5.21'
        Class: 0x000104
        Service Classes: Unspecified
        Device Class: Computer, Desktop workstation
        HCI Version: 4.0 (0x6)  Revision: 0x1000
        LMP Version: 4.0 (0x6)  Subversion: 0x220e
        Manufacturer: Broadcom Corporation (15)

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

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

root #hciconfig hci0 up
When attempting to enable the controller, the following message may be displayed: Can't init device hci0: Operation not possible due to RF-kill

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

root #rfkill list bluetooth
0: hci0: Bluetooth
        Soft blocked: no
        Hard blocked: no

rfkill is provided by >=sys-apps/util-linux-2.31. It can also be installed by the unmaintained net-wireless/rfkill package.

If Bluetooth is blocked or disabled in the BIOS/UEFI, rfkill may incorrectly list the controller as Hard blocked: no.

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

root #rfkill unblock bluetooth

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:

FILE /etc/bluetooth/main.conf

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:

FILE /etc/udev/rules.d/10-local-powersave.rules
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. Paring 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 or net-wireless/blueberry.

Previously paired devices will need to be paired again when upgrading from BlueZ 4.

Start bluetoothctl:

user $bluetoothctl

List the available controllers:


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

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:


Pair with the device:

[bluetooth]#pair device_mac_address

Enter the PIN if prompted:

[agent]PIN code: ####

Allow the service authorization if requested:

[agent]Authorize service service_uuid (yes/no): yes

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:


Disable Bluetooth

To disable Bluetooth at runtime, run the following command:

root #rfkill block bluetooth

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:

FILE /etc/udev/rules.d/80-disable-bluetooth.rules
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:

FILE /etc/local.d/disable-bluetooth.start
rfkill block bluetooth
root #chmod o+x /etc/local.d/disable-bluetooth.start

Disable Bluetooth at kernel level

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

FILE /etc/modprobe.d/blacklist-bluetooth.conf
blacklist bnep
blacklist bluetooth
blacklist btusb


TLP and laptop_mode

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

See also