Configuring Bluetooth devices with bluetoothctl

Blue Control

© Lead Image © stockfotocz,

© Lead Image © stockfotocz,

Article from Issue 197/2017

The bluetoothctl command will keep your Bluetooth devices talking to Linux.

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.

Table 1

bluetoothctl Commands



1. list

Generates a list of available controllers. You can pair a controller and a device while working from another controller, but on a home system you may have only one controller. However, you need the controller's MAC address to run other commands. If it is no longer visible on screen, run list again. You might be able to simplify the process by turning off all controllers except the one to pair.

2. show

Gathers information about available controllers, including their names and current state. This information can be useful for distinguishing one controller from the other.


Selects the controller to pair. Once you select the controller, all controller-related commands will apply to it for three minutes or until you select a new controller.

4. power on

Enables the selected controller. If you are pairing the controller on which bluetoothctl is running, this step is unnecessary.

5. agent on

Turns on Bluetooth support. If you use a USB adapter, it is on as long as it is plugged in.

6. default agent

Sets the current agent to the default.

7. discoverable on

Makes the controller visible to other devices. As a security precaution, run discoverable off after pairing.

8. scan on

Receives a list of detected devices (Figure 3). If a device you expect is not visible, check that it is turned on, ready to pair, and within range. Already paired devices will not be listed.

9. pairable on

Readies the controller for pairing. Remember that you have three minutes after running this command to pair.

10. devices

Lists available devices. You want the MAC address, not the name, to use with other commands.


Displays information about a particular device (Figure 4). This command is most often useful in identifying the correct device.

12. connect <DEVICE-MAC-ADDRESS>

Readies the device for pairing.


Pairs the device with the default controller.


Sets the device to re-pair automatically when it is turned on, which eliminates the need to pair all over again.

15. discoverable off

Hides the controller from other Bluetooth devices. Otherwise, any device that can detect it has access to it, leaving a major security hole. In this respect, running bluetoothctl resembles logging in as root: you want to spend as little time running it as possible.

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.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

comments powered by Disqus
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More