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
-
TUXEDO Computers Unveils Linux Laptop Featuring AMD Ryzen CPU
This latest release is the first laptop to include the new CPU from Ryzen and Linux preinstalled.
-
XZ Gets the All-Clear
The back door xz vulnerability has been officially reverted for Fedora 40 and versions 38 and 39 were never affected.
-
Canonical Collaborates with Qualcomm on New Venture
This new joint effort is geared toward bringing Ubuntu and Ubuntu Core to Qualcomm-powered devices.
-
Kodi 21.0 Open-Source Entertainment Hub Released
After a year of development, the award-winning Kodi cross-platform, media center software is now available with many new additions and improvements.
-
Linux Usage Increases in Two Key Areas
If market share is your thing, you'll be happy to know that Linux is on the rise in two areas that, if they keep climbing, could have serious meaning for Linux's future.
-
Vulnerability Discovered in xz Libraries
An urgent alert for Fedora 40 has been posted and users should pay attention.
-
Canonical Bumps LTS Support to 12 years
If you're worried that your Ubuntu LTS release won't be supported long enough to last, Canonical has a surprise for you in the form of 12 years of security coverage.
-
Fedora 40 Beta Released Soon
With the official release of Fedora 40 coming in April, it's almost time to download the beta and see what's new.
-
New Pentesting Distribution to Compete with Kali Linux
SnoopGod is now available for your testing needs
-
Juno Computers Launches Another Linux Laptop
If you're looking for a powerhouse laptop that runs Ubuntu, the Juno Computers Neptune 17 v6 should be on your radar.