From Gentoo Wiki
Jump to: navigation, 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, HIDP, HCI USB and/or HCI UART should be sufficient.

[*] Networking support --->
      <*>   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 Low Energy (LE) features
                    Bluetooth device drivers --->
                      <*> HCI USB driver
                      <*> HCI UART driver
      <*>   RF switch subsystem support --->

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

cups Add support for CUPS (Common Unix Printing System) global
debug Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see global
deprecated Build deprecated plugins local
doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally global
experimental Build experimental plugins local
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. local
obex Enable OBEX transfer support. local
readline Enable support for libreadline, a GNU line-editing library that almost everyone wants global
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur global
systemd Enable use of systemd-specific libraries and features like socket activation or session tracking global
test Workaround to pull in packages needed to run with FEATURES=test. Portage-2.1.2 handles this internally, so don't set it in make.conf/package.use anymore global
test-programs Install tools for testing of various Bluetooth functions local
udev Enable virtual/udev integration (device discovery, power and storage device support, etc) global

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

FILE /etc/portage/make.conf


Portage will by default install BlueZ 5. If the deprecated BlueZ 4 is required, mask BlueZ 5 to prevent it from being installed:

FILE /etc/portage/package.mask
Installing BlueZ 4, while Bluetooth support is enabled system-wide, may cause various dependency issues.

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 will be handled automatically if the USE variable is set to acl, and ConsoleKit or systemd is being used.

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

root #gpasswd -a <user> plugdev



  • 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:
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 indicates that the controller is enabled.

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

root #hciconfig hci0 up

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

root #hciconfig hci0 up
Can't init device hci0: Operation not possible due to RF-kill

In this case, query the state of the Bluetooth radio transmitter with net-wireless/rfkill:

root #rfkill list bluetooth
0: hci0: Bluetooth
        Soft blocked: no
        Hard blocked: no
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.

  • The following udev rule will enable a controller before a graphical desktop environment is up and running:
FILE /etc/udev/rules.d/90-bluetooth.rules
# Enable the Bluetooth controller

# BlueZ 5
ACTION=="add", KERNEL=="hci0", TEST=="/usr/bin/hciconfig", RUN+="/usr/bin/hciconfig hci0 up"
# BlueZ 4
ACTION=="add", KERNEL=="hci0", TEST=="/usr/sbin/hciconfig", RUN+="/usr/sbin/hciconfig hci0 up"

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 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 net-wireless/bluedevil, for GNOME use net-wireless/gnome-bluetooth and for GTK+ use net-wireless/blueman.

BlueZ 5

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

Device paring is done with bluetoothctl, which is provided by the net-wireless/bluez package.

  • 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:

BlueZ 4

BlueZ 4 is deprecated and no longer supported by the BlueZ developers.

Device paring, which is done with simple-agent, requires the USE flag test-programs to be enabled for the net-wireless/bluez 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:
user $hcitool scan
Scanning ...
        00:1F:20:1D:1B:4B       Bluetooth Device

Where 00:1F:20:1D:1B:4B is the MAC address of the device.

  • Pair with the device:
user $simple-agent hci0 00:1F:20:1D:1B:4B
RequestPinCode (/org/bluez/1664/hci0/dev_00_1F_20_1D_1B_4B)
Enter PIN Code: 0000
New device (/org/bluez/1664/hci0/dev_00_1F_20_1D_1B_4B)

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

  • When attempting to pair with the device, the following message may be displayed if a graphical interaction agent is installed.
user $simple-agent hci0 00:1F:20:1D:1B:4B
dbus.exceptions.DBusException: org.bluez.Error.AlreadyExists: Already Exists

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:
user $bluez-test-device trusted 00:1F:20:1D:1B:4B

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

  • Trust the device so it can connect automatically:
user $bluez-test-device trusted 00:1F:20:1D:1B:4B yes
  • Connect to the device. This only needs to be done once if the device is trusted:
user $bluez-test-input connect 00:1F:20:1D:1B:4B
  • The device is now paired.

See also

External resources