4.1 KiB
title, date, excerpt
| title | date | excerpt |
|---|---|---|
| Bluetooth on Linux | 2025-12-08 | Learn how to use bluetooth on a debian based linux distribution. |
So I've been on quite the journey learning linux as my daily driver operating system. Today I wanted to pair my bluetooth keyboard to my desktop because.. why not, I like swapping between a few keyboards sometimes. I went to the panel/app bar and saw no trace of a 'bluetooth' icon I had come to expect during my days on Windows and MacOS. I attempted to look for a 'bluetooth' app to no avail and then finally went to the internet.
It didn't take long to find that my flavor of linux (mint) has a built in bluetoothctl tool that we can use.
bluetoothctl
There are two ways to use bluetoothctl the first is by prepending every command with bluetoothctl. This is how the tutorial ran me through it but I wasn't a big fan and opted for the alternative way.
If you just type bluetoothctl you will enter an interactive utility.
muszyn:~/$ bluetoothctl
[Keychron K6 Pro]# Agent registered
[Keychron K6 Pro]# [CHG] Controller B4:6B:FC:6A:DB:27 Pairable: yes
You may notice that I have a bluetooth device already registered
Keychron K6 Pro, this is the keyboard I am currently using.
Once you are in the control menu there are a list of commands to easily get started:
you can type
helpat any time to print a list of all available commands.
- scan on | scan off
- pair
{device-mac-addr} - connect
{device-mac-addr} - devices
- remove
{device-mac-addr} - disconnect
{device-mac-addr}
So lets put these commands to work.
Scanning for Devices
To search for a bluetooth device that you can connect to use the scan command.
scan on
This will begin discovery and output the devices that your system detects.
[Keychron K6 Pro]# scan on
[Keychron K6 Pro]# SetDiscoveryFilter success
[Keychron K6 Pro]# Discovery started
[Keychron K6 Pro]# [CHG] Controller B4:6B:FC:6A:DB:27 Discovering: yes
[Keychron K6 Pro]# [NEW] Device 55:41:D0:21:FD:EE 55-41-D0-21-FD-EE
[Keychron K6 Pro]# [NEW] Device 04:D5:83:26:88:0A KM18
The output above has a good deal of information so lets break it down.
Bluetooth devices are labeled as Device follwed by their Media Access Control (MAC) addresses which is a unique identifier for the device. All MAC addresses follow the format XX:XX:XX:XX:XX:XX. If the device has a name associated with it like KM18, bluetoothctl will display it. However, not every device has a display name as shown above by 55-41-D0-21-FD-EE which is just the MAC address with '-' instead of ':'.
Connecting to a Device
Once we have found a list of available devices we can choose to connect to one.
The first step is to pair your system to the device using the pair command.
Using KM18 in the list above:
pair 04:D5:83:26:88:0A
Note: when using the interactive utility you can press
TABtwice to ouput the available MAC addresses, begin typing one and then pressTABonce to auto-fill the rest of the address.
If this isn't your first time pairing to the device then you can use the connect command to establish a bluetooth connection.
This is useful if your device does not automatically connect on startup or if you would like to take over the connection from another device (this happens all the time with my headphones).
connect 04:D5:83:26:88:0A
Listing Paired Devices
Using the utility listing paried devices can be useful if you don't want to scan all the time.
devices Paried
This will output a list of your paired devices that you can then use to connect/disconnect from your system.
Disconnecting Devices
To unpair the device use the remove command.
remove 04:D5:83:26:88:0A
To disconnect the device use the disconnect command:
disconnect 04:D5:83:26:88:0A
Exiting the Interactive Mode
To exit, either type exit, or quit, OR you can use ctl+D whichever you prefer.
Non-Interactive
If you want to use the non-interactive tool then simply place bluetoothctl in front of each command.
The primary benefit I found for the interactive tool was the tab completion for the MAC addresses :D.