[PATCH BlueZ v3 1/7] doc: Add org.bluez.Ranging1 documentation

[Naga Bhavani Akella <naga.akella@oss.qualcomm.com>]

Document org.bluez.Ranging1 interface, which
exposes the Distance estimate computed by an
external ranging provider registered via
RangingProviderManager.

Add org.bluez.ChannelSounding1.rst to EXTRA_DIST
---
 Makefile.am                |  9 ++++-
 doc/org.bluez.Ranging1.rst | 78 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 85 insertions(+), 2 deletions(-)
 create mode 100644 doc/org.bluez.Ranging1.rst

diff --git a/Makefile.am b/Makefile.am
index ab7457252..682ec26e5 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -405,7 +405,8 @@ man_MANS += doc/org.bluez.Telephony.5 doc/org.bluez.Call.5
 man_MANS += doc/org.bluez.ThermometerManager.5 \
 		doc/org.bluez.Thermometer.5 \
 		doc/org.bluez.ThermometerWatcher.5
-man_MANS += doc/org.bluez.ChannelSounding1.5
+man_MANS += doc/org.bluez.ChannelSounding1.5 \
+		doc/org.bluez.Ranging1.5
 endif
 manual_pages += doc/bluetoothd.8
 manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7 \
@@ -446,7 +447,8 @@ manual_pages += doc/org.bluez.Telephony.5 doc/org.bluez.Call.5
 manual_pages += doc/org.bluez.ThermometerManager.5 \
 		doc/org.bluez.Thermometer.5 \
 		doc/org.bluez.ThermometerWatcher.5
-manual_pages += doc/org.bluez.ChannelSounding1.5
+manual_pages += doc/org.bluez.ChannelSounding1.5 \
+		doc/org.bluez.Ranging1.5
 
 EXTRA_DIST += src/genbuiltin src/bluetooth.conf \
 			src/main.conf profiles/network/network.conf \
@@ -535,6 +537,9 @@ EXTRA_DIST += doc/org.bluez.ThermometerManager.rst \
 	      doc/org.bluez.Thermometer.rst \
 	      doc/org.bluez.ThermometerWatcher.rst
 
+EXTRA_DIST += doc/org.bluez.ChannelSounding1.rst \
+		doc/org.bluez.Ranging1.rst
+
 EXTRA_DIST += doc/pics-opp.txt doc/pixit-opp.txt \
 		doc/pts-opp.txt
 
diff --git a/doc/org.bluez.Ranging1.rst b/doc/org.bluez.Ranging1.rst
new file mode 100644
index 000000000..8dce07e04
--- /dev/null
+++ b/doc/org.bluez.Ranging1.rst
@@ -0,0 +1,78 @@
+==================
+org.bluez.Ranging1
+==================
+
+--------------------------------------
+BlueZ D-Bus Ranging API documentation
+--------------------------------------
+
+:Version: BlueZ
+:Date: August 2026
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.Ranging1
+:Object path:	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+
+Properties
+----------
+
+uint32 Distance [readonly]
+``````````````````````````
+
+Estimated distance to the remote device, in millimeters, as last
+reported by a ranging provider.
+
+Providers implementing **org.bluez.RangingProvider1(5)**, registered via
+**org.bluez.RangingProviderManager1(5)**, compute this value and report
+it back to **bluetoothd(8)** for reflection here. For Channel Sounding
+based ranging, a provider derives the distance from the raw procedure
+data reported via the **ProcedureData** signal on
+**org.bluez.ChannelSounding1(5)**, but this interface itself carries no
+assumption about the underlying ranging technology.
+
+This property emits ``PropertiesChanged`` whenever a new estimate is
+reported.
+
+This property does not exist until a ranging provider has reported at
+least one estimate for this device; reading it before then (e.g. via
+**org.freedesktop.DBus.Properties.Get**) fails with
+**org.freedesktop.DBus.Error.UnknownProperty**, and it is omitted from
+**GetAll**/**GetManagedObjects** results. Once a provider unregisters
+or stops providing ranging for this device, this whole
+**Ranging** interface — and therefore the **Distance** property — is
+removed (**InterfacesRemoved**); it does not linger with a stale value.
+
+Overview
+========
+
+**Ranging** is the read side of a three-party pattern ::
+
+    Ranging daemon -- RangingProvider --> BlueZ -- Ranging --> Desktop clients
+                       (registered via RangingProviderManager)
+
+Sequence for a single distance update, once a provider is registered
+(see **org.bluez.RangingProviderManager1(5)**) and has exposed a
+**org.bluez.RangingProvider1(5)** object for the device (see
+**org.bluez.RangingProvider1(5)**)::
+
+    Ranging daemon                    bluetoothd                  Desktop client
+         |                                 |                             |
+         | Distance = D on its             |                             |
+         | RangingProvider object          |                             |
+         |                                 |                             |
+         | PropertiesChanged(              |                             |
+         |   RangingProvider,              |                             |
+         |   "Distance", D)                |                             |
+         |-------------------------------->|                             |
+         |                                 | updates Ranging on the      |
+         |                                 | device path with D          |
+         |                                 |                             |
+         |                                 | PropertiesChanged(          |
+         |                                 |   Ranging,                  |
+         |                                 |   "Distance", D)            |
+         |                                 |---------------------------->|
--