From Gentoo Wiki
Jump to: navigation, search

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


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



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.

Kernel configuration

[*] Networking support --->
      <*>   Bluetooth subsystem support --->
              <*>   RFCOMM protocol support
              [ ]     RFCOMM TTY support
              < >   BNEP protocol support
              [ ]     Multicast filter support
              [ ]     Protocol filter support
              <*>   HIDP protocol support
                    Bluetooth device drivers --->
                      <*> HCI USB driver
                      <*> HCI UART driver
                      [ ]   UART (H4) protocol support
                      [ ]   BCSP protocol support
                      [ ]   Atheros AR300x serial support
                      [ ]   HCILL protocol support
                      [ ]   Three-wire UART (H5) protocol support
      <*>   RF switch subsystem support --->
Bluetooth Options
Option Driver Description
RFCOMM protocol support rfcomm Enables RFCOMM support which is required for OBEX file transfers, dial-up networking and other Bluetooth applications.
RFCOMM TTY support - Enables terminal emulator connections over RFCOMM.
BNEP protocol support bnep Enables network support, e.g. the PAN profile.
Multicast filter support - Enables multicast filter support.
Protocol filter support - Enables protocol filter support.
HIDP protocol support hidp Enables input device support.
HCI USB driver btusb Enables USB device support.
HCI UART driver hci_uart Enables UART based PCMCIA and CF device support.


Bluetooth user space support is provided by net-wireless/bluez. Portage has ebuilds for BlueZ 4 (deprecated) and BlueZ 5.

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



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



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

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

Install BlueZ.

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



If you have the acl 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.

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 Bluetooth 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 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.
root # hciconfig hci0 up
  • You may receive the following message when attempting to enable the controller.
root # hciconfig hci0 up
Can't init device hci0: Operation not possible due to RF-kill

In this case you will need to query the controllers rfkill state with net-wireless/rfkill.

root # rfkill list bluetooth
0: hci0: Bluetooth
        Soft blocked: no
        Hard blocked: no
  • If rfkill indicates that the controller is blocked with Soft blocked: yes, you will need to unblock the controller.
root # rfkill unblock bluetooth
  • 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.

# Enable the Bluetooth controller

# BlueZ 4
ACTION=="add", KERNEL=="hci0", TEST=="/usr/sbin/hciconfig", RUN+="/usr/sbin/hciconfig hci0 up"
# BlueZ 5
ACTION=="add", KERNEL=="hci0", TEST=="/usr/bin/hciconfig", RUN+="/usr/bin/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 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 net-wireless/bluedevil for KDE, net-wireless/gnome-bluetooth for GNOME and net-wireless/blueman for GTK+.

BlueZ 4

Device paring which is done with simple-agent, requires that you enable the test-programs USE flag for net-wireless/bluez.

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

  • 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.
user $ simple-agent hci0 00:1F:20:1D:1B:4B
dbus.exceptions.DBusException: org.bluez.Error.AlreadyExists: Already Exists

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

Where 0 is not trusted and 1 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. If the device is trusted you only need to do this once.
user $ bluez-test-input connect 00:1F:20:1D:1B:4B
  • The device is now paired.

BlueZ 5

If you have upgraded from BlueZ 4 you will need to pair any previously paired devices again.

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

  • Start bluetoothctl.
user $ bluetoothctl
  • List the available controllers.
[bluetooth]# list
  • 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
pairable on
  • Scan for devices.
[bluetooth]# scan on
  • Put the device into pairing mode.
  • Discover the device MAC address.
[bluetooth]# devices
  • Pair with the device.
[bluetooth]# pair device_mac_address
  • If prompted enter the PIN code.
[agent] PIN code: ####
  • If prompted allow the service authorization request.
[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.
[bluetooth]# quit

See also