Quickly Connect Bluetooth Devices with Wayland Compositor

If you are using a lightweight Linux desktop environment built with Wayland Compositor (such as Labwc, Sway, Niri, etc.), you will often encounter the problem of connecting Bluetooth headphones or Bluetooth speakers in daily use.

This article mainly introduces how to quickly connect Bluetooth headphones or speakers in an Arch + Labwc environment (speakers are used as an example below).

1. Connecting via a script using Waybar

This is the method I currently use. Before this, I connected directly using the command line:

1➜ ~ abbr | grep acton3
2abbr -a -- acton3 'bluetoothctl connect 50:5E:5C:95:0B:A4'
3abbr -a -- dis-acton3 'bluetoothctl disconnect 50:5E:5C:95:0B:A4'

Looking at Fish's abbr above, abbr is Fish's built-in abbreviation tool, different from traditional aliases: typing an abbreviation and pressing space/enter will expand the complete command in real time, which can be edited and then executed. The history stores the complete command; it can be simply understood as a variant of aliases.

The above configuration means: type acton3 to connect to the ACTON III Bluetooth speaker, and dis-acton3 to disconnect. It seems simple and straightforward, with no apparent problems.

I used to do it this way too, but over time, it started to feel inconvenient:

• I needed to open the terminal first;

• Then I had to type the command;

• I had to remember the alias, and I might forget it when I turned on my computer after a long holiday.

Because the above steps were too lengthy and burdensome to remember, I eventually abandoned it.

My proposed alternative is to use Waybar's Bluetooth module to trigger a script for automatic connection.

An example configuration is as follows:

 1"bluetooth": {
 2    "format": "{status}",
 3	  "format-on": "{status}|none",
 4    "format-off": "{status}",
 5    "format-disabled": "󰂲{status}",
 6    "format-connected": "{device_alias}",
 7    "format-connected-battery": " {device_alias} {device_battery_percentage}%",
 8    // "format-device-preference": [ "device1", "device2" ], // preference list deciding the displayed device
 9    "tooltip-format": "{controller_alias}\t{controller_address}\n{num_connections} connected",
10    "tooltip-format-connected": "{controller_alias}\t{controller_address}\n{num_connections} connected\n{device_enumerate}",
11    "tooltip-format-enumerate-connected": "{device_alias}\t{device_address}",
12    "tooltip-format-enumerate-connected-battery": "{device_alias}\t{device_address}\t{device_battery_percentage}%",
13    "on-click": "~/.config/waybar/scripts/bluetooth-toggle.sh"
14},

In Waybar, the on-click attribute is used to add mouse click interaction events to the status bar module.

From the above configuration, it can be seen that I selected left mouse button click to trigger the script to connect to the Bluetooth speaker.

Here's a script example:

 1➜  ~ cat ~/.config/waybar/scripts/bluetooth-toggle.sh
 2#!/bin/bash
 3BLUETOOTH_MAC="50:5E:5C:95:0B:A4"
 4WAIT=0.2
 5
 6notify() {
 7    notify-send -i audio-speakers "$1" "$2"
 8}
 9
10# 确保蓝牙已开启
11if ! bluetoothctl show | grep -q "Powered: yes"; then
12    notify "蓝牙未开启" "正在开启..."
13    bluetoothctl power on >/dev/null 2>&1
14    sleep $WAIT
15fi
16
17# 获取当前连接状态
18info=$(bluetoothctl info "$BLUETOOTH_MAC")
19
20if echo "$info" | grep -q "Connected: yes"; then
21    # 已连接 → 断开
22    bluetoothctl disconnect "$BLUETOOTH_MAC" >/dev/null 2>&1
23    notify "已断开⏹️" "$BLUETOOTH_MAC"
24else
25    # 尝试连接
26    bluetoothctl connect "$BLUETOOTH_MAC" >/dev/null 2>&1
27    sleep $WAIT
28
29    # 验证结果
30    if bluetoothctl info "$BLUETOOTH_MAC" | grep -q "Connected: yes"; then
31        notify "连接成功✅" "$BLUETOOTH_MAC"
32    else
33        notify "连接失败❌" "蓝牙设备未开机或不在附近"
34        exit 1
35    fi
36fi

The logic is very simple: click connect, then click disconnect. If the speaker is not powered on or not turned on, a notification will pop up.

Screenshot of the effect

A careful observer might ask, doesn't this only allow one Bluetooth device to connect? Yes, I mainly use it at home to connect speakers and rarely need to connect other devices, so it's sufficient and simple for me.

What if I need to connect multiple devices? Of course, I can revert to the command line.

There are also the following methods.

2. Using the Orbit GUI tool to manage Bluetooth devices

Actually, there are many GUI tools for managing Bluetooth devices on Linux, such as Blueman and Blueberry, but they are all incredibly ugly and I don't like them at all.

I did a search myself, and Orbit is a tool that has only emerged in the last few months. It's written in Rust, uses GTK4 for its UI, and the overall interface looks quite beautiful and harmonious.

Example image:

It can manage not only Bluetooth, but also Wi-Fi and VPN. It can also be used in conjunction with the Waybar. You can also:

1orbit toggle --tab [wifi|bluetooth|vpn]

This focuses on a specific sub-tab, showing that the author understands the pain points of incomplete DE (Deep Execution Environment).

For complete usage instructions, please see the README file at https://github.com/LifeOfATitan/orbit. I'm too lazy to write it out, but it's simple and easy to use, and still worth recommending.

The only drawback is that it requires starting an extra process 😅 (But how can it provide functionality without a process? bluetoothctl requires bluetoothd, right? Makes sense!)

1systemctl --user enable --now orbit

After all this, why don't you use it? I find method 1 above sufficient; it's simple and clear. I display Wi-Fi and other settings using the Waybar and manage them with the UI. If you need a tool that combines Wi-Fi, Bluetooth, and VPN, why not use it?

In summary, if you want simplicity and don't want to connect multiple devices, use Waybar's Bluetooth module with custom scripts; if you want to manage Wi-Fi, Bluetooth, and VPN simultaneously, or prefer a GUI interface, Orbit is also a good option. Choose according to your needs.