From Gentoo Wiki
Jump to: navigation, search
External resources

This article describes the setup of Bluetooth controllers.


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



Use the table below to determine which Bluetooth subsystem you need to enable. In most cases enabling RFCOMM, HIDP, HCI USB and/or HCI UART will 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 subsystem support
Option Driver Description
RFCOMM protocol support rfcomm RFCOMM is a requirement of the OBEX file transfer, dialup connections and more Bluetooth applications.
RFCOMM TTY support - Enables terminal emulator connections over RFCOMM.
BNEP protocol support bnep Enables network support, e.g. for 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. See the Bluetooth Input devices article.
HCI USB driver btusb Enables USB Bluetooth device support.
HCI UART driver hci_uart Enables UART based PCMCIA and CF Bluetooth 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 globally 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 globally you should update your system. This will automatically install BlueZ.

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

If you didn't enable the bluetooth USE flag globally you will need to manually install BlueZ.

root # emerge --ask net-wireless/bluez



If you have the acl USE flag enabled globally and are using ConsoleKit or systemd, then 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

Adapter Information

Check that your Bluetooth adapter is working.

If no Bluetooth controllers are found, check that your Bluetooth device is enabled. This may be a physical switch or keyboard function key that enables/disables the Bluetooth radio. You can use net-wireless/rfkill to query and set the state of the Bluetooth radio.
user $ 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)

Bring interface up at bootup time

In case you need to use trusted Bluetooth devices before a GUI is up and running, you can use an udev rule:


# Set bluetooth power up
ACTION=="add", KERNEL=="hci0", RUN+="/usr/bin/hciconfig hci0 up"


To start Bluetooth:

root # /etc/init.d/bluetooth start

To start Bluetooth at boot:

root # rc-update add bluetooth default


Device pairing

Before a device can be used, it must be attached (paired in Bluetooth terminology). This is done by entering a PIN (or other code) on both devices.

Some simple devices like headsets do not allow entering an arbitrary PIN, they always use the same one (usually 0000 or 9999). Check the manual of your device which is to be used.

In order to pair, you must first have the interaction agent active. Most desktop environments have Bluetooth integration so will automatically support the interaction agent. For example, KDE has net-wireless/bluedevil.

BlueZ 4

Configuration can either be performed using the BlueZ test programs (available if you enable the test-programs USE flag for net-wireless/bluez), or by using the D-Bus API. The first way is described here.

  • Retrieve the address of the mouse. Most of the devices need you to press a special button, possibly for several seconds, to render them discoverable.
user $ hcitool scan
Scanning ...
	00:1F:20:1D:1B:4B	Bluetooth Laser Travel Mouse
Where 00:1F:20:1D:1B:4B is the MAC address for your device.
  • Pair 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, then enter the same PIN at the device. If you don't know the PIN, then it is probably 0000. It could be 1234.

user $ simple-agent hci0 00:1F:20:1D:1B:4B
dbus.exceptions.DBusException: org.bluez.Error.AlreadyExists: Already Exists
Means that you already have an interaction agent running on your system.
  • Mark the device as trusted so it can connect automatically:
user $ bluez-test-device trusted 00:1F:20:1D:1B:4B yes
  • Devices are not trusted by default. You can check trust status by leaving off the "yes" from the previous command.
user $ bluez-test-device trusted 00:1F:20:1D:1B:4B
"1" is trusted, "0" is not trusted.
  • Connect the device (this only needs to be done once, it will be done automatically after that):
user $ bluez-test-input connect 00:1F:20:1D:1B:4B
  • Your device should now be paired. You are now ready to proceed.

BlueZ 5

If you have upgraded from BlueZ 4 you will need to pair with your devices again.
  • 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 requested enter the PIN code.
[agent] PIN code: ####
  • 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

Desktop integration

See also