Manpages - bluetoothctl.1

NAME

bluetoothctl - Bluetooth Control Command Line Tool

SYNOPSIS

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

DESCRIPTION

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.

OPTIONS

-a*/ capability,/ –agent*/ capability/

Register agent handler: <capability>

-e, –endpoints

Register Media endpoints

-m, –monitor

Enable monitor output

-t*/ seconds,/ –timeout*/ seconds/

Timeout in seconds for non-interactive mode

-v, –version

Display version

-h, –help

Display help

COMMANDS

list

List available controllers.

Usage

# list

show

Controller information.

Usage

# show [ctrl]

select

Select default controller.

Usage

# select <ctrl>

devices

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

Usage

# devices [Paired/Bonded/Trusted/Connected]

system-alias

Set controller alias.

Usage

# system-alias <name>

reset-alias

Reset controller alias.

Usage

# reset-alias

power

Set controller power.

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

Usage

# power <on/off>

advertise

Enable/disable advertising with given type.

If you exit the program advertising will be disabled.

When advertising the controller should advertise with random address but may 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.

Usage

# advertise <on/off/type>

set-alias

Set device alias.

Usage

# set-alias <alias>

scan

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.

Note the following when scanning:

When scanning the controller will use a random address that is not resolvable so the public address is not leaked. A new random address is created every time scan on is used.

When turning on scanning the device will start receiving advertising reports of what devices are advertising.

The filtering of duplicate advertising reports may be enabled depending on the filtering settings.

Device objects found during a scan session will only be persisted if they are connected/paired otherwise they are removed after some time.

Usage

# scan <on/off/bredr/le>

pair

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.

Usage

# pair <dev>

pairable

Set controller pairable mode.

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

Usage

# pairable <on/off>

discoverable

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.

Usage

# discoverable <on/off>

discoverable-timeout

Set discoverable timeout.

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

Usage

# discoverable-timeout [value]

agent

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.

Usage

# agent <on/off/capability>

default-agent

Set current agent as the default one.

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

Usage

# default-agent

trust

Trust device.

Usage

# trust <dev>

untrust

Untrust device.

Usage

# untrust <dev>

block

Block device.

Usage

# block <dev>

unblock

Unblock device

Usage

# unblock <dev>

remove

Remove device.

Usage

# remove <dev>

connect

Connect device.

This will initiate a connection to a device.

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.

Usage

# connect <dev>

disconnect

Disconnect device.

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

Usage

# disconnect <dev>

info

Device information.

Usage

# info <dev>

ADVERTISE SUBMENU

See bluetoothctl-advertise(1).

MONITOR SUBMENU

See bluetoothctl-monitor(1)

SCAN SUBMENU

See bluetoothctl-scan(1)

GATT SUBMENU

See bluetoothctl-gatt(1)

ADMIN SUBMENU

See bluetoothctl-admin(1)

PLAYER SUBMENU

See bluetoothctl-player(1)

ENDPOINT SUBMENU

See bluetoothctl-endpoint(1)

TRANSPORT SUBMENU

See bluetoothctl-transport(1)

MANAGEMENT SUBMENU

See bluetoothctl-mgmt(1)

ASSISTANT SUBMENU

See bluetoothctl-assistant(1)

AUTOMATION

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

RESOURCES

<http://www.bluez.org>

REPORTING BUGS

<[email protected]>

COPYRIGHT

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