From c623de844c88a4058df2e027346f82ff38dca0fc Mon Sep 17 00:00:00 2001 From: Paul Otto Date: Sun, 10 Dec 2023 09:43:32 -0500 Subject: [PATCH] client: Add initial manpage of bluetoothctl This page was accidently not added in the recent documentation update. --- Makefile.tools | 4 +- client/bluetoothctl.rst | 358 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 361 insertions(+), 1 deletion(-) create mode 100644 client/bluetoothctl.rst diff --git a/Makefile.tools b/Makefile.tools index 8d8dbe268..e541084e9 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 000000000..3a223ef3b --- /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: +-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 ** + +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 ** + +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 ** + +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 ** + +set-alias +--------- + +Set device alias. + +:Usage: **# set-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 ** + +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 ** + +pairable +-------- + +Set controller pairable mode. + +This enables/disables pairing. If pairing is disabled then the controller will +not accept any pairing requests. + +:Usage: **# pairable ** + +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 ** + +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 ** + +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 ** + +untrust +------- + +Untrust device. + +:Usage: **# untrust ** + +block +----- + +Block device. + +:Usage: **# block ** + +unblock +------- +Unblock device + +:Usage: **# unblock ** + +remove +------ + +Remove device. + +:Usage: **# remove ** + +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 ** + +disconnect +---------- + +Disconnect device. + +For LE when disconnecting from an active connection the device address is not +needed. + +:Usage: **# disconnect ** + +info +---- + +Device information. + +:Usage: **# info ** + + +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 <