btmgmt

btmgmt [options] [command] [command_options]

-i <adapter_id>
    Specify the Bluetooth adapter to use, e.g., hci0. If not specified, the default adapter is used.

-s
    Show adapter settings for the specified or default adapter.

-v
    Show the controller version information.

-h
    Display a help message with command usage and options.

info
    Display general information and current settings about the selected adapter.

power <on/off>
    Turn the Bluetooth adapter's power on or off.

discov <on/off>
    Set the adapter's discoverability to on (discoverable by others) or off.

connectable <on/off>
    Set the adapter's connectability to on (allow incoming connections) or off.

pairable <on/off>
    Set the adapter's pairability to on (allow pairing requests) or off.

bondable <on/off>
    Set the adapter's bondability to on (store bond information after pairing) or off.

le <on/off>
    Enable or disable Bluetooth Low Energy (LE) functionality.

bredr <on/off>
    Enable or disable Bluetooth Basic Rate/Enhanced Data Rate (BR/EDR) functionality.

scan <on/off>
    Start or stop continuous device discovery scans.

find
    Perform a single, brief device discovery scan and list found devices.

addalias <name>
    Add a local alias (friendly name) for the adapter.

delalias <name>
    Delete an existing local alias for the adapter.

adduuid <uuid>
    Add a service UUID to the adapter's advertised capabilities.

deluuid <uuid>
    Delete a service UUID from the adapter's advertised capabilities.

btmgmt is a command-line utility from the BlueZ stack that provides a powerful and flexible interface for managing Bluetooth adapters on Linux systems. It allows users to control various aspects of a Bluetooth device, including its power state, discoverability, connectability, pairing capabilities, local name, and supported features like Low Energy (LE) and BR/EDR.

It's often used for scripting and advanced diagnostics, offering more granular control over adapter settings compared to higher-level tools like bluetoothctl for certain operations. It is an essential tool for developers and system administrators working with Bluetooth.

• Most btmgmt commands require root privileges or appropriate capabilities (e.g., CAP_NET_ADMIN) to modify adapter settings.
• It primarily manages the Bluetooth adapter itself, not individual paired devices. For device-centric operations like connecting to specific devices or managing trusted devices, bluetoothctl is generally more suitable.
• Some commands might require the Bluetooth adapter to be powered on (e.g., power on) before they can be executed successfully.

Here are some common ways btmgmt is used:

• btmgmt info: Get a quick overview of the current adapter status and capabilities.
• btmgmt power on: Enable the Bluetooth adapter.
• btmgmt discov on: Make the adapter discoverable by other devices.
• btmgmt scan on: Start scanning for nearby Bluetooth devices continuously.
• btmgmt find: Perform a one-time scan and list found devices.
• btmgmt -i hci1 power off: Turn off a specific adapter if multiple are present (e.g., hci1).

btmgmt directly leverages the BlueZ Management API. This is a D-Bus interface that provides a clean, standardized way for applications to interact with Bluetooth adapters and their settings at a lower level than the GATT/Profile APIs. This makes btmgmt a powerful tool for developers and system integrators who need precise control over Bluetooth hardware.

btmgmt was introduced as part of the BlueZ stack to provide a more consistent and modern interface for Bluetooth adapter management, gradually replacing older, less maintained tools like hciconfig and hcitool. Its development is closely tied to the evolution of the BlueZ project, which is the official Linux Bluetooth protocol stack. It aims to offer direct control over the kernel's Bluetooth subsystem through the management interface, aligning with contemporary D-Bus-based service architectures.

bluetoothctl(1), hciconfig(8), hcitool(1), systemctl(1)