[PATCH BlueZ v1] doc: Add org.bluez.Device.LE and org.bluez.Device.BREDR

[PATCH BlueZ v1] doc: Add org.bluez.Device.LE and org.bluez.Device.BREDR

[Luiz Augusto von Dentz]

From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>

This adds bearer specific interfaces so they can properly be operated
separately.

Fixes: https://github.com/bluez/bluez/issues/1350
---
 Makefile.am                    |   3 +
 doc/org.bluez.Device.BREDR.rst | 137 ++++++++++++++++++++++++++++++++
 doc/org.bluez.Device.LE.rst    | 138 +++++++++++++++++++++++++++++++++
 3 files changed, 278 insertions(+)
 create mode 100644 doc/org.bluez.Device.BREDR.rst
 create mode 100644 doc/org.bluez.Device.LE.rst

diff --git a/Makefile.am b/Makefile.am
index c4b88d83c962..6d5c6b9eebfc 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -358,6 +358,7 @@ if MANPAGES
 man_MANS += src/bluetoothd.8
 man_MANS += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7
 man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
+		doc/org.bluez.Device.LE.5 doc/org.bluez.Device.BREDR.5 \
 		doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \
 		doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \
 		doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.5 \
@@ -392,6 +393,7 @@ endif
 manual_pages += src/bluetoothd.8
 manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7
 manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
+		doc/org.bluez.Device.LE.5 doc/org.bluez.Device.BREDR.5 \
 		doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \
 		doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \
 		doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.5 \
@@ -470,6 +472,7 @@ EXTRA_DIST += doc/health-api.txt \
 EXTRA_DIST += doc/hci.rst doc/mgmt.rst doc/l2cap.rst doc/rfcomm.rst doc/sco.rst
 
 EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \
+		doc/org.bluez.Device.LE.rst doc/org.bluez.Device.BREDR.rst \
 		doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \
 		doc/org.bluez.Agent.rst doc/org.bluez.ProfileManager.rst \
 		doc/org.bluez.Profile.rst doc/org.bluez.NetworkServer.rst \
diff --git a/doc/org.bluez.Device.BREDR.rst b/doc/org.bluez.Device.BREDR.rst
new file mode 100644
index 000000000000..e1aa883b8342
--- /dev/null
+++ b/doc/org.bluez.Device.BREDR.rst
@@ -0,0 +1,137 @@
+======================
+org.bluez.Device.BREDR
+======================
+
+-------------------------------------------------
+BlueZ D-Bus Device BREDR bearer API documentation
+-------------------------------------------------
+
+:Version: BlueZ
+:Date: July 2025
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.Device1
+:Object path:	[variable prefix]/{hci0,hci1,...}/dev_{BDADDR}
+
+Methods
+-------
+
+void Connect() [experimental]
+`````````````````````````````
+
+Connects all BREDR profiles the remote device supports that can be connected to
+and have been flagged as auto-connectable. If only subset of profiles is already
+connected it will try to connect currently disconnected ones.
+
+If at least one profile was connected successfully this method will indicate
+success.
+
+Possible errors:
+
+:org.bluez.Error.NotReady:
+:org.bluez.Error.Failed:
+:org.bluez.Error.InProgress:
+:org.bluez.Error.AlreadyConnected:
+
+void Disconnect() [experimental]
+````````````````````````````````
+
+Disconnects all connected profiles and then terminates low-level ACL connection.
+
+ACL connection will be terminated even if some profiles were not disconnected
+properly e.g. due to misbehaving device.
+
+This method can be also used to cancel a preceding Connect call before a reply
+to it has been received.
+
+For non-trusted devices connected calling this method will disable incoming
+connections until Connect method is called again.
+
+Possible errors:
+
+:org.bluez.Error.NotConnected:
+
+Signals
+-------
+
+void Disconnected(string reason, string message) [experimental]
+```````````````````````````````````````````````````````````````
+
+This signal is launched when a device is disconnected, with the reason of the
+disconnection.
+
+This could be used by client application, depending on internal policy, to try
+to reconnect to the device in case of timeout or unknown disconnection, or to
+try to connect to another device.
+
+Possible reasons:
+
+:org.bluez.Reason.Unknown:
+
+:org.bluez.Reason.Timeout:
+
+	Connection timeout.
+
+	The link supervision timeout has expired for a connection or the
+	synchronization timeout has expired for a broadcast.
+
+:org.bluez.Reason.Local:
+
+	Connection terminated by local host.
+
+	The local device terminated the connection, terminated synchronization
+	with a broadcaster, or terminated broadcasting packets.
+
+:org.bluez.Reason.Remote:
+
+	Connection terminated by remote host.
+
+	This disconnection can be due to:
+
+	- the user on the remote device either terminated the connection or
+	  stopped broadcasting packets,
+
+	- the remote device terminated the connection because of low
+	  resources,
+
+	- the remote device terminated the connection because the device is
+	  about to power off.
+
+:org.bluez.Reason.Authentication:
+
+	Connection terminated due to an authentication failure.
+
+:org.bluez.Reason.Suspend:
+
+	Connection terminated by local host for suspend.
+
+Properties
+----------
+
+boolean Paired [readonly, experimental]
+```````````````````````````````````````
+
+Indicates if the remote device is paired to BREDR bearer.
+
+Paired means the pairing process where devices exchange the information to
+establish an encrypted connection has been completed.
+
+boolean Bonded [readonly, experimental]
+```````````````````````````````````````
+
+Indicates if the remote device is bonded to BREDR bearer.
+
+Bonded means the information exchanged on pairing process has been stored and
+will be persisted.
+
+boolean Connected [readonly, experimental]
+``````````````````````````````````````````
+
+Indicates if the remote device is currently connected to BREDR bearer.
+
+A PropertiesChanged signal indicate changes to this status.
diff --git a/doc/org.bluez.Device.LE.rst b/doc/org.bluez.Device.LE.rst
new file mode 100644
index 000000000000..dceec59f565a
--- /dev/null
+++ b/doc/org.bluez.Device.LE.rst
@@ -0,0 +1,138 @@
+===================
+org.bluez.Device.LE
+===================
+
+----------------------------------------------
+BlueZ D-Bus Device LE bearer API documentation
+----------------------------------------------
+
+:Version: BlueZ
+:Date: July 2025
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.Device1
+:Object path:	[variable prefix]/{hci0,hci1,...}/dev_{BDADDR}
+
+Methods
+-------
+
+void Connect() [experimental]
+`````````````````````````````
+
+Connects all LE profiles the remote device supports that can be connected to and
+have been flagged as auto-connectable. If only subset of profiles is already
+connected it will try to connect currently disconnected ones.
+
+If at least one profile was connected successfully this method will indicate
+success.
+
+Possible errors:
+
+:org.bluez.Error.NotReady:
+:org.bluez.Error.Failed:
+:org.bluez.Error.InProgress:
+:org.bluez.Error.AlreadyConnected:
+
+void Disconnect() [experimental]
+````````````````````````````````
+
+Disconnects all connected profiles and then terminates low-level ACL-LE
+connection.
+
+ACL-LE connection will be terminated even if some profiles were not disconnected
+properly e.g. due to misbehaving device.
+
+This method can be also used to cancel a preceding Connect call before a reply
+to it has been received.
+
+For non-trusted devices connected calling this method will disable incoming
+connections until Connect method is called again.
+
+Possible errors:
+
+:org.bluez.Error.NotConnected:
+
+Signals
+-------
+
+void Disconnected(string reason, string message) [experimental]
+```````````````````````````````````````````````````````````````
+
+This signal is launched when a device is disconnected, with the reason of the
+disconnection.
+
+This could be used by client application, depending on internal policy, to try
+to reconnect to the device in case of timeout or unknown disconnection, or to
+try to connect to another device.
+
+Possible reasons:
+
+:org.bluez.Reason.Unknown:
+
+:org.bluez.Reason.Timeout:
+
+	Connection timeout.
+
+	The link supervision timeout has expired for a connection or the
+	synchronization timeout has expired for a broadcast.
+
+:org.bluez.Reason.Local:
+
+	Connection terminated by local host.
+
+	The local device terminated the connection, terminated synchronization
+	with a broadcaster, or terminated broadcasting packets.
+
+:org.bluez.Reason.Remote:
+
+	Connection terminated by remote host.
+
+	This disconnection can be due to:
+
+	- the user on the remote device either terminated the connection or
+	  stopped broadcasting packets,
+
+	- the remote device terminated the connection because of low
+	  resources,
+
+	- the remote device terminated the connection because the device is
+	  about to power off.
+
+:org.bluez.Reason.Authentication:
+
+	Connection terminated due to an authentication failure.
+
+:org.bluez.Reason.Suspend:
+
+	Connection terminated by local host for suspend.
+
+Properties
+----------
+
+boolean Paired [readonly, experimental]
+```````````````````````````````````````
+
+Indicates if the remote device is paired to LE bearer.
+
+Paired means the pairing process where devices exchange the information to
+establish an encrypted connection has been completed.
+
+boolean Bonded [readonly, experimental]
+```````````````````````````````````````
+
+Indicates if the remote device is bonded to LE bearer.
+
+Bonded means the information exchanged on pairing process has been stored and
+will be persisted.
+
+boolean Connected [readonly, experimental]
+``````````````````````````````````````````
+
+Indicates if the remote device is currently connected to LE bearer.
+
+A PropertiesChanged signal indicate changes to this status.
-- 
2.50.0

RE: [BlueZ,v1] doc: Add org.bluez.Device.LE and org.bluez.Device.BREDR

[bluez.test.bot]

[-- Attachment #1: Type: text/plain, Size: 1261 bytes --]

This is automated email and please do not reply to this email!

Dear submitter,

Thank you for submitting the patches to the linux bluetooth mailing list.
This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=979806

---Test result---

Test Summary:
CheckPatch                    PENDING   0.36 seconds
GitLint                       PENDING   0.32 seconds
BuildEll                      PASS      20.09 seconds
BluezMake                     PASS      2622.21 seconds
MakeCheck                     PASS      20.57 seconds
MakeDistcheck                 PASS      182.93 seconds
CheckValgrind                 PASS      233.59 seconds
CheckSmatch                   PASS      302.65 seconds
bluezmakeextell               PASS      126.84 seconds
IncrementalBuild              PENDING   0.37 seconds
ScanBuild                     PASS      906.52 seconds

Details
##############################
Test: CheckPatch - PENDING
Desc: Run checkpatch.pl script
Output:

##############################
Test: GitLint - PENDING
Desc: Run gitlint
Output:

##############################
Test: IncrementalBuild - PENDING
Desc: Incremental build with the patches in the series
Output:



---
Regards,
Linux Bluetooth