Important: You are required to change your passwords used for Gentoo services and set an email address for your Wiki account if you haven't done so. See the full announcement and Wiki email policy change for more information.


From Gentoo Wiki
Revision as of 08:09, 11 August 2013 by Estellnb (Talk | contribs)

Jump to: navigation, search
External resources

This article describes the setup of bluetooth controllers.



Bluez (net-wireless/bluez) uses udev, so set it up first.


You need USB and/or PC-Card support. Also you need to activate the following kernel options:

Kernel configuration

[*] Networking support  --->
    <*> Bluetooth subsystem support  --->
        Select options for Bluetooth applications, see table below:
        <*>   ...

            Bluetooth device drivers  --->

               Select a Bluetooth HCI driver, e.g.:
               <*> HCI USB driver (btusb)
Bluetooth applications
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 protocoll filter support.
HIDP protocol support hidp Enables input device support. See the Bluetooth Input devices article.


Portage knows the global USE flag bluetooth for enabling support for Bluetooth in other packages. Enabling this USE flag will pull in net-wireless/bluez automatically:


USE="... bluetooth ..."

The USE flags of bluez are:

→ Information about USE flags
USE flag Default Recommended Description
alsa Yes Adds support for media-libs/alsa-lib (Advanced Linux Sound Architecture)
consolekit Yes Use sys-auth/pambase[consolekit] to determine access to bluetooth devices based on whether a user is logged in locally or remotely
cups Yes Add support for CUPS (Common Unix Printing System)
debug No Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see
gstreamer No Adds support for media-libs/gstreamer (Streaming media)
pcmcia No Adds support for PCMCIA slots/devices found on laptop computers
readline Yes Enables support for libreadline, a GNU line-editing library that almost everyone wants
selinux No No  !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
test-programs No Install tools for testing of various Bluetooth functions
usb Yes Adds USB support to applications that have optional USB support (e.g. cups)

After setting this you want to update your system so the changes take effect:

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


Boot service

You can now start bluetooth:

root # /etc/init.d/bluetooth start

To start bluetooth at boot time, add it your default runlevel:

root # rc-update add bluetooth default


If you have the USE flag acl enabled globally and are using ConsoleKit (i.e you're using a desktop profile) permissions to bluetooth devices will be handled automatically.

A broader solution is to add the user you want to be able to access bluetooth devices to the plugdev group:

root # gpasswd -a larry plugdev

Adapter Information

Check that your bluetooth adapter is working.

user $ hcitool dev
	hci1	00:02:72:2F:A9:33
	hci0	60:D8:19:B6:C3:1F

Where hci0 is the first device ID and 60:D8:19:B6:C3:1F is the MAC address.

In this case there are two adapters but only one is required.
If no adapters are found. Check that your bluetooth adapter is enabled. This may be a physical switch or keyboard function key. net-wireless/rfkill is helpful for determining and setting the state of wireless adapters.


Device Attach/Pairing

Before a device can be used, it must be attached (paired in Bluetooth-lingo). 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.

Using simple-agent

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.

Desktop integration

See also