bluetoothctl [1] is the main command for configuring Bluetooth devices on Linux. Contrary to what the name's structure might lead you to expect, bluetoothctl is not part of systemd, but rather a simple set of options for setting up Bluetooth devices.

As you probably know, the Bluetooth standard is a collection of protocols for exchanging data over short distances – typically, less than five meters. Named for the 10th-century king Harald Bluetooth, who unified Denmark under the banner of Christianity, Bluetooth was developed by the Swedish company Ericsson, largely under the direction of Sven Mattisson. It was first released in 1998 and is now developed by the Bluetooth Special Interest Group [2]. Since 2005, it has been fully supported by Linux, and it has been included in the kernel since 2001. Today, the Linux implementation of Bluetooth is maintained by the BlueZ project[3]. bluetoothctl is part of the bluez-utilities package.

Bluetooth took several years to establish itself, but today, it can be used to add to your system almost every type of hardware, including speakers, printers, hard drives, keyboards, and mouses. The rise of the Internet of Things (IoT) has given the standard an enormous boost, because not only is Bluetooth's short range a security feature in itself, but the latest versions of the standard – version 5.0 as of mid-2016, although most available hardware uses version 4.0-4.2 – have exactly the built-in security features that companies are starting to realize are required by the IoT. Bluetooth smart light bulbs are already available, and more Bluetooth IoT devices are scheduled to follow.

Acceptance of Bluetooth is also helped by the fact that it is a mature standard whose user interface has become simpler over the years. In particular, bluetoothctl does not require users to concern themselves about which Bluetooth profile [4] (e.g., A2DP for headsets) devices need to communicate. Similarly, users no longer need to enter encryption PINs, which the latest versions of bluetoothctl now handle automatically unless an older device is involved. For that matter, bluetoothctl itself is in many ways an updated version of hcitool [5], the configuration tool that was used at the command line until a couple of years ago.

Preparing for Configuration

Most modern computers support Bluetooth by default. However, older or custom-compiled ones may not. Although you can add kernel modules to a system [6], the quickest way to add support is a USB Bluetooth dongle. Few dongles will actually advertise Linux support, but, as USB devices, almost any should work after you reboot the system.

If you are unsure whether a system supports Bluetooth, try installing the necessary packages – bluetooth or bluez on Debian, or bluetoothctl on Debian. Depending on the type of device, you may also need to install other packages. For example, for a speaker, you need to install pulseaudio and pavucontrol, and for a printer, the necessary CUPS package. You can check whether Bluetooth is enabled with the command (Figure 1):

Figure 1: Before pairing, check that Bluetooth control is enabled on your system. If not, then enable it.

systemctl status bluetooth

If it is not, then you can start it with:

systemctl start bluetooth

Your goal is to pair your computer with the device. In other words, you want your computer and the device set to have encrypted communication with each other. Some devices pair automatically when they are turned on, while others like phones provide interfaces or apps. A few, like Logitech's UE Boom 2 speakers, can be readied by pressing physical buttons.

Typically, devices will stay ready to pair for as long as three minutes, after which they have to be readied again. Unfortunately, these methods are not standardized, but they are usually easy enough to use. If you do run into difficulty, many devices will not be shipped with a manual, but most will have a reasonably current online manual.

Configuring Support

bluetoothctl is the command for pairing the system with a device. You can use several desktop applications instead (including Bluedevil, Blueman, gnome-bluetooth, and Blueberry), but all except Blueman are specific to a desktop environment. None have any advantage over bluetoothctl.

Whereas most commands modify the bare command with options, running bluetoothctl starts its own prompt for entering options instead. You can see a list of commands by entering help (Figure 2). Above the prompt is a list of systems (which bluetoothctl calls controllers) and devices that are available for use.

Figure 2: bluetoothctl's help shows the available commands.

In its current version, bluetoothctl works only with MAC addresses. Both controllers and devices may also have a human-friendly name. For controllers, the name is the computer's name. For devices, the default name is usually the product name.

Many devices allow you to change the name, which can reduce the possibility of confusion if you have two devices of the same kind from the same manufacturer. However, while bluetoothctl may list device names, its options do not work with the device names.

Depending on the device, you may be able to use only some of the bluetoothctl commands shown in Table 1. More often, you need to include all or some of these commands. Try them in the order listed.

Figure 3: Choose the device to pair from the list of detected devices.

Figure 4: Checking the information about a device can help you with identifying it and with troubleshooting.

As you might have noticed, many of the commands shown in Table 1 can be used to turn a setting both on and off. In other cases, a separate command is used instead – for example, you can use untrust if you no longer want a device to pair immediately. Similarly, you can use disconnect to break the connection with a device or remove to make a device unavailable for pairing until you scan again. If you want to make a device unavailable on an ongoing basis, use block and its counterpart unblock.

Whatever commands you use, run quit to close the bluetoothctl shell and return to Bash. With some devices, you need to do additional setup, such as setting up speakers with pavucontrol or KDE's Phonon.

Troubleshooting and Fine-Tuning

Bluetooth is far more reliable today than it was as recently as five years ago. Still, it can sometimes behave erratically, so you may have to attempt pairing several times. Scanning with another Bluetooth device, such as a phone, can sometimes tell you if the problem is with the controller or the device.

If problems persist, check that the device is turned on and set to discover other devices. Other possibilities may be that the device is positioned outside the controller's range, or that the device or controller has exceeded the maximum of seven devices supported by Bluetooth.

In addition, for devices like printers, you may want to write a Bash script to autostart as you log in to your desktop environment. Login managers sometimes interfere with Bluetooth starting, so you might want to set the script to delay running until your desktop appears, however long that may be.

One final tip: Some recent Bluetooth devices, such as the Fiio X7 portable stereo, can be set to turn off after a few minutes to preserve battery power. If the device turning off unpairs it, run trust from the bluetoothctl shell to have it reconnect automatically when turned back on.

Today, however, such problems are becoming rare. After all the years it has been available, Bluetooth is finally coming into its own – and bluetoothctl is the key to running it without difficulties on Linux.