---
title: 'Bluetooth on Linux'
date: '2025-12-08'
excerpt: '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 `help` at 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.

```bash
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:

```bash
pair 04:D5:83:26:88:0A
```

> Note: when using the interactive utility you can press `TAB` twice to ouput the available MAC addresses, begin typing one and then press `TAB` once 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).

```bash
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.

```bash
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.

```bash
remove 04:D5:83:26:88:0A
```

To disconnect the device use the `disconnect` command:

```bash
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.
