From Gentoo Wiki
Revision as of 17:47, 16 July 2014 by Wild Penguin (Talk | contribs) (Bring interface up at bootup time -> formatting fix)

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. Bluetooth device does not show in 'lsusb' if USB support not present. 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)

This is a deprecated template. Help us update this template!

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 protocol 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 ..."

This is a deprecated template. Help us update this template! The USE flags of bluez are:

USE flag (what is that?) Default Recommended Description
alsa Yes Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture)
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 Add support for media-libs/gstreamer (Streaming media)
pcmcia No Add support for PCMCIA slots/devices found on laptop computers
readline Yes Enable 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 Add 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: {{RootCmd|/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.

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"

This is a deprecated template. Help us update this template!


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.

After an upgrade to BlueZ 5, pairing has to be redone.

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