Manual Page Search Parameters
BLUETOOTHCTL(1) Linux System Administration BLUETOOTHCTL(1)

bluetoothctl - Bluetooth Control Command Line Tool

bluetoothctl [-a capability] [-e] [-m] [-t seconds] [-v] [-h]

bluetoothctl(1) interactive bluetooth control tool. The tool works with Bluetooth Classic (BR/EDR) and Bluetooth Low Energy (LE) controllers.

The tool is menu driven but can be automated from the command line. Examples are given in the automation section.

This tool communicates with the BlueZ daemon via D-Bus, primarily using the org.bluez.Adapter(5) and org.bluez.Device(5) interfaces. Each command documents which D-Bus interface and method/property it uses.

Register agent handler: <capability>
Register Media endpoints
Enable monitor output
Timeout in seconds for non-interactive mode
Display version
Display help

List available controllers.

> list
> list


Controller information.

> show [ctrl]
org.bluez.Adapter(5) properties
[ctrl]
Bluetooth controller address
> show

> show 00:11:22:33:44:55


Select default controller.

> select <ctrl>
<ctrl>
Bluetooth controller address
> select 00:11:22:33:44:55


List available devices, with an optional property as the filter.

> devices [Paired/Bonded/Trusted/Connected]
[Paired/Bonded/Trusted/Connected]
Filter to show only devices with specific property (optional)
> devices

> devices Paired

> devices Bonded

> devices Trusted

> devices Connected


Set controller alias.

> system-alias <name>
org.bluez.Adapter(5) property Alias
<name>
New alias name for the Bluetooth controller (required)
> system-alias "My Desktop Bluetooth"

> system-alias MyLaptop

> system-alias "Home-Office-PC"


Reset controller alias.

> reset-alias
org.bluez.Adapter(5) property Alias
> reset-alias


Set controller power.

When the controller is powered off, the USB port the controller is attached to is put into a suspend state.

> power <on/off>
org.bluez.Adapter(5) property Powered
<on/off>
Power state - "on" to enable or "off" to disable the controller (required)
> power on

> power off


Enable/disable advertising with given type.

When the controller advertises an LE device (peripheral) it will generate a random address for its own privacy if the controller is capable of it, it will use its public address if it does not support the feature (address of the device).

A device can advertise if it initiated the connection to another advertising device.

> advertise <on/off/type>
org.bluez.LEAdvertisingManager(5) method RegisterAdvertisement
<on/off/type>
Advertising mode - "on", "off", "peripheral", or "broadcast" (required)
> advertise on

> advertise off

> advertise peripheral

> advertise broadcast


Set device alias.

> set-alias <alias>
org.bluez.Device(5) property Alias
<alias>
New alias name for the device (required)
> set-alias "My Headphones"

> set-alias MyMouse

> set-alias "Kitchen-Speaker"


Scan for devices.

For LE, scanning is an important requirement before connecting or pairing.

The purpose of scanning is to find devices that are advertising with their discoverable flag set (either limited or general). Once you have found the address then you can connect or pair.

> scan <on/off/bredr/le>
org.bluez.Adapter(5) methods StartDiscovery, StopDiscovery
<on/off/bredr/le>
Scan mode - "on", "off", "bredr" for Classic, or "le" for Low Energy (required)
> scan on

> scan off

> scan le

> scan bredr


Pair with device.

This will pair with a device and then trust and connect to it. If the device is already paired this will first remove the pairing.

The command can either be used while the controller is in the connected or not connected state.

If the controller is already connected then the pair command can be used without an arguments. If the controller is not connected, the pair command can be given the address of a device with an active scan report and it will initiate the connection before pairing.

Before pairing the agent must be selected to choose the authentication mechanism.

> pair [dev]
org.bluez.Device(5) method Pair
[dev]
Device MAC address (XX:XX:XX:XX:XX:XX) (optional, uses current device if omitted)
> pair 00:11:22:33:44:55

> pair AA:BB:CC:DD:EE:FF

> pair /org/bluez/hci0/dev_00_11_22_33_44_55


Set controller pairable mode.

This enables/disables pairing. If pairing is disabled then the controller will not accept any pairing requests.

> pairable <on/off>
org.bluez.Adapter(5) property Pairable
<on/off>
Pairable mode - "on" to accept or "off" to reject pairing requests (required)
> pairable on

> pairable off


Set discoverable mode.

This enables/disables discoverable mode. If discoverable is disabled then the controller will not respond to any scan requests.

In LE if discoverable if off the controller will just passively scan and not make scan requests to advertising devices. If on it will make the advertising requests.

It will use a random address if supported by the controller. The length of time "discoverable on" is valid is determined by discoverable-timeout command.

> discoverable <on/off>
org.bluez.Adapter(5) property Discoverable
<on/off>
Discoverable mode - "on" to be discoverable or "off" to be non-discoverable (required)
> discoverable on

> discoverable off


discoverable-timeout

Set discoverable timeout.

The time in seconds that "discoverable on" is valid.

> discoverable-timeout [value]
org.bluez.Adapter(5) property DiscoverableTimeout
[value]
Timeout duration in seconds for discoverable mode (0 for unlimited, optional)
> discoverable-timeout

> discoverable-timeout 30

> discoverable-timeout 120

> discoverable-timeout 300

> discoverable-timeout 0


Enable/disable agent with given capability.

This chooses the local authentication mechanism of the controller. It is needed for pairing and allows you to choose the IO capabilities of the controller.

The valid agent capabilities are: DisplayOnly, DisplayYesNo, KeyboardDisplay, KeyboardOnly, NoInputNoOutput.

> agent <on/off/auto/capability>
org.bluez.AgentManager(5) method RegisterAgent
<on/off/auto/capability>
Agent mode - "on", "off", "auto", or capability type (DisplayOnly, DisplayYesNo, KeyboardDisplay, KeyboardOnly, NoInputNoOutput) (required)
> agent on

> agent off

> agent DisplayOnly

> agent DisplayYesNo

> agent KeyboardDisplay

> agent KeyboardOnly

> agent NoInputNoOutput


Set current agent as the default one.

After selecting the agent this will make it the default agent.

> default-agent
org.bluez.AgentManager(5) method RequestDefaultAgent
> default-agent


Trust device.

> trust [dev]
org.bluez.Device(5) property Trusted
[dev]
Device MAC address (XX:XX:XX:XX:XX:XX) or object path (optional, uses current device if omitted)
> trust 00:11:22:33:44:55

> trust AA:BB:CC:DD:EE:FF

> trust /org/bluez/hci0/dev_00_11_22_33_44_55


Untrust device.

> untrust [dev]
org.bluez.Device(5) property Trusted
[dev]
Device MAC address (XX:XX:XX:XX:XX:XX) or object path (optional, uses current device if omitted)
> untrust 00:11:22:33:44:55

> untrust AA:BB:CC:DD:EE:FF

> untrust /org/bluez/hci0/dev_00_11_22_33_44_55


Block device.

> block [dev]
org.bluez.Device(5) property Blocked
[dev]
Device MAC address (XX:XX:XX:XX:XX:XX) or object path (optional, uses current device if omitted)
> block 00:11:22:33:44:55

> block AA:BB:CC:DD:EE:FF

> block /org/bluez/hci0/dev_00_11_22_33_44_55


Unblock device

> unblock [dev]
org.bluez.Device(5) property Blocked
[dev]
Device MAC address (XX:XX:XX:XX:XX:XX) or object path (optional, uses current device if omitted)
> unblock 00:11:22:33:44:55

> unblock AA:BB:CC:DD:EE:FF

> unblock /org/bluez/hci0/dev_00_11_22_33_44_55


Remove device.

> remove <dev>
org.bluez.Adapter(5) method RemoveDevice
<dev>
Device MAC address (XX:XX:XX:XX:XX:XX) or object path (required)
> remove 00:11:22:33:44:55

> remove AA:BB:CC:DD:EE:FF

> remove /org/bluez/hci0/dev_00_11_22_33_44_55


Connect device.

This will initiate a connection to a device.

By default this commands tries to connect all the profiles the remote device supports and have been flagged as auto-connectable. In case when the UUID of the remote service is given only that service will be connected. The UUID can be either a short form (16-bit UUID) or a long form (128-bit UUID). There are also some special values for well-known profiles like "a2dp-sink", "a2dp-source", "hfp-hf", "hfp-ag", "ftp" or "spp".

To connect with an LE device the controller must have an active scan report of the device it wants to connect to.

If no advertising report is received before the timeout a le-connection-abort-by-local error will be issued. In that case either try again to connect assuming the device is advertising.

> connect <dev> [uuid]
org.bluez.Device(5) methods Connect, ConnectProfile
<dev>
Device MAC address (XX:XX:XX:XX:XX:XX) or object path (required)
[uuid]
Specific service UUID to connect to (16-bit, 128-bit UUID, or profile name like "a2dp-sink", "hfp-hf", etc.) (optional)
> connect 1C:48:F9:9D:81:5C

> connect 1C:48:F9:9D:81:5C hsp-hs

> connect 1C:48:F9:9D:81:5C a2dp-sink

> connect 1C:48:F9:9D:81:5C a2dp-source

> connect 1C:48:F9:9D:81:5C hfp-hf

> connect 1C:48:F9:9D:81:5C hfp-ag

> connect 1C:48:F9:9D:81:5C ftp

> connect 1C:48:F9:9D:81:5C spp

> connect 1C:48:F9:9D:81:5C 00001108-0000-1000-8000-00805f9b34fb

> connect 1C:48:F9:9D:81:5C 0x1108

> connect 1C:48:F9:9D:81:5C 0x110E


Disconnect device.

By default this commands disconnects all profiles and then terminates the connection. In case when the UUID of the remote service is given only that service will be disconnected.

For LE when disconnecting from an active connection the device address is not needed.

> disconnect [dev] [uuid]
org.bluez.Device(5) methods Disconnect, DisconnectProfile
[dev]
Device MAC address (XX:XX:XX:XX:XX:XX) or object path (optional, uses current device if omitted)
[uuid]
Specific service UUID to disconnect from (16-bit, 128-bit UUID, or profile name) (optional)
> disconnect 1C:48:F9:9D:81:5C

> disconnect 1C:48:F9:9D:81:5C a2dp-sink

> disconnect 1C:48:F9:9D:81:5C hfp-hf

> disconnect 1C:48:F9:9D:81:5C spp

> disconnect 1C:48:F9:9D:81:5C 0x110E

> disconnect 1C:48:F9:9D:81:5C 00001108-0000-1000-8000-00805f9b34fb


Device information.

> info [dev/set]
org.bluez.Device(5) properties
[dev/set]
Device MAC address (XX:XX:XX:XX:XX:XX), object path, or DeviceSet (optional, uses current device if omitted)
> info 1C:48:F9:9D:81:5C

> info 00:11:22:33:44:55

> info /org/bluez/hci0/dev_1C_48_F9_9D_81_5C


Get/Set preferred bearer.

> bearer <dev> [last-seen/bredr/le]
org.bluez.Device(5) property PreferredBearer
<dev>
Device MAC address (XX:XX:XX:XX:XX:XX) or object path (required)
[last-seen/bredr/le]
Preferred bearer type - "last-seen", "bredr" for Classic, or "le" for Low Energy (optional)
> bearer <addr>


PreferredBearer: last-seen


    

> bearer <addr> le
[CHG] Device <addr> PreferredBearer: le
Changing le succeeded

> bearer <addr> bredr
[CHG] Device <addr> PreferredBearer: bredr
Changing bredr succeeded


See bluetoothctl-advertise(1).

See bluetoothctl-monitor(1)

See bluetoothctl-scan(1)

See bluetoothctl-gatt(1)

See bluetoothctl-admin(1)

See bluetoothctl-player(1)

See bluetoothctl-endpoint(1)

See bluetoothctl-transport(1)

See bluetoothctl-mgmt(1)

See bluetoothctl-assistant(1)

See bluetoothctl-le(1)

See bluetoothctl-bredr(1)

Two common ways to automate the tool are to use Here Docs or the program expect. Using Here Docs to show information about the Bluetooth controller.

bluetoothctl <<EOF
list
show
EOF



<http://www.bluez.org>


<linux-bluetooth@vger.kernel.org>

Free use of this software is granted under the terms of the GNU Lesser General Public Licenses (LGPL).

March 2024 BlueZ