mirror of
https://git.kernel.org/pub/scm/bluetooth/bluez.git
synced 2024-11-15 00:04:29 +08:00
2f3f63467d
This adds bluetoothctl-assistant.rst which is then converted to bluetoothctl-assistant.1 using rst2man.
364 lines
7.0 KiB
ReStructuredText
364 lines
7.0 KiB
ReStructuredText
============
|
|
bluetoothctl
|
|
============
|
|
|
|
-----------------------------------
|
|
Bluetooth Control Command Line Tool
|
|
-----------------------------------
|
|
|
|
:Version: BlueZ
|
|
:Copyright: Free use of this software is granted under the terms of the GNU
|
|
Lesser General Public Licenses (LGPL).
|
|
:Date: November 2022
|
|
:Manual section: 1
|
|
:Manual group: Linux System Administration
|
|
|
|
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.
|
|
|
|
.. code::
|
|
|
|
bluetoothctl <<EOF
|
|
list
|
|
show
|
|
EOF
|
|
|
|
|
|
RESOURCES
|
|
=========
|
|
|
|
http://www.bluez.org
|
|
|
|
REPORTING BUGS
|
|
==============
|
|
|
|
linux-bluetooth@vger.kernel.org
|