Configuring Bluetooth devices with bluetoothctl
Blue Control

© Lead Image © stockfotocz, 123RF.com
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):

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.
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
Command | Description |
---|---|
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. |
3. select <CONTROLLER-MAC-ADDRESS> |
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. |
11. info <DEVICE-MAC-ADDRESS> |
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. |
13. pair <DEVICE-MAC-ADDRESS> |
Pairs the device with the default controller. |
14. trust <DEVICE-MAC-ADDRESS> |
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. |

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.
Infos
- bluetoothctl: http://www.bluez.org
- Bluetooth Special Interest Group: https://www.bluetooth.com/
- The BlueZ project: http://www.bluez.org/about/history/
- Bluetooth profiles: http://www.mobileburn.com/definition.jsp?term=Bluetooth+profile
- hcitool: http://linuxcommand.org/man_pages/hcitool1.html
- Configuring Bluetooth: https://wiki.gentoo.org/wiki/Bluetooth
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Direct Download
Read full article as PDF:
Price $2.95
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Find SysAdmin Jobs
News
-
Kubuntu Focus Announces XE Gen 2 Linux Laptop
Another Kubuntu-based laptop has arrived to be your next ultra-portable powerhouse with a Linux heart.
-
MNT Seeks Financial Backing for New Seven-Inch Linux Laptop
MNT Pocket Reform is a tiny laptop that is modular, upgradable, recyclable, reusable, and ships with Debian Linux.
-
Ubuntu Flatpak Remix Adds Flatpak Support Preinstalled
If you're looking for a version of Ubuntu that includes Flatpak support out of the box, there's one clear option.
-
Gnome 44 Release Candidate Now Available
The Gnome 44 release candidate has officially arrived and adds a few changes into the mix.
-
Flathub Vying to Become the Standard Linux App Store
If the Flathub team has any say in the matter, their product will become the default tool for installing Linux apps in 2023.
-
Debian 12 to Ship with KDE Plasma 5.27
The Debian development team has shifted to the latest version of KDE for their testing branch.
-
Planet Computers Launches ARM-based Linux Desktop PCs
The firm that originally released a line of mobile keyboards has taken a different direction and has developed a new line of out-of-the-box mini Linux desktop computers.
-
Ubuntu No Longer Shipping with Flatpak
In a move that probably won’t come as a shock to many, Ubuntu and all of its official spins will no longer ship with Flatpak installed.
-
openSUSE Leap 15.5 Beta Now Available
The final version of the Leap 15 series of openSUSE is available for beta testing and offers only new software versions.
-
Linux Kernel 6.2 Released with New Hardware Support
Find out what's new in the most recent release from Linus Torvalds and the Linux kernel team.