BlueZ Guide

Bluetooth is a communication protocol used for wireless peripherals such as headphones, speakers, keyboards, mice, game controllers, and various other devices. On Linux, Bluetooth support is typically provided by BlueZ, the official Bluetooth stack used by most distributions. On Arch/Artix Linux, it's provided by the bluez package, and the command-line interface is provided by bluez-utils.

For the stack to function, the Bluetooth daemon service (bluetoothd) must be actively running in the background. On Arch (using Systemd), you can enable and start the service simultaneously by issuing: systemctl enable --now bluetooth.service. On Artix, it must be enabled manually according to your chosen init system (e.g., for Dinit, you must install the bluez-dinit package and enable the service by issuing: sudo dinitctl enable bluetoothd).

Before attempting to connect a device, it is worth ensuring that the Bluetooth adapter is not blocked by the kernel. To check this, issue the command: rfkill list. If Bluetooth appears as "soft-blocked", unblock it by issuing: rfkill unblock bluetooth. A reboot afterwards may also be necessary.

Bluetooth devices can be managed through bluetoothctl, a command-line interface provided by BlueZ. Simply issue:

bluetoothctl

This will launch an interactive shell, usually indicated by a prompt similar to:

[bluetoothctl]#

To discover nearby devices, enable scanning:

[bluetoothctl]# scan on

As devices are discovered, their MAC addresses and names will be displayed. The MAC address uniquely identifies the Bluetooth device and is used for most operations within bluetoothctl.

To pair with a device, issue:

[bluetoothctl]# pair [mac-address]

The MAC address can be tedious to type manually, but shell completion usually works; typing a few characters and pressing Tab is often sufficient.

Some devices automatically connect after pairing, while others require a separate connection step:

[bluetoothctl]# connect [mac-address]

Once connected, the Bluetooth device is managed by the Bluetooth daemon running in the background. Closing the terminal or exiting bluetoothctl will not disconnect the device.

If device discovery is no longer needed, scanning can be disabled:

[bluetoothctl]# scan off

For devices that will be used regularly, it is usually convenient to mark them as trusted:

[bluetoothctl]# trust [mac-address]

A trusted device may automatically reconnect when powered on again, avoiding the need for manual reconnection each time.

To disconnect a currently connected device, issue:

[bluetoothctl]# disconnect [mac-address]

To revoke the device's trusted status, issue:

[bluetoothctl]# untrust [mac-address]

Finally, if you wish to completely forget a previously paired device, remove it from BlueZ's database:

[bluetoothctl]# remove [mac-address]

That is all there is to it. Despite Bluetooth's reputation for being unreliable, the actual setup procedure through bluetoothctl is surprisingly straightforward.