Revision as of 10:59, 1 January 2014

Bluetooth is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. In Linux, the canonical implementation of the Bluetooth protocol stack is BlueZ.

Installation

Install the Bluetooth protocol stack bluez and the utilities bluez-utils from the official repositories. The dbus daemon, which is started automatically by systemd, is used to read settings and for PIN pairing, while the bluetooth daemon is required for the Bluetooth protocol.

Note: Some Bluetooth adapters are bundled with a Wi-Fi card (e.g. Intel Centrino). These require that the Wi-Fi card is first enabled (typically a keyboard shortcut on a laptop) in order to make the Bluetooth adapter visible to the kernel.

Configuration via the CLI

Bluetoothctl

Pairing a device from the shell is one of the most simplistic and reliable options. The exact procedure depends on the devices involved and their input functionality. What follows is a general outline of pairing a device using /usr/bin/bluetoothctl:

Start the bluetoothctl interactive command. There one can input help to get a list of available commands.

Turn the power to the controller on by entering power on. It is off by default.

Enter devices to get the MAC Address of the device with which to pair.

Enter device discovery mode with scan on command if device is not yet on the list.

Turn the agent on with agent on.

Enter pair MAC Address to do the pairing (tab completion works).

If using a device without a PIN, one may need to manually trust the device before it can reconnect successfully. Enter trust MAC Address to do so.

In order to have the device active after a reboot, a udev rule is needed:
/etc/udev/rules.d/10-local.rules

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

Configuration with a Graphical Front-end

The following packages allow for a graphical interface to customize Bluetooth.

GNOME Bluetooth

GNOME Bluetooth is a fork of the old bluez-gnome and is focused on integration with the GNOME desktop environment. The gnome-bluetooth package provides the back-end, gnome-shell provides the status monitor applet, and gnome-control-center provides the configuration front-end GUI that can be accessed by typing Bluetooth on the Activities overview, or with the gnome-control-center bluetooth command.

Users who are not using GNOME Shell can install gnome-bluetooth-applet-gitAUR from AUR, which provides the old status monitor applet, and allows setup devices and transfer of files by clicking the Bluetooth icon. Just make sure that bluetooth-applet is autostarted with your session.

You can also launch the following commands directly:

bluetooth-sendto: send files to a remote device

bluetooth-wizard: for new devices to be paired

To add a Bluetooth entry to the SendTo menu in Thunar's file properties menu, see instructions here. (The command that needs to be configured is bluetooth-sendto %F)

BlueDevil

The Bluetooth tool for KDE is BlueDevil. It can be installed with the package bluedevil, available in the official repositories.

Make sure bluetooth daemon is running, as described above. A Bluetooth icon should be visible in both Dolphin and in the system tray, from which users may configure BlueDevil and detect Bluetooth devices by clicking the icon. An interface is also available from the KDE System Settings.

Using Obex for sending and receiving files

Another option, rather than using KDE or Gnome Bluetooth packages, is ObexFS which allows for the mounting of phones which are treated like any other filesystem.

Note: To use ObexFS, one needs a device that provides an ObexFTP service.

Note: Ensure that the bluetooth device you are mounting is not set to mount read-only. You should be able to do this from the device's settings. If the device is mounted read-only you may encounter a permissions error when trying to transfer files to the device.

For devices that do not support Obex FTP service, check if Obex Object Push is supported.

# sdptool browse XX:XX:XX:XX:XX:XX

Read the output, look for Obex Object Push, remember the channel for this service. If supported, one can use ussp-push to send files to this device:

# ussp-push XX:XX:XX:XX:XX:XX@CHANNELfilewanted_file_name_on_phone

ObexFTP Transfers

If you device does support the Obex FTP service but you do not wish to mount the device you can transfer files to and from the device using the obexftp command.

Tip: If you installed obexfs earlier then obexftp should have also been installed a a dependency.

To send a file to a device run the command:

$ obexftp -b devices_MAC_address -p /path/to/file

To retrieve a file from a device run the command:

$ obexftp -b devices_MAC_address -g filename

Note: Ensure that the file you are retrieving is in the devices exchange folder. If the file is in a subfolder in the exchange folder then provide the correct path in the command.

Examples

All examples have been moved to bluez4 article. They need to be checked and fixed for use with bluez5. See bluez4.

Troubleshooting

gnome-bluetooth

If you see this when trying to enable receiving files in bluetooth-properties:

Bluetooth USB Dongle

If you are using a USB dongle, you should check that your Bluetooth dongle is recognized. You can do that by running journalctl -f when plugging in the USB dongle (or inspecting /var/log/messages.log). It should look something like the following (look out for hci):

it could be due either to the rfkill utility, in which case it should be resolved with

# rfkill unblock all

or, it could simply be the hardware switch of the computer. The hardware bluetooth switch (at least sometimes) controls access to USB bluetooth dongles also. Flip/press this switch and try bringing the device up again.

To verify that the device was detected you can use hcitool which is part of the bluez-utils. You can get a list of available devices and their identifiers and their MAC address by issuing:

$ hcitool dev

Devices:
hci0 00:1B:DC:0F:DB:40

More detailed information about the device can be retrieved by using hciconfig.

Logitech Bluetooth USB Dongle

There are Logitech dongles (ex. Logitech MX5000) that can work in two modes Embedded and HCI. In embedded mode dongle emulates a USB device so it seems to your PC that your using a normal USB mouse/keyoard.

If you hold the little red Button on the USB BT mini-receiver it will enable the other mode. Hold the red button on the BT dongle and plug it into the computer, and after 3-5 seconds of holding the button, the Bluetooth icon will appear in the system tray. Discussion

hcitool scan: Device not found

On some Dell laptops (e.g. Studio 15) you have to switch the Bluetooth mode from HID to HCI using

# hid2hci

Note: hid2hci is no longer in the $PATH, it is under /lib/udev/hid2hci, but udev should run it automatically for you.

If the device will not show up and you have a Windows operating system on your machine, try booting it and enable the bluetooth adapter from windows.