[PATCH BlueZ v2 2/5] doc: Add org.bluez.Bearer.LE and org.bluez.Bearer.BREDR

[Luiz Augusto von Dentz <luiz.dentz@gmail.com>]

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.Bearer.BREDR.rst | 143 +++++++++++++++++++++++++++++++++
 doc/org.bluez.Bearer.LE.rst    | 143 +++++++++++++++++++++++++++++++++
 3 files changed, 289 insertions(+)
 create mode 100644 doc/org.bluez.Bearer.BREDR.rst
 create mode 100644 doc/org.bluez.Bearer.LE.rst

diff --git a/Makefile.am b/Makefile.am
index c4b88d83c962..b75125e8887f 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.Bearer.LE.5 doc/org.bluez.Bearer.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.Bearer.LE.5 doc/org.bluez.Bearer.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.Bearer.LE.rst doc/org.bluez.Bearer.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.Bearer.BREDR.rst b/doc/org.bluez.Bearer.BREDR.rst
new file mode 100644
index 000000000000..779490728872
--- /dev/null
+++ b/doc/org.bluez.Bearer.BREDR.rst
@@ -0,0 +1,143 @@
+======================
+org.bluez.Bearer.BREDR
+======================
+
+------------------------------------------
+BlueZ D-Bus Bearer BREDR API documentation
+------------------------------------------
+
+:Version: BlueZ
+:Date: July 2025
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.Bearer.BREDR1
+: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
+----------
+
+object Adapter [readonly, experimental]
+```````````````````````````````````````
+
+The object path of the adapter the set belongs to.
+
+
+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.Bearer.LE.rst b/doc/org.bluez.Bearer.LE.rst
new file mode 100644
index 000000000000..a4657755d119
--- /dev/null
+++ b/doc/org.bluez.Bearer.LE.rst
@@ -0,0 +1,143 @@
+===================
+org.bluez.Bearer.LE
+===================
+
+---------------------------------------
+BlueZ D-Bus Bearer LE API documentation
+---------------------------------------
+
+:Version: BlueZ
+:Date: July 2025
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.Bearer.LE1
+: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
+----------
+
+object Adapter [readonly, experimental]
+```````````````````````````````````````
+
+The object path of the adapter the set belongs to.
+
+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