* [PATCH BlueZ v2 01/35] doc/bluetoothctl: Add :Uses: fields and document arguments
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 20:37 ` doc: Add cross-references between bluetoothctl and D-Bus API documentation bluez.test.bot
2026-01-30 19:38 ` [PATCH BlueZ v2 02/35] doc/bluetoothctl-mgmt: Add :Uses: fields and document arguments Luiz Augusto von Dentz
` (34 subsequent siblings)
35 siblings, 1 reply; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
doc/bluetoothctl.rst | 250 ++++++++++++++++++++++++++++++++++++++-----
1 file changed, 223 insertions(+), 27 deletions(-)
diff --git a/doc/bluetoothctl.rst b/doc/bluetoothctl.rst
index f8d6c3457977..0c55092b880f 100644
--- a/doc/bluetoothctl.rst
+++ b/doc/bluetoothctl.rst
@@ -28,6 +28,10 @@ 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.
+This tool communicates with the BlueZ daemon via D-Bus, primarily using the
+**org.bluez.Adapter(5)** and **org.bluez.Device(5)** interfaces. Each command
+documents which D-Bus interface and method/property it uses.
+
OPTIONS
=======
@@ -48,6 +52,8 @@ list
List available controllers.
:Usage: **> list**
+:Example Display all Bluetooth controllers available on the system:
+ | **> list**
show
----
@@ -55,6 +61,12 @@ show
Controller information.
:Usage: **> show [ctrl]**
+:Uses: **org.bluez.Adapter(5)** properties
+:[ctrl]: Bluetooth controller address
+:Example Display information for currently selected controller:
+ | **> show**
+:Example Show information for controller 00:11:22:33:44:55:
+ | **> show 00:11:22:33:44:55**
select
------
@@ -62,6 +74,9 @@ select
Select default controller.
:Usage: **> select <ctrl>**
+:<ctrl>: Bluetooth controller address
+:Example Select controller 00:11:22:33:44:55:
+ | **> select 00:11:22:33:44:55**
devices
-------
@@ -69,6 +84,17 @@ devices
List available devices, with an optional property as the filter.
:Usage: **> devices [Paired/Bonded/Trusted/Connected]**
+:[Paired/Bonded/Trusted/Connected]: Filter to show only devices with specific property (optional)
+:Example List all discovered devices:
+ | **> devices**
+:Example List only paired devices:
+ | **> devices Paired**
+:Example List only bonded devices:
+ | **> devices Bonded**
+:Example List only trusted devices:
+ | **> devices Trusted**
+:Example List only currently connected devices:
+ | **> devices Connected**
system-alias
------------
@@ -76,6 +102,14 @@ system-alias
Set controller alias.
:Usage: **> system-alias <name>**
+:Uses: **org.bluez.Adapter(5)** property **Alias**
+:<name>: New alias name for the Bluetooth controller (required)
+:Example Set controller alias with spaces (note quotes):
+ | **> system-alias "My Desktop Bluetooth"**
+:Example Set controller alias without spaces:
+ | **> system-alias MyLaptop**
+:Example Set controller alias with hyphens:
+ | **> system-alias "Home-Office-PC"**
reset-alias
-----------
@@ -83,6 +117,9 @@ reset-alias
Reset controller alias.
:Usage: **> reset-alias**
+:Uses: **org.bluez.Adapter(5)** property **Alias**
+:Example Reset controller alias to default (usually the hostname):
+ | **> reset-alias**
power
-----
@@ -93,15 +130,20 @@ When the controller is powered off, the USB port the controller is attached to
is put into a suspend state.
:Usage: **> power <on/off>**
+:Uses: **org.bluez.Adapter(5)** property **Powered**
+:<on/off>: Power state - "on" to enable or "off" to disable the controller (required)
+:Example Turn on the Bluetooth controller:
+ | **> power on**
+:Example Turn off the Bluetooth controller:
+ | **> power 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
+When the controller advertises an LE device (peripheral) it will generate a
+random address for its own privacy if the controller is capable of it, it will
use its public address if it does not support the feature (address of the
device).
@@ -109,6 +151,16 @@ A device can advertise if it initiated the connection to another advertising
device.
:Usage: **> advertise <on/off/type>**
+:Uses: **org.bluez.LEAdvertisingManager(5)** method **RegisterAdvertisement**
+:<on/off/type>: Advertising mode - "on", "off", "peripheral", or "broadcast" (required)
+:Example Enable basic LE advertising:
+ | **> advertise on**
+:Example Disable LE advertising:
+ | **> advertise off**
+:Example Advertise as peripheral device:
+ | **> advertise peripheral**
+:Example Advertise as broadcast source:
+ | **> advertise broadcast**
set-alias
---------
@@ -116,6 +168,14 @@ set-alias
Set device alias.
:Usage: **> set-alias <alias>**
+:Uses: **org.bluez.Device(5)** property **Alias**
+:<alias>: New alias name for the device (required)
+:Example Set device alias with spaces (note quotes):
+ | **> set-alias "My Headphones"**
+:Example Set device alias without spaces:
+ | **> set-alias MyMouse**
+:Example Set device alias with hyphens:
+ | **> set-alias "Kitchen-Speaker"**
scan
----
@@ -128,19 +188,17 @@ 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>**
+:Uses: **org.bluez.Adapter(5)** methods **StartDiscovery**, **StopDiscovery**
+:<on/off/bredr/le>: Scan mode - "on", "off", "bredr" for Classic, or "le" for Low Energy (required)
+:Example Start scanning for all device types (LE + Classic):
+ | **> scan on**
+:Example Stop scanning:
+ | **> scan off**
+:Example Scan for Low Energy devices only:
+ | **> scan le**
+:Example Scan for BR/EDR (Classic) devices only:
+ | **> scan bredr**
pair
----
@@ -161,7 +219,15 @@ connection before pairing.
Before pairing the agent must be selected to choose the authentication
mechanism.
-:Usage: **> pair <dev>**
+:Usage: **> pair [dev]**
+:Uses: **org.bluez.Device(5)** method **Pair**
+:[dev]: Device MAC address (XX:XX:XX:XX:XX:XX) (optional, uses current device if omitted)
+:Example Pair with device using MAC address:
+ | **> pair 00:11:22:33:44:55**
+:Example Pair with another device:
+ | **> pair AA:BB:CC:DD:EE:FF**
+:Example Pair using device object path:
+ | **> pair /org/bluez/hci0/dev_00_11_22_33_44_55**
pairable
--------
@@ -172,6 +238,12 @@ This enables/disables pairing. If pairing is disabled then the controller will
not accept any pairing requests.
:Usage: **> pairable <on/off>**
+:Uses: **org.bluez.Adapter(5)** property **Pairable**
+:<on/off>: Pairable mode - "on" to accept or "off" to reject pairing requests (required)
+:Example Enable pairing (accept pairing requests):
+ | **> pairable on**
+:Example Disable pairing (reject pairing requests):
+ | **> pairable off**
discoverable
------------
@@ -189,6 +261,12 @@ 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>**
+:Uses: **org.bluez.Adapter(5)** property **Discoverable**
+:<on/off>: Discoverable mode - "on" to be discoverable or "off" to be non-discoverable (required)
+:Example Make controller discoverable to other devices:
+ | **> discoverable on**
+:Example Make controller non-discoverable:
+ | **> discoverable off**
discoverable-timeout
--------------------
@@ -198,6 +276,18 @@ Set discoverable timeout.
The time in seconds that "discoverable on" is valid.
:Usage: **> discoverable-timeout [value]**
+:Uses: **org.bluez.Adapter(5)** property **DiscoverableTimeout**
+:[value]: Timeout duration in seconds for discoverable mode (0 for unlimited, optional)
+:Example Show current discoverable timeout value:
+ | **> discoverable-timeout**
+:Example Set discoverable timeout to 30 seconds:
+ | **> discoverable-timeout 30**
+:Example Set discoverable timeout to 2 minutes:
+ | **> discoverable-timeout 120**
+:Example Set discoverable timeout to 5 minutes:
+ | **> discoverable-timeout 300**
+:Example Set unlimited discoverable timeout:
+ | **> discoverable-timeout 0**
agent
-----
@@ -210,7 +300,23 @@ 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>**
+:Usage: **> agent <on/off/auto/capability>**
+:Uses: **org.bluez.AgentManager(5)** method **RegisterAgent**
+:<on/off/auto/capability>: Agent mode - "on", "off", "auto", or capability type (DisplayOnly, DisplayYesNo, KeyboardDisplay, KeyboardOnly, NoInputNoOutput) (required)
+:Example Enable agent with default capability:
+ | **> agent on**
+:Example Disable agent:
+ | **> agent off**
+:Example Enable agent that can only display pairing codes:
+ | **> agent DisplayOnly**
+:Example Enable agent that can display codes and accept/reject:
+ | **> agent DisplayYesNo**
+:Example Enable agent that can display and input pairing codes:
+ | **> agent KeyboardDisplay**
+:Example Enable agent that can only input pairing codes:
+ | **> agent KeyboardOnly**
+:Example Enable agent with no input/output (JustWorks):
+ | **> agent NoInputNoOutput**
default-agent
-------------
@@ -220,33 +326,68 @@ Set current agent as the default one.
After selecting the agent this will make it the default agent.
:Usage: **> default-agent**
+:Uses: **org.bluez.AgentManager(5)** method **RequestDefaultAgent**
+:Example Set the current agent as default:
+ | **> default-agent**
trust
-----
Trust device.
-:Usage: **> trust <dev>**
+:Usage: **> trust [dev]**
+:Uses: **org.bluez.Device(5)** property **Trusted**
+:[dev]: Device MAC address (XX:XX:XX:XX:XX:XX) or object path (optional, uses current device if omitted)
+:Example Trust device using MAC address:
+ | **> trust 00:11:22:33:44:55**
+:Example Trust another device:
+ | **> trust AA:BB:CC:DD:EE:FF**
+:Example Trust device using object path:
+ | **> trust /org/bluez/hci0/dev_00_11_22_33_44_55**
untrust
-------
Untrust device.
-:Usage: **> untrust <dev>**
+:Usage: **> untrust [dev]**
+:Uses: **org.bluez.Device(5)** property **Trusted**
+:[dev]: Device MAC address (XX:XX:XX:XX:XX:XX) or object path (optional, uses current device if omitted)
+:Example Remove trust from device using MAC address:
+ | **> untrust 00:11:22:33:44:55**
+:Example Remove trust from another device:
+ | **> untrust AA:BB:CC:DD:EE:FF**
+:Example Remove trust using object path:
+ | **> untrust /org/bluez/hci0/dev_00_11_22_33_44_55**
block
-----
Block device.
-:Usage: **> block <dev>**
+:Usage: **> block [dev]**
+:Uses: **org.bluez.Device(5)** property **Blocked**
+:[dev]: Device MAC address (XX:XX:XX:XX:XX:XX) or object path (optional, uses current device if omitted)
+:Example Block device using MAC address:
+ | **> block 00:11:22:33:44:55**
+:Example Block another device:
+ | **> block AA:BB:CC:DD:EE:FF**
+:Example Block device using object path:
+ | **> block /org/bluez/hci0/dev_00_11_22_33_44_55**
unblock
-------
Unblock device
-:Usage: **> unblock <dev>**
+:Usage: **> unblock [dev]**
+:Uses: **org.bluez.Device(5)** property **Blocked**
+:[dev]: Device MAC address (XX:XX:XX:XX:XX:XX) or object path (optional, uses current device if omitted)
+:Example Unblock device using MAC address:
+ | **> unblock 00:11:22:33:44:55**
+:Example Unblock another device:
+ | **> unblock AA:BB:CC:DD:EE:FF**
+:Example Unblock device using object path:
+ | **> unblock /org/bluez/hci0/dev_00_11_22_33_44_55**
remove
------
@@ -254,6 +395,14 @@ remove
Remove device.
:Usage: **> remove <dev>**
+:Uses: **org.bluez.Adapter(5)** method **RemoveDevice**
+:<dev>: Device MAC address (XX:XX:XX:XX:XX:XX) or object path (required)
+:Example Remove device using MAC address:
+ | **> remove 00:11:22:33:44:55**
+:Example Remove another device:
+ | **> remove AA:BB:CC:DD:EE:FF**
+:Example Remove device using object path:
+ | **> remove /org/bluez/hci0/dev_00_11_22_33_44_55**
connect
-------
@@ -277,10 +426,31 @@ 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> [uuid]**
-:Example: **> connect 1C:48:F9:9D:81:5C**
-:Example: **> connect 1C:48:F9:9D:81:5C hsp-hs**
-:Example: **> connect 1C:48:F9:9D:81:5C 00001108-0000-1000-8000-00805f9b34fb**
-:Example: **> connect 1C:48:F9:9D:81:5C 0x1108**
+:Uses: **org.bluez.Device(5)** methods **Connect**, **ConnectProfile**
+:<dev>: Device MAC address (XX:XX:XX:XX:XX:XX) or object path (required)
+:[uuid]: Specific service UUID to connect to (16-bit, 128-bit UUID, or profile name like "a2dp-sink", "hfp-hf", etc.) (optional)
+:Example Connect to device (all supported profiles):
+ | **> connect 1C:48:F9:9D:81:5C**
+:Example Connect to HSP Headset profile:
+ | **> connect 1C:48:F9:9D:81:5C hsp-hs**
+:Example Connect to A2DP Sink profile:
+ | **> connect 1C:48:F9:9D:81:5C a2dp-sink**
+:Example Connect to A2DP Source profile:
+ | **> connect 1C:48:F9:9D:81:5C a2dp-source**
+:Example Connect to HFP Hands-Free profile:
+ | **> connect 1C:48:F9:9D:81:5C hfp-hf**
+:Example Connect to HFP Audio Gateway profile:
+ | **> connect 1C:48:F9:9D:81:5C hfp-ag**
+:Example Connect to File Transfer Profile:
+ | **> connect 1C:48:F9:9D:81:5C ftp**
+:Example Connect to Serial Port Profile:
+ | **> connect 1C:48:F9:9D:81:5C spp**
+:Example Connect using full 128-bit UUID (HSP):
+ | **> connect 1C:48:F9:9D:81:5C 00001108-0000-1000-8000-00805f9b34fb**
+:Example Connect using short 16-bit UUID (HSP):
+ | **> connect 1C:48:F9:9D:81:5C 0x1108**
+:Example Connect to A2DP profile using short UUID:
+ | **> connect 1C:48:F9:9D:81:5C 0x110E**
disconnect
----------
@@ -294,14 +464,37 @@ service will be disconnected.
For LE when disconnecting from an active connection the device address is not
needed.
-:Usage: **> disconnect <dev> [uuid]**
+:Usage: **> disconnect [dev] [uuid]**
+:Uses: **org.bluez.Device(5)** methods **Disconnect**, **DisconnectProfile**
+:[dev]: Device MAC address (XX:XX:XX:XX:XX:XX) or object path (optional, uses current device if omitted)
+:[uuid]: Specific service UUID to disconnect from (16-bit, 128-bit UUID, or profile name) (optional)
+:Example Disconnect all profiles and terminate connection:
+ | **> disconnect 1C:48:F9:9D:81:5C**
+:Example Disconnect only A2DP Sink profile:
+ | **> disconnect 1C:48:F9:9D:81:5C a2dp-sink**
+:Example Disconnect only HFP Hands-Free profile:
+ | **> disconnect 1C:48:F9:9D:81:5C hfp-hf**
+:Example Disconnect only Serial Port Profile:
+ | **> disconnect 1C:48:F9:9D:81:5C spp**
+:Example Disconnect A2DP profile using short UUID:
+ | **> disconnect 1C:48:F9:9D:81:5C 0x110E**
+:Example Disconnect HSP profile using full UUID:
+ | **> disconnect 1C:48:F9:9D:81:5C 00001108-0000-1000-8000-00805f9b34fb**
info
----
Device information.
-:Usage: **> info <dev>**
+:Usage: **> info [dev/set]**
+:Uses: **org.bluez.Device(5)** properties
+:[dev/set]: Device MAC address (XX:XX:XX:XX:XX:XX), object path, or DeviceSet (optional, uses current device if omitted)
+:Example Show detailed information for device:
+ | **> info 1C:48:F9:9D:81:5C**
+:Example Show information for another device:
+ | **> info 00:11:22:33:44:55**
+:Example Show device info using object path:
+ | **> info /org/bluez/hci0/dev_1C_48_F9_9D_81_5C**
bearer
------
@@ -309,6 +502,9 @@ bearer
Get/Set preferred bearer.
:Usage: **> bearer <dev> [last-seen/bredr/le]**
+:Uses: **org.bluez.Device(5)** property **PreferredBearer**
+:<dev>: Device MAC address (XX:XX:XX:XX:XX:XX) or object path (required)
+:[last-seen/bredr/le]: Preferred bearer type - "last-seen", "bredr" for Classic, or "le" for Low Energy (optional)
:Example get preferred bearer:
| > bearer <addr>
| PreferredBearer: last-seen
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 02/35] doc/bluetoothctl-mgmt: Add :Uses: fields and document arguments
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 01/35] doc/bluetoothctl: Add :Uses: fields and document arguments Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 03/35] doc/bluetoothctl-admin: " Luiz Augusto von Dentz
` (33 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
doc/bluetoothctl-mgmt.rst | 743 +++++++++++++++++++++++++++++++++++++-
1 file changed, 738 insertions(+), 5 deletions(-)
diff --git a/doc/bluetoothctl-mgmt.rst b/doc/bluetoothctl-mgmt.rst
index cf252f3a5b87..0ff16e4d268e 100644
--- a/doc/bluetoothctl-mgmt.rst
+++ b/doc/bluetoothctl-mgmt.rst
@@ -18,6 +18,11 @@ SYNOPSIS
**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.
+
Mgmt Commands
=============
@@ -27,6 +32,13 @@ select
Select a different index
:Usage: **> select <index>**
+:<index>: Controller index number (0-based) to select
+:Example Select controller index 0 (hci0):
+ | **> select 0**
+:Example Select controller index 1 (hci1):
+ | **> select 1**
+:Example Select controller index 2 (hci2):
+ | **> select 2**
revision
--------
@@ -34,6 +46,8 @@ revision
Get the MGMT Revision
:Usage: **> revision**
+:Example Display MGMT API revision information:
+ | **> revision**
commands
--------
@@ -41,6 +55,8 @@ commands
List supported commands
:Usage: **> commands**
+:Example List all supported management commands:
+ | **> commands**
config
------
@@ -48,6 +64,8 @@ config
Show configuration info
:Usage: **> config**
+:Example Show current controller configuration:
+ | **> config**
info
----
@@ -55,6 +73,8 @@ info
Show controller info
:Usage: **> info**
+:Example Show detailed controller information:
+ | **> info**
extinfo
-------
@@ -62,6 +82,8 @@ extinfo
Show extended controller info
:Usage: **> extinfo**
+:Example Show extended controller information:
+ | **> extinfo**
auto-power
----------
@@ -69,6 +91,8 @@ auto-power
Power all available features
:Usage: **> auto-power**
+:Example Automatically power on all available controller features:
+ | **> auto-power**
power
-----
@@ -76,6 +100,11 @@ power
Toggle powered state
:Usage: **> power <on/off>**
+:<on/off>: Power state - "on" to enable controller, "off" to disable
+:Example Power on the controller:
+ | **> power on**
+:Example Power off the controller:
+ | **> power off**
discov
------
@@ -83,6 +112,22 @@ discov
Toggle discoverable state
:Usage: **> 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
+:Example Make controller discoverable indefinitely:
+ | **> discov yes**
+:Example Make controller non-discoverable:
+ | **> discov no**
+:Example Enable limited discoverable mode:
+ | **> discov limited**
+:Example Make discoverable for 30 seconds:
+ | **> discov yes 30**
+:Example Make discoverable for 2 minutes:
+ | **> discov yes 120**
+:Example Make discoverable for 5 minutes:
+ | **> discov yes 300**
+:Example Limited discoverable for 60 seconds:
+ | **> discov limited 60**
connectable
-----------
@@ -90,6 +135,11 @@ connectable
Toggle connectable state
:Usage: **> connectable <on/off>**
+:<on/off>: Connectable state - "on" to allow connections, "off" to reject
+:Example Make controller connectable:
+ | **> connectable on**
+:Example Make controller non-connectable:
+ | **> connectable off**
fast-conn
---------
@@ -97,6 +147,11 @@ fast-conn
Toggle fast connectable state
:Usage: **> fast-conn <on/off>**
+:<on/off>: Fast connectable state - "on" to enable fast connection mode, "off" to disable
+:Example Enable fast connectable mode:
+ | **> fast-conn on**
+:Example Disable fast connectable mode:
+ | **> fast-conn off**
bondable
--------
@@ -104,6 +159,11 @@ bondable
Toggle bondable state
:Usage: **> bondable <on/off>**
+:<on/off>: Bondable state - "on" to enable bonding capability, "off" to disable
+:Example Enable bonding capability:
+ | **> bondable on**
+:Example Disable bonding capability:
+ | **> bondable off**
pairable
--------
@@ -111,6 +171,11 @@ pairable
Toggle bondable state
:Usage: **> pairable <on/off>**
+:<on/off>: Pairable state - "on" to enable pairing capability, "off" to disable
+:Example Enable pairing capability:
+ | **> pairable on**
+:Example Disable pairing capability:
+ | **> pairable off**
linksec
-------
@@ -118,13 +183,23 @@ linksec
Toggle link level security
:Usage: **> linksec <on/off>**
+:<on/off>: Link level security - "on" to enable, "off" to disable
+:Example Enable link level security:
+ | **> linksec on**
+:Example Disable link level security:
+ | **> linksec off**
ssp
---
Toggle SSP mode
-:Usage: **> spp <on/off>**
+:Usage: **> ssp <on/off>**
+:<on/off>: Secure Simple Pairing mode - "on" to enable SSP, "off" to disable
+:Example Enable Secure Simple Pairing:
+ | **> ssp on**
+:Example Disable Secure Simple Pairing:
+ | **> ssp off**
sc
--
@@ -132,6 +207,13 @@ sc
Toggle SC support
:Usage: **> sc <on/off/only>**
+:<on/off/only>: Secure Connections support - "on" to enable, "off" to disable, "only" for exclusive use
+:Example Enable Secure Connections support:
+ | **> sc on**
+:Example Disable Secure Connections support:
+ | **> sc off**
+:Example Use Secure Connections exclusively:
+ | **> sc only**
hs
--
@@ -139,6 +221,11 @@ hs
Toggle HS support
:Usage: **> hs <on/off>**
+:<on/off>: High Speed support - "on" to enable 802.11 High Speed, "off" to disable
+:Example Enable High Speed support:
+ | **> hs on**
+:Example Disable High Speed support:
+ | **> hs off**
le
--
@@ -146,13 +233,23 @@ le
Toggle LE support
:Usage: **> le <on/off>**
+:<on/off>: Low Energy support - "on" to enable LE functionality, "off" to disable
+:Example Enable Low Energy support:
+ | **> le on**
+:Example Disable Low Energy support:
+ | **> le off**
advertising
-----------
Toggle LE advertising
-:Usage: **> advertise <on/off>**
+:Usage: **> advertising <on/off>**
+:<on/off>: LE advertising state - "on" to enable advertising, "off" to disable
+:Example Enable LE advertising:
+ | **> advertising on**
+:Example Disable LE advertising:
+ | **> advertising off**
bredr
-----
@@ -160,6 +257,11 @@ bredr
Toggle BR/EDR support
:Usage: **> bredr <on/off>**
+:<on/off>: BR/EDR support - "on" to enable Classic Bluetooth, "off" to disable
+:Example Enable BR/EDR (Classic Bluetooth) support:
+ | **> bredr on**
+:Example Disable BR/EDR support:
+ | **> bredr off**
privacy
-------
@@ -167,6 +269,16 @@ privacy
Toggle privacy support
:Usage: **> privacy <on/off> [irk]**
+:<on/off>: Privacy support - "on" to enable privacy features, "off" to disable
+:[irk]: Optional 32-character hexadecimal Identity Resolving Key
+:Example Enable privacy with auto-generated IRK:
+ | **> privacy on**
+:Example Disable privacy:
+ | **> privacy off**
+:Example Enable privacy with specific IRK:
+ | **> privacy on 0123456789abcdef0123456789abcdef**
+:Example Enable privacy with different IRK:
+ | **> privacy on 1234567890abcdef1234567890abcdef**
class
-----
@@ -174,6 +286,30 @@ class
Set device major/minor class
:Usage: **> class <major> <minor>**
+:<major>: Major device class code (hexadecimal)
+:<minor>: Minor device class code (hexadecimal)
+:Example Set class to Audio/Video - Wearable Headset:
+ | **> class 0x04 0x01**
+:Example Set class to Audio/Video - Hands-free:
+ | **> class 0x04 0x02**
+:Example Set class to Audio/Video - Headphones:
+ | **> class 0x04 0x06**
+:Example Set class to Audio/Video - VCR:
+ | **> class 0x04 0x0B**
+:Example Set class to Computer - Desktop workstation:
+ | **> class 0x01 0x01**
+:Example Set class to Computer - Server:
+ | **> class 0x01 0x02**
+:Example Set class to Computer - Laptop:
+ | **> class 0x01 0x03**
+:Example Set class to Computer - Handheld PC/PDA:
+ | **> class 0x01 0x04**
+:Example Set class to Phone - Cellular:
+ | **> class 0x02 0x01**
+:Example Set class to Phone - Cordless:
+ | **> class 0x02 0x02**
+:Example Set class to Phone - Smart phone:
+ | **> class 0x02 0x03**
disconnect
----------
@@ -181,6 +317,20 @@ disconnect
Disconnect device
:Usage: **> disconnect [-t type] <remote address>**
+:[-t type]: Optional address type (public, random, le_public, le_random)
+:<remote address>: Bluetooth address of device to disconnect
+:Example Disconnect device using public address:
+ | **> disconnect 00:11:22:33:44:55**
+:Example Disconnect another device:
+ | **> disconnect AA:BB:CC:DD:EE:FF**
+:Example Disconnect device with public address type:
+ | **> disconnect -t public 00:11:22:33:44:55**
+:Example Disconnect device with random address type:
+ | **> disconnect -t random AA:BB:CC:DD:EE:FF**
+:Example Disconnect LE device with public address:
+ | **> disconnect -t le_public 11:22:33:44:55:66**
+:Example Disconnect LE device with random address:
+ | **> disconnect -t le_random CC:DD:EE:FF:00:11**
con
---
@@ -188,6 +338,8 @@ con
List connections
:Usage: **> con**
+:Example List all active connections:
+ | **> con**
find
----
@@ -195,6 +347,20 @@ find
Discover nearby devices
:Usage: **> find [-l|-b] [-L]**
+:[-l|-b]: Discovery type - "-l" for LE only, "-b" for BR/EDR only (default: both)
+:[-L]: Limited discovery mode flag
+:Example Discover both LE and BR/EDR devices:
+ | **> find**
+:Example Discover LE devices only:
+ | **> find -l**
+:Example Discover BR/EDR devices only:
+ | **> find -b**
+:Example Discover devices in limited mode:
+ | **> find -L**
+:Example Discover LE devices in limited mode:
+ | **> find -l -L**
+:Example Discover BR/EDR devices in limited mode:
+ | **> find -b -L**
find-service
------------
@@ -202,6 +368,27 @@ find-service
Discover nearby service
:Usage: **> 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
+:Example Find devices with Generic Access service:
+ | **> find-service -u 0x1800**
+:Example Find devices with Battery Service:
+ | **> find-service -u 0x180F**
+:Example Find devices with custom service:
+ | **> find-service -u 12345678-1234-5678-9abc-123456789abc**
+:Example Find devices with RSSI ≥ -60 dBm:
+ | **> find-service -r -60**
+:Example Find devices with RSSI ≥ -80 dBm:
+ | **> find-service -r -80**
+:Example Find Battery Service devices with RSSI ≥ -70 dBm:
+ | **> find-service -u 0x180F -r -70**
+:Example Find Generic Access on LE devices with strong signal:
+ | **> find-service -u 0x1800 -r -50 -l**
+:Example Find Serial Port Profile on BR/EDR devices:
+ | **> find-service -u 0x1101 -b**
+:Example Find Battery Service on LE devices:
+ | **> find-service -u 0x180F -l**
stop-find
---------
@@ -209,6 +396,13 @@ stop-find
Stop discovery
:Usage: **> stop-find [-l|-b]**
+:[-l|-b]: Discovery type to stop - "-l" for LE only, "-b" for BR/EDR only (default: all)
+:Example Stop all discovery:
+ | **> stop-find**
+:Example Stop LE discovery only:
+ | **> stop-find -l**
+:Example Stop BR/EDR discovery only:
+ | **> stop-find -b**
name
----
@@ -216,6 +410,20 @@ name
Set local name
:Usage: **> name <name> [shortname]**
+:<name>: Complete local name for the controller
+:[shortname]: Optional shortened local name
+:Example Set complete local name:
+ | **> name "My Bluetooth Device"**
+:Example Set name without spaces:
+ | **> name MyComputer**
+:Example Set name with hyphens:
+ | **> name "Home-Office-PC"**
+:Example Set both complete and shortened names:
+ | **> name "My Long Device Name" MyDevice**
+:Example Set descriptive and short names:
+ | **> name "Professional Workstation" ProWork**
+:Example Set audio device names:
+ | **> name "Bluetooth Audio Headset" BT-Audio**
pair
----
@@ -223,6 +431,35 @@ pair
Pair with a remote device
:Usage: **> 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
+:Example Pair with device using default settings:
+ | **> pair 00:11:22:33:44:55**
+:Example Pair with another device:
+ | **> pair AA:BB:CC:DD:EE:FF**
+:Example Pair with display-only IO capability:
+ | **> pair -c DisplayOnly 00:11:22:33:44:55**
+:Example Pair with display and yes/no capability:
+ | **> pair -c DisplayYesNo AA:BB:CC:DD:EE:FF**
+:Example Pair with keyboard-only capability:
+ | **> pair -c KeyboardOnly 11:22:33:44:55:66**
+:Example Pair with no I/O capability:
+ | **> pair -c NoInputNoOutput CC:DD:EE:FF:00:11**
+:Example Pair with keyboard and display capability:
+ | **> pair -c KeyboardDisplay 22:33:44:55:66:77**
+:Example Pair with public address device:
+ | **> pair -t public 00:11:22:33:44:55**
+:Example Pair with random address device:
+ | **> pair -t random AA:BB:CC:DD:EE:FF**
+:Example Pair with LE public address device:
+ | **> pair -t le_public 11:22:33:44:55:66**
+:Example Pair with LE random address device:
+ | **> pair -t le_random CC:DD:EE:FF:00:11**
+:Example Pair LE device with keyboard/display capability:
+ | **> pair -c KeyboardDisplay -t le_public 00:11:22:33:44:55**
+:Example Pair random address device with display/yes-no capability:
+ | **> pair -c DisplayYesNo -t random AA:BB:CC:DD:EE:FF**
cancelpair
----------
@@ -230,6 +467,16 @@ cancelpair
Cancel pairing
:Usage: **> 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
+:Example Cancel ongoing pairing with device:
+ | **> cancelpair 00:11:22:33:44:55**
+:Example Cancel pairing with another device:
+ | **> cancelpair AA:BB:CC:DD:EE:FF**
+:Example Cancel pairing with public address device:
+ | **> cancelpair -t public 00:11:22:33:44:55**
+:Example Cancel pairing with LE random address device:
+ | **> cancelpair -t le_random AA:BB:CC:DD:EE:FF**
unpair
------
@@ -237,13 +484,27 @@ unpair
Unpair device
:Usage: **> unpair [-t type] <remote address>**
+:[-t type]: Address type (public, random, le_public, le_random)
+:<remote address>: Bluetooth address of device to unpair
+:Example Remove pairing with device:
+ | **> unpair 00:11:22:33:44:55**
+:Example Remove pairing with another device:
+ | **> unpair AA:BB:CC:DD:EE:FF**
+:Example Unpair public address device:
+ | **> unpair -t public 00:11:22:33:44:55**
+:Example Unpair LE public address device:
+ | **> unpair -t le_public 11:22:33:44:55:66**
+:Example Unpair LE random address device:
+ | **> unpair -t le_random CC:DD:EE:FF:00:11**
keys
----
Load Link Keys
-:Usage: **keys**
+:Usage: **> keys**
+:Example Load stored link keys:
+ | **> keys**
ltks
----
@@ -251,6 +512,8 @@ ltks
Load Long Term Keys
:Usage: **> ltks**
+:Example Load stored LE long term keys:
+ | **> ltks**
irks
----
@@ -258,6 +521,20 @@ irks
Load Identity Resolving Keys
:Usage: **> irks [--local index] [--file file path]**
+:[--local index]: Local controller index to use
+:[--file file path]: Custom IRK configuration file path
+:Example Load IRKs with default local index and file:
+ | **> irks**
+:Example Load IRKs for controller index 0:
+ | **> irks --local 0**
+:Example Load IRKs for controller index 1:
+ | **> irks --local 1**
+:Example Load IRKs from custom configuration file:
+ | **> irks --file /etc/bluetooth/irks.conf**
+:Example Load IRKs from user file:
+ | **> irks --file /home/user/bluetooth_irks.txt**
+:Example Load IRKs for hci0 from specific file:
+ | **> irks --local 0 --file /etc/bluetooth/hci0_irks.conf**
block
-----
@@ -265,6 +542,20 @@ block
Block Device
:Usage: **> block [-t type] <remote address>**
+:[-t type]: Address type (public, random, le_public, le_random)
+:<remote address>: Bluetooth address of device to block
+:Example Block device using default address type:
+ | **> block 00:11:22:33:44:55**
+:Example Block another device:
+ | **> block AA:BB:CC:DD:EE:FF**
+:Example Block device with public address:
+ | **> block -t public 00:11:22:33:44:55**
+:Example Block device with random address:
+ | **> block -t random AA:BB:CC:DD:EE:FF**
+:Example Block LE device with public address:
+ | **> block -t le_public 11:22:33:44:55:66**
+:Example Block LE device with random address:
+ | **> block -t le_random CC:DD:EE:FF:00:11**
unblock
-------
@@ -272,6 +563,20 @@ unblock
Unblock Device
:Usage: **> unblock [-t type] <remote address>**
+:[-t type]: Address type (public, random, le_public, le_random)
+:<remote address>: Bluetooth address of device to unblock
+:Example Unblock device using default address type:
+ | **> unblock 00:11:22:33:44:55**
+:Example Unblock another device:
+ | **> unblock AA:BB:CC:DD:EE:FF**
+:Example Unblock device with public address:
+ | **> unblock -t public 00:11:22:33:44:55**
+:Example Unblock device with random address:
+ | **> unblock -t random AA:BB:CC:DD:EE:FF**
+:Example Unblock LE device with public address:
+ | **> unblock -t le_public 11:22:33:44:55:66**
+:Example Unblock LE device with random address:
+ | **> unblock -t le_random CC:DD:EE:FF:00:11**
add-uuid
--------
@@ -279,6 +584,22 @@ add-uuid
Add UUID
:Usage: **> 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)
+:Example Add Serial Port Profile with object transfer hint:
+ | **> add-uuid 0x1101 0x100000**
+:Example Add A2DP with audio hint:
+ | **> add-uuid 0x110E 0x200000**
+:Example Add HFP with audio hint:
+ | **> add-uuid 0x111E 0x200000**
+:Example Add custom service UUID with no hint:
+ | **> add-uuid 12345678-1234-5678-9abc-123456789abc 0x000000**
+:Example Add custom UUID with object transfer hint:
+ | **> add-uuid ABCD1234-ABCD-1234-ABCD-123456789ABC 0x100000**
+:Example Add Generic Access with no specific hint:
+ | **> add-uuid 0x1800 0x000000**
+:Example Add Battery Service with no hint:
+ | **> add-uuid 0x180F 0x000000**
rm-uuid
-------
@@ -286,13 +607,22 @@ rm-uuid
Remove UUID
:Usage: **> rm-uuid <UUID>**
+:<UUID>: Service UUID to remove (16-bit, 32-bit, or 128-bit format)
+:Example Remove Serial Port Profile UUID:
+ | **> rm-uuid 0x1101**
+:Example Remove A2DP UUID:
+ | **> rm-uuid 0x110E**
+:Example Remove custom service UUID:
+ | **> rm-uuid 12345678-1234-5678-9abc-123456789abc**
clr-uuids
---------
Clear UUIDs
-:Usage: **> clear-uuids**
+:Usage: **> clr-uuids**
+:Example Clear all registered UUIDs:
+ | **> clr-uuids**
local-oob
---------
@@ -300,6 +630,8 @@ local-oob
Local OOB data
:Usage: **> local-oob**
+:Example Generate and display local OOB authentication data:
+ | **> local-oob**
remote-oob
----------
@@ -308,6 +640,24 @@ Remote OOB data
:Usage: **> 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
+:Example Set remote OOB data for device (minimal):
+ | **> remote-oob 00:11:22:33:44:55**
+:Example Set P-192 random and hash values:
+ | **> remote-oob -r 0123456789abcdef0123456789abcdef -h fedcba9876543210fedcba9876543210 00:11:22:33:44:55**
+:Example Set P-256 random and hash values:
+ | **> remote-oob -R 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef -H fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210 AA:BB:CC:DD:EE:FF**
+:Example Set OOB data for LE public address device:
+ | **> remote-oob -t le_public 11:22:33:44:55:66**
+:Example Set OOB data for LE random address device:
+ | **> remote-oob -t le_random CC:DD:EE:FF:00:11**
+:Example Set complete OOB data with both P-192 and P-256 values:
+ | **> remote-oob -t public -r 0123456789abcdef0123456789abcdef -h fedcba9876543210fedcba9876543210 -R 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef -H fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210 00:11:22:33:44:55**
did
---
@@ -315,6 +665,19 @@ did
Set Device ID
:Usage: **> did <source>:<vendor>:<product>:<version>**
+:<source>:<vendor>:<product>:<version>: Device ID in format source:vendor:product:version (all hexadecimal)
+:Example Set USB source with Linux Foundation vendor ID:
+ | **> did 0x0002:0x1D6B:0x0001:0x0100**
+:Example Set USB device with Cypress vendor ID:
+ | **> did 0x0002:0x04B4:0x1234:0x0200**
+:Example Set Bluetooth SIG source with Broadcom vendor:
+ | **> did 0x0001:0x000F:0x0001:0x0100**
+:Example Set Bluetooth SIG source with Apple vendor:
+ | **> did 0x0001:0x004C:0x0001:0x0100**
+:Example Set custom USB device ID:
+ | **> did 0x0002:0xFFFF:0x1234:0x5678**
+:Example Set Qualcomm Bluetooth device:
+ | **> did 0x0001:0x05F1:0xABCD:0x0001**
static-addr
-----------
@@ -322,6 +685,13 @@ static-addr
Set static address
:Usage: **> static-addr <address>**
+:<address>: Static random Bluetooth address (must have bits 47-46 set to 11)
+:Example Set static random address (bit 47=1, bit 46=1):
+ | **> static-addr C0:00:00:00:00:01**
+:Example Set another static random address:
+ | **> static-addr D0:11:22:33:44:55**
+:Example Set different static address:
+ | **> static-addr E0:AA:BB:CC:DD:EE**
public-addr
-----------
@@ -329,6 +699,13 @@ public-addr
Set public address
:Usage: **> public-addr <address>**
+:<address>: Public Bluetooth address to set for the controller
+:Example Set public Bluetooth address:
+ | **> public-addr 00:11:22:33:44:55**
+:Example Set different public address:
+ | **> public-addr AA:BB:CC:DD:EE:FF**
+:Example Set custom public address:
+ | **> public-addr 12:34:56:78:9A:BC**
ext-config
----------
@@ -336,6 +713,11 @@ ext-config
External configuration
:Usage: **> ext-config <on/off>**
+:<on/off>: External configuration - "on" to enable external config, "off" to disable
+:Example Enable external configuration:
+ | **> ext-config on**
+:Example Disable external configuration:
+ | **> ext-config off**
debug-keys
----------
@@ -343,6 +725,11 @@ debug-keys
Toggle debug keys
:Usage: **> debug-keys <on/off>**
+:<on/off>: Debug keys support - "on" to enable debug keys, "off" to disable
+:Example Enable debug key support:
+ | **> debug-keys on**
+:Example Disable debug key support:
+ | **> debug-keys off**
conn-info
---------
@@ -350,6 +737,18 @@ conn-info
Get connection information
:Usage: **> conn-info [-t type] <remote address>**
+:[-t type]: Address type (public, random, le_public, le_random)
+:<remote address>: Bluetooth address of connected device
+:Example Get connection information for device:
+ | **> conn-info 00:11:22:33:44:55**
+:Example Get info for another device:
+ | **> conn-info AA:BB:CC:DD:EE:FF**
+:Example Get info for public address device:
+ | **> conn-info -t public 00:11:22:33:44:55**
+:Example Get info for LE public address device:
+ | **> conn-info -t le_public 11:22:33:44:55:66**
+:Example Get info for LE random address device:
+ | **> conn-info -t le_random CC:DD:EE:FF:00:11**
io-cap
------
@@ -357,6 +756,17 @@ io-cap
Set IO Capability
:Usage: **> io-cap <cap>**
+:<cap>: IO capability (DisplayOnly, DisplayYesNo, KeyboardOnly, NoInputNoOutput, KeyboardDisplay)
+:Example Set IO capability to display only:
+ | **> io-cap DisplayOnly**
+:Example Set IO capability to display with yes/no:
+ | **> io-cap DisplayYesNo**
+:Example Set IO capability to keyboard only:
+ | **> io-cap KeyboardOnly**
+:Example Set IO capability to no input/output:
+ | **> io-cap NoInputNoOutput**
+:Example Set IO capability to keyboard and display:
+ | **> io-cap KeyboardDisplay**
scan-params
-----------
@@ -364,6 +774,20 @@ scan-params
Set Scan Parameters
:Usage: **> 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)
+:Example Set fast scan (16ms interval, 16ms window):
+ | **> scan-params 0x0010 0x0010**
+:Example Set moderate fast scan (32ms interval, 32ms window):
+ | **> scan-params 0x0020 0x0020**
+:Example Set balanced scan (96ms interval, 48ms window):
+ | **> scan-params 0x0060 0x0030**
+:Example Set slow scan (256ms interval, 80ms window):
+ | **> scan-params 0x0100 0x0050**
+:Example Set background scan (2.56s interval, 18ms window):
+ | **> scan-params 0x0800 0x0012**
+:Example Set very slow background scan:
+ | **> scan-params 0x1000 0x0020**
get-clock
---------
@@ -371,6 +795,13 @@ get-clock
Get Clock Information
:Usage: **> get-clock [address]**
+:[address]: Optional remote device Bluetooth address (omit for local clock)
+:Example Get local Bluetooth clock information:
+ | **> get-clock**
+:Example Get clock information for remote device:
+ | **> get-clock 00:11:22:33:44:55**
+:Example Get clock for another remote device:
+ | **> get-clock AA:BB:CC:DD:EE:FF**
add-device
----------
@@ -378,6 +809,33 @@ add-device
Add Device
:Usage: **> 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
+:Example Add device with auto-connect action and default type:
+ | **> add-device 00:11:22:33:44:55**
+:Example Add another device with defaults:
+ | **> add-device AA:BB:CC:DD:EE:FF**
+:Example Add device with auto-connect action:
+ | **> add-device -a auto 00:11:22:33:44:55**
+:Example Add device with allow-only action (no auto-connect):
+ | **> add-device -a allow 11:22:33:44:55:66**
+:Example Add device with deny action (blocked):
+ | **> add-device -a deny CC:DD:EE:FF:00:11**
+:Example Add device with public address type:
+ | **> add-device -t public 00:11:22:33:44:55**
+:Example Add device with random address type:
+ | **> add-device -t random AA:BB:CC:DD:EE:FF**
+:Example Add LE device with public address:
+ | **> add-device -t le_public 11:22:33:44:55:66**
+:Example Add LE device with random address:
+ | **> add-device -t le_random CC:DD:EE:FF:00:11**
+:Example Add LE public device with auto-connect:
+ | **> add-device -a auto -t le_public 00:11:22:33:44:55**
+:Example Add random address device with allow action:
+ | **> add-device -a allow -t random AA:BB:CC:DD:EE:FF**
+:Example Add LE random device with deny action:
+ | **> add-device -a deny -t le_random CC:DD:EE:FF:00:11**
del-device
----------
@@ -385,6 +843,20 @@ del-device
Remove Device
:Usage: **> del-device [-t type] <address>**
+:[-t type]: Address type (public, random, le_public, le_random)
+:<address>: Bluetooth address of device to remove
+:Example Remove device using default address type:
+ | **> del-device 00:11:22:33:44:55**
+:Example Remove another device:
+ | **> del-device AA:BB:CC:DD:EE:FF**
+:Example Remove device with public address type:
+ | **> del-device -t public 00:11:22:33:44:55**
+:Example Remove device with random address type:
+ | **> del-device -t random AA:BB:CC:DD:EE:FF**
+:Example Remove LE device with public address:
+ | **> del-device -t le_public 11:22:33:44:55:66**
+:Example Remove LE device with random address:
+ | **> del-device -t le_random CC:DD:EE:FF:00:11**
clr-devices
-----------
@@ -392,6 +864,8 @@ clr-devices
Clear Devices
:Usage: **> clr-devices**
+:Example Clear all devices from the device list:
+ | **> clr-devices**
bredr-oob
---------
@@ -399,6 +873,8 @@ bredr-oob
Local OOB data (BR/EDR)
:Usage: **> bredr-oob**
+:Example Generate and display local BR/EDR OOB authentication data:
+ | **> bredr-oob**
le-oob
------
@@ -406,6 +882,8 @@ le-oob
Local OOB data (LE)
:Usage: **> le-oob**
+:Example Generate and display local LE OOB authentication data:
+ | **> le-oob**
advinfo
-------
@@ -413,6 +891,8 @@ advinfo
Show advertising features
:Usage: **> advinfo**
+:Example Display advertising capabilities and supported features:
+ | **> advinfo**
advsize
-------
@@ -420,6 +900,14 @@ advsize
Show advertising size info
:Usage: **> advsize [options] <instance_id>**
+:[options]: Advertising options flags
+:<instance_id>: Advertising instance identifier (0-based)
+:Example Show advertising data size information for instance 0:
+ | **> advsize 0**
+:Example Show size information for advertising instance 1:
+ | **> advsize 1**
+:Example Show size information for advertising instance 5:
+ | **> advsize 5**
add-adv
-------
@@ -427,6 +915,32 @@ add-adv
Add advertising instance
:Usage: **> 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)
+:Example Add advertising instance 0 with default settings:
+ | **> add-adv 0**
+:Example Add advertising instance 1:
+ | **> add-adv 1**
+:Example Add advertising instance 5:
+ | **> add-adv 5**
+:Example Add connectable advertising instance 0:
+ | **> add-adv -c 0**
+:Example Add scannable advertising instance 1:
+ | **> add-adv -s 1**
+:Example Add general discoverable advertising instance 2:
+ | **> add-adv -g 2**
+:Example Add limited discoverable advertising instance 3:
+ | **> add-adv -l 3**
+:Example Add managed flags advertising instance 4:
+ | **> add-adv -m 4**
+:Example Add TX power advertising instance 5:
+ | **> add-adv -p 5**
+:Example Add connectable and scannable advertising instance:
+ | **> add-adv -c -s 0**
+:Example Add general discoverable with TX power:
+ | **> add-adv -g -p 1**
+:Example Add connectable, general discoverable, and scannable:
+ | **> add-adv -c -g -s 2**
rm-adv
------
@@ -434,6 +948,13 @@ rm-adv
Remove advertising instance
:Usage: **> rm-adv <instance_id>**
+:<instance_id>: Advertising instance identifier (0-based) to remove
+:Example Remove advertising instance 0:
+ | **> rm-adv 0**
+:Example Remove advertising instance 1:
+ | **> rm-adv 1**
+:Example Remove advertising instance 5:
+ | **> rm-adv 5**
clr-adv
-------
@@ -441,13 +962,41 @@ clr-adv
Clear advertising instances
:Usage: **> clr-adv**
+:Example Clear all advertising instances:
+ | **> clr-adv**
add-ext-adv-params
------------------
Add extended advertising params
-:Usage: **> add-ext-adv-parms [options] <instance_id>**
+:Usage: **> 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)
+:Example Add extended advertising parameters for instance 0:
+ | **> add-ext-adv-params 0**
+:Example Add extended advertising parameters for instance 1:
+ | **> add-ext-adv-params 1**
+:Example Add connectable extended advertising for instance 0:
+ | **> add-ext-adv-params -c 0**
+:Example Add scannable extended advertising for instance 1:
+ | **> add-ext-adv-params -s 1**
+:Example Add directed extended advertising for instance 2:
+ | **> add-ext-adv-params -d 2**
+:Example Add high duty cycle extended advertising for instance 3:
+ | **> add-ext-adv-params -h 3**
+:Example Add legacy PDU extended advertising for instance 4:
+ | **> add-ext-adv-params -l 4**
+:Example Add anonymous extended advertising for instance 5:
+ | **> add-ext-adv-params -a 5**
+:Example Add include TX power extended advertising for instance 6:
+ | **> add-ext-adv-params -i 6**
+:Example Add connectable and scannable extended advertising:
+ | **> add-ext-adv-params -c -s 0**
+:Example Add connectable extended advertising with TX power:
+ | **> add-ext-adv-params -c -i 1**
+:Example Add scannable legacy PDU extended advertising:
+ | **> add-ext-adv-params -s -l 2**
add-ext-adv-data
----------------
@@ -455,6 +1004,20 @@ add-ext-adv-data
Add extended advertising data
:Usage: **> 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)
+:Example Add advertising data to extended instance 0:
+ | **> add-ext-adv-data 0**
+:Example Add advertising data to extended instance 1:
+ | **> add-ext-adv-data 1**
+:Example Add scan response data to extended instance 0:
+ | **> add-ext-adv-data -s 0**
+:Example Add scan response data to extended instance 1:
+ | **> add-ext-adv-data -s 1**
+:Example Add complete advertising data to instance 0:
+ | **> add-ext-adv-data -c 0**
+:Example Add complete scan response data to instance 1:
+ | **> add-ext-adv-data -c -s 1**
appearance
----------
@@ -462,6 +1025,43 @@ appearance
Set appearance
:Usage: **> appearance <appearance>**
+:<appearance>: Appearance value (16-bit integer) representing device type
+:Example Set appearance to Unknown:
+ | **> appearance 0**
+:Example Set appearance to Generic Phone:
+ | **> appearance 64**
+:Example Set appearance to Generic Computer:
+ | **> appearance 128**
+:Example Set appearance to Generic Audio/Video device:
+ | **> appearance 832**
+:Example Set appearance to Speaker:
+ | **> appearance 833**
+:Example Set appearance to Microphone:
+ | **> appearance 834**
+:Example Set appearance to Headset:
+ | **> appearance 835**
+:Example Set appearance to Headphones:
+ | **> appearance 836**
+:Example Set appearance to Generic HID:
+ | **> appearance 960**
+:Example Set appearance to Keyboard:
+ | **> appearance 961**
+:Example Set appearance to Mouse:
+ | **> appearance 962**
+:Example Set appearance to Joystick:
+ | **> appearance 963**
+:Example Set appearance to Generic Health Sensor:
+ | **> appearance 1344**
+:Example Set appearance to Heart Rate Sensor:
+ | **> appearance 1345**
+:Example Set appearance to Blood Pressure Monitor:
+ | **> appearance 1346**
+:Example Set appearance to Generic Sports and Fitness:
+ | **> appearance 1472**
+:Example Set appearance to Location Display:
+ | **> appearance 1473**
+:Example Set appearance to Location Navigation Display:
+ | **> appearance 1474**
phy
---
@@ -471,6 +1071,45 @@ Get/Set PHY Configuration
:Usage: **> 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.)
+:Example Display current PHY configuration:
+ | **> phy**
+:Example Enable LE 1M TX PHY:
+ | **> phy LE1MTX**
+:Example Enable LE 1M RX PHY:
+ | **> phy LE1MRX**
+:Example Enable LE 2M TX PHY:
+ | **> phy LE2MTX**
+:Example Enable LE 2M RX PHY:
+ | **> phy LE2MRX**
+:Example Enable LE Coded TX PHY:
+ | **> phy LECODEDTX**
+:Example Enable LE Coded RX PHY:
+ | **> phy LECODEDRX**
+:Example Enable BR 1M 1-slot packets:
+ | **> phy BR1M1SLOT**
+:Example Enable BR 1M 3-slot packets:
+ | **> phy BR1M3SLOT**
+:Example Enable BR 1M 5-slot packets:
+ | **> phy BR1M5SLOT**
+:Example Enable EDR 2M 1-slot packets:
+ | **> phy EDR2M1SLOT**
+:Example Enable EDR 2M 3-slot packets:
+ | **> phy EDR2M3SLOT**
+:Example Enable EDR 2M 5-slot packets:
+ | **> phy EDR2M5SLOT**
+:Example Enable EDR 3M 1-slot packets:
+ | **> phy EDR3M1SLOT**
+:Example Enable EDR 3M 3-slot packets:
+ | **> phy EDR3M3SLOT**
+:Example Enable EDR 3M 5-slot packets:
+ | **> phy EDR3M5SLOT**
+:Example Enable LE 1M TX and RX PHYs:
+ | **> phy LE1MTX LE1MRX**
+:Example Enable LE 1M and 2M TX/RX PHYs:
+ | **> phy LE1MTX LE1MRX LE2MTX LE2MRX**
+:Example Enable 1-slot packets for all BR/EDR PHYs:
+ | **> phy BR1M1SLOT EDR2M1SLOT EDR3M1SLOT**
wbs
---
@@ -478,6 +1117,11 @@ wbs
Toggle Wideband-Speech support
:Usage: **> wbs <on/off>**
+:<on/off>: Wideband Speech support - "on" to enable for audio profiles, "off" to disable
+:Example Enable Wideband Speech support for audio profiles:
+ | **> wbs on**
+:Example Disable Wideband Speech support:
+ | **> wbs off**
secinfo
-------
@@ -485,6 +1129,8 @@ secinfo
Show security information
:Usage: **> secinfo**
+:Example Display security features and capabilities:
+ | **> secinfo**
expinfo
-------
@@ -492,6 +1138,8 @@ expinfo
Show experimental features
:Usage: **> expinfo**
+:Example Display available experimental features and their status:
+ | **> expinfo**
exp-debug
---------
@@ -499,6 +1147,11 @@ exp-debug
Set debug feature
:Usage: **> exp-debug <on/off>**
+:<on/off>: Experimental debug features - "on" to enable, "off" to disable
+:Example Enable experimental debug features:
+ | **> exp-debug on**
+:Example Disable experimental debug features:
+ | **> exp-debug off**
exp-privacy
-----------
@@ -506,6 +1159,11 @@ exp-privacy
Set LL privacy feature
:Usage: **> exp-privacy <on/off>**
+:<on/off>: Experimental Link Layer privacy - "on" to enable LL privacy features, "off" to disable
+:Example Enable experimental Link Layer privacy features:
+ | **> exp-privacy on**
+:Example Disable experimental Link Layer privacy features:
+ | **> exp-privacy off**
exp-quality
-----------
@@ -513,6 +1171,11 @@ exp-quality
Set bluetooth quality report feature
:Usage: **> exp-quality <on/off>**
+:<on/off>: Experimental quality reporting - "on" to enable Bluetooth quality reports, "off" to disable
+:Example Enable experimental Bluetooth quality reporting:
+ | **> exp-quality on**
+:Example Disable experimental Bluetooth quality reporting:
+ | **> exp-quality off**
exp-offload
-----------
@@ -520,6 +1183,11 @@ exp-offload
Toggle codec support
:Usage: **> exp-offload <on/off>**
+:<on/off>: Experimental codec offload - "on" to enable codec offload support, "off" to disable
+:Example Enable experimental codec offload support:
+ | **> exp-offload on**
+:Example Disable experimental codec offload support:
+ | **> exp-offload off**
read-sysconfig
--------------
@@ -527,6 +1195,8 @@ read-sysconfig
Read System Configuration
:Usage: **> read-sysconfig**
+:Example Read current system configuration parameters:
+ | **> read-sysconfig**
set-sysconfig
-------------
@@ -534,12 +1204,52 @@ set-sysconfig
Set System Configuration
:Usage: **> 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.)
+:Example Show help for system configuration options:
+ | **> set-sysconfig -h**
+:Example Set system configuration with verbose output:
+ | **> set-sysconfig -v**
+:Example Set BR/EDR page scan type with verbose output:
+ | **> set-sysconfig -v --br-page-scan-type=0**
+:Example Set BR/EDR page scan interval:
+ | **> set-sysconfig -v --br-page-scan-interval=0x800**
+:Example Set BR/EDR page scan window:
+ | **> set-sysconfig -v --br-page-scan-window=0x12**
+:Example Set BR/EDR inquiry scan type:
+ | **> set-sysconfig -v --br-inquiry-scan-type=0**
+:Example Set BR/EDR link supervision timeout:
+ | **> set-sysconfig -v --br-link-supervision-timeout=0x2000**
+:Example Set LE minimum connection interval:
+ | **> set-sysconfig -v --le-min-connection-interval=0x18**
+:Example Set LE maximum connection interval:
+ | **> set-sysconfig -v --le-max-connection-interval=0x28**
+:Example Set multiple BR/EDR scan parameters:
+ | **> set-sysconfig -v --br-page-scan-type=0 --br-page-scan-interval=0x800 --br-page-scan-window=0x12**
+:Example Set multiple LE connection parameters:
+ | **> set-sysconfig -v --le-min-connection-interval=0x18 --le-max-connection-interval=0x28 --le-connection-latency=0**
get-flags
---------
Get device flags
+:Usage: **> get-flags [-t type] <address>**
+:[-t type]: Address type (public, random, le_public, le_random)
+:<address>: Bluetooth address of device to query flags for
+:Example Get device flags for device using default type:
+ | **> get-flags 00:11:22:33:44:55**
+:Example Get flags for another device:
+ | **> get-flags AA:BB:CC:DD:EE:FF**
+:Example Get flags for public address device:
+ | **> get-flags -t public 00:11:22:33:44:55**
+:Example Get flags for random address device:
+ | **> get-flags -t random AA:BB:CC:DD:EE:FF**
+:Example Get flags for LE public address device:
+ | **> get-flags -t le_public 11:22:33:44:55:66**
+:Example Get flags for LE random address device:
+ | **> get-flags -t le_random CC:DD:EE:FF:00:11**
+
set-flags
---------
@@ -547,6 +1257,29 @@ set-flags
Set device flags
:Usage: **> 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
+:Example Set default flags for device:
+ | **> set-flags 00:11:22:33:44:55**
+:Example Set default flags for another device:
+ | **> set-flags AA:BB:CC:DD:EE:FF**
+:Example Set remote wake flag for device:
+ | **> set-flags -f 0x01 00:11:22:33:44:55**
+:Example Set device privacy flag:
+ | **> set-flags -f 0x02 AA:BB:CC:DD:EE:FF**
+:Example Set both remote wake and privacy flags:
+ | **> set-flags -f 0x03 11:22:33:44:55:66**
+:Example Set remote wake for public address device:
+ | **> set-flags -f 0x01 -t public 00:11:22:33:44:55**
+:Example Set privacy flag for LE public device:
+ | **> set-flags -f 0x02 -t le_public 11:22:33:44:55:66**
+:Example Set multiple flags for LE random device:
+ | **> set-flags -f 0x03 -t le_random CC:DD:EE:FF:00:11**
+:Example Clear all flags for device:
+ | **> set-flags -f 0x00 00:11:22:33:44:55**
+:Example Clear all flags for LE public device:
+ | **> set-flags -f 0x00 -t le_public 11:22:33:44:55:66**
RESOURCES
=========
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 03/35] doc/bluetoothctl-admin: Add :Uses: fields and document arguments
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 01/35] doc/bluetoothctl: Add :Uses: fields and document arguments Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 02/35] doc/bluetoothctl-mgmt: Add :Uses: fields and document arguments Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 04/35] doc/bluetoothctl-advertise: " Luiz Augusto von Dentz
` (32 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
doc/bluetoothctl-admin.rst | 28 ++++++++++++++++++++++++++--
1 file changed, 26 insertions(+), 2 deletions(-)
diff --git a/doc/bluetoothctl-admin.rst b/doc/bluetoothctl-admin.rst
index b0f7f94c18cf..d4446ce95e5f 100644
--- a/doc/bluetoothctl-admin.rst
+++ b/doc/bluetoothctl-admin.rst
@@ -18,6 +18,10 @@ SYNOPSIS
**bluetoothctl** [--options] [admin.commands]
+This submenu configures administrative policies using the
+**org.bluez.AdminPolicySet(5)** and **org.bluez.AdminPolicyStatus(5)**
+interfaces.
+
Admin Policy Commands
=====================
@@ -27,8 +31,28 @@ allow
Allow service UUIDs and block rest of them.
:Usage: **> allow [clear/uuid1 uuid2 ...]**
-:Example: **> allow 0x1101 0x1102 0x1103**
-:Example: **> allow clear**
+:Uses: **org.bluez.AdminPolicySet(5)** property **ServiceAllowList**
+:[clear/uuid1 uuid2 ...]: List of service UUIDs to allow, or "clear" to remove all restrictions
+:Example Get current allowed UUIDs list:
+ | **> allow**
+:Example Allow Serial Port Profile only:
+ | **> allow 0x1101**
+:Example Allow Serial Port Profile and LAN Access Profile:
+ | **> allow 0x1101 0x1102**
+:Example Allow Serial Port Profile, LAN Access Profile, and Dialup Networking Profile:
+ | **> allow 0x1101 0x1102 0x1103**
+:Example Allow Advanced Audio Distribution Profile only:
+ | **> allow 0x110e**
+:Example Allow A2DP Source and Sink profiles:
+ | **> allow 0x110e 0x110f**
+:Example Allow Serial Port Profile using full UUID:
+ | **> allow 00001101-0000-1000-8000-00805f9b34fb**
+:Example Allow SPP and LAP using full UUIDs:
+ | **> allow 00001101-0000-1000-8000-00805f9b34fb 00001102-0000-1000-8000-00805f9b34fb**
+:Example Remove all UUID restrictions:
+ | **> allow clear**
+:Example Allow SPP, LAP, and DUN using mixed UUID formats:
+ | **> allow 0x1101 00001102-0000-1000-8000-00805f9b34fb 0x1103**
RESOURCES
=========
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 04/35] doc/bluetoothctl-advertise: Add :Uses: fields and document arguments
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (2 preceding siblings ...)
2026-01-30 19:38 ` [PATCH BlueZ v2 03/35] doc/bluetoothctl-admin: " Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 05/35] doc/bluetoothctl-assistant: " Luiz Augusto von Dentz
` (31 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
doc/bluetoothctl-advertise.rst | 356 +++++++++++++++++++++++++++++++--
1 file changed, 342 insertions(+), 14 deletions(-)
diff --git a/doc/bluetoothctl-advertise.rst b/doc/bluetoothctl-advertise.rst
index b1a950409ba4..0780cd9d8fde 100644
--- a/doc/bluetoothctl-advertise.rst
+++ b/doc/bluetoothctl-advertise.rst
@@ -18,6 +18,10 @@ SYNOPSIS
**bluetoothctl** [--options] [advertise.commands]
+This submenu configures LE advertising data and parameters using the
+**org.bluez.LEAdvertisement(5)** and **org.bluez.LEAdvertisingManager(5)**
+interfaces.
+
Advertise Options Commands
==========================
@@ -26,16 +30,50 @@ uuids
Set/Get advertise uuids.
-:Usage: **> uuids [all/uuid1 uuid2 ...]**
-:Example: **> uuids 0x1234**
-:Example: **> uuids 0x12345678**
-:Example: **> uuids 90f95193-35de-4306-a6e9-699328f15059**
+:Usage: **> uuids [uuid1 uuid2 ...]**
+:Uses: **org.bluez.LEAdvertisement(5)** property **ServiceUUIDs**
+:[uuid1 uuid2 ...]: List of UUIDs to advertise (default: none)
+:Example Show current advertised UUIDs:
+ | **> uuids**
+:Example Advertise custom 16-bit service UUID:
+ | **> uuids 0x1234**
+:Example Advertise custom 32-bit service UUID:
+ | **> uuids 0x12345678**
+:Example Advertise custom 128-bit service UUID:
+ | **> uuids 90f95193-35de-4306-a6e9-699328f15059**
+:Example Advertise Battery and Generic Attribute services:
+ | **> uuids 0x180F 0x1801**
+:Example Advertise Device Information, Battery, and HID services:
+ | **> uuids 0x180A 0x180F 0x1812**
+:Example Advertise Generic Access service:
+ | **> uuids 0x1800**
+:Example Advertise Environmental Sensing service:
+ | **> uuids 0x181A**
+:Example Advertise Pulse Oximeter service:
+ | **> uuids 0x183B**
+:Example Mix short and full UUID formats:
+ | **> uuids 0x180F 12345678-1234-5678-9abc-123456789abc**
solicit
-------
Set/Get advertise solicit uuids.
-:Usage: **# solicit [all/uuid1 uuid2 ...]**
+
+:Usage: **> solicit [uuid1 uuid2 ...]**
+:Uses: **org.bluez.LEAdvertisement(5)** property **SolicitUUIDs**
+:[uuid1 uuid2 ...]: List of UUIDs to advertise (default: none)
+:Example Show current solicited service UUIDs:
+ | **> solicit**
+:Example Solicit Generic Access service:
+ | **> solicit 0x1800**
+:Example Solicit Device Information service:
+ | **> solicit 0x180A**
+:Example Solicit User Data service:
+ | **> solicit 0x181C**
+:Example Solicit Battery and Generic Attribute services:
+ | **> solicit 0x180F 0x1801**
+:Example Solicit Device Info, Environmental Sensing, and Pulse Oximeter:
+ | **> solicit 0x180A 0x181A 0x183B**
service
-------
@@ -43,6 +81,23 @@ service
Set/Get advertise service data.
:Usage: **> service [uuid] [data=xx xx ...]**
+:Uses: **org.bluez.LEAdvertisement(5)** property **ServiceData**
+:[uuid]: Service UUID
+:[data=xx xx ...]: Service data
+:Example Show current service data:
+ | **> service**
+:Example Set battery level to 100 (0x64):
+ | **> service 0x180F 64**
+:Example Set battery level to 50 (0x32):
+ | **> service 0x180F 32**
+:Example Set battery level to 0 (0x00):
+ | **> service 0x180F 00**
+:Example Set environmental data (temperature, humidity, pressure):
+ | **> service 0x181A 20 15 C8 07**
+:Example Set device information data:
+ | **> service 0x180A 01 02 03 04**
+:Example Set custom service data with 128-bit UUID:
+ | **> service 12345678-1234-5678-9abc-123456789abc FF EE DD CC**
manufacturer
------------
@@ -57,6 +112,23 @@ maximum has been exceeded so you may receive an error from bluetoothd that it
manufacturer data length.
:Usage: **> manufacturer [id] [data=xx xx ...]**
+:Uses: **org.bluez.LEAdvertisement(5)** property **ManufacturerData**
+:[id]: Manufacturer ID (default: 0x004C for Apple Inc.)
+:[data=xx xx ...]: Manufacturer data
+:Example Show current manufacturer data:
+ | **> manufacturer**
+:Example Set Apple Inc. manufacturer data:
+ | **> manufacturer 0x004C 01 02 03 04**
+:Example Set Apple manufacturer data with 8 bytes:
+ | **> manufacturer 0x004C FF FE FD FC FB FA F9 F8**
+:Example Set Microsoft Corp. manufacturer data:
+ | **> manufacturer 0x0006 10 11 12 13**
+:Example Set Samsung Electronics manufacturer data:
+ | **> manufacturer 0x0075 AA BB CC DD EE**
+:Example Set Google LLC manufacturer data:
+ | **> manufacturer 0x00E0 01 23 45 67 89 AB CD EF**
+:Example Set custom manufacturer ID with test data:
+ | **> manufacturer 0xFFFF DE AD BE EF**
data
----
@@ -75,40 +147,111 @@ You can modify the advertising data while it is advertising.
To get the currently set data use the command data without any arguments.
:Usage: **> data [type] [data=xx xx ...]**
-:Example: **> data 0x0C 01 0x0F 13**
+:Uses: **org.bluez.LEAdvertisement(5)** property **Data**
+:[type]: Advertising data type
+:[data=xx xx ...]: Advertising data (default: none)
+:Example Show current advertising data:
+ | **> data**
+:Example Set slave connection interval range data:
+ | **> data 0x0C 01 0x0F 13**
+:Example Set complete local name to "Hello":
+ | **> data 0x09 48 65 6C 6C 6F**
+:Example Set shortened local name to "Test":
+ | **> data 0x08 54 65 73 74**
+:Example Set flags (LE General Discoverable + BR/EDR not supported):
+ | **> data 0x01 06**
+:Example Set appearance (keyboard, 0x0341):
+ | **> data 0x19 41 03**
+:Example Set TX power level to +4 dBm:
+ | **> data 0x0A 04**
+:Example Set TX power level to -4 dBm:
+ | **> data 0x0A FC**
+:Example Set URI "//google.com":
+ | **> data 0x24 17 2F 2F 67 6F 6F 67 6C 65 2E 63 6F 6D**
+:Example Set service data for Battery Service (UUID 0x180F, level 100):
+ | **> data 0x16 0F 18 64**
sr-uuids
--------
Set/Get scan response uuids.
-:Usage: **# sr-uuids [all/uuid1 uuid2 ...]**
+:Usage: **> sr-uuids [uuid1 uuid2 ...]**
+:[uuid1 uuid2 ...]: List of UUIDs to advertise in scan response
+:Example Show current scan response UUIDs:
+ | **> sr-uuids**
+:Example Set Generic Access in scan response:
+ | **> sr-uuids 0x1800**
+:Example Set Device Info and Battery services in scan response:
+ | **> sr-uuids 0x180A 0x180F**
+:Example Set custom UUID in scan response:
+ | **> sr-uuids 12345678-1234-5678-9abc-123456789abc**
sr-solicit
----------
Set/Get scan response solicit uuids.
-:Usage: **# sr-solicit [all/uuid1 uuid2 ...]**
+
+:Usage: **> sr-solicit [uuid1 uuid2 ...]**
+:[uuid1 uuid2 ...]: List of UUIDs to advertise in scan response
+:Example Show current scan response solicited UUIDs:
+ | **> sr-solicit**
+:Example Solicit Generic Attribute service in scan response:
+ | **> sr-solicit 0x1801**
+
+:Example Solicit Device Info and Environmental Sensing in scan response:
+ | **> sr-solicit 0x180A 0x181A**
sr-service
----------
Set/Get scan response service data.
-:Usage: **# sr-service [uuid] [data=xx xx ...]**
+:Usage: **> sr-service [uuid] [data=xx xx ...]**
+:[uuid]: Service UUID
+:[data=xx xx ...]: Service data
+:Example Show current scan response service data:
+ | **> sr-service**
+:Example Set battery level to 128 in scan response:
+ | **> sr-service 0x180F 80**
+:Example Set environmental data in scan response:
+ | **> sr-service 0x181A 22 18 C0 05**
+:Example Set device info "Hello" in scan response:
+ | **> sr-service 0x180A 48 65 6C 6C 6F**
sr-manufacturer
---------------
Set/Get scan response manufacturer data.
-:Usage: **# sr-manufacturer [id] [data=xx xx ...]**
+:Usage: **> sr-manufacturer [id] [data=xx xx ...]**
+:[id]: Manufacturer ID (default: 0x004C for Apple Inc.)
+:[data=xx xx ...]: Manufacturer data
+:Example Show current scan response manufacturer data:
+ | **> sr-manufacturer**
+:Example Set Apple manufacturer data in scan response:
+ | **> sr-manufacturer 0x004C 05 06 07 08**
+:Example Set Microsoft manufacturer data in scan response:
+ | **> sr-manufacturer 0x0006 20 21 22 23**
+:Example Set custom manufacturer data in scan response:
+ | **> sr-manufacturer 0xFFFF CA FE BA BE**
sr-data
-------
Set/Get scan response data.
-:Usage: **# sr-data [type] [data=xx xx ...]**
+
+:Usage: **> sr-data [type] [data=xx xx ...]**
+:[type]: Scan Response data type
+:[data=xx xx ...]: Scan Response data
+:Example Show current scan response data:
+ | **> sr-data**
+:Example Set complete local name "ScanResp" in scan response:
+ | **> sr-data 0x09 53 63 61 6E 52 65 73 70**
+:Example Set TX power level +8 dBm in scan response:
+ | **> sr-data 0x0A 08**
+:Example Set Battery service data (level 50) in scan response:
+ | **> sr-data 0x16 0F 18 32**
discoverable
------------
@@ -125,6 +268,14 @@ will be ignored.
Entering the command by itself will show the status of the setting
:Usage: **> discoverable [on/off]**
+:Uses: **org.bluez.LEAdvertisement(5)** property **Discoverable**
+:[on/off]: Enable/Disable LE General Discoverable Mode
+:Example Show current discoverable setting:
+ | **> discoverable**
+:Example Enable LE General Discoverable Mode:
+ | **> discoverable on**
+:Example Disable discoverable mode:
+ | **> discoverable off**
discoverable-timeout
--------------------
@@ -141,6 +292,18 @@ discoverable [on] must be set to use this feature.
Entering the command by itself will show the current value set.
:Usage: **> discoverable-timeout [seconds]**
+:Uses: **org.bluez.LEAdvertisement(5)** property **DiscoverableTimeout**
+:[seconds]: Timeout duration in seconds for LE Limited Discoverable Mode
+:Example Show current discoverable timeout:
+ | **> discoverable-timeout**
+:Example Set LE Limited Discoverable for 30 seconds:
+ | **> discoverable-timeout 30**
+:Example Set LE Limited Discoverable for 2 minutes:
+ | **> discoverable-timeout 120**
+:Example Set LE Limited Discoverable for 5 minutes:
+ | **> discoverable-timeout 300**
+:Example Disable discoverable timeout (unlimited):
+ | **> discoverable-timeout 0**
tx-power
--------
@@ -158,7 +321,15 @@ This feature can be modified while advertising.
Entering the command by itself will show the current value set.
-:Usage: **> tx-power [on/off] [power]**
+:Usage: **> tx-power [on/off]**
+:Uses: **org.bluez.LEAdvertisement(5)** property **Includes**
+:[on/off]: Enable or disable TX power advertisement (optional, shows current if omitted)
+:Example Show current TX power advertisement setting:
+ | **> tx-power**
+:Example Enable TX power advertisement with default power:
+ | **> tx-power on**
+:Example Disable TX power advertisement:
+ | **> tx-power off**
name
----
@@ -173,7 +344,28 @@ It will either advertise as a complete local name or if it has to be truncated
then a shortened local name.
:Usage: **> name [on/off/name]**
-:Example: **> name "0123456789abcdef0123456789abcdef"**
+:Uses: **org.bluez.LEAdvertisement(5)** property **LocalName**
+:[name]: Local name (optional, shows current if omitted)
+:Example Show current advertised name setting:
+ | **> name**
+:Example Enable advertising the system hostname:
+ | **> name on**
+:Example Disable name advertisement:
+ | **> name off**
+:Example Advertise "My Device" as local name:
+ | **> name "My Device"**
+:Example Advertise "Smart Sensor" as local name:
+ | **> name "Smart Sensor"**
+:Example Advertise device with ID suffix:
+ | **> name "BLE-Peripheral-001"**
+:Example Advertise long name (will be truncated to fit):
+ | **> name "0123456789abcdef0123456789abcdef"**
+:Example Long descriptive name (automatically truncated):
+ | **> name "This is a very long device name that will be truncated"**
+:Example Name with special characters:
+ | **> name "Device™"**
+:Example Name with accented characters:
+ | **> name "Tëst-Dëvicë"**
appearance
----------
@@ -181,6 +373,44 @@ appearance
Configure custom appearance to be advertised.
:Usage: **> appearance [on/off/value]**
+:Uses: **org.bluez.LEAdvertisement(5)** property **Appearance**
+:[value]: Appearance value (optional, shows current if omitted)
+:Example Show current appearance setting:
+ | **> appearance**
+:Example Enable appearance advertisement with default value:
+ | **> appearance on**
+:Example Disable appearance advertisement:
+ | **> appearance off**
+:Example Set appearance to keyboard (0x03C1):
+ | **> appearance 961**
+:Example Set appearance to mouse (0x03C2):
+ | **> appearance 962**
+:Example Set appearance to joystick (0x03C3):
+ | **> appearance 963**
+:Example Set appearance to gamepad (0x03C4):
+ | **> appearance 964**
+:Example Set appearance to generic audio sink (0x0340):
+ | **> appearance 832**
+:Example Set appearance to speaker (0x0341):
+ | **> appearance 833**
+:Example Set appearance to microphone (0x0342):
+ | **> appearance 834**
+:Example Set appearance to headset (0x0343):
+ | **> appearance 835**
+:Example Set appearance to headphones (0x0344):
+ | **> appearance 836**
+:Example Set appearance to heart rate sensor (0x0540):
+ | **> appearance 1344**
+:Example Set appearance to thermometer (0x05C0):
+ | **> appearance 1472**
+:Example Set appearance to glucose meter (0x0640):
+ | **> appearance 1600**
+:Example Set appearance to generic phone (0x0040):
+ | **> appearance 64**
+:Example Set appearance to generic computer (0x0080):
+ | **> appearance 128**
+:Example Set appearance to generic watch (0x00C0):
+ | **> appearance 192**
duration
--------
@@ -212,6 +442,24 @@ set for each Instance. The advertising interval is the maximum of the
advertising intervals set for each Instance.
:Usage: **> duration [seconds]**
+:Uses: **org.bluez.LEAdvertisement(5)** property **Duration**
+:[seconds]: Duration in seconds (optional, shows current if omitted)
+:Example Show current advertising duration setting:
+ | **> duration**
+:Example Use default duration (2 seconds):
+ | **> duration 0**
+:Example Set duration to 1 second:
+ | **> duration 1**
+:Example Set duration to 5 seconds:
+ | **> duration 5**
+:Example Set duration to 10 seconds:
+ | **> duration 10**
+:Example Set duration to 30 seconds:
+ | **> duration 30**
+:Example Set duration to 1 minute:
+ | **> duration 60**
+:Example Set duration to 5 minutes:
+ | **> duration 300**
timeout
-------
@@ -219,6 +467,18 @@ timeout
Set/Get advertise timeout.
:Usage: **> timeout [seconds]**
+:Uses: **org.bluez.LEAdvertisement(5)** property **Timeout**
+:[seconds]: Timeout in seconds (optional, shows current if omitted)
+:Example Show current advertising timeout setting:
+ | **> timeout**
+:Example Unlimited advertising (no timeout):
+ | **> timeout 0**
+:Example Stop advertising after 30 seconds:
+ | **> timeout 30**
+:Example Stop advertising after 2 minutes:
+ | **> timeout 120**
+:Example Stop advertising after 1 hour:
+ | **> timeout 3600**
secondary
---------
@@ -226,6 +486,33 @@ secondary
Set/Get advertise secondary channel.
:Usage: **> secondary [1M/2M/Coded]**
+:Uses: **org.bluez.LEAdvertisement(5)** property **SecondaryChannel**
+:[1M/2M/Coded]: Secondary channel (optional, shows current if omitted)
+:Example Show current secondary channel setting:
+ | **> secondary**
+:Example Use LE 1M PHY for secondary advertising channel:
+ | **> secondary 1M**
+:Example Use LE 2M PHY for secondary advertising channel:
+ | **> secondary 2M**
+:Example Use LE Coded PHY for secondary advertising channel:
+ | **> secondary Coded**
+
+rsi
+---
+
+Show/Enable/Disable RSI to be advertised.
+
+RSI (Resolvable Set Identifier) is used to advertise a resolvable identifier
+for Coordinated Set Identification.
+
+:Usage: **> rsi [on/off]**
+:[on/off]: Enable or disable RSI advertisement (optional, shows current if omitted)
+:Example Show current RSI setting:
+ | **> rsi**
+:Example Enable RSI advertisement:
+ | **> rsi on**
+:Example Disable RSI advertisement:
+ | **> rsi off**
interval
--------
@@ -252,7 +539,25 @@ set for each Instance.
The advertising interval is the maximum of the advertising intervals set for
each Instance.
-:Usage: **> interval [milliseconds]**
+:Usage: **> interval [min] [max]**
+:[min]: Minimum advertising interval in milliseconds (optional, shows current if omitted)
+:[max]: Maximum advertising interval in milliseconds (optional, defaults to min value)
+:Example Show current advertising interval setting:
+ | **> interval**
+:Example Set minimum advertising interval (20ms):
+ | **> interval 20**
+:Example Set advertising interval range (50-100ms):
+ | **> interval 50 100**
+:Example Set normal advertising interval (100ms):
+ | **> interval 100**
+:Example Set moderate advertising interval (200ms):
+ | **> interval 200**
+:Example Set slow advertising interval (500ms):
+ | **> interval 500**
+:Example Set very slow advertising interval (1 second):
+ | **> interval 1000**
+:Example Set maximum advertising interval (10.24 seconds):
+ | **> interval 10240**
clear
-----
@@ -266,6 +571,29 @@ first clear the advertise configuration and then set the new advertise
configuration.
:Usage: **> clear [uuids/service/manufacturer/config-name...]**
+:[uuids/service/manufacturer/config-name...]: List of configuration to clear
+:Example Clear all advertising configuration:
+ | **> clear**
+:Example Clear only advertised UUIDs:
+ | **> clear uuids**
+:Example Clear only service data:
+ | **> clear service**
+:Example Clear only manufacturer data:
+ | **> clear manufacturer**
+:Example Clear only advertised name:
+ | **> clear name**
+:Example Clear only appearance data:
+ | **> clear appearance**
+:Example Clear only TX power advertisement:
+ | **> clear tx-power**
+:Example Clear UUIDs and service data:
+ | **> clear uuids service**
+:Example Clear manufacturer data and name:
+ | **> clear manufacturer name**
+:Example Clear UUIDs, service data, and manufacturer data:
+ | **> clear uuids service manufacturer**
+:Example Clear discoverable mode and TX power:
+ | **> clear discoverable tx-power**
RESOURCES
=========
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 05/35] doc/bluetoothctl-assistant: Add :Uses: fields and document arguments
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (3 preceding siblings ...)
2026-01-30 19:38 ` [PATCH BlueZ v2 04/35] doc/bluetoothctl-advertise: " Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 06/35] doc/bluetoothctl-bredr: " Luiz Augusto von Dentz
` (30 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
doc/bluetoothctl-assistant.rst | 24 +++++++++++++++++++++---
1 file changed, 21 insertions(+), 3 deletions(-)
diff --git a/doc/bluetoothctl-assistant.rst b/doc/bluetoothctl-assistant.rst
index 33fbcbc764cf..ff22e2a82291 100644
--- a/doc/bluetoothctl-assistant.rst
+++ b/doc/bluetoothctl-assistant.rst
@@ -18,6 +18,9 @@ SYNOPSIS
**bluetoothctl** [--options] [assistant.commands]
+This submenu manages BAP Broadcast Assistants using the
+**org.bluez.MediaAssistant(5)** interface.
+
Assistant Commands
==================
@@ -27,6 +30,8 @@ list
List available assistants.
:Usage: **> list**
+:Example Display all available BAP Broadcast Assistants:
+ | **> list**
show
----
@@ -34,6 +39,12 @@ show
Show assistant information.
:Usage: **> show [assistant]**
+:Uses: **org.bluez.MediaAssistant(5)** properties
+:[assistant]: BAP Broadcast Assistant path (optional, shows current if omitted)
+:Example Show information for currently selected assistant:
+ | **> show**
+:Example Show specific BAP Broadcast Assistant information:
+ | **> show /org/bluez/hci0/src_05_1F_EE_F3_F8_7D/dev_00_60_37_31_7E_3F/bis1**
push
----
@@ -66,9 +77,16 @@ Code, a zero filled array will be sent to the peer. Otherwise,
the string entered by the user will be sent as an array of bytes.
:Usage: **> push <assistant>**
-:Example: | **> push /org/bluez/hci0/src_05_1F_EE_F3_F8_7D/dev_00_60_37_31_7E_3F/bis1**
- | **[Assistant] Enter Metadata (auto/value): 0x03 0x02 0x04 0x00**
- | **[Assistant] Enter Broadcast Code (auto/value): Borne House**
+:Uses: **org.bluez.MediaAssistant(5)** method **Push**
+:<assistant>: BAP Broadcast Assistant path to send stream information to
+:Example Push stream info with automatic metadata and broadcast code:
+ | **> push /org/bluez/hci0/src_05_1F_EE_F3_F8_7D/dev_00_60_37_31_7E_3F/bis1**
+ | **[Assistant] Enter Metadata (auto/value): auto**
+ | **[Assistant] Enter Broadcast Code (auto/value): auto**
+:Example Push stream info with custom metadata and broadcast code:
+ | **> push /org/bluez/hci0/src_05_1F_EE_F3_F8_7D/dev_00_60_37_31_7E_3F/bis1**
+ | **[Assistant] Enter Metadata (auto/value): 0x03 0x02 0x04 0x00**
+ | **[Assistant] Enter Broadcast Code (auto/value): Borne House**
RESOURCES
=========
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 06/35] doc/bluetoothctl-bredr: Add :Uses: fields and document arguments
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (4 preceding siblings ...)
2026-01-30 19:38 ` [PATCH BlueZ v2 05/35] doc/bluetoothctl-assistant: " Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 07/35] doc/bluetoothctl-endpoint: " Luiz Augusto von Dentz
` (29 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
doc/bluetoothctl-bredr.rst | 25 +++++++++++++++++++++----
1 file changed, 21 insertions(+), 4 deletions(-)
diff --git a/doc/bluetoothctl-bredr.rst b/doc/bluetoothctl-bredr.rst
index 3ec702a59ff3..2425707f3285 100644
--- a/doc/bluetoothctl-bredr.rst
+++ b/doc/bluetoothctl-bredr.rst
@@ -18,6 +18,9 @@ SYNOPSIS
**bluetoothctl** [--options] [bredr.commands]
+This submenu manages BR/EDR (Classic Bluetooth) bearer connections using the
+**org.bluez.Device(5)** interface.
+
BREDR Commands
==============
@@ -27,6 +30,8 @@ list
List available bredr devices.
:Usage: **> list**
+:Example Display all BR/EDR (Classic Bluetooth) devices that have been discovered:
+ | **> list**
show
----
@@ -34,6 +39,12 @@ show
Show bredr bearer information on a device.
:Usage: **> show [dev]**
+:Uses: **org.bluez.Device(5)** properties
+:[dev]: Bluetooth device address or object path (optional, uses current device if omitted)
+:Example Show BR/EDR bearer information for currently selected device:
+ | **> show**
+:Example Show BR/EDR bearer info for device with specified address:
+ | **> show 00:11:22:33:44:55**
connect
-------
@@ -45,8 +56,11 @@ This command initiates a bredr connection to a remote device.
By default, it establishes the bredr connection and then connects all profiles
that marked as auto-connectable.
-:Usage: > connect <dev>
-:Example: > connect 1C:48:F9:9D:81:5C
+:Usage: **> connect <dev>**
+:Uses: **org.bluez.Device(5)** method **Connect**
+:<dev>: Bluetooth device address to connect to
+:Example Connect to BR/EDR device:
+ | **> connect 00:11:22:33:44:55**
disconnect
----------
@@ -56,8 +70,11 @@ Disconnect device over bredr.
By default this command disconnects all profiles associated with the bredr
connection, and then terminates the bredr link.
-:Usage: > disconnect <dev>
-:Example: > disconnect 1C:48:F9:9D:81:5C
+:Usage: **> disconnect <dev>**
+:Uses: **org.bluez.Device(5)** method **Disconnect**
+:<dev>: Bluetooth device address to disconnect from
+:Example Disconnect from BR/EDR device:
+ | **> disconnect 00:11:22:33:44:55**
RESOURCES
=========
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 07/35] doc/bluetoothctl-endpoint: Add :Uses: fields and document arguments
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (5 preceding siblings ...)
2026-01-30 19:38 ` [PATCH BlueZ v2 06/35] doc/bluetoothctl-bredr: " Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 08/35] doc/bluetoothctl-gatt: " Luiz Augusto von Dentz
` (28 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
doc/bluetoothctl-endpoint.rst | 217 +++++++++++++++++++++++-----------
1 file changed, 145 insertions(+), 72 deletions(-)
diff --git a/doc/bluetoothctl-endpoint.rst b/doc/bluetoothctl-endpoint.rst
index b7ecd96244b7..019e64e38452 100644
--- a/doc/bluetoothctl-endpoint.rst
+++ b/doc/bluetoothctl-endpoint.rst
@@ -18,6 +18,9 @@ SYNOPSIS
**bluetoothctl** [--options] [endpoint.commands]
+This submenu manages media endpoints for audio streaming using the
+**org.bluez.MediaEndpoint(5)** and **org.bluez.Media(5)** interfaces.
+
Endpoint Commands
=================
@@ -27,6 +30,11 @@ list
List available endpoints.
:Usage: **> list [local]**
+:[local]: Only show locally registered endpoints (optional, shows all if omitted)
+:Example List all available endpoints (local and remote):
+ | **> list**
+:Example List only locally registered endpoints:
+ | **> list local**
show
----
@@ -34,6 +42,16 @@ show
Endpoint information.
:Usage: **> show [endpoint]**
+:Uses: **org.bluez.MediaEndpoint(5)** properties
+:[endpoint]: Path to specific endpoint to display (optional, shows current selection if omitted)
+:Example Show information for currently selected endpoint:
+ | **> show**
+:Example Show local endpoint information:
+ | **> show /local/endpoint/ep0**
+:Example Show remote endpoint information:
+ | **> show /org/bluez/hci0/dev_00_11_22_33_44_55/ep1**
+:Example Show another local endpoint:
+ | **> show /local/endpoint/ep1**
register
--------
@@ -41,37 +59,41 @@ register
Register Endpoint.
:Usage: **> register <UUID> <codec[:company]> [capabilities...]**
+:Uses: **org.bluez.Media(5)** method **RegisterEndpoint**
+:<UUID>: Bluetooth service UUID for the endpoint type (required)
+:<codec[:company]>: Codec ID in hex format, optionally with company ID (required)
+:[capabilities...]: Optional codec-specific capability data in hex format
:Example LC3 BAP source:
- | **>endpoint.register 00002bcb-0000-1000-8000-00805f9b34fb 0x06**
- | **>Auto Accept (yes/no):** y
- | **>Max Transports (auto/value):** a
- | **>Locations:** a
- | **>Supported Context (value):** 3
- | **>Context (value):** 3
- | **>CIG (auto/value):** a
- | **>CIS (auto/value):** a
+ | **>endpoint.register 00002bcb-0000-1000-8000-00805f9b34fb 0x06**
+ | **>Auto Accept (yes/no):** y
+ | **>Max Transports (auto/value):** a
+ | **>Locations:** a
+ | **>Supported Context (value):** 3
+ | **>Context (value):** 3
+ | **>CIG (auto/value):** a
+ | **>CIS (auto/value):** a
:Example LC3 BAP sink with extra capabilities:
- | **>endpoint.register 00002bc9-0000-1000-8000-00805f9b34fb 0x06 "0x03 0xe5 0x03 0x00 0x02 0xe6 0x07"**
- | **>Enter Metadata (value/no):** n
- | **>Auto Accept (yes/no):** y
- | **>Max Transports (auto/value):** a
- | **>Locations:** a
- | **>Supported Context (value):** 3
- | **>Context (value):** 3
- | **>CIG (auto/value):** a
- | **>CIS (auto/value):** a
+ | **>endpoint.register 00002bc9-0000-1000-8000-00805f9b34fb 0x06 "0x03 0xe5 0x03 0x00 0x02 0xe6 0x07"**
+ | **>Enter Metadata (value/no):** n
+ | **>Auto Accept (yes/no):** y
+ | **>Max Transports (auto/value):** a
+ | **>Locations:** a
+ | **>Supported Context (value):** 3
+ | **>Context (value):** 3
+ | **>CIG (auto/value):** a
+ | **>CIS (auto/value):** a
:Example LC3 BAP Broadcast source:
- | **>endpoint.register 00001852-0000-1000-8000-00805f9b34fb 0x06**
- | **>Auto Accept (yes/no):** y
- | **>Max Transports (auto/value):** a
- | **>Locations:** 3
- | **>Supported Context (value):** 1
+ | **>endpoint.register 00001852-0000-1000-8000-00805f9b34fb 0x06**
+ | **>Auto Accept (yes/no):** y
+ | **>Max Transports (auto/value):** a
+ | **>Locations:** 3
+ | **>Supported Context (value):** 1
:Example LC3 BAP Broadcast sink:
- | **>endpoint.register 00001851-0000-1000-8000-00805f9b34fb 0x06**
- | **>Auto Accept (yes/no):** y
- | **>Max Transports (auto/value):** a
- | **>Locations:** 3
- | **>Supported Context (value):** 1
+ | **>endpoint.register 00001851-0000-1000-8000-00805f9b34fb 0x06**
+ | **>Auto Accept (yes/no):** y
+ | **>Max Transports (auto/value):** a
+ | **>Locations:** 3
+ | **>Supported Context (value):** 1
Note:
@@ -86,6 +108,24 @@ unregister
Unregister Endpoint.
:Usage: **> unregister <UUID/object>**
+:Uses: **org.bluez.Media(5)** method **UnregisterEndpoint**
+:<UUID/object>: Either the service UUID or the object path of the endpoint to unregister
+:Example Unregister LC3 source endpoint by UUID:
+ | **> unregister 00002bcb-0000-1000-8000-00805f9b34fb**
+:Example Unregister LC3 sink endpoint by UUID:
+ | **> unregister 00002bc9-0000-1000-8000-00805f9b34fb**
+:Example Unregister broadcast source endpoint by UUID:
+ | **> unregister 00001852-0000-1000-8000-00805f9b34fb**
+:Example Unregister broadcast sink endpoint by UUID:
+ | **> unregister 00001851-0000-1000-8000-00805f9b34fb**
+:Example Unregister endpoint by object path:
+ | **> unregister /local/endpoint/ep0**
+:Example Unregister another endpoint by object path:
+ | **> unregister /local/endpoint/ep1**
+:Example Unregister source endpoint by path:
+ | **> unregister /local/endpoint/source0**
+:Example Unregister sink endpoint by path:
+ | **> unregister /local/endpoint/sink0**
Note:
@@ -98,6 +138,16 @@ config
Configure Endpoint.
:Usage: **> config <endpoint> <local endpoint> [preset]**
+:Uses: **org.bluez.MediaEndpoint(5)** method **SetConfiguration**
+:<endpoint>: Path to the remote endpoint to configure
+:<local endpoint>: Path to the local endpoint to use for the configuration
+:[preset]: Audio quality preset name (optional, auto-detected if omitted)
+:Example Configure remote endpoint with local endpoint (auto preset):
+ | **> config /org/bluez/hci0/dev_00_11_22_33_44_55/ep0 /local/endpoint/ep0**
+:Example Configure LE Audio Unicast with BAP setting 32_1_1:
+ | **> config /org/bluez/hci0/dev_00_11_22_33_44_55/ep0 /local/endpoint/ep0 32_1_1**
+:Example Configure LE Audio Broadcast Source:
+ | **> config /org/bluez/hci0/dev_00_11_22_33_44_55/bis0 /local/endpoint/broadcast0**
Note:
@@ -110,55 +160,78 @@ presets
List available presets.
:Usage: **> presets <endpoint>/<UUID> [codec[:company]] [preset] [codec config] [metadata]**
+:<endpoint>/<UUID>: Either endpoint path or service UUID to work with presets
+:[codec[:company]]: Codec ID with optional company identifier
+:[preset]: Preset name to display details or create custom preset
+:[codec config]: Custom codec configuration data in hex format
+:[metadata]: Additional metadata for the preset
:Example using endpoint:
- | **>presets /local/endpoint/ep0 32_1_1**
- | **>presets /local/endpoint/ep0**
- | Preset 32_1_1
- | Configuration.**>0: len 0x02 type 0x01
- | Configuration.Sampling Frequency: 32 Khz (0x06)
- | Configuration.**>1: len 0x02 type 0x02
- | Configuration.Frame Duration: 7.5 ms (0x00)
- | Configuration.**>2: len 0x03 type 0x04
- | Configuration.Frame Length: 60 (0x003c)
+ | **>presets /local/endpoint/ep0 32_1_1**
+ | **>presets /local/endpoint/ep0**
+ | Preset 32_1_1
+ | Configuration.**>0: len 0x02 type 0x01
+ | Configuration.Sampling Frequency: 32 Khz (0x06)
+ | Configuration.**>1: len 0x02 type 0x02
+ | Configuration.Frame Duration: 7.5 ms (0x00)
+ | Configuration.**>2: len 0x03 type 0x04
+ | Configuration.Frame Length: 60 (0x003c)
+:Example List all available presets for local endpoint:
+ | **>presets /local/endpoint/ep0**
+:Example List all presets for another endpoint:
+ | **>presets /local/endpoint/ep1**
:Example using UUID:
- | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06 32_1_1**
- | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06**
- | ...
- | ***32_1_1**
+ | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06 32_1_1**
+ | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06**
+ | ...
+ | ***32_1_1**
+:Example List all LC3 sink presets:
+ | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06**
+:Example List all LC3 source presets:
+ | **>presets 00002bcb-0000-1000-8000-00805f9b34fb 0x06**
+:Example List all broadcast source presets:
+ | **>presets 00001852-0000-1000-8000-00805f9b34fb 0x06**
+:Example List all broadcast sink presets:
+ | **>presets 00001851-0000-1000-8000-00805f9b34fb 0x06**
+:Example Show details for 48kHz stereo preset:
+ | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06 48_2_1**
+:Example Show details for 24kHz mono high-quality preset:
+ | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06 24_1_2**
+:Example Show details for 16kHz mono preset:
+ | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06 16_1_1**
:Example setting up LC3 custom preset:
- | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06 custom**
- | **>[Codec] Enter frequency (Khz):** 48
- | **>[Codec] Enter frame duration (ms):** 10
- | **>[Codec] Enter channel allocation:** 3
- | **>[Codec] Enter frame length:** 100
- | **>[QoS] Enter Target Latency (Low, Balance, High):** Low
- | **>[QoS] Enter SDU Interval (us):** 1000
- | **>[QoS] Enter Framing (Unframed, Framed):** Unframed
- | **>[QoS] Enter PHY (1M, 2M):** 2M
- | **>[QoS] Enter Max SDU:** 200
- | **>[QoS] Enter RTN:** 3
- | **>[QoS] Enter Max Transport Latency (ms):** 10
- | **>[QoS] Enter Presentation Delay (us):** 20000
- | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06**
- | ...
- | ***custom**
+ | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06 custom**
+ | **>[Codec] Enter frequency (Khz):** 48
+ | **>[Codec] Enter frame duration (ms):** 10
+ | **>[Codec] Enter channel allocation:** 3
+ | **>[Codec] Enter frame length:** 100
+ | **>[QoS] Enter Target Latency (Low, Balance, High):** Low
+ | **>[QoS] Enter SDU Interval (us):** 1000
+ | **>[QoS] Enter Framing (Unframed, Framed):** Unframed
+ | **>[QoS] Enter PHY (1M, 2M):** 2M
+ | **>[QoS] Enter Max SDU:** 200
+ | **>[QoS] Enter RTN:** 3
+ | **>[QoS] Enter Max Transport Latency (ms):** 10
+ | **>[QoS] Enter Presentation Delay (us):** 20000
+ | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06**
+ | ...
+ | ***custom**
:Example setting up LC3 custom preset with extra configuration:
- | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06 custom "0x03 0xe8 0x00 0x00 0x02 0xe9 0x00"**
- | **>[Codec] Enter frequency (Khz):** 48
- | **>[Codec] Enter frame duration (ms):** 10
- | **>[Codec] Enter channel allocation:** 3
- | **>[Codec] Enter frame length:** 100
- | **>[QoS] Enter Target Latency (Low, Balance, High):** Low
- | **>[QoS] Enter SDU Interval (us):** 1000
- | **>[QoS] Enter Framing (Unframed, Framed):** Unframed
- | **>[QoS] Enter PHY (1M, 2M):** 2M
- | **>[QoS] Enter Max SDU:** 200
- | **>[QoS] Enter RTN:** 3
- | **>[QoS] Enter Max Transport Latency (ms):** 10
- | **>[QoS] Enter Presentation Delay (us):** 20000
- | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06**
- | ...
- | ***custom**
+ | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06 custom "0x03 0xe8 0x00 0x00 0x02 0xe9 0x00"**
+ | **>[Codec] Enter frequency (Khz):** 48
+ | **>[Codec] Enter frame duration (ms):** 10
+ | **>[Codec] Enter channel allocation:** 3
+ | **>[Codec] Enter frame length:** 100
+ | **>[QoS] Enter Target Latency (Low, Balance, High):** Low
+ | **>[QoS] Enter SDU Interval (us):** 1000
+ | **>[QoS] Enter Framing (Unframed, Framed):** Unframed
+ | **>[QoS] Enter PHY (1M, 2M):** 2M
+ | **>[QoS] Enter Max SDU:** 200
+ | **>[QoS] Enter RTN:** 3
+ | **>[QoS] Enter Max Transport Latency (ms):** 10
+ | **>[QoS] Enter Presentation Delay (us):** 20000
+ | **>presets 00002bc9-0000-1000-8000-00805f9b34fb 0x06**
+ | ...
+ | ***custom**
RESOURCES
=========
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 08/35] doc/bluetoothctl-gatt: Add :Uses: fields and document arguments
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (6 preceding siblings ...)
2026-01-30 19:38 ` [PATCH BlueZ v2 07/35] doc/bluetoothctl-endpoint: " Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 09/35] doc/bluetoothctl-hci: " Luiz Augusto von Dentz
` (27 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
doc/bluetoothctl-gatt.rst | 249 +++++++++++++++++++++++++++++++++++++-
1 file changed, 244 insertions(+), 5 deletions(-)
diff --git a/doc/bluetoothctl-gatt.rst b/doc/bluetoothctl-gatt.rst
index 6c72302ae935..493c7cf3b2c1 100644
--- a/doc/bluetoothctl-gatt.rst
+++ b/doc/bluetoothctl-gatt.rst
@@ -18,6 +18,10 @@ SYNOPSIS
**bluetoothctl** [--options] [gatt.commands]
+This submenu interacts with GATT services, characteristics, and descriptors
+using the **org.bluez.GattService(5)**, **org.bluez.GattCharacteristic(5)**,
+**org.bluez.GattDescriptor(5)**, and **org.bluez.GattManager(5)** interfaces.
+
Generic Attribute Commands
==========================
@@ -30,7 +34,24 @@ encompassing services, characteristics, and handles. This command provides
a comprehensive overview of the available Bluetooth attributes, which can
be further interacted with using other commands.
-:Usage: **> list-attributes <attribute/UUID> <dev/local>**
+:Usage: **> list-attributes [dev/local]**
+:[dev/local]: Device MAC address, object path, or "local" to list locally registered attributes (optional, lists all if omitted)
+:Example List attributes for specific service:
+ | **> list-attributes /org/bluez/hci0/dev_00_11_22_33_44_55/service001a**
+:Example List attributes for specific characteristic:
+ | **> list-attributes /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c**
+:Example List attributes for service on different device:
+ | **> list-attributes /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service0020**
+:Example List all Generic Access service attributes:
+ | **> list-attributes 0x1800**
+:Example List all Battery Service attributes:
+ | **> list-attributes 0x180F**
+:Example List all Device Name characteristic attributes:
+ | **> list-attributes 0x2A00**
+:Example List attributes using full UUID:
+ | **> list-attributes 00001801-0000-1000-8000-00805f9b34fb**
+:Example List attributes for custom service UUID:
+ | **> list-attributes 12345678-1234-5678-9abc-123456789abc**
select-attribute
----------------
@@ -41,7 +62,25 @@ must select it with this command. This establishes a context for many
other commands (read, write, notify, etc.), specifying the attribute
they should operate on.
-:Usage: **> select-attribute <attribute/UUID/local>**
+:Usage: **> select-attribute <attribute/UUID/local> [attribute/UUID]**
+:<attribute/UUID/local>: GATT attribute path, UUID, or "local" to select from local attributes
+:[attribute/UUID]: Additional attribute path or UUID when using "local" (optional)
+:Example Select specific characteristic:
+ | **> select-attribute /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c**
+:Example Select specific descriptor:
+ | **> select-attribute /org/bluez/hci0/dev_00_11_22_33_44_55/service0020/char0022/desc0024**
+:Example Select service on different device:
+ | **> select-attribute /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service001a**
+:Example Select Device Name characteristic:
+ | **> select-attribute 0x2A00**
+:Example Select Battery Level characteristic:
+ | **> select-attribute 0x2A19**
+:Example Select Client Characteristic Configuration descriptor:
+ | **> select-attribute 0x2902**
+:Example Select Temperature characteristic using full UUID:
+ | **> select-attribute 00002a6e-0000-1000-8000-00805f9b34fb**
+:Example Select custom characteristic:
+ | **> select-attribute 12345678-1234-5678-9abc-123456789abc**
attribute-info
--------------
@@ -52,6 +91,17 @@ attribute. This command is useful for understanding the properties and
capabilities of an attribute.
:Usage: **> attribute-info [attribute/UUID]**
+:[attribute/UUID]: GATT attribute path or UUID to get info for (optional, uses current if omitted)
+:Example Show information for currently selected attribute:
+ | **> attribute-info**
+:Example Show info for specific characteristic:
+ | **> attribute-info /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c**
+:Example Show info for Battery Level characteristic:
+ | **> attribute-info 0x2A19**
+:Example Show info for Device Name characteristic:
+ | **> attribute-info 0x2A00**
+:Example Show info for Temperature characteristic:
+ | **> attribute-info 00002a6e-0000-1000-8000-00805f9b34fb**
read
----
@@ -61,6 +111,18 @@ beforehand with select-attribute. The optional offset parameter can be
used for attributes that allow partial reads.
:Usage: **> read [offset]**
+:Uses: **org.bluez.GattCharacteristic(5)** method **ReadValue**
+:[offset]: Byte offset to start reading from (optional, defaults to 0)
+:Example Read attribute value from offset 0:
+ | **> read**
+:Example Read attribute value from offset 0 (explicit):
+ | **> read 0**
+:Example Read attribute value starting from offset 4:
+ | **> read 4**
+:Example Read attribute value starting from offset 10:
+ | **> read 10**
+:Example Read attribute value starting from offset 16:
+ | **> read 16**
write
-----
@@ -70,7 +132,25 @@ be selected in advance using select-attribute. Data must be provided in
hexadecimal format. Optional offset and type parameters can accommodate
specific write requirements.
-:Usage: **> write <data=xx xx ...> [offset] [type]**
+:Usage: **> write <data="xx xx ..."> [offset] [type]**
+:Uses: **org.bluez.GattCharacteristic(5)** method **WriteValue**
+:<xx xx ...>: Hexadecimal data bytes to write to the attribute
+:[offset]: Byte offset to start writing at (optional, defaults to 0)
+:[type]: Write type - request, command, or reliable (optional, defaults to request)
+:Example Write "Hello" to attribute (ASCII bytes):
+ | **> write "48 65 6C 6C 6F"**
+:Example Write binary data to attribute:
+ | **> write "01 02 03 04"**
+:Example Write single byte value:
+ | **> write "FF"**
+:Example Write 2 bytes starting at offset 4:
+ | **> write "01 02" 4**
+:Example Write with write request (default):
+ | **> write "48 65 6C 6C 6F" 0 request**
+:Example Write with write command (no response):
+ | **> write "01 02 03" 0 command**
+:Example Write with reliable write:
+ | **> write "FF EE DD" 0 reliable**
acquire-write
-------------
@@ -80,6 +160,9 @@ is useful for applications that need a file descriptor to perform
write operations.
:Usage: **> acquire-write**
+:Uses: **org.bluez.GattCharacteristic(5)** method **AcquireWrite**
+:Example Acquire write file descriptor for current attribute:
+ | **> acquire-write**
release-write
-------------
@@ -89,6 +172,8 @@ command is necessary to clean up resources after you're done with the
write operation.
:Usage: **> release-write**
+:Example Release write file descriptor for current attribute:
+ | **> release-write**
acquire-notify
--------------
@@ -98,6 +183,9 @@ This enables applications to listen for notifications on attribute
value changes.
:Usage: **> acquire-notify**
+:Uses: **org.bluez.GattCharacteristic(5)** method **AcquireNotify**
+:Example Acquire notify file descriptor for current attribute:
+ | **> acquire-notify**
release-notify
--------------
@@ -106,6 +194,8 @@ Releases the Notify file descriptor obtained with acquire-notify. Ensures
resources are freed once notification listening is no longer needed.
:Usage: **> release-notify**
+:Example Release notify file descriptor for current attribute:
+ | **> release-notify**
notify
------
@@ -116,6 +206,12 @@ command allows applications to be notified of attribute changes without
polling.
:Usage: **> notify <on/off>**
+:Uses: **org.bluez.GattCharacteristic(5)** methods **StartNotify**, **StopNotify**
+:<on/off>: Enable or disable notifications for the current attribute
+:Example Enable notifications for current attribute:
+ | **> notify on**
+:Example Disable notifications for current attribute:
+ | **> notify off**
clone
-----
@@ -124,6 +220,21 @@ Creates a clone of a device or attribute. This can be useful for creating
a backup or working with a copy for testing purposes.
:Usage: **> clone [dev/attribute/UUID]**
+:[dev/attribute/UUID]: Device MAC address, attribute path, or UUID to clone (optional, clones current if omitted)
+:Example Clone entire device GATT database:
+ | **> clone 00:11:22:33:44:55**
+:Example Clone another device:
+ | **> clone AA:BB:CC:DD:EE:FF**
+:Example Clone specific service:
+ | **> clone /org/bluez/hci0/dev_00_11_22_33_44_55/service001a**
+:Example Clone specific characteristic:
+ | **> clone /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c**
+:Example Clone Generic Access service:
+ | **> clone 0x1800**
+:Example Clone Battery Service:
+ | **> clone 0x180F**
+:Example Clone Battery Level characteristic:
+ | **> clone 0x2A19**
register-application
--------------------
@@ -133,6 +244,18 @@ management of services, characteristics, and descriptors under this
application.
:Usage: **> register-application [UUID ...]**
+:Uses: **org.bluez.GattManager(5)** method **RegisterApplication**
+:[UUID ...]: Optional list of service UUIDs to register with the application
+:Example Register GATT application without specific UUIDs:
+ | **> register-application**
+:Example Register application with Battery Service:
+ | **> register-application 0x180F**
+:Example Register with Generic Access and Battery Service:
+ | **> register-application 0x1800 0x180F**
+:Example Register application with custom service UUID:
+ | **> register-application 12345678-1234-5678-9abc-123456789abc**
+:Example Register with multiple standard services:
+ | **> register-application 0x1800 0x180F 0x180A**
unregister-application
----------------------
@@ -140,6 +263,9 @@ unregister-application
Removes a previously registered application from the Bluetooth system.
:Usage: **> unregister-application**
+:Uses: **org.bluez.GattManager(5)** method **UnregisterApplication**
+:Example Unregister current GATT application:
+ | **> unregister-application**
register-service
----------------
@@ -148,6 +274,24 @@ Adds a new service under a registered application. This command is
crucial for defining new services that devices can offer.
:Usage: **> register-service <UUID> [handle]**
+:<UUID>: Service UUID to register (16-bit, 32-bit, or 128-bit format)
+:[handle]: Specific attribute handle to assign (optional, auto-assigned if omitted)
+:Example Register Generic Access service (auto handle):
+ | **> register-service 0x1800**
+:Example Register Battery Service (auto handle):
+ | **> register-service 0x180F**
+:Example Register Device Information service (auto handle):
+ | **> register-service 0x180A**
+:Example Register Generic Access service at handle 1:
+ | **> register-service 0x1800 0x0001**
+:Example Register Battery Service at handle 16:
+ | **> register-service 0x180F 0x0010**
+:Example Register Device Info service at handle 32:
+ | **> register-service 0x180A 0x0020**
+:Example Register custom service (auto handle):
+ | **> register-service 12345678-1234-5678-9abc-123456789abc**
+:Example Register custom service at specific handle:
+ | **> register-service 12345678-1234-5678-9abc-123456789abc 0x0050**
unregister-service
------------------
@@ -156,6 +300,17 @@ Removes a service from a registered application, effectively ceasing
its availability.
:Usage: **> unregister-service <UUID/object>**
+:<UUID/object>: Service UUID or object path of the service to unregister
+:Example Unregister Generic Access service:
+ | **> unregister-service 0x1800**
+:Example Unregister Battery Service:
+ | **> unregister-service 0x180F**
+:Example Unregister custom service:
+ | **> unregister-service 12345678-1234-5678-9abc-123456789abc**
+:Example Unregister service by object path:
+ | **> unregister-service /org/bluez/example/service0**
+:Example Unregister another service:
+ | **> unregister-service /org/bluez/example/service1**
register-includes
-----------------
@@ -163,14 +318,28 @@ register-includes
Marks a service as included within another service, allowing for
service hierarchies and complex service structures.
-:Usage: **>r egister-includes <UUID> [handle]**
+:Usage: **> register-includes <UUID> [handle]**
+:<UUID>: Service UUID to register as included service
+:[handle]: Specific attribute handle to assign (optional, auto-assigned if omitted)
+:Example Register Generic Access as included service:
+ | **> register-includes 0x1800**
+:Example Register Battery Service as included at handle 21:
+ | **> register-includes 0x180F 0x0015**
+:Example Register custom service as included:
+ | **> register-includes 12345678-1234-5678-9abc-123456789abc**
unregister-includes
-------------------
Removes an included service relationship, simplifying the service structure.
-:Usage: **> unregister-includes <Service-UUID><Inc-UUID>**
+:Usage: **> unregister-includes <Service-UUID> <Inc-UUID>**
+:<Service-UUID>: Parent service UUID that contains the included service
+:<Inc-UUID>: Included service UUID to remove from the parent service
+:Example Unregister Battery Service inclusion from Generic Access:
+ | **> unregister-includes 0x1800 0x180F**
+:Example Unregister Device Info inclusion from custom service:
+ | **> unregister-includes 12345678-1234-5678-9abc-123456789abc 0x180A**
register-characteristic
-----------------------
@@ -179,6 +348,31 @@ Introduces a new characteristic under a service, specifying its properties
and access permissions with flags.
:Usage: **> register-characteristic <UUID> <Flags=read,write,notify...> [handle]**
+:<UUID>: Characteristic UUID to register (16-bit, 32-bit, or 128-bit format)
+:<Flags=read,write,notify...>: Comma-separated list of characteristic properties and permissions
+:[handle]: Specific attribute handle to assign (optional, auto-assigned if omitted)
+:Example Register Device Name (read-only):
+ | **> register-characteristic 0x2A00 read**
+:Example Register Battery Level (read + notifications):
+ | **> register-characteristic 0x2A19 read,notify**
+:Example Register Heart Rate Measurement (notify-only):
+ | **> register-characteristic 0x2A37 notify**
+:Example Register Device Name (read + write):
+ | **> register-characteristic 0x2A00 read,write**
+:Example Register Battery Level (read + write + notify):
+ | **> register-characteristic 0x2A19 read,write,notify**
+:Example Register Temperature (read + indications):
+ | **> register-characteristic 0x2A6E read,indicate**
+:Example Register Device Name at handle 3:
+ | **> register-characteristic 0x2A00 read 0x0003**
+:Example Register Battery Level at handle 19:
+ | **> register-characteristic 0x2A19 read,notify 0x0013**
+:Example Register custom characteristic with full capabilities:
+ | **> register-characteristic 12345678-1234-5678-9abc-123456789abc read,write,notify**
+:Example Register custom write-only characteristic:
+ | **> register-characteristic ABCD1234-ABCD-1234-ABCD-123456789ABC write-without-response**
+:Example Register with all flags:
+ | **> register-characteristic 0x2A00 read,write,write-without-response,notify,indicate**
unregister-characteristic
-------------------------
@@ -186,6 +380,17 @@ unregister-characteristic
Eliminates a characteristic from a service, removing its functionality.
:Usage: **> unregister-characteristic <UUID/object>**
+:<UUID/object>: Characteristic UUID or object path of the characteristic to unregister
+:Example Unregister Device Name characteristic:
+ | **> unregister-characteristic 0x2A00**
+:Example Unregister Battery Level characteristic:
+ | **> unregister-characteristic 0x2A19**
+:Example Unregister custom characteristic:
+ | **> unregister-characteristic 12345678-1234-5678-9abc-123456789abc**
+:Example Unregister characteristic by object path:
+ | **> unregister-characteristic /org/bluez/example/service0/char0**
+:Example Unregister another characteristic:
+ | **> unregister-characteristic /org/bluez/example/service1/char1**
register-descriptor
-------------------
@@ -194,6 +399,29 @@ Adds a descriptor to a characteristic, further defining its behavior and
access controls.
:Usage: **> register-descriptor <UUID> <Flags=read,write...> [handle]**
+:<UUID>: Descriptor UUID to register (16-bit, 32-bit, or 128-bit format)
+:<Flags=read,write...>: Comma-separated list of descriptor properties and permissions
+:[handle]: Specific attribute handle to assign (optional, auto-assigned if omitted)
+:Example Register Client Characteristic Configuration:
+ | **> register-descriptor 0x2902 read,write**
+:Example Register Characteristic User Description:
+ | **> register-descriptor 0x2901 read**
+:Example Register Characteristic Presentation Format:
+ | **> register-descriptor 0x2904 read**
+:Example Register CCCD at handle 5:
+ | **> register-descriptor 0x2902 read,write 0x0005**
+:Example Register User Description at handle 21:
+ | **> register-descriptor 0x2901 read 0x0015**
+:Example Register custom descriptor:
+ | **> register-descriptor 12345678-1234-5678-9abc-123456789abc read,write**
+:Example Register custom read-only descriptor:
+ | **> register-descriptor ABCD1234-ABCD-1234-ABCD-123456789ABC read**
+:Example Register Valid Range descriptor:
+ | **> register-descriptor 0x2906 read**
+:Example Register External Report Reference:
+ | **> register-descriptor 0x2907 read**
+:Example Register Report Reference:
+ | **> register-descriptor 0x2908 read**
unregister-descriptor
---------------------
@@ -201,6 +429,17 @@ unregister-descriptor
Removes a descriptor from a characteristic, simplifying its behavior.
:Usage: **> unregister-descriptor <UUID/object>**
+:<UUID/object>: Descriptor UUID or object path of the descriptor to unregister
+:Example Unregister Client Characteristic Configuration:
+ | **> unregister-descriptor 0x2902**
+:Example Unregister Characteristic User Description:
+ | **> unregister-descriptor 0x2901**
+:Example Unregister custom descriptor:
+ | **> unregister-descriptor 12345678-1234-5678-9abc-123456789abc**
+:Example Unregister descriptor by object path:
+ | **> unregister-descriptor /org/bluez/example/service0/char0/desc0**
+:Example Unregister another descriptor:
+ | **> unregister-descriptor /org/bluez/example/service1/char1/desc1**
RESOURCES
=========
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 09/35] doc/bluetoothctl-hci: Add :Uses: fields and document arguments
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (7 preceding siblings ...)
2026-01-30 19:38 ` [PATCH BlueZ v2 08/35] doc/bluetoothctl-gatt: " Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 10/35] doc/bluetoothctl-le: " Luiz Augusto von Dentz
` (26 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
doc/bluetoothctl-hci.rst | 112 ++++++++++++++++++++++++++++++++++-----
1 file changed, 99 insertions(+), 13 deletions(-)
diff --git a/doc/bluetoothctl-hci.rst b/doc/bluetoothctl-hci.rst
index 70aa5e7afaa4..05cd763f5465 100644
--- a/doc/bluetoothctl-hci.rst
+++ b/doc/bluetoothctl-hci.rst
@@ -18,6 +18,11 @@ SYNOPSIS
**bluetoothctl** [--options] [hci.commands]
+.. note::
+ This submenu communicates directly with the Bluetooth controller via HCI
+ socket, bypassing the BlueZ D-Bus API. Commands use the Host Controller
+ Interface (HCI) protocol.
+
Commands
========
@@ -27,12 +32,22 @@ open
Open HCI channel.
:Usage: **> open <index> <chan=raw,user>**
-:Example open user channel:
- | In order to open a user channel the controller needs to be power off
- | first:
- | > power off
- | > hci.open 0 user
- | HCI index 0 user channel opened
+:index: HCI controller index number (e.g., 0, 1, 2)
+:chan: Channel type (raw or user)
+:Example Open user channel (controller needs to be powered off first):
+ | **> power off**
+ | **> hci.open 0 user**
+ | **HCI index 0 user channel opened**
+:Example Open user channel for HCI controller 0:
+ | **> hci.open 0 user**
+:Example Open user channel for HCI controller 1:
+ | **> hci.open 1 user**
+:Example Open user channel for HCI controller 2:
+ | **> hci.open 2 user**
+:Example Open raw channel for HCI controller 0:
+ | **> hci.open 0 raw**
+:Example Open raw channel for HCI controller 1:
+ | **> hci.open 1 raw**
cmd
---
@@ -40,10 +55,30 @@ cmd
Send HCI command.
:Usage: **> cmd <opcode> [parameters...]**
-:Example send HCI Reset command:
- | > hci.cmd 0x0c03
- | HCI Command complete:
- | 00
+:opcode: HCI command opcode in hexadecimal format (e.g., 0x0c03)
+:parameters: Optional command parameters as hexadecimal bytes
+:Example Send HCI Reset command:
+ | **> hci.cmd 0x0c03**
+ | **HCI Command complete:**
+ | **00**
+:Example Send HCI Reset command (no parameters):
+ | **> hci.cmd 0x0c03**
+:Example Send HCI Read Local Version Information:
+ | **> hci.cmd 0x1003**
+:Example Send HCI Read BD Address:
+ | **> hci.cmd 0x1009**
+:Example Send HCI Set Event Filter with parameter 0x01:
+ | **> hci.cmd 0x0c01 0x01**
+:Example Send LE Set Advertising Parameters with 2 parameters:
+ | **> hci.cmd 0x200f 0x00 0x08**
+:Example Send LE Set Advertising Data with length and data bytes:
+ | **> hci.cmd 0x2008 0x20 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08**
+:Example Send HCI Set Event Mask command:
+ | **> hci.cmd 0x0c05 0x02**
+:Example Send HCI Write Scan Enable:
+ | **> hci.cmd 0x0c2a 0x01**
+:Example Send HCI Write Class of Device:
+ | **> hci.cmd 0x0c23 0x00 0x08**
send
----
@@ -51,8 +86,29 @@ send
Send HCI data packet.
:Usage: **> send <type=acl,sco,iso> <handle> [data...]**
-:Example send ACL data packet to connection handle 0x0000:
- | > hci.send acl 0x0000
+:type: Packet type (acl, sco, or iso)
+:handle: Connection handle in hexadecimal format (e.g., 0x0000)
+:data: Optional data bytes in hexadecimal format
+:Example Send ACL data packet to connection handle 0x0000:
+ | **> hci.send acl 0x0000**
+:Example Send empty ACL packet to handle 0x0000:
+ | **> hci.send acl 0x0000**
+:Example Send ACL packet with "Hello" data to handle 0x0001:
+ | **> hci.send acl 0x0001 0x48 0x65 0x6c 0x6c 0x6f**
+:Example Send ACL packet with custom data to handle 0x0010:
+ | **> hci.send acl 0x0010 0x01 0x02 0x03 0x04**
+:Example Send empty SCO packet to handle 0x0000:
+ | **> hci.send sco 0x0000**
+:Example Send SCO packet with audio data:
+ | **> hci.send sco 0x0001 0xaa 0xbb 0xcc**
+:Example Send SCO packet with sine wave pattern:
+ | **> hci.send sco 0x0002 0x80 0x00 0x80 0x00**
+:Example Send empty ISO packet to handle 0x0000:
+ | **> hci.send iso 0x0000**
+:Example Send ISO packet with sample data:
+ | **> hci.send iso 0x0001 0x12 0x34 0x56 0x78**
+:Example Send ISO packet for LE Audio stream:
+ | **> hci.send iso 0x0020 0xa0 0xa1 0xa2 0xa3**
register
--------
@@ -60,6 +116,21 @@ register
Register HCI event handler.
:Usage: **> register <event>**
+:event: HCI event code in hexadecimal format (e.g., 0x0e)
+:Example Register handler for Command Complete event:
+ | **> register 0x0e**
+:Example Register handler for Command Status event:
+ | **> register 0x0f**
+:Example Register handler for Connection Complete event:
+ | **> register 0x03**
+:Example Register handler for Disconnection Complete event:
+ | **> register 0x05**
+:Example Register handler for LE Meta events:
+ | **> register 0x3e**
+:Example Register handler for Inquiry Complete event:
+ | **> register 0x02**
+:Example Register handler for Role Change event:
+ | **> register 0x22**
unregister
----------
@@ -67,13 +138,28 @@ unregister
Unregister HCI event handler.
:Usage: **> unregister <event>**
+:event: HCI event code in hexadecimal format (e.g., 0x0e)
+:Example Unregister Command Complete event handler:
+ | **> unregister 0x0e**
+:Example Unregister Command Status event handler:
+ | **> unregister 0x0f**
+:Example Unregister Connection Complete event handler:
+ | **> unregister 0x03**
+:Example Unregister Disconnection Complete event handler:
+ | **> unregister 0x05**
+:Example Unregister LE Meta event handler:
+ | **> unregister 0x3e**
close
-----
Close HCI channel.
-:Usage: **> close <index>**
+Closes the currently open HCI channel.
+
+:Usage: **> close**
+:Example Close the current HCI channel:
+ | **> close**
RESOURCES
=========
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 10/35] doc/bluetoothctl-le: Add :Uses: fields and document arguments
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (8 preceding siblings ...)
2026-01-30 19:38 ` [PATCH BlueZ v2 09/35] doc/bluetoothctl-hci: " Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 11/35] doc/bluetoothctl-monitor: " Luiz Augusto von Dentz
` (25 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
doc/bluetoothctl-le.rst | 26 ++++++++++++++++++++++----
1 file changed, 22 insertions(+), 4 deletions(-)
diff --git a/doc/bluetoothctl-le.rst b/doc/bluetoothctl-le.rst
index 808d5786ee80..a6e1074ffa87 100644
--- a/doc/bluetoothctl-le.rst
+++ b/doc/bluetoothctl-le.rst
@@ -18,6 +18,9 @@ SYNOPSIS
**bluetoothctl** [--options] [le.commands]
+This submenu manages LE (Low Energy) bearer connections using the
+**org.bluez.Device(5)** interface.
+
LE Commands
===========
@@ -27,6 +30,8 @@ list
List available le devices.
:Usage: **> list**
+:Example Display all LE (Low Energy) devices that have been discovered:
+ | **> list**
show
----
@@ -34,6 +39,12 @@ show
Show le bearer information on a device.
:Usage: **> show [dev]**
+:Uses: **org.bluez.Device(5)** properties
+:[dev]: Bluetooth device address (optional, shows all LE bearers if omitted)
+:Example Show all LE bearer information:
+ | **> show**
+:Example Show LE bearer info for device with specified address:
+ | **> show 00:11:22:33:44:55**
connect
-------
@@ -46,8 +57,11 @@ An active scan report is required before the connection can be
established. If no advertising report is received before the timeout,
a le-connection-abort-by-local error will be issued.
-:Usage: > connect <dev>
-:Example: > connect 1C:48:F9:9D:81:5C
+:Usage: **> connect <dev>**
+:Uses: **org.bluez.Device(5)** method **Connect**
+:<dev>: Bluetooth device address to connect to
+:Example Connect to another LE device:
+ | **> connect 00:11:22:33:44:55**
disconnect
----------
@@ -57,8 +71,12 @@ Disconnect device over le.
By default this command disconnects all profiles/services associated with the le
connection, and then terminates the le link.
-:Usage: > disconnect <dev>
-:Example: > disconnect 1C:48:F9:9D:81:5C
+:Usage: **> disconnect <dev>**
+:Uses: **org.bluez.Device(5)** method **Disconnect**
+:<dev>: Bluetooth device address to disconnect from
+:Example Disconnect from another LE device:
+ | **> disconnect 00:11:22:33:44:55**
+
RESOURCES
=========
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 11/35] doc/bluetoothctl-monitor: Add :Uses: fields and document arguments
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (9 preceding siblings ...)
2026-01-30 19:38 ` [PATCH BlueZ v2 10/35] doc/bluetoothctl-le: " Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 12/35] doc/bluetoothctl-player: " Luiz Augusto von Dentz
` (24 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
doc/bluetoothctl-monitor.rst | 79 +++++++++++++++++++++++++++++++++++-
1 file changed, 77 insertions(+), 2 deletions(-)
diff --git a/doc/bluetoothctl-monitor.rst b/doc/bluetoothctl-monitor.rst
index 1e2bfeecc931..25c73655e2e2 100644
--- a/doc/bluetoothctl-monitor.rst
+++ b/doc/bluetoothctl-monitor.rst
@@ -18,6 +18,10 @@ SYNOPSIS
**bluetoothctl** [--options] [monitor.commands]
+This submenu configures advertisement monitors using the
+**org.bluez.AdvertisementMonitor(5)** and
+**org.bluez.AdvertisementMonitorManager(5)** interfaces.
+
Monitor Commands
================
@@ -27,6 +31,16 @@ set-rssi-threshold
Set RSSI threshold parameter
:Usage: **> set-rssi-threshold <low_threshold> <high_threshold>**
+:<low_threshold>: Lower RSSI threshold value in dBm for monitoring
+:<high_threshold>: Higher RSSI threshold value in dBm for monitoring
+:Example Set low threshold to -80 dBm and high threshold to -40 dBm:
+ | **> set-rssi-threshold -80 -40**
+:Example Set low threshold to -70 dBm and high threshold to -30 dBm:
+ | **> set-rssi-threshold -70 -30**
+:Example Set very sensitive low threshold and moderate high threshold:
+ | **> set-rssi-threshold -90 -50**
+:Example Set less sensitive thresholds for close range monitoring:
+ | **> set-rssi-threshold -60 -20**
set-rssi-timeout
----------------
@@ -34,20 +48,56 @@ set-rssi-timeout
Set RSSI timeout parameter
:Usage: **> set-rssi-timeout <low_timeout> <high_timeout>**
+:<low_timeout>: Timeout value in seconds for low RSSI threshold
+:<high_timeout>: Timeout value in seconds for high RSSI threshold
+:Example Set low timeout to 5 seconds, high timeout to 10 seconds:
+ | **> set-rssi-timeout 5 10**
+:Example Set quick timeout response for both thresholds:
+ | **> set-rssi-timeout 1 5**
+:Example Set longer timeout periods for stable monitoring:
+ | **> set-rssi-timeout 10 30**
+:Example Set asymmetric timeout values:
+ | **> set-rssi-timeout 3 15**
set-rssi-sampling-period
-------------------------
Set RSSI sampling period parameter
-:Usage: **> set-rssi-timeout <low_timeout> <high_timeout>**
+:Usage: **> set-rssi-sampling-period <sampling_period>**
+:<sampling_period>: Sampling period in 100ms units (0-255, where 0 means report all, 255 means report only first)
+:Example Set sampling period to 100ms (1 unit):
+ | **> set-rssi-sampling-period 1**
+:Example Set sampling period to 500ms (5 units):
+ | **> set-rssi-sampling-period 5**
+:Example Set sampling period to 1 second (10 units):
+ | **> set-rssi-sampling-period 10**
+:Example Report all advertisements (no sampling):
+ | **> set-rssi-sampling-period 0**
+:Example Report only first advertisement:
+ | **> set-rssi-sampling-period 255**
add-or-pattern
--------------
Register 'or pattern' type monitor with the specified RSSI parameters
-:Usage: **> add-or-pattern [patterns=pattern1 pattern2 ...]**
+Each pattern requires 3 arguments: <start_position> <ad_data_type> <content_of_pattern>
+Multiple patterns can be specified to create an OR condition.
+
+:Usage: **> add-or-pattern <start_pos> <ad_type> <content> [start_pos ad_type content ...]**
+:Uses: **org.bluez.AdvertisementMonitorManager(5)** method **RegisterMonitor**
+:<start_pos>: Byte position in advertisement data where pattern matching starts (0-based)
+:<ad_type>: Advertisement data type (e.g., 9 for Complete Local Name, 1 for Flags)
+:<content>: Hexadecimal pattern content to match
+:Example Monitor for "Samsung" in Complete Local Name (type 9):
+ | **> add-or-pattern 0 9 53616d73756e67**
+:Example Monitor for devices with Flags type (type 1) containing 0x06:
+ | **> add-or-pattern 0 1 06**
+:Example Monitor for two different patterns (OR condition):
+ | **> add-or-pattern 0 9 53616d73756e67 0 9 4170706c65**
+:Example Monitor for specific manufacturer data (type 255):
+ | **> add-or-pattern 0 255 4c000215**
get-pattern
-----------
@@ -55,6 +105,15 @@ get-pattern
Get advertisement monitor
:Usage: **> get-pattern <monitor-id/all>**
+:<monitor-id/all>: Monitor ID number to retrieve details for, or "all" for all active monitors
+:Example Get details of monitor ID 0:
+ | **> get-pattern 0**
+:Example Get details of monitor ID 1:
+ | **> get-pattern 1**
+:Example Get details of monitor ID 5:
+ | **> get-pattern 5**
+:Example Get details of all active monitors:
+ | **> get-pattern all**
remove-pattern
--------------
@@ -62,6 +121,16 @@ remove-pattern
Remove advertisement monitor
:Usage: **> remove-pattern <monitor-id/all>**
+:Uses: **org.bluez.AdvertisementMonitorManager(5)** method **UnregisterMonitor**
+:<monitor-id/all>: Monitor ID number to remove, or "all" to remove all active monitors
+:Example Remove monitor with ID 0:
+ | **> remove-pattern 0**
+:Example Remove monitor with ID 1:
+ | **> remove-pattern 1**
+:Example Remove monitor with ID 3:
+ | **> remove-pattern 3**
+:Example Remove all active advertisement monitors:
+ | **> remove-pattern all**
get-supported-info
------------------
@@ -69,6 +138,9 @@ get-supported-info
Get advertisement manager supported features and supported monitor types
:Usage: **> get-supported-info**
+:Uses: **org.bluez.AdvertisementMonitorManager(5)** properties
+:Example Display supported monitor features and types:
+ | **> get-supported-info**
print-usage
-----------
@@ -76,6 +148,9 @@ print-usage
Print the command usage
:Usage: **> print-usage <add-or-pattern>**
+:<add-or-pattern>: Command name to display detailed usage information for
+:Example Show detailed usage for add-or-pattern command:
+ | **> print-usage add-or-pattern**
RESOURCES
=========
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 12/35] doc/bluetoothctl-player: Add :Uses: fields and document arguments
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (10 preceding siblings ...)
2026-01-30 19:38 ` [PATCH BlueZ v2 11/35] doc/bluetoothctl-monitor: " Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 13/35] doc/bluetoothctl-scan: " Luiz Augusto von Dentz
` (23 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
doc/bluetoothctl-player.rst | 118 ++++++++++++++++++++++++++++++++++++
1 file changed, 118 insertions(+)
diff --git a/doc/bluetoothctl-player.rst b/doc/bluetoothctl-player.rst
index 1c5d436b31db..ccdd66663c67 100644
--- a/doc/bluetoothctl-player.rst
+++ b/doc/bluetoothctl-player.rst
@@ -18,6 +18,9 @@ SYNOPSIS
**bluetoothctl** [--options] [player.commands]
+This submenu controls media playback using the **org.bluez.MediaPlayer(5)**
+interface.
+
Media Player Commands
=====================
@@ -27,6 +30,8 @@ list
List available players.
:Usage: **> list**
+:Example Display all available media players (local and remote):
+ | **> list**
show
----
@@ -34,6 +39,12 @@ show
Show player information.
:Usage: **> show [player]**
+:Uses: **org.bluez.MediaPlayer(5)** properties
+:[player]: Media player path or identifier (optional, shows currently selected player if omitted)
+:Example Show information for currently selected player:
+ | **> show**
+:Example Show remote player information:
+ | **> show /org/bluez/hci0/dev_00_11_22_33_44_55/player0**
select
------
@@ -41,6 +52,9 @@ select
Select default player.
:Usage: **> select <player>**
+:<player>: Media player path or identifier to select as default
+:Example Select remote Bluetooth media player:
+ | **> select /org/bluez/hci0/dev_00_11_22_33_44_55/player0**
play
----
@@ -48,6 +62,16 @@ play
Start playback.
:Usage: **> play [item]**
+:Uses: **org.bluez.MediaPlayer(5)** method **Play**
+:[item]: Media item path to play (optional, starts playback of current item if omitted)
+:Example Start playback on current player:
+ | **> play**
+:Example Play specific item from media browser:
+ | **> play /org/bluez/item/1**
+:Example Play named track item:
+ | **> play /org/bluez/item/track_001**
+:Example Play track from specific album folder:
+ | **> play /org/bluez/item/album_rock/track_05**
pause
-----
@@ -55,6 +79,9 @@ pause
Pause playback.
:Usage: **> pause**
+:Uses: **org.bluez.MediaPlayer(5)** method **Pause**
+:Example Pause current playback:
+ | **> pause**
stop
----
@@ -62,6 +89,9 @@ stop
Stop playback.
:Usage: **> stop**
+:Uses: **org.bluez.MediaPlayer(5)** method **Stop**
+:Example Stop current playback:
+ | **> stop**
next
----
@@ -69,6 +99,9 @@ next
Jump to next item.
:Usage: **> next**
+:Uses: **org.bluez.MediaPlayer(5)** method **Next**
+:Example Skip to next track:
+ | **> next**
previous
--------
@@ -76,6 +109,9 @@ previous
Jump to previous item.
:Usage: **> previous**
+:Uses: **org.bluez.MediaPlayer(5)** method **Previous**
+:Example Go back to previous track:
+ | **> previous**
fast-forward
------------
@@ -83,6 +119,9 @@ fast-forward
Fast forward playback.
:Usage: **> fast-forward**
+:Uses: **org.bluez.MediaPlayer(5)** method **FastForward**
+:Example Enable fast forward mode:
+ | **> fast-forward**
rewind
------
@@ -90,6 +129,9 @@ rewind
Rewind playback.
:Usage: **> rewind**
+:Uses: **org.bluez.MediaPlayer(5)** method **Rewind**
+:Example Enable rewind mode:
+ | **> rewind**
equalizer
---------
@@ -97,6 +139,12 @@ equalizer
Enable/Disable equalizer.
:Usage: **> equalizer <on/off>**
+:Uses: **org.bluez.MediaPlayer(5)** property **Equalizer**
+:<on/off>: Enable (on) or disable (off) the equalizer
+:Example Enable equalizer:
+ | **> equalizer on**
+:Example Disable equalizer:
+ | **> equalizer off**
repeat
------
@@ -104,6 +152,16 @@ repeat
Set repeat mode.
:Usage: **> repeat <singletrack/alltrack/group/off>**
+:Uses: **org.bluez.MediaPlayer(5)** property **Repeat**
+:<singletrack/alltrack/group/off>: Set repeat mode - singletrack (current track), alltrack (all tracks), group (current group/album), or off (no repeat)
+:Example Disable repeat mode:
+ | **> repeat off**
+:Example Repeat current track:
+ | **> repeat singletrack**
+:Example Repeat entire playlist/queue:
+ | **> repeat alltrack**
+:Example Repeat current group/album:
+ | **> repeat group**
shuffle
-------
@@ -111,6 +169,14 @@ shuffle
Set shuffle mode.
:Usage: **> shuffle <alltracks/group/off>**
+:Uses: **org.bluez.MediaPlayer(5)** property **Shuffle**
+:<alltracks/group/off>: Set shuffle mode - alltracks (shuffle all tracks), group (shuffle within current group), or off (no shuffle)
+:Example Disable shuffle mode:
+ | **> shuffle off**
+:Example Shuffle all tracks in playlist:
+ | **> shuffle alltracks**
+:Example Shuffle tracks within current group:
+ | **> shuffle group**
scan
----
@@ -118,6 +184,14 @@ scan
Set scan mode.
:Usage: **> scan <alltracks/group/off>**
+:Uses: **org.bluez.MediaPlayer(5)** property **Scan**
+:<alltracks/group/off>: Set scan mode - alltracks (scan through all tracks), group (scan within current group), or off (no scan)
+:Example Disable scan mode:
+ | **> scan off**
+:Example Scan through all tracks:
+ | **> scan alltracks**
+:Example Scan through current group only:
+ | **> scan group**
change-folder
-------------
@@ -125,6 +199,15 @@ change-folder
Change current folder.
:Usage: **> change-folder <item>**
+:<item>: Folder path to navigate to, or ".." to go up one directory level
+:Example Navigate to Albums folder:
+ | **> change-folder /org/bluez/item/Albums**
+:Example Navigate to Artists folder:
+ | **> change-folder /org/bluez/item/Artists**
+:Example Navigate to Playlists folder:
+ | **> change-folder /org/bluez/item/Playlists**
+:Example Go up one directory level:
+ | **> change-folder ..**
list-items
----------
@@ -132,6 +215,18 @@ list-items
List items of current folder.
:Usage: **> list-items [start] [end]**
+:[start]: Starting index for item list (optional, defaults to 0)
+:[end]: Ending index for item list (optional, lists all items from start if omitted)
+:Example List all items in current folder:
+ | **> list-items**
+:Example List first 10 items (0-10):
+ | **> list-items 0 10**
+:Example List items 5 through 15:
+ | **> list-items 5 15**
+:Example List items 10 through 20:
+ | **> list-items 10 20**
+:Example List first 50 items:
+ | **> list-items 0 50**
search
------
@@ -139,6 +234,15 @@ search
Search items containing string.
:Usage: **> search <string>**
+:<string>: Search term to find matching items (songs, albums, artists, etc.)
+:Example Search for Beatles songs/albums:
+ | **> search "The Beatles"**
+:Example Search for items containing "rock":
+ | **> search "rock"**
+:Example Search for items from 2023:
+ | **> search "2023"**
+:Example Search for playlists:
+ | **> search "playlist"**
queue
-----
@@ -146,6 +250,13 @@ queue
Add item to playlist queue.
:Usage: **> queue <item>**
+:<item>: Media item path to add to the playback queue
+:Example Add specific track to queue:
+ | **> queue /org/bluez/item/track_001**
+:Example Add entire album to queue:
+ | **> queue /org/bluez/item/album_rock**
+:Example Add playlist to queue:
+ | **> queue /org/bluez/item/playlist_favorites**
show-item
---------
@@ -153,6 +264,13 @@ show-item
Show item information.
:Usage: **> show-item <item>**
+:<item>: Media item path to display detailed information for
+:Example Show details of specific track:
+ | **> show-item /org/bluez/item/track_001**
+:Example Show details of album:
+ | **> show-item /org/bluez/item/album_rock**
+:Example Show details of artist:
+ | **> show-item /org/bluez/item/artist_beatles**
RESOURCES
=========
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 13/35] doc/bluetoothctl-scan: Add :Uses: fields and document arguments
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (11 preceding siblings ...)
2026-01-30 19:38 ` [PATCH BlueZ v2 12/35] doc/bluetoothctl-player: " Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 14/35] doc/bluetoothctl-telephony: " Luiz Augusto von Dentz
` (22 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
doc/bluetoothctl-scan.rst | 126 ++++++++++++++++++++++++++++++++++++--
1 file changed, 122 insertions(+), 4 deletions(-)
diff --git a/doc/bluetoothctl-scan.rst b/doc/bluetoothctl-scan.rst
index cee255131622..16b4d08daddf 100644
--- a/doc/bluetoothctl-scan.rst
+++ b/doc/bluetoothctl-scan.rst
@@ -18,6 +18,9 @@ SYNOPSIS
**bluetoothctl** [--options] [scan.commands]
+This submenu configures discovery filters using **org.bluez.Adapter(5)**
+method **SetDiscoveryFilter**.
+
Scan Commands
=============
@@ -27,6 +30,24 @@ uuids
Set/Get UUIDs filter.
:Usage: **> uuids [all/uuid1 uuid2 ...]**
+:Uses: **org.bluez.Adapter(5)** method **SetDiscoveryFilter** property **UUIDs**
+:[all/uuid1 uuid2 ...]: List of UUIDs to filter for during scanning (default: none, use "all" to scan for any UUID)
+:Example Show current UUID filter settings:
+ | **> uuids**
+:Example Filter for Generic Access service only:
+ | **> uuids 0x1800**
+:Example Filter for Battery service only:
+ | **> uuids 0x180F**
+:Example Filter for Generic Access and Battery services:
+ | **> uuids 0x1800 0x180F**
+:Example Filter for Device Info, Battery, and Environmental Sensing:
+ | **> uuids 0x180A 0x180F 0x181A**
+:Example Filter for Generic Access using full UUID:
+ | **> uuids 00001800-0000-1000-8000-00805f9b34fb**
+:Example Filter using mixed short and long forms:
+ | **> uuids 00001800-0000-1000-8000-00805f9b34fb 0000180f-0000-1000-8000-00805f9b34fb**
+:Example Remove UUID filtering (scan for all devices):
+ | **> uuids all**
rssi
----
@@ -41,7 +62,20 @@ If one or more discovery filters have been set, the RSSI delta-threshold imposed
by starting discovery by default will not be applied.
:Usage: **> rssi [rssi]**
-:Example: **> rssi -60**
+:Uses: **org.bluez.Adapter(5)** method **SetDiscoveryFilter** property **RSSI**
+:[rssi]: Minimum RSSI threshold value in dBm (optional, shows current if omitted)
+:Example Show current RSSI filter setting:
+ | **> rssi**
+:Example Only report devices with RSSI ≥ -60 dBm (close range):
+ | **> rssi -60**
+:Example Report devices with RSSI ≥ -80 dBm (medium range):
+ | **> rssi -80**
+:Example Report devices with RSSI ≥ -90 dBm (extended range):
+ | **> rssi -90**
+:Example Report only very close devices (RSSI ≥ -40 dBm):
+ | **> rssi -40**
+:Example Report devices with very weak signals (maximum sensitivity):
+ | **> rssi -100**
pathloss
--------
@@ -55,7 +89,20 @@ If one or more discovery filters have been set, the RSSI delta-threshold
imposed by starting discovery by default will not be applied.
:Usage: **> pathloss [pathloss]**
-:Example: **> pathloss 4**
+:Uses: **org.bluez.Adapter(5)** method **SetDiscoveryFilter** property **Pathloss**
+:[pathloss]: Maximum pathloss threshold value in dB (optional, shows current if omitted)
+:Example Show current pathloss filter setting:
+ | **> pathloss**
+:Example Report devices with maximum 4 dB pathloss (very close):
+ | **> pathloss 4**
+:Example Report devices with maximum 10 dB pathloss (close range):
+ | **> pathloss 10**
+:Example Report devices with maximum 20 dB pathloss (medium range):
+ | **> pathloss 20**
+:Example Report devices with maximum 30 dB pathloss (extended range):
+ | **> pathloss 30**
+:Example Report devices with maximum 50 dB pathloss (maximum range):
+ | **> pathloss 50**
transport
---------
@@ -79,6 +126,15 @@ If "auto" transport is requested, the scan will use LE, BREDR, or both,
depending on what's currently enabled on the controller.
:Usage: **> transport [auto/bredr/le]**
+:[auto/bredr/le]: Transport type for scanning (optional, shows current if omitted)
+:Example Show current transport filter setting:
+ | **> transport**
+:Example Use automatic transport selection (LE + BR/EDR):
+ | **> transport auto**
+:Example Scan only Low Energy devices:
+ | **> transport le**
+:Example Scan only BR/EDR (Classic Bluetooth) devices:
+ | **> transport bredr**
duplicate-data
--------------
@@ -91,6 +147,13 @@ When enabled, PropertiesChanged signals will be generated for ManufacturerData
and ServiceData every time they are discovered.
:Usage: **> duplicate-data [on/off]**
+:[on/off]: Enable or disable duplicate advertisement data reporting (optional, shows current if omitted)
+:Example Show current duplicate data filter setting:
+ | **> duplicate-data**
+:Example Enable reporting of duplicate advertisement data:
+ | **> duplicate-data on**
+:Example Disable duplicate data reporting (filter duplicates):
+ | **> duplicate-data off**
discoverable
------------
@@ -103,6 +166,13 @@ If the adapter is already discoverable, setting this filter won't have any
effect.
:Usage: **> discoverable [on/off]**
+:[on/off]: Make adapter discoverable during scanning (optional, shows current if omitted)
+:Example Show current discoverable filter setting:
+ | **> discoverable**
+:Example Make adapter discoverable during scanning:
+ | **> discoverable on**
+:Example Keep adapter non-discoverable during scanning:
+ | **> discoverable off**
pattern
-------
@@ -120,7 +190,21 @@ When set, it disregards device discoverable flags.
string "" pattern will match any device found.
:Usage: **> pattern [value]**
-
+:[value]: Pattern to match device address prefix or name (optional, shows current if omitted)
+:Example Show current pattern filter setting:
+ | **> pattern**
+:Example Discover devices with "Samsung" in the name:
+ | **> pattern Samsung**
+:Example Discover devices with "iPhone" in the name:
+ | **> pattern iPhone**
+:Example Discover devices with "Headphones" in the name:
+ | **> pattern Headphones**
+:Example Discover devices with addresses starting with 00:11:22:
+ | **> pattern 00:11:22**
+:Example Discover devices with addresses starting with AA:BB:CC:
+ | **> pattern AA:BB:CC**
+:Example Clear pattern filter (match any device):
+ | **> pattern ""**
auto-connect
------------
@@ -131,13 +215,47 @@ Connect to discovered devices automatically if pattern filter has been set and
it matches the device address or name and the device is connectable.
:Usage: **> auto-connect [on/off]**
+:[on/off]: Automatically connect to discovered devices matching pattern filter (optional, shows current if omitted)
+:Example Show current auto-connect filter setting:
+ | **> auto-connect**
+:Example Enable automatic connection to matching devices:
+ | **> auto-connect on**
+:Example Disable automatic connection (manual connection required):
+ | **> auto-connect off**
clear
-----
Clears discovery filter.
-:Usage: **> clear [uuids/rssi/pathloss/transport/duplicate-data/discoverable/pattern]**
+:Usage: **> clear [uuids/rssi/pathloss/transport/duplicate-data/discoverable/pattern/auto-connect]**
+:[uuids/rssi/pathloss/transport/duplicate-data/discoverable/pattern/auto-connect]: Specific filter(s) to clear (optional, clears all if omitted)
+:Example Clear all discovery filters:
+ | **> clear**
+:Example Clear only UUID filter:
+ | **> clear uuids**
+:Example Clear only RSSI filter:
+ | **> clear rssi**
+:Example Clear only pathloss filter:
+ | **> clear pathloss**
+:Example Clear only transport filter:
+ | **> clear transport**
+:Example Clear only duplicate data filter:
+ | **> clear duplicate-data**
+:Example Clear only discoverable filter:
+ | **> clear discoverable**
+:Example Clear only pattern filter:
+ | **> clear pattern**
+:Example Clear only auto-connect filter:
+ | **> clear auto-connect**
+:Example Clear UUID and RSSI filters:
+ | **> clear uuids rssi**
+:Example Clear transport and pattern filters:
+ | **> clear transport pattern**
+:Example Clear pattern and auto-connect filters:
+ | **> clear pattern auto-connect**
+:Example Clear RSSI, pathloss, and discoverable filters:
+ | **> clear rssi pathloss discoverable**
RESOURCES
=========
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 14/35] doc/bluetoothctl-telephony: Add :Uses: fields and document arguments
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (12 preceding siblings ...)
2026-01-30 19:38 ` [PATCH BlueZ v2 13/35] doc/bluetoothctl-scan: " Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 15/35] doc/bluetoothctl-transport: " Luiz Augusto von Dentz
` (21 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
doc/bluetoothctl-telephony.rst | 75 ++++++++++++++++++++++++++++++++--
1 file changed, 71 insertions(+), 4 deletions(-)
diff --git a/doc/bluetoothctl-telephony.rst b/doc/bluetoothctl-telephony.rst
index a6870e781a7a..84ea36f778ed 100644
--- a/doc/bluetoothctl-telephony.rst
+++ b/doc/bluetoothctl-telephony.rst
@@ -18,6 +18,9 @@ SYNOPSIS
**bluetoothctl** [--options] [telephony.commands]
+This submenu manages telephony features using the **org.bluez.Telephony(5)**
+and **org.bluez.Call(5)** interfaces.
+
Telephony Commands
==================
@@ -27,34 +30,72 @@ list
List available audio gateways.
:Usage: **> list**
+:Example Display all available HFP audio gateways:
+ | **> list**
show
----
Show audio gateway information.
-:Usage: **> show [audiogw]**
+:Usage: **> show [telephony]**
+:Uses: **org.bluez.Telephony(5)** properties
+:[telephony]: Audio gateway device path (optional, shows current if omitted)
+:Example Show information for currently selected audio gateway:
+ | **> show**
+:Example Show information for specific audio gateway device:
+ | **> show /org/bluez/hci0/dev_00_11_22_33_44_55**
+:Example Show information for another audio gateway:
+ | **> show /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF**
select
------
Select default audio gateway.
-:Usage: **> select <audiogw>**
+:Usage: **> select <telephony>**
+:<telephony>: Audio gateway device path to set as default
+:Example Select specific audio gateway as default:
+ | **> select /org/bluez/hci0/dev_00_11_22_33_44_55**
+:Example Select different audio gateway as default:
+ | **> select /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF**
dial
----
Dial number.
-:Usage: **> dial <number> [audiogw]**
+:Usage: **> dial <number> [telephony]**
+:Uses: **org.bluez.Telephony(5)** method **Dial**
+:<number>: Phone number to dial
+:[telephony]: Audio gateway device path (optional, uses current if omitted)
+:Example Dial number using currently selected audio gateway:
+ | **> dial 555-1234**
+:Example Dial international number using current audio gateway:
+ | **> dial +1-555-123-4567**
+:Example Dial emergency number using current audio gateway:
+ | **> dial 911**
+:Example Dial number using specific audio gateway:
+ | **> dial 555-1234 /org/bluez/hci0/dev_00_11_22_33_44_55**
+:Example Dial UK number using specific audio gateway:
+ | **> dial +44-20-7946-0958 /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF**
+:Example Dial with caller ID blocking:
+ | **> dial *67-555-1234**
+:Example Dial with caller ID hiding (GSM format):
+ | **> dial #31#555-1234**
hangup-all
----------
Hangup all calls.
-:Usage: **> hangup-all**
+:Usage: **> hangup-all [telephony]**
+:Uses: **org.bluez.Telephony(5)** method **HangupAll**
+:[telephony]: Audio gateway device path (optional, uses current if omitted)
+:Example Terminate all active and waiting calls on current gateway:
+ | **> hangup-all**
+:Example Terminate all calls on specific audio gateway:
+ | **> hangup-all /org/bluez/hci0/dev_00_11_22_33_44_55**
list-calls
----------
@@ -62,6 +103,8 @@ list-calls
List available calls.
:Usage: **> list-calls**
+:Example Display all active, waiting, and held calls:
+ | **> list-calls**
show-call
---------
@@ -69,6 +112,14 @@ show-call
Show call information.
:Usage: **> show-call <call>**
+:Uses: **org.bluez.Call(5)** properties
+:<call>: Call object path to display information for
+:Example Show information for specific call:
+ | **> show-call /org/bluez/hci0/dev_00_11_22_33_44_55/call1**
+:Example Show information for another call:
+ | **> show-call /org/bluez/hci0/dev_00_11_22_33_44_55/call2**
+:Example Show call information from different device:
+ | **> show-call /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/call1**
answer
------
@@ -76,6 +127,14 @@ answer
Answer call.
:Usage: **> answer <call>**
+:Uses: **org.bluez.Call(5)** method **Answer**
+:<call>: Call object path to answer
+:Example Answer incoming call:
+ | **> answer /org/bluez/hci0/dev_00_11_22_33_44_55/call1**
+:Example Answer waiting call:
+ | **> answer /org/bluez/hci0/dev_00_11_22_33_44_55/call2**
+:Example Answer call from different device:
+ | **> answer /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/call1**
hangup
------
@@ -83,6 +142,14 @@ hangup
Hangup call.
:Usage: **> hangup <call>**
+:Uses: **org.bluez.Call(5)** method **Hangup**
+:<call>: Call object path to terminate
+:Example Terminate specific active call:
+ | **> hangup /org/bluez/hci0/dev_00_11_22_33_44_55/call1**
+:Example Terminate waiting or held call:
+ | **> hangup /org/bluez/hci0/dev_00_11_22_33_44_55/call2**
+:Example Terminate call from different device:
+ | **> hangup /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/call1**
RESOURCES
=========
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 15/35] doc/bluetoothctl-transport: Add :Uses: fields and document arguments
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (13 preceding siblings ...)
2026-01-30 19:38 ` [PATCH BlueZ v2 14/35] doc/bluetoothctl-telephony: " Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 16/35] doc/org.bluez.Adapter: Add Used by reference and Examples Luiz Augusto von Dentz
` (20 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
doc/bluetoothctl-transport.rst | 78 +++++++++++++++++++++++++++++++++-
1 file changed, 77 insertions(+), 1 deletion(-)
diff --git a/doc/bluetoothctl-transport.rst b/doc/bluetoothctl-transport.rst
index 77d8457a5d6f..7e3809e5ac18 100644
--- a/doc/bluetoothctl-transport.rst
+++ b/doc/bluetoothctl-transport.rst
@@ -18,6 +18,9 @@ SYNOPSIS
**bluetoothctl** [--options] [transport.commands]
+This submenu manages media transports for audio streaming using the
+**org.bluez.MediaTransport(5)** interface.
+
Media Transport Commands
=========================
@@ -28,12 +31,23 @@ List available transports.
:Usage: **> list**
+:Example Display all available media transports (A2DP, LE Audio, etc.):
+ | **> list**
+
show
----
Show transport information.
:Usage: **> show [transport]**
+:Uses: **org.bluez.MediaTransport(5)** properties
+:[transport]: Specific transport object path (optional, shows current if omitted)
+:Example Show information for currently selected transport:
+ | **> show**
+:Example Show transport information:
+ | **> show /org/bluez/hci0/dev_00_11_22_33_44_55/fd0**
+:Example Show Broadcast Isochronous Stream transport:
+ | **> show /org/bluez/hci0/dev_11_22_33_44_55_66/bis1**
acquire
-------
@@ -41,6 +55,13 @@ acquire
Acquire transport.
:Usage: **> acquire <transport> [transport1...]**
+:Uses: **org.bluez.MediaTransport(5)** method **Acquire**
+:<transport>: Media transport object path to acquire for audio streaming
+:[transport1...]: Additional transport paths for multi-stream acquisition (optional)
+:Example Acquire transport:
+ | **> acquire /org/bluez/hci0/dev_00_11_22_33_44_55/fd0**
+:Example Acquire multiple transports:
+ | **> acquire /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 /org/bluez/hci0/dev_00_11_22_33_44_55/fd1**
Note:
@@ -54,6 +75,13 @@ Select transport. For transports created on a Broadcast Sink device only. This m
the transport to the "broadcasting" state, pending acquire.
:Usage: **> select <transport> [transport1...]**
+:Uses: **org.bluez.MediaTransport(5)** method **Select**
+:<transport>: Broadcast sink transport path to move to broadcasting state
+:[transport1...]: Additional transport paths for multi-stream selection (optional)
+:Example Select single Broadcast Isochronous Stream:
+ | **> select /org/bluez/hci0/dev_00_11_22_33_44_55/bis1**
+:Example Select stereo broadcast streams:
+ | **> select /org/bluez/hci0/dev_00_11_22_33_44_55/bis1 /org/bluez/hci0/dev_00_11_22_33_44_55/bis2**
Note:
@@ -77,6 +105,12 @@ was acquired by bluetoothctl it can be released straight away, without having to
unselected.
:Usage: **> unselect <transport> [transport1...]**
+:<transport>: Broadcast sink transport path to move to idle state
+:[transport1...]: Additional transport paths for multi-stream unselection (optional)
+:Example Unselect broadcast stream transport:
+ | **> unselect /org/bluez/hci0/dev_00_11_22_33_44_55/bis1**
+:Example Unselect multiple broadcast streams:
+ | **> unselect /org/bluez/hci0/dev_00_11_22_33_44_55/bis1 /org/bluez/hci0/dev_00_11_22_33_44_55/bis2**
Note:
If running the setup with an audio server that has LE Audio support (such as PipeWire), it will
@@ -88,6 +122,13 @@ release
Release transport.
:Usage: **> release <transport> [transport1...]**
+:Uses: **org.bluez.MediaTransport(5)** method **Release**
+:<transport>: Media transport object path to release from audio streaming
+:[transport1...]: Additional transport paths for multi-stream release (optional)
+:Example Release transport:
+ | **> release /org/bluez/hci0/dev_00_11_22_33_44_55/fd0**
+:Example Release multiple transports:
+ | **> release /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 /org/bluez/hci0/dev_00_11_22_33_44_55/fd1**
Note:
@@ -98,7 +139,14 @@ send
Send contents of a file.
-:Usage: **> send <transport> <filename>**
+:Usage: **> send <transport> <filename> [transport1...]**
+:<transport>: Media transport object path to send audio data through
+:<filename>: Path to audio file to transmit (supports WAV, MP3, PCM formats)
+:[transport1...]: Additional transport paths for multi-stream sending (optional)
+:Example Send encoded audio file via transport:
+ | **> send /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 /home/user/music.<format>**
+:Example Send to multiple transports simultaneously:
+ | **> send /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 /home/user/stereo-left.<format> /org/bluez/hci0/dev_00_11_22_33_44_55/fd1 /home/user/stereo-rigth.<format>**
receive
-------
@@ -106,6 +154,14 @@ receive
Get/Set file to receive.
:Usage: **> receive <transport> [filename]**
+:<transport>: Media transport object path to receive audio data from
+:[filename]: Path to save received audio data (optional, shows current if omitted)
+:Example Show current receive file for transport:
+ | **> receive /org/bluez/hci0/dev_00_11_22_33_44_55/fd0**
+:Example Set file to receive audio data:
+ | **> receive /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 /tmp/recorded_audio.wav**
+:Example Set file for broadcast audio capture (note quotes):
+ | **> receive /org/bluez/hci0/dev_11_22_33_44_55_66/bis1 "/home/user/My Recordings/broadcast.wav"**
volume
------
@@ -113,6 +169,26 @@ volume
Get/Set transport volume.
:Usage: **> volume <transport> [value]**
+:Uses: **org.bluez.MediaTransport(5)** property **Volume**
+:<transport>: Media transport object path to control volume for
+:[value]: Volume level (0-127, optional, shows current if omitted)
+:Example Show current volume level:
+ | **> volume /org/bluez/hci0/dev_00_11_22_33_44_55/fd0**
+:Example Set volume to 100:
+ | **> volume /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 100**
+
+metadata
+--------
+
+Get/Set Transport Metadata.
+
+:Usage: **> metadata <transport> [value...]**
+:<transport>: Media transport object path
+:[value...]: Metadata value as hex string (optional, shows current if omitted)
+:Example Show current metadata for transport:
+ | **> metadata /org/bluez/hci0/dev_00_11_22_33_44_55/fd0**
+:Example Set metadata value:
+ | **> metadata /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 0x03020100**
RESOURCES
=========
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 16/35] doc/org.bluez.Adapter: Add Used by reference and Examples
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (14 preceding siblings ...)
2026-01-30 19:38 ` [PATCH BlueZ v2 15/35] doc/bluetoothctl-transport: " Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:38 ` [PATCH BlueZ v2 17/35] doc/org.bluez.AdminPolicySet: " Luiz Augusto von Dentz
` (19 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl and Examples sections
showing corresponding bluetoothctl commands for D-Bus methods.
---
doc/org.bluez.Adapter.rst | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/doc/org.bluez.Adapter.rst b/doc/org.bluez.Adapter.rst
index 41d6517b512e..bef7a387512c 100644
--- a/doc/org.bluez.Adapter.rst
+++ b/doc/org.bluez.Adapter.rst
@@ -17,6 +17,7 @@ Interface
:Service: org.bluez
:Interface: org.bluez.Adapter1
:Object path: [variable prefix]/{hci0,hci1,...}
+:Used by: **bluetoothctl(1)**
Methods
-------
@@ -41,6 +42,10 @@ Possible errors:
:org.bluez.Error.Failed:
:org.bluez.Error.InProgress:
+Examples:
+
+:bluetoothctl: > scan <on/off/bredr/le>
+
void StopDiscovery()
````````````````````
@@ -67,6 +72,10 @@ Possible errors:
:org.bluez.Error.InvalidArguments:
:org.bluez.Error.Failed:
+Examples:
+
+:bluetoothctl: > remove <dev>
+
void SetDiscoveryFilter(dict filter)
````````````````````````````````````
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 17/35] doc/org.bluez.AdminPolicySet: Add Used by reference and Examples
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (15 preceding siblings ...)
2026-01-30 19:38 ` [PATCH BlueZ v2 16/35] doc/org.bluez.Adapter: Add Used by reference and Examples Luiz Augusto von Dentz
@ 2026-01-30 19:38 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 18/35] doc/org.bluez.AdminPolicyStatus: Add Used by reference Luiz Augusto von Dentz
` (18 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:38 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-admin and Examples sections
showing corresponding bluetoothctl commands for D-Bus methods.
---
doc/org.bluez.AdminPolicySet.rst | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/doc/org.bluez.AdminPolicySet.rst b/doc/org.bluez.AdminPolicySet.rst
index ff4cdd2bae8a..db132b7de4cd 100644
--- a/doc/org.bluez.AdminPolicySet.rst
+++ b/doc/org.bluez.AdminPolicySet.rst
@@ -28,6 +28,7 @@ Interface
:Service: org.bluez
:Interface: org.bluez.AdminPolicySet1 [experimental]
:Object path: [variable prefix]/{hci0,hci1,...}
+:Used by: **bluetoothctl-admin(1)**
Methods
-------
@@ -50,3 +51,7 @@ Possible errors:
:org.bluez.Error.InvalidArguments:
:org.bluez.Error.Failed:
+
+Examples:
+
+:bluetoothctl: > admin.allow [clear/uuid1 uuid2 ...]
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 18/35] doc/org.bluez.AdminPolicyStatus: Add Used by reference
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (16 preceding siblings ...)
2026-01-30 19:38 ` [PATCH BlueZ v2 17/35] doc/org.bluez.AdminPolicySet: " Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 19/35] doc/org.bluez.AdvertisementMonitor: " Luiz Augusto von Dentz
` (17 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-admin for this interface
which exposes properties read by admin policy commands.
---
doc/org.bluez.AdminPolicyStatus.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/doc/org.bluez.AdminPolicyStatus.rst b/doc/org.bluez.AdminPolicyStatus.rst
index 18008a2b07af..702e020aa601 100644
--- a/doc/org.bluez.AdminPolicyStatus.rst
+++ b/doc/org.bluez.AdminPolicyStatus.rst
@@ -26,6 +26,7 @@ Adapter
:Service: org.bluez
:Interface: org.bluez.AdminPolicyStatus1 [experimental]
:Object path: [variable prefix]/{hci0,hci1,...}
+:Used by: **bluetoothctl-admin(1)**
Device
------
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 19/35] doc/org.bluez.AdvertisementMonitor: Add Used by reference
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (17 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 18/35] doc/org.bluez.AdminPolicyStatus: Add Used by reference Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 20/35] doc/org.bluez.AdvertisementMonitorManager: " Luiz Augusto von Dentz
` (16 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-monitor for this callback
interface implemented by advertisement monitor clients.
---
doc/org.bluez.AdvertisementMonitor.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/doc/org.bluez.AdvertisementMonitor.rst b/doc/org.bluez.AdvertisementMonitor.rst
index e08bf41e7a58..ddcc7b0b432d 100644
--- a/doc/org.bluez.AdvertisementMonitor.rst
+++ b/doc/org.bluez.AdvertisementMonitor.rst
@@ -29,6 +29,7 @@ Interface
:Service: org.bluez
:Interface: org.bluez.AdvertisementMonitor1 [experimental]
:Object path: freely definable
+:Used by: **bluetoothctl-monitor(1)**
Methods
-------
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 20/35] doc/org.bluez.AdvertisementMonitorManager: Add Used by reference
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (18 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 19/35] doc/org.bluez.AdvertisementMonitor: " Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 21/35] doc/org.bluez.AgentManager: Add Used by reference and Examples Luiz Augusto von Dentz
` (15 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-monitor for this interface
used to register advertisement monitors.
---
doc/org.bluez.AdvertisementMonitorManager.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/doc/org.bluez.AdvertisementMonitorManager.rst b/doc/org.bluez.AdvertisementMonitorManager.rst
index 3860429b0cee..fb5addf2a007 100644
--- a/doc/org.bluez.AdvertisementMonitorManager.rst
+++ b/doc/org.bluez.AdvertisementMonitorManager.rst
@@ -17,6 +17,7 @@ Interface
:Service: org.bluez
:Interface: org.bluez.AdvertisementMonitorManager1 [experimental]
:Object path: /org/bluez/{hci0,hci1,...}
+:Used by: **bluetoothctl-monitor(1)**
Methods
-------
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 21/35] doc/org.bluez.AgentManager: Add Used by reference and Examples
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (19 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 20/35] doc/org.bluez.AdvertisementMonitorManager: " Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 22/35] doc/org.bluez.Call: " Luiz Augusto von Dentz
` (14 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl and Examples sections
showing corresponding bluetoothctl commands for agent methods.
---
doc/org.bluez.AgentManager.rst | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/doc/org.bluez.AgentManager.rst b/doc/org.bluez.AgentManager.rst
index 77373c0153fd..23e4229adaf1 100644
--- a/doc/org.bluez.AgentManager.rst
+++ b/doc/org.bluez.AgentManager.rst
@@ -17,6 +17,7 @@ Interface
:Service: org.bluez
:Interface: org.bluez.AgentManager1
:Object path: /org/bluez
+:Used by: **bluetoothctl(1)**
Methods
-------
@@ -57,6 +58,10 @@ Possible errors:
:org.bluez.Error.InvalidArguments:
:org.bluez.Error.AlreadyExists:
+Examples:
+
+:bluetoothctl: > agent <on/off/auto/capability>
+
void UnregisterAgent(object agent)
``````````````````````````````````
@@ -79,3 +84,7 @@ Special permission might be required to become the default agent.
Possible errors:
:org.bluez.Error.DoesNotExist:
+
+Examples:
+
+:bluetoothctl: > default-agent
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 22/35] doc/org.bluez.Call: Add Used by reference and Examples
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (20 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 21/35] doc/org.bluez.AgentManager: Add Used by reference and Examples Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 23/35] doc/org.bluez.Device: " Luiz Augusto von Dentz
` (13 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-telephony and Examples
sections showing corresponding bluetoothctl commands for call methods.
---
doc/org.bluez.Call.rst | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/doc/org.bluez.Call.rst b/doc/org.bluez.Call.rst
index 8825e0f17231..e4e043f49f96 100644
--- a/doc/org.bluez.Call.rst
+++ b/doc/org.bluez.Call.rst
@@ -17,6 +17,7 @@ Interface
:Service: org.bluez
:Interface: org.bluez.Call1 [experimental]
:Object path: [variable prefix]/{hci0,hci1,...}/dev_{BDADDR}/telephony#/call#
+:Used by: **bluetoothctl-telephony(1)**
Methods
-------
@@ -30,6 +31,10 @@ Possible Errors:
:org.bluez.Error.InvalidState
:org.bluez.Error.Failed
+Examples:
+
+:bluetoothctl: > telephony.answer <call>
+
void Hangup()
`````````````
@@ -62,6 +67,10 @@ Possible Errors:
:org.bluez.Error.InvalidState
:org.bluez.Error.Failed
+Examples:
+
+:bluetoothctl: > telephony.hangup <call>
+
Properties
----------
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 23/35] doc/org.bluez.Device: Add Used by reference and Examples
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (21 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 22/35] doc/org.bluez.Call: " Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 24/35] doc/org.bluez.GattCharacteristic: " Luiz Augusto von Dentz
` (12 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl and Examples sections
showing corresponding bluetoothctl commands for device methods.
---
doc/org.bluez.Device.rst | 13 +++++++++++++
1 file changed, 13 insertions(+)
diff --git a/doc/org.bluez.Device.rst b/doc/org.bluez.Device.rst
index 593ff06643f3..85247cbfbfac 100644
--- a/doc/org.bluez.Device.rst
+++ b/doc/org.bluez.Device.rst
@@ -17,6 +17,7 @@ Interface
:Service: org.bluez
:Interface: org.bluez.Device1
:Object path: [variable prefix]/{hci0,hci1,...}/dev_{BDADDR}
+:Used by: **bluetoothctl(1)**
Methods
-------
@@ -51,6 +52,10 @@ Possible errors:
:org.bluez.Error.AlreadyConnected:
:org.bluez.Error.BREDR.ProfileUnavailable:
+Examples:
+
+:bluetoothctl: > connect <dev> [uuid]
+
void Disconnect()
`````````````````
@@ -69,6 +74,10 @@ Possible errors:
:org.bluez.Error.NotConnected:
+Examples:
+
+:bluetoothctl: > disconnect [dev] [uuid]
+
void ConnectProfile(string uuid)
````````````````````````````````
@@ -125,6 +134,10 @@ Possible errors:
:org.bluez.Error.AuthenticationTimeout:
:org.bluez.Error.ConnectionAttemptFailed:
+Examples:
+
+:bluetoothctl: > pair [dev]
+
void CancelPairing()
````````````````````
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 24/35] doc/org.bluez.GattCharacteristic: Add Used by reference and Examples
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (22 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 23/35] doc/org.bluez.Device: " Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 25/35] doc/org.bluez.GattDescriptor: Add Used by reference Luiz Augusto von Dentz
` (11 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-gatt and Examples sections
showing corresponding bluetoothctl commands for GATT operations.
---
doc/org.bluez.GattCharacteristic.rst | 21 +++++++++++++++++++++
1 file changed, 21 insertions(+)
diff --git a/doc/org.bluez.GattCharacteristic.rst b/doc/org.bluez.GattCharacteristic.rst
index 3cbf361cc904..805f39593903 100644
--- a/doc/org.bluez.GattCharacteristic.rst
+++ b/doc/org.bluez.GattCharacteristic.rst
@@ -31,6 +31,7 @@ Client
:Service: org.bluez
:Interface: org.bluez.GattCharacteristic1
:Object path: [variable prefix]/{hci0,hci1,...}/dev_{BDADDR}/service#/char#
+:Used by: **bluetoothctl-gatt(1)**
Server
------
@@ -83,6 +84,10 @@ Possible Errors:
:org.bluez.Error.InvalidOffset:
:org.bluez.Error.NotSupported:
+Examples:
+
+:bluetoothctl: > gatt.read [offset]
+
void WriteValue(array{byte} value, dict options)
````````````````````````````````````````````````
@@ -144,6 +149,10 @@ Possible Errors:
:org.bluez.Error.NotSupported:
:org.bluez.Error.ImproperlyConfigured:
+Examples:
+
+:bluetoothctl: > gatt.write <data=xx xx ...> [offset] [type]
+
fd, uint16 AcquireWrite(dict options) [optional]
````````````````````````````````````````````````
@@ -187,6 +196,10 @@ Possible Errors:
:org.bluez.Error.Failed:
:org.bluez.Error.NotSupported:
+Examples:
+
+:bluetoothctl: > gatt.acquire-write
+
fd, uint16 AcquireNotify(dict options) [optional]
`````````````````````````````````````````````````
@@ -243,6 +256,10 @@ Possible Errors:
:org.bluez.Error.NotSupported:
:org.bluez.Error.NotPermitted:
+Examples:
+
+:bluetoothctl: > gatt.acquire-notify
+
void StartNotify()
``````````````````
@@ -257,6 +274,10 @@ Possible Errors:
:org.bluez.Error.NotConnected:
:org.bluez.Error.NotSupported:
+Examples:
+
+:bluetoothctl: > gatt.notify <on/off>
+
void StopNotify()
`````````````````
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 25/35] doc/org.bluez.GattDescriptor: Add Used by reference
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (23 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 24/35] doc/org.bluez.GattCharacteristic: " Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 26/35] doc/org.bluez.GattManager: Add Used by reference and Examples Luiz Augusto von Dentz
` (10 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-gatt for this interface
used by GATT descriptor operations.
---
doc/org.bluez.GattDescriptor.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/doc/org.bluez.GattDescriptor.rst b/doc/org.bluez.GattDescriptor.rst
index 76d274464f51..969976d1fc2b 100644
--- a/doc/org.bluez.GattDescriptor.rst
+++ b/doc/org.bluez.GattDescriptor.rst
@@ -31,6 +31,7 @@ Client
:Service: org.bluez
:Interface: org.bluez.GattDescriptor1
:Object path: [variable prefix]/{hci0,hci1,...}/dev_{BDADDR}/service#/char#/descriptor#
+:Used by: **bluetoothctl-gatt(1)**
Server
------
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 26/35] doc/org.bluez.GattManager: Add Used by reference and Examples
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (24 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 25/35] doc/org.bluez.GattDescriptor: Add Used by reference Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 27/35] doc/org.bluez.GattService: Add Used by reference Luiz Augusto von Dentz
` (9 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-gatt and Examples sections
showing corresponding bluetoothctl commands for GATT application methods.
---
doc/org.bluez.GattManager.rst | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/doc/org.bluez.GattManager.rst b/doc/org.bluez.GattManager.rst
index 2501530d8112..cb2a7f8ff86e 100644
--- a/doc/org.bluez.GattManager.rst
+++ b/doc/org.bluez.GattManager.rst
@@ -81,6 +81,7 @@ Interface
:Service: org.bluez
:Interface: org.bluez.GattManager1
:Object path: [variable prefix]/{hci0,hci1,...}
+:Used by: **bluetoothctl-gatt(1)**
Methods
-------
@@ -100,6 +101,10 @@ Possible errors:
:org.bluez.Error.InvalidArguments:
:org.bluez.Error.AlreadyExists:
+Examples:
+
+:bluetoothctl: > gatt.register-application [UUID ...]
+
void UnregisterApplication(object application)
``````````````````````````````````````````````
@@ -111,3 +116,7 @@ Possible errors:
:org.bluez.Error.InvalidArguments:
:org.bluez.Error.DoesNotExist:
+
+Examples:
+
+:bluetoothctl: > gatt.unregister-application
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 27/35] doc/org.bluez.GattService: Add Used by reference
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (25 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 26/35] doc/org.bluez.GattManager: Add Used by reference and Examples Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 28/35] doc/org.bluez.LEAdvertisement: " Luiz Augusto von Dentz
` (8 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-gatt for this interface
exposing GATT service properties.
---
doc/org.bluez.GattService.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/doc/org.bluez.GattService.rst b/doc/org.bluez.GattService.rst
index 9aba1c166f74..04228b9b3665 100644
--- a/doc/org.bluez.GattService.rst
+++ b/doc/org.bluez.GattService.rst
@@ -31,6 +31,7 @@ Client
:Service: org.bluez
:Interface: org.bluez.GattService1
:Object path: [variable prefix]/{hci0,hci1,...}/dev_{BDADDR}/service#
+:Used by: **bluetoothctl-gatt(1)**
Server
------
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 28/35] doc/org.bluez.LEAdvertisement: Add Used by reference
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (26 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 27/35] doc/org.bluez.GattService: Add Used by reference Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 29/35] doc/org.bluez.LEAdvertisingManager: Add Used by reference and Examples Luiz Augusto von Dentz
` (7 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-advertise for this callback
interface implemented by LE advertisement clients.
---
doc/org.bluez.LEAdvertisement.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/doc/org.bluez.LEAdvertisement.rst b/doc/org.bluez.LEAdvertisement.rst
index 680a6c4cb97b..aae80f08f3a5 100644
--- a/doc/org.bluez.LEAdvertisement.rst
+++ b/doc/org.bluez.LEAdvertisement.rst
@@ -35,6 +35,7 @@ versions of the same UUID will be used in the advertising data as appropriate.
:Service: org.bluez
:Interface: org.bluez.LEAdvertisement1
:Object path: freely definable
+:Used by: **bluetoothctl-advertise(1)**
Methods
-------
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 29/35] doc/org.bluez.LEAdvertisingManager: Add Used by reference and Examples
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (27 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 28/35] doc/org.bluez.LEAdvertisement: " Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 30/35] doc/org.bluez.Media: Add Used by reference Luiz Augusto von Dentz
` (6 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-advertise and Examples
sections showing corresponding bluetoothctl advertising commands.
---
doc/org.bluez.LEAdvertisingManager.rst | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/doc/org.bluez.LEAdvertisingManager.rst b/doc/org.bluez.LEAdvertisingManager.rst
index 464a2e5fb726..c7f575f7991a 100644
--- a/doc/org.bluez.LEAdvertisingManager.rst
+++ b/doc/org.bluez.LEAdvertisingManager.rst
@@ -21,6 +21,7 @@ follow the API for LE Advertisement Data described above.
:Service: org.bluez
:Interface: org.bluez.LEAdvertisingManager1
:Object path: /org/bluez/{hci0,hci1,...}
+:Used by: **bluetoothctl(1)**
Methods
-------
@@ -52,6 +53,10 @@ Possible errors:
Indicates the maximum number of advertisement instances has been
reached.
+Examples:
+
+:bluetoothctl: > advertise <on/off/type>
+
void UnregisterAdvertisement(object advertisement)
``````````````````````````````````````````````````
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 30/35] doc/org.bluez.Media: Add Used by reference
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (28 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 29/35] doc/org.bluez.LEAdvertisingManager: Add Used by reference and Examples Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 31/35] doc/org.bluez.MediaAssistant: Add Used by reference and Examples Luiz Augusto von Dentz
` (5 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-endpoint for this interface
used for media endpoint registration.
---
doc/org.bluez.Media.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/doc/org.bluez.Media.rst b/doc/org.bluez.Media.rst
index dc265d783cbe..35aef2646ad6 100644
--- a/doc/org.bluez.Media.rst
+++ b/doc/org.bluez.Media.rst
@@ -17,6 +17,7 @@ Interface
:Service: org.bluez
:Interface: org.bluez.Media1
:Object path: [variable prefix]/{hci0,hci1,...}
+:Used by: **bluetoothctl-endpoint(1)**
Methods
-------
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 31/35] doc/org.bluez.MediaAssistant: Add Used by reference and Examples
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (29 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 30/35] doc/org.bluez.Media: Add Used by reference Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 32/35] doc/org.bluez.MediaEndpoint: Add Used by reference Luiz Augusto von Dentz
` (4 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-assistant and Examples
sections showing corresponding bluetoothctl assistant commands.
---
doc/org.bluez.MediaAssistant.rst | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/doc/org.bluez.MediaAssistant.rst b/doc/org.bluez.MediaAssistant.rst
index 8650d8abb379..45143cee8dbf 100644
--- a/doc/org.bluez.MediaAssistant.rst
+++ b/doc/org.bluez.MediaAssistant.rst
@@ -17,6 +17,7 @@ Interface
:Service: org.bluez
:Interface: org.bluez.MediaAssistant1
:Object path: /org/bluez/{hci0,hci1,...}/dev_{BDADDR}/src_{BDADDR}/sid#/bis#
+:Used by: **bluetoothctl-assistant(1)**
Methods
-------
@@ -45,6 +46,10 @@ Values:
Push to a specific device. Device must be connected and with
an active BASS session.
+Examples:
+
+:bluetoothctl: > assistant.push <assistant>
+
Properties
----------
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 32/35] doc/org.bluez.MediaEndpoint: Add Used by reference
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (30 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 31/35] doc/org.bluez.MediaAssistant: Add Used by reference and Examples Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 33/35] doc/org.bluez.MediaPlayer: Add Used by reference and Examples Luiz Augusto von Dentz
` (3 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-endpoint for this callback
interface implemented by media endpoint clients.
---
doc/org.bluez.MediaEndpoint.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/doc/org.bluez.MediaEndpoint.rst b/doc/org.bluez.MediaEndpoint.rst
index 8202b2fdfec2..ee9bac20bc30 100644
--- a/doc/org.bluez.MediaEndpoint.rst
+++ b/doc/org.bluez.MediaEndpoint.rst
@@ -19,6 +19,7 @@ Interface
:Interface: org.bluez.MediaEndpoint1
:Object path: freely definable (Server role)
[variable prefix]/{hci0,hci1,...}/dev_{BDADDR}/sep# (Client role)
+:Used by: **bluetoothctl-endpoint(1)**
Methods
-------
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 33/35] doc/org.bluez.MediaPlayer: Add Used by reference and Examples
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (31 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 32/35] doc/org.bluez.MediaEndpoint: Add Used by reference Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 34/35] doc/org.bluez.MediaTransport: " Luiz Augusto von Dentz
` (2 subsequent siblings)
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-player and Examples sections
showing corresponding bluetoothctl player commands.
---
doc/org.bluez.MediaPlayer.rst | 29 +++++++++++++++++++++++++++++
1 file changed, 29 insertions(+)
diff --git a/doc/org.bluez.MediaPlayer.rst b/doc/org.bluez.MediaPlayer.rst
index 14768cf433ac..03513842a880 100644
--- a/doc/org.bluez.MediaPlayer.rst
+++ b/doc/org.bluez.MediaPlayer.rst
@@ -17,6 +17,7 @@ Interface
:Service: org.bluez (Controller role)
:Interface: org.bluez.MediaPlayer1
:Object path: [variable prefix]/{hci0,hci1,...}/dev_{BDADDR}/player#
+:Used by: **bluetoothctl-player(1)**
Methods
-------
@@ -31,6 +32,10 @@ Possible Errors:
:org.bluez.Error.NotSupported:
:org.bluez.Error.Failed:
+Examples:
+
+:bluetoothctl: > player.play [item]
+
void Pause()
````````````
@@ -41,6 +46,10 @@ Possible Errors:
:org.bluez.Error.NotSupported:
:org.bluez.Error.Failed:
+Examples:
+
+:bluetoothctl: > player.pause
+
void Stop()
```````````
@@ -51,6 +60,10 @@ Possible Errors:
:org.bluez.Error.NotSupported:
:org.bluez.Error.Failed:
+Examples:
+
+:bluetoothctl: > player.stop
+
void Next()
```````````
@@ -61,6 +74,10 @@ Possible Errors:
:org.bluez.Error.NotSupported:
:org.bluez.Error.Failed:
+Examples:
+
+:bluetoothctl: > player.next
+
void Previous()
```````````````
@@ -71,6 +88,10 @@ Possible Errors:
:org.bluez.Error.NotSupported:
:org.bluez.Error.Failed:
+Examples:
+
+:bluetoothctl: > player.previous
+
void FastForward()
``````````````````
@@ -82,6 +103,10 @@ Possible Errors:
:org.bluez.Error.NotSupported:
:org.bluez.Error.Failed:
+Examples:
+
+:bluetoothctl: > player.fast-forward
+
void Rewind()
`````````````
@@ -93,6 +118,10 @@ Possible Errors:
:org.bluez.Error.NotSupported:
:org.bluez.Error.Failed:
+Examples:
+
+:bluetoothctl: > player.rewind
+
void Press(byte avc_key)
````````````````````````
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 34/35] doc/org.bluez.MediaTransport: Add Used by reference and Examples
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (32 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 33/35] doc/org.bluez.MediaPlayer: Add Used by reference and Examples Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-01-30 19:39 ` [PATCH BlueZ v2 35/35] doc/org.bluez.Telephony: " Luiz Augusto von Dentz
2026-02-03 18:20 ` [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation patchwork-bot+bluetooth
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-transport and Examples
sections showing corresponding bluetoothctl transport commands.
---
doc/org.bluez.MediaTransport.rst | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
diff --git a/doc/org.bluez.MediaTransport.rst b/doc/org.bluez.MediaTransport.rst
index 3d1e8c5b5a40..0525caa91169 100644
--- a/doc/org.bluez.MediaTransport.rst
+++ b/doc/org.bluez.MediaTransport.rst
@@ -17,6 +17,7 @@ Interface
:Service: org.bluez
:Interface: org.bluez.MediaTransport1
:Object path: [variable prefix]/{hci0,hci1,...}/dev_{BDADDR}/fd#
+:Used by: **bluetoothctl-transport(1)**
Methods
-------
@@ -31,6 +32,10 @@ Possible Errors:
:org.bluez.Error.NotAuthorized:
:org.bluez.Error.Failed:
+Examples:
+
+:bluetoothctl: > transport.acquire <transport> [transport1...]
+
fd, uint16, uint16 TryAcquire()
```````````````````````````````
@@ -50,6 +55,10 @@ void Release()
Releases file descriptor.
+Examples:
+
+:bluetoothctl: > transport.release <transport> [transport1...]
+
void Select()
`````````````
@@ -68,6 +77,10 @@ Possible Errors:
:org.bluez.Error.NotAuthorized:
+Examples:
+
+:bluetoothctl: > transport.select <transport> [transport1...]
+
void Unselect()
```````````````
@@ -84,6 +97,10 @@ Possible Errors:
:org.bluez.Error.NotAuthorized:
+Examples:
+
+:bluetoothctl: > transport.unselect <transport> [transport1...]
+
Properties
----------
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* [PATCH BlueZ v2 35/35] doc/org.bluez.Telephony: Add Used by reference and Examples
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (33 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 34/35] doc/org.bluez.MediaTransport: " Luiz Augusto von Dentz
@ 2026-01-30 19:39 ` Luiz Augusto von Dentz
2026-02-03 18:20 ` [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation patchwork-bot+bluetooth
35 siblings, 0 replies; 38+ messages in thread
From: Luiz Augusto von Dentz @ 2026-01-30 19:39 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add :Used by: field linking to bluetoothctl-telephony and Examples
sections showing corresponding bluetoothctl telephony commands.
---
doc/org.bluez.Telephony.rst | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/doc/org.bluez.Telephony.rst b/doc/org.bluez.Telephony.rst
index a722e2a38394..4a2159e17bcd 100644
--- a/doc/org.bluez.Telephony.rst
+++ b/doc/org.bluez.Telephony.rst
@@ -17,6 +17,7 @@ Interface
:Service: org.bluez
:Interface: org.bluez.Telephony1 [experimental]
:Object path: [variable prefix]/{hci0,hci1,...}/dev_{BDADDR}/telephony#
+:Used by: **bluetoothctl-telephony(1)**
Methods
-------
@@ -54,6 +55,10 @@ Possible Errors:
:org.bluez.Error.NotSupported:
:org.bluez.Error.Failed:
+Examples:
+
+:bluetoothctl: > telephony.dial <number> [telephony]
+
void SwapCalls()
````````````````
@@ -113,6 +118,10 @@ Possible Errors:
:org.bluez.Error.InvalidState
:org.bluez.Error.Failed
+Examples:
+
+:bluetoothctl: > telephony.hangup-all [telephony]
+
void HangupActive()
```````````````````
--
2.52.0
^ permalink raw reply related [flat|nested] 38+ messages in thread* Re: [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation
2026-01-30 19:38 [PATCH BlueZ v2 00/35] doc: Add cross-references between bluetoothctl and D-Bus API documentation Luiz Augusto von Dentz
` (34 preceding siblings ...)
2026-01-30 19:39 ` [PATCH BlueZ v2 35/35] doc/org.bluez.Telephony: " Luiz Augusto von Dentz
@ 2026-02-03 18:20 ` patchwork-bot+bluetooth
35 siblings, 0 replies; 38+ messages in thread
From: patchwork-bot+bluetooth @ 2026-02-03 18:20 UTC (permalink / raw)
To: Luiz Augusto von Dentz; +Cc: linux-bluetooth
Hello:
This series was applied to bluetooth/bluez.git (master)
by Luiz Augusto von Dentz <luiz.von.dentz@intel.com>:
On Fri, 30 Jan 2026 14:38:42 -0500 you wrote:
> From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
>
> This patch series enhances the BlueZ documentation by adding cross-references
> between bluetoothctl command documentation and D-Bus API documentation:
>
> - bluetoothctl docs: Add :Uses: fields linking each command to its
> corresponding D-Bus interface method(s)
>
> [...]
Here is the summary with links:
- [BlueZ,v2,01/35] doc/bluetoothctl: Add :Uses: fields and document arguments
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=b4284016a35b
- [BlueZ,v2,02/35] doc/bluetoothctl-mgmt: Add :Uses: fields and document arguments
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=8153258ebe6c
- [BlueZ,v2,03/35] doc/bluetoothctl-admin: Add :Uses: fields and document arguments
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=7213d8dfd041
- [BlueZ,v2,04/35] doc/bluetoothctl-advertise: Add :Uses: fields and document arguments
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=c5715df9adb1
- [BlueZ,v2,05/35] doc/bluetoothctl-assistant: Add :Uses: fields and document arguments
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=fefe8c741363
- [BlueZ,v2,06/35] doc/bluetoothctl-bredr: Add :Uses: fields and document arguments
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=061759b8736c
- [BlueZ,v2,07/35] doc/bluetoothctl-endpoint: Add :Uses: fields and document arguments
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=e3c20c3183ed
- [BlueZ,v2,08/35] doc/bluetoothctl-gatt: Add :Uses: fields and document arguments
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=459e46abd054
- [BlueZ,v2,09/35] doc/bluetoothctl-hci: Add :Uses: fields and document arguments
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=8e926e4d8f16
- [BlueZ,v2,10/35] doc/bluetoothctl-le: Add :Uses: fields and document arguments
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=6238b7c3cabd
- [BlueZ,v2,11/35] doc/bluetoothctl-monitor: Add :Uses: fields and document arguments
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=192dd3f72f36
- [BlueZ,v2,12/35] doc/bluetoothctl-player: Add :Uses: fields and document arguments
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=0dfb1cad3863
- [BlueZ,v2,13/35] doc/bluetoothctl-scan: Add :Uses: fields and document arguments
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=16057f2ea3ee
- [BlueZ,v2,14/35] doc/bluetoothctl-telephony: Add :Uses: fields and document arguments
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=d7119120d26c
- [BlueZ,v2,15/35] doc/bluetoothctl-transport: Add :Uses: fields and document arguments
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=4d69f11acf8a
- [BlueZ,v2,16/35] doc/org.bluez.Adapter: Add Used by reference and Examples
(no matching commit)
- [BlueZ,v2,17/35] doc/org.bluez.AdminPolicySet: Add Used by reference and Examples
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=d0841ac272dd
- [BlueZ,v2,18/35] doc/org.bluez.AdminPolicyStatus: Add Used by reference
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=5490e7e4ccaf
- [BlueZ,v2,19/35] doc/org.bluez.AdvertisementMonitor: Add Used by reference
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=21732e9c6b9c
- [BlueZ,v2,20/35] doc/org.bluez.AdvertisementMonitorManager: Add Used by reference
(no matching commit)
- [BlueZ,v2,21/35] doc/org.bluez.AgentManager: Add Used by reference and Examples
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=aeff7ee796ff
- [BlueZ,v2,22/35] doc/org.bluez.Call: Add Used by reference and Examples
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=58029c4cf245
- [BlueZ,v2,23/35] doc/org.bluez.Device: Add Used by reference and Examples
(no matching commit)
- [BlueZ,v2,24/35] doc/org.bluez.GattCharacteristic: Add Used by reference and Examples
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=2123ab772fbe
- [BlueZ,v2,25/35] doc/org.bluez.GattDescriptor: Add Used by reference
(no matching commit)
- [BlueZ,v2,26/35] doc/org.bluez.GattManager: Add Used by reference and Examples
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=fe274b385fda
- [BlueZ,v2,27/35] doc/org.bluez.GattService: Add Used by reference
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=313ea6ba6121
- [BlueZ,v2,28/35] doc/org.bluez.LEAdvertisement: Add Used by reference
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=056589a17947
- [BlueZ,v2,29/35] doc/org.bluez.LEAdvertisingManager: Add Used by reference and Examples
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=4bb5abd20484
- [BlueZ,v2,30/35] doc/org.bluez.Media: Add Used by reference
(no matching commit)
- [BlueZ,v2,31/35] doc/org.bluez.MediaAssistant: Add Used by reference and Examples
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=bd7396ef8a62
- [BlueZ,v2,32/35] doc/org.bluez.MediaEndpoint: Add Used by reference
(no matching commit)
- [BlueZ,v2,33/35] doc/org.bluez.MediaPlayer: Add Used by reference and Examples
(no matching commit)
- [BlueZ,v2,34/35] doc/org.bluez.MediaTransport: Add Used by reference and Examples
(no matching commit)
- [BlueZ,v2,35/35] doc/org.bluez.Telephony: Add Used by reference and Examples
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=d390dbb58d45
You are awesome, thank you!
--
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html
^ permalink raw reply [flat|nested] 38+ messages in thread