Browse Bluetooth Devices

mcdbus provides a bluetooth_devices shortcut tool that reads from bluez on the system bus. It uses the ObjectManager interface to get all known Bluetooth devices in a single call, then formats them into a sorted table.

Listing devices

“What Bluetooth devices are nearby?”

bluetooth_devices()

The tool returns a table sorted with connected devices first, then paired devices, then everything else alphabetically:

## Bluetooth Devices -- 5 found

| Name | Address | Connected | Paired | Trusted |
|------|---------|-----------|--------|---------|
| WH-1000XM4 | 38:18:4C:XX:XX:XX | yes | yes | yes |
| Keyboard K380 | 34:88:5D:XX:XX:XX | yes | yes | yes |
| Galaxy Buds2 | A0:C5:F2:XX:XX:XX | no | yes | yes |
| iPhone | 7C:04:D0:XX:XX:XX | no | no | no |
| [unknown] | 48:A4:93:XX:XX:XX | no | no | no |

What it reads

The tool calls org.freedesktop.DBus.ObjectManager.GetManagedObjects on org.bluez at the root path /. This returns every managed object in the bluez hierarchy. The tool filters for objects that have the org.bluez.Device1 interface and extracts:

Column	Source property	Notes
Name	`Name` or `Alias`	Falls back to “Unknown” if neither is set
Address	`Address`	Bluetooth MAC address
Connected	`Connected`	Boolean — active link to this device
Paired	`Paired`	Boolean — bonding keys exchanged
Trusted	`Trusted`	Boolean — auto-connect permitted

Reading detailed device properties

Each Bluetooth device has an object path under /org/bluez/hci0/ (or whichever adapter is active). The path encodes the MAC address with underscores replacing colons:

/org/bluez/hci0/dev_38_18_4C_XX_XX_XX

To read all properties on a specific device:

“Tell me everything about my WH-1000XM4 headphones.”

get_all_properties(
    bus="system",
    service="org.bluez",
    object_path="/org/bluez/hci0/dev_38_18_4C_XX_XX_XX",
    interface="org.bluez.Device1"
)

This returns additional properties beyond what the shortcut tool shows:

Property	What it contains
`RSSI`	Signal strength in dBm (only present during discovery)
`Appearance`	GAP appearance value indicating device category
`Icon`	Icon hint string (e.g., “audio-headphones”, “input-keyboard”)
`Adapter`	Object path of the Bluetooth adapter this device was seen by
`ServicesResolved`	Whether service discovery has completed
`UUIDs`	List of Bluetooth service UUIDs the device advertises
`Modalias`	USB-style modalias string for driver matching

Battery level

Some Bluetooth devices report their battery level through the org.bluez.Battery1 interface. To check:

get_all_properties(
    bus="system",
    service="org.bluez",
    object_path="/org/bluez/hci0/dev_38_18_4C_XX_XX_XX",
    interface="org.bluez.Battery1"
)

If the device supports it, this returns a Percentage property (0-100). Not all devices report battery level over Bluetooth — it depends on the device firmware and profile support.

Inspecting the adapter

The Bluetooth adapter itself (typically hci0) has its own set of properties at /org/bluez/hci0:

get_all_properties(
    bus="system",
    service="org.bluez",
    object_path="/org/bluez/hci0",
    interface="org.bluez.Adapter1"
)

This shows the adapter’s name, MAC address, power state, discoverability, and supported features.

Finding device paths

If you are unsure of the exact object path for a device, walk the bluez object tree:

list_objects(bus="system", service="org.bluez")

This returns paths like:

/org/bluez
/org/bluez/hci0
/org/bluez/hci0/dev_38_18_4C_XX_XX_XX
/org/bluez/hci0/dev_34_88_5D_XX_XX_XX

Each dev_ path corresponds to a known device. The MAC address in the path matches the Address property with colons replaced by underscores.