Configuring Bluetooth devices with bluetoothctl
Blue Control
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
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.
News
-
Latest Cinnamon Desktop Releases with a Bold New Look
Just in time for the holidays, the developer of the Cinnamon desktop has shipped a new release to help spice up your eggnog with new features and a new look.
-
Armbian 24.11 Released with Expanded Hardware Support
If you've been waiting for Armbian to support OrangePi 5 Max and Radxa ROCK 5B+, the wait is over.
-
SUSE Renames Several Products for Better Name Recognition
SUSE has been a very powerful player in the European market, but it knows it must branch out to gain serious traction. Will a name change do the trick?
-
ESET Discovers New Linux Malware
WolfsBane is an all-in-one malware that has hit the Linux operating system and includes a dropper, a launcher, and a backdoor.
-
New Linux Kernel Patch Allows Forcing a CPU Mitigation
Even when CPU mitigations can consume precious CPU cycles, it might not be a bad idea to allow users to enable them, even if your machine isn't vulnerable.
-
Red Hat Enterprise Linux 9.5 Released
Notify your friends, loved ones, and colleagues that the latest version of RHEL is available with plenty of enhancements.
-
Linux Sees Massive Performance Increase from a Single Line of Code
With one line of code, Intel was able to increase the performance of the Linux kernel by 4,000 percent.
-
Fedora KDE Approved as an Official Spin
If you prefer the Plasma desktop environment and the Fedora distribution, you're in luck because there's now an official spin that is listed on the same level as the Fedora Workstation edition.
-
New Steam Client Ups the Ante for Linux
The latest release from Steam has some pretty cool tricks up its sleeve.
-
Gnome OS Transitioning Toward a General-Purpose Distro
If you're looking for the perfectly vanilla take on the Gnome desktop, Gnome OS might be for you.