bluetoothctl-mgmt(1) Linux System Administration bluetoothctl-mgmt(1)

bluetoothctl-mgmt - Management Submenu

bluetoothctl [--options] [mgmt.commands]

Note:

This submenu communicates directly with the kernel via the Bluetooth Management socket (mgmt), bypassing the BlueZ D-Bus API. Commands use the Bluetooth Management API defined in the kernel documentation.

Select a different index

> select <index>
<index>
Controller index number (0-based) to select
> select 0
> select 1
> select 2

Get the MGMT Revision

> revision
> revision

List supported commands

> commands
> commands

Show configuration info

> config
> config

Show controller info

> info
> info

Show extended controller info

> extinfo
> extinfo

Power all available features

> auto-power
> auto-power

Toggle powered state

> power <on/off>
<on/off>
Power state - "on" to enable controller, "off" to disable
> power on
> power off

Toggle discoverable state

> discov <yes/no/limited> [timeout]
<yes/no/limited>
Discoverable mode - "yes" for general, "no" to disable, "limited" for limited discoverable
[timeout]
Optional timeout in seconds for discoverable mode duration
> discov yes
> discov no
> discov limited
> discov yes 30
> discov yes 120
> discov yes 300
> discov limited 60

Toggle connectable state

> connectable <on/off>
<on/off>
Connectable state - "on" to allow connections, "off" to reject
> connectable on
> connectable off

Toggle fast connectable state

> fast-conn <on/off>
<on/off>
Fast connectable state - "on" to enable fast connection mode, "off" to disable
> fast-conn on
> fast-conn off

Toggle bondable state

> bondable <on/off>
<on/off>
Bondable state - "on" to enable bonding capability, "off" to disable
> bondable on
> bondable off

Toggle bondable state

> pairable <on/off>
<on/off>
Pairable state - "on" to enable pairing capability, "off" to disable
> pairable on
> pairable off

Toggle link level security

> linksec <on/off>
<on/off>
Link level security - "on" to enable, "off" to disable
> linksec on
> linksec off

Toggle SSP mode

> ssp <on/off>
<on/off>
Secure Simple Pairing mode - "on" to enable SSP, "off" to disable
> ssp on
> ssp off

Toggle SC support

> sc <on/off/only>
<on/off/only>
Secure Connections support - "on" to enable, "off" to disable, "only" for exclusive use
> sc on
> sc off
> sc only

Toggle HS support

> hs <on/off>
<on/off>
High Speed support - "on" to enable 802.11 High Speed, "off" to disable
> hs on
> hs off

Toggle LE support

> le <on/off>
<on/off>
Low Energy support - "on" to enable LE functionality, "off" to disable
> le on
> le off

Toggle LE advertising

> advertising <on/off>
<on/off>
LE advertising state - "on" to enable advertising, "off" to disable
> advertising on
> advertising off

Toggle BR/EDR support

> bredr <on/off>
<on/off>
BR/EDR support - "on" to enable Classic Bluetooth, "off" to disable
> bredr on
> bredr off

Toggle privacy support

> privacy <on/off> [irk]
<on/off>
Privacy support - "on" to enable privacy features, "off" to disable
[irk]
Optional 32-character hexadecimal Identity Resolving Key
> privacy on
> privacy off
> privacy on 0123456789abcdef0123456789abcdef
> privacy on 1234567890abcdef1234567890abcdef

Set device major/minor class

> class <major> <minor>
<major>
Major device class code (hexadecimal)
<minor>
Minor device class code (hexadecimal)
> class 0x04 0x01
> class 0x04 0x02
> class 0x04 0x06
> class 0x04 0x0B
> class 0x01 0x01
> class 0x01 0x02
> class 0x01 0x03
> class 0x01 0x04
> class 0x02 0x01
> class 0x02 0x02
> class 0x02 0x03

Disconnect device

> disconnect [-t type] <remote address>
[-t type]
Optional address type (public, random, le_public, le_random)
<remote address>
Bluetooth address of device to disconnect
> disconnect 00:11:22:33:44:55
> disconnect AA:BB:CC:DD:EE:FF
> disconnect -t public 00:11:22:33:44:55
> disconnect -t random AA:BB:CC:DD:EE:FF
> disconnect -t le_public 11:22:33:44:55:66
> disconnect -t le_random CC:DD:EE:FF:00:11

List connections

> con
> con

Discover nearby devices

> find [-l|-b] [-L]
[-l|-b]
Discovery type - "-l" for LE only, "-b" for BR/EDR only (default: both)
[-L]
Limited discovery mode flag
> find
> find -l
> find -b
> find -L
> find -l -L
> find -b -L

find-service

Discover nearby service

> find-service [-u UUID] [-r RSSI_Threshold] [-l|-b]
[-u UUID]
Service UUID to search for (16-bit, 32-bit, or 128-bit)
[-r RSSI_Threshold]
Minimum RSSI value in dBm for device filtering
[-l|-b]
Discovery type - "-l" for LE only, "-b" for BR/EDR only
> find-service -u 0x1800
> find-service -u 0x180F
> find-service -u 12345678-1234-5678-9abc-123456789abc
> find-service -r -60
> find-service -r -80
> find-service -u 0x180F -r -70
> find-service -u 0x1800 -r -50 -l
> find-service -u 0x1101 -b
> find-service -u 0x180F -l

Stop discovery

> stop-find [-l|-b]
[-l|-b]
Discovery type to stop - "-l" for LE only, "-b" for BR/EDR only (default: all)
> stop-find
> stop-find -l
> stop-find -b

Set local name

> name <name> [shortname]
<name>
Complete local name for the controller
[shortname]
Optional shortened local name
> name "My Bluetooth Device"
> name MyComputer
> name "Home-Office-PC"
> name "My Long Device Name" MyDevice
> name "Professional Workstation" ProWork
> name "Bluetooth Audio Headset" BT-Audio

Pair with a remote device

> pair [-c cap] [-t type] <remote address>
[-c cap]
IO capability (DisplayOnly, DisplayYesNo, KeyboardOnly, NoInputNoOutput, KeyboardDisplay)
[-t type]
Address type (public, random, le_public, le_random)
<remote address>
Bluetooth address of device to pair with
> pair 00:11:22:33:44:55
> pair AA:BB:CC:DD:EE:FF
> pair -c DisplayOnly 00:11:22:33:44:55
> pair -c DisplayYesNo AA:BB:CC:DD:EE:FF
> pair -c KeyboardOnly 11:22:33:44:55:66
> pair -c NoInputNoOutput CC:DD:EE:FF:00:11
> pair -c KeyboardDisplay 22:33:44:55:66:77
> pair -t public 00:11:22:33:44:55
> pair -t random AA:BB:CC:DD:EE:FF
> pair -t le_public 11:22:33:44:55:66
> pair -t le_random CC:DD:EE:FF:00:11
> pair -c KeyboardDisplay -t le_public 00:11:22:33:44:55
> pair -c DisplayYesNo -t random AA:BB:CC:DD:EE:FF

Cancel pairing

> cancelpair [-t type] <remote address>
[-t type]
Address type (public, random, le_public, le_random)
<remote address>
Bluetooth address of device to cancel pairing with
> cancelpair 00:11:22:33:44:55
> cancelpair AA:BB:CC:DD:EE:FF
> cancelpair -t public 00:11:22:33:44:55
> cancelpair -t le_random AA:BB:CC:DD:EE:FF

Unpair device

> unpair [-t type] <remote address>
[-t type]
Address type (public, random, le_public, le_random)
<remote address>
Bluetooth address of device to unpair
> unpair 00:11:22:33:44:55
> unpair AA:BB:CC:DD:EE:FF
> unpair -t public 00:11:22:33:44:55
> unpair -t le_public 11:22:33:44:55:66
> unpair -t le_random CC:DD:EE:FF:00:11

Load Link Keys

> keys
> keys

Load Long Term Keys

> ltks
> ltks

Load Identity Resolving Keys

> irks [--local index] [--file file path]
[--local index]
Local controller index to use
[--file file path]
Custom IRK configuration file path
> irks
> irks --local 0
> irks --local 1
> irks --file /etc/bluetooth/irks.conf
> irks --file /home/user/bluetooth_irks.txt
> irks --local 0 --file /etc/bluetooth/hci0_irks.conf

Block Device

> block [-t type] <remote address>
[-t type]
Address type (public, random, le_public, le_random)
<remote address>
Bluetooth address of device to block
> block 00:11:22:33:44:55
> block AA:BB:CC:DD:EE:FF
> block -t public 00:11:22:33:44:55
> block -t random AA:BB:CC:DD:EE:FF
> block -t le_public 11:22:33:44:55:66
> block -t le_random CC:DD:EE:FF:00:11

Unblock Device

> unblock [-t type] <remote address>
[-t type]
Address type (public, random, le_public, le_random)
<remote address>
Bluetooth address of device to unblock
> unblock 00:11:22:33:44:55
> unblock AA:BB:CC:DD:EE:FF
> unblock -t public 00:11:22:33:44:55
> unblock -t random AA:BB:CC:DD:EE:FF
> unblock -t le_public 11:22:33:44:55:66
> unblock -t le_random CC:DD:EE:FF:00:11

Add UUID

> add-uuid <UUID> <service class hint>
<UUID>
Service UUID (16-bit, 32-bit, or 128-bit format)
<service class hint>
Service class hint bitmask (hexadecimal)
> add-uuid 0x1101 0x100000
> add-uuid 0x110E 0x200000
> add-uuid 0x111E 0x200000
> add-uuid 12345678-1234-5678-9abc-123456789abc 0x000000
> add-uuid ABCD1234-ABCD-1234-ABCD-123456789ABC 0x100000
> add-uuid 0x1800 0x000000
> add-uuid 0x180F 0x000000

Remove UUID

> rm-uuid <UUID>
<UUID>
Service UUID to remove (16-bit, 32-bit, or 128-bit format)
> rm-uuid 0x1101
> rm-uuid 0x110E
> rm-uuid 12345678-1234-5678-9abc-123456789abc

Clear UUIDs

> clr-uuids
> clr-uuids

Local OOB data

> local-oob
> local-oob

Remote OOB data

> remote-oob [-t <addr_type>] [-r <rand192>] [-h <hash192>] [-R <rand256>] [-H <hash256>] <addr>
[-t <addr_type>]
Address type (public, random, le_public, le_random)
[-r <rand192>]
P-192 random value (32 hexadecimal characters)
[-h <hash192>]
P-192 hash value (32 hexadecimal characters)
[-R <rand256>]
P-256 random value (64 hexadecimal characters)
[-H <hash256>]
P-256 hash value (64 hexadecimal characters)
<addr>
Remote device Bluetooth address
> remote-oob 00:11:22:33:44:55
> remote-oob -r 0123456789abcdef0123456789abcdef -h fedcba9876543210fedcba9876543210 00:11:22:33:44:55
> remote-oob -R 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef -H fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210 AA:BB:CC:DD:EE:FF
> remote-oob -t le_public 11:22:33:44:55:66
> remote-oob -t le_random CC:DD:EE:FF:00:11
> remote-oob -t public -r 0123456789abcdef0123456789abcdef -h fedcba9876543210fedcba9876543210 -R 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef -H fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210 00:11:22:33:44:55

Set Device ID

> did <source>:<vendor>:<product>:<version>
<source>:<vendor>:<product>:<version>
Device ID in format source:vendor:product:version (all hexadecimal)
> did 0x0002:0x1D6B:0x0001:0x0100
> did 0x0002:0x04B4:0x1234:0x0200
> did 0x0001:0x000F:0x0001:0x0100
> did 0x0001:0x004C:0x0001:0x0100
> did 0x0002:0xFFFF:0x1234:0x5678
> did 0x0001:0x05F1:0xABCD:0x0001

Set static address

> static-addr <address>
<address>
Static random Bluetooth address (must have bits 47-46 set to 11)
> static-addr C0:00:00:00:00:01
> static-addr D0:11:22:33:44:55
> static-addr E0:AA:BB:CC:DD:EE

Set public address

> public-addr <address>
<address>
Public Bluetooth address to set for the controller
> public-addr 00:11:22:33:44:55
> public-addr AA:BB:CC:DD:EE:FF
> public-addr 12:34:56:78:9A:BC

External configuration

> ext-config <on/off>
<on/off>
External configuration - "on" to enable external config, "off" to disable
> ext-config on
> ext-config off

Toggle debug keys

> debug-keys <on/off>
<on/off>
Debug keys support - "on" to enable debug keys, "off" to disable
> debug-keys on
> debug-keys off

Get connection information

> conn-info [-t type] <remote address>
[-t type]
Address type (public, random, le_public, le_random)
<remote address>
Bluetooth address of connected device
> conn-info 00:11:22:33:44:55
> conn-info AA:BB:CC:DD:EE:FF
> conn-info -t public 00:11:22:33:44:55
> conn-info -t le_public 11:22:33:44:55:66
> conn-info -t le_random CC:DD:EE:FF:00:11

Set IO Capability

> io-cap <cap>
<cap>
IO capability (DisplayOnly, DisplayYesNo, KeyboardOnly, NoInputNoOutput, KeyboardDisplay)
> io-cap DisplayOnly
> io-cap DisplayYesNo
> io-cap KeyboardOnly
> io-cap NoInputNoOutput
> io-cap KeyboardDisplay

Set Scan Parameters

> scan-params <interval> <window>
<interval>
Scan interval in hexadecimal (0x0004 to 0x4000, units of 0.625ms)
<window>
Scan window in hexadecimal (0x0004 to 0x4000, units of 0.625ms)
> scan-params 0x0010 0x0010
> scan-params 0x0020 0x0020
> scan-params 0x0060 0x0030
> scan-params 0x0100 0x0050
> scan-params 0x0800 0x0012
> scan-params 0x1000 0x0020

Get Clock Information

> get-clock [address]
[address]
Optional remote device Bluetooth address (omit for local clock)
> get-clock
> get-clock 00:11:22:33:44:55
> get-clock AA:BB:CC:DD:EE:FF

Add Device

> add-device [-a action] [-t type] <address>
[-a action]
Device action (auto, allow, deny) - "auto" for auto-connect, "allow" for allow-only, "deny" to block
[-t type]
Address type (public, random, le_public, le_random)
<address>
Bluetooth address of device to add
> add-device 00:11:22:33:44:55
> add-device AA:BB:CC:DD:EE:FF
> add-device -a auto 00:11:22:33:44:55
> add-device -a allow 11:22:33:44:55:66
> add-device -a deny CC:DD:EE:FF:00:11
> add-device -t public 00:11:22:33:44:55
> add-device -t random AA:BB:CC:DD:EE:FF
> add-device -t le_public 11:22:33:44:55:66
> add-device -t le_random CC:DD:EE:FF:00:11
> add-device -a auto -t le_public 00:11:22:33:44:55
> add-device -a allow -t random AA:BB:CC:DD:EE:FF
> add-device -a deny -t le_random CC:DD:EE:FF:00:11

Remove Device

> del-device [-t type] <address>
[-t type]
Address type (public, random, le_public, le_random)
<address>
Bluetooth address of device to remove
> del-device 00:11:22:33:44:55
> del-device AA:BB:CC:DD:EE:FF
> del-device -t public 00:11:22:33:44:55
> del-device -t random AA:BB:CC:DD:EE:FF
> del-device -t le_public 11:22:33:44:55:66
> del-device -t le_random CC:DD:EE:FF:00:11

Clear Devices

> clr-devices
> clr-devices

bredr-oob

Local OOB data (BR/EDR)

> bredr-oob
> bredr-oob

le-oob

Local OOB data (LE)

> le-oob
> le-oob

Show advertising features

> advinfo
> advinfo

Show advertising size info

> advsize [options] <instance_id>
[options]
Advertising options flags
<instance_id>
Advertising instance identifier (0-based)
> advsize 0
> advsize 1
> advsize 5

Add advertising instance

> add-adv [options] <instance_id>
[options]
Advertising options (-c connectable, -s scannable, -g general discoverable, -l limited discoverable, -m managed flags, -p TX power)
<instance_id>
Advertising instance identifier (0-based)
> add-adv 0
> add-adv 1
> add-adv 5
> add-adv -c 0
> add-adv -s 1
> add-adv -g 2
> add-adv -l 3
> add-adv -m 4
> add-adv -p 5
> add-adv -c -s 0
> add-adv -g -p 1
> add-adv -c -g -s 2

Remove advertising instance

> rm-adv <instance_id>
<instance_id>
Advertising instance identifier (0-based) to remove
> rm-adv 0
> rm-adv 1
> rm-adv 5

Clear advertising instances

> clr-adv
> clr-adv

Add extended advertising params

> add-ext-adv-params [options] <instance_id>
[options]
Extended advertising options (-c connectable, -s scannable, -d directed, -h high duty cycle, -l legacy PDU, -a anonymous, -i include TX power)
<instance_id>
Extended advertising instance identifier (0-based)
> add-ext-adv-params 0
> add-ext-adv-params 1
> add-ext-adv-params -c 0
> add-ext-adv-params -s 1
> add-ext-adv-params -d 2
> add-ext-adv-params -h 3
> add-ext-adv-params -l 4
> add-ext-adv-params -a 5
> add-ext-adv-params -i 6
> add-ext-adv-params -c -s 0
> add-ext-adv-params -c -i 1
> add-ext-adv-params -s -l 2

Add extended advertising data

> add-ext-adv-data [options] <instance_id>
[options]
Data options (-s for scan response data, -c for complete data)
<instance_id>
Extended advertising instance identifier (0-based)
> add-ext-adv-data 0
> add-ext-adv-data 1
> add-ext-adv-data -s 0
> add-ext-adv-data -s 1
> add-ext-adv-data -c 0
> add-ext-adv-data -c -s 1

Set appearance

> appearance <appearance>
<appearance>
Appearance value (16-bit integer) representing device type
> appearance 0
> appearance 64
> appearance 128
> appearance 832
> appearance 833
> appearance 834
> appearance 835
> appearance 836
> appearance 960
> appearance 961
> appearance 962
> appearance 963
> appearance 1344
> appearance 1345
> appearance 1346
> appearance 1472
> appearance 1473
> appearance 1474

Get/Set PHY Configuration

> phy [LE1MTX] [LE1MRX] [LE2MTX] [LE2MRX] [LECODEDTX] [LECODEDRX] [BR1M1SLOT] [BR1M3SLOT] [BR1M5SLOT][EDR2M1SLOT] [EDR2M3SLOT] [EDR2M5SLOT][EDR3M1SLOT] [EDR3M3SLOT] [EDR3M5SLOT]
[PHY flags]
PHY configuration flags to enable (LE1MTX, LE1MRX, LE2MTX, LE2MRX, LECODEDTX, LECODEDRX, BR1M1SLOT, etc.)
> phy
> phy LE1MTX
> phy LE1MRX
> phy LE2MTX
> phy LE2MRX
> phy LECODEDTX
> phy LECODEDRX
> phy BR1M1SLOT
> phy BR1M3SLOT
> phy BR1M5SLOT
> phy EDR2M1SLOT
> phy EDR2M3SLOT
> phy EDR2M5SLOT
> phy EDR3M1SLOT
> phy EDR3M3SLOT
> phy EDR3M5SLOT
> phy LE1MTX LE1MRX
> phy LE1MTX LE1MRX LE2MTX LE2MRX
> phy BR1M1SLOT EDR2M1SLOT EDR3M1SLOT

Toggle Wideband-Speech support

> wbs <on/off>
<on/off>
Wideband Speech support - "on" to enable for audio profiles, "off" to disable
> wbs on
> wbs off

Show security information

> secinfo
> secinfo

Show experimental features

> expinfo
> expinfo

Set debug feature

> exp-debug <on/off>
<on/off>
Experimental debug features - "on" to enable, "off" to disable
> exp-debug on
> exp-debug off

Set LL privacy feature

> exp-privacy <on/off>
<on/off>
Experimental Link Layer privacy - "on" to enable LL privacy features, "off" to disable
> exp-privacy on
> exp-privacy off

Set bluetooth quality report feature

> exp-quality <on/off>
<on/off>
Experimental quality reporting - "on" to enable Bluetooth quality reports, "off" to disable
> exp-quality on
> exp-quality off

Toggle codec support

> exp-offload <on/off>
<on/off>
Experimental codec offload - "on" to enable codec offload support, "off" to disable
> exp-offload on
> exp-offload off

Read System Configuration

> read-sysconfig
> read-sysconfig

Set System Configuration

> set-sysconfig <-v|-h> [options...]
<-v|-h>
Verbose output or help flag
[options...]
System configuration options (--br-page-scan-type, --br-page-scan-interval, etc.)
> set-sysconfig -h
> set-sysconfig -v
> set-sysconfig -v --br-page-scan-type=0
> set-sysconfig -v --br-page-scan-interval=0x800
> set-sysconfig -v --br-page-scan-window=0x12
> set-sysconfig -v --br-inquiry-scan-type=0
> set-sysconfig -v --br-link-supervision-timeout=0x2000
> set-sysconfig -v --le-min-connection-interval=0x18
> set-sysconfig -v --le-max-connection-interval=0x28
> set-sysconfig -v --br-page-scan-type=0 --br-page-scan-interval=0x800 --br-page-scan-window=0x12
> set-sysconfig -v --le-min-connection-interval=0x18 --le-max-connection-interval=0x28 --le-connection-latency=0

Get device flags

> get-flags [-t type] <address>
[-t type]
Address type (public, random, le_public, le_random)
<address>
Bluetooth address of device to query flags for
> get-flags 00:11:22:33:44:55
> get-flags AA:BB:CC:DD:EE:FF
> get-flags -t public 00:11:22:33:44:55
> get-flags -t random AA:BB:CC:DD:EE:FF
> get-flags -t le_public 11:22:33:44:55:66
> get-flags -t le_random CC:DD:EE:FF:00:11

Set device flags

> set-flags [-f flags] [-t type] <address>
[-f flags]
Device flags bitmask in hexadecimal (0x01=remote wake, 0x02=privacy)
[-t type]
Address type (public, random, le_public, le_random)
<address>
Bluetooth address of device to set flags for
> set-flags 00:11:22:33:44:55
> set-flags AA:BB:CC:DD:EE:FF
> set-flags -f 0x01 00:11:22:33:44:55
> set-flags -f 0x02 AA:BB:CC:DD:EE:FF
> set-flags -f 0x03 11:22:33:44:55:66
> set-flags -f 0x01 -t public 00:11:22:33:44:55
> set-flags -f 0x02 -t le_public 11:22:33:44:55:66
> set-flags -f 0x03 -t le_random CC:DD:EE:FF:00:11
> set-flags -f 0x00 00:11:22:33:44:55
> set-flags -f 0x00 -t le_public 11:22:33:44:55:66

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).

July 2023 BlueZ