Diff between eb07ec1f6ffb57f41edbedaeb0da9eb1bd11be28 and c623de844c88a4058df2e027346f82ff38dca0fc

Changed Files

File Additions Deletions Status
Makefile.tools +3 -1 modified
client/bluetoothctl.rst +358 -0 added

Full Patch

diff --git a/Makefile.tools b/Makefile.tools
index 8d8dbe2..e541084 100644
--- a/Makefile.tools
+++ b/Makefile.tools
@@ -348,7 +348,8 @@ profiles_iap_iapd_LDADD = gdbus/libgdbus-internal.la $(GLIB_LIBS) $(DBUS_LIBS)
 
 if MANPAGES
 man_MANS += tools/rctest.1 tools/l2ping.1 tools/btattach.1 tools/isotest.1 \
-		tools/btmgmt.1 client/bluetoothctl-mgmt.1 \
+		tools/btmgmt.1 client/bluetoothctl.1 \
+		client/bluetoothctl-mgmt.1 \
 		client/bluetoothctl-monitor.1 client/bluetoothctl-admin.1 \
 		client/bluetoothctl-advertise.1 client/bluetoothctl-endpoint.1 \
 		client/bluetoothctl-gatt.1 client/bluetoothctl-player.1 \
@@ -475,6 +476,7 @@ manual_pages += tools/hciattach.1 tools/hciconfig.1 \
 			tools/rfcomm.1 tools/sdptool.1 tools/ciptool.1 \
 			tools/rctest.1 tools/l2ping.1 tools/btattach.1 \
 			tools/bdaddr.1 tools/isotest.1 tools/btmgmt.1 \
+			client/bluetoothctl.1 \
 			client/bluetoothctl-mgmt.1 \
 			client/bluetoothctl-monitor.1 \
 			client/bluetoothctl-admin.1 \
diff --git a/client/bluetoothctl.rst b/client/bluetoothctl.rst
new file mode 100644
index 0000000..3a223ef
--- /dev/null
+++ b/client/bluetoothctl.rst
@@ -0,0 +1,358 @@
+============
+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)**
+
+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:: bash
+
+   bluetoothctl <<EOF
+   list
+   show
+   EOF
+
+
+RESOURCES
+=========
+
+http://www.bluez.org
+
+REPORTING BUGS
+==============
+
+linux-bluetooth@vger.kernel.org