BTDevice: API Doc: Detail RSSI and Tx Power Level

2 files changed, 66 insertions, 8 deletions

diff --git a/api/direct_bt/BTDevice.hpp b/api/direct_bt/BTDevice.hpp
index c42a8b88..0d8c52c1 100644
--- a/api/direct_bt/BTDevice.hpp
+++ b/api/direct_bt/BTDevice.hpp
@@ -398,10 +398,41 @@ namespace direct_bt {
              */
             BDAddressAndType const & getVisibleAddressAndType() const noexcept { return visibleAddressAndType; }
 
-            /** Return RSSI of device as recognized at discovery and connect. */
+            /**
+             * Returns Received Signal Strength Indicator (RSSI)
+             * in dBm with ±6 dB accuracy of device as recognized at discovery and connect.
+             * <p>
+             * BT Core Spec v5.2: Vol 4, Part E HCI: 7.5.4 Read RSSI command
+             * </p>
+             * <p>
+             * Any positive RSSI value indicates how many dB the RSSI is above the upper limit,
+             * any negative value indicates how many dB the RSSI is below the lower limit.
+             * The value zero indicates that the RSSI is inside the Golden Receive Power Range.
+             * </p>
+             * <p>
+             * LE range [-127..20] with 0 inside the Golden Receive Power Range
+             * and 127 as "not available" value (core spec).
+             * </p>
+             * <pre>
+             * pathloss = Tx Power Level – RSSI
+             * </pre>
+             * @see #getTxPower()
+             */
             int8_t getRSSI() const noexcept { return rssi; }
 
-            /** Return Tx Power of device as recognized at discovery and connect. */
+            /**
+             * Return Tx Power Level in dBm with ±6 dB accuracy of device as recognized at discovery and connect.
+             * <p>
+             * Core Specification Supplement, Part A, Section 1.5.
+             * </p>
+             * <p>
+             * Range [-127..20] with 127 as "not available" value (core spec).
+             * </p>
+             * <pre>
+             * pathloss = Tx Power Level – RSSI
+             * </pre>
+             * @see #getRSSI()
+             */
             int8_t getTxPower() const noexcept { return tx_power; }
 
             /**
diff --git a/java/org/direct_bt/BTDevice.java b/java/org/direct_bt/BTDevice.java
index f3b18f94..f5e97aa7 100644
--- a/java/org/direct_bt/BTDevice.java
+++ b/java/org/direct_bt/BTDevice.java
@@ -825,9 +825,26 @@ public interface BTDevice extends BTObject
      */
     String getName();
 
-    /** Returns the Received Signal Strength Indicator of the device.
-      * @return The Received Signal Strength Indicator of the device.
-      */
+    /**
+     * Returns Received Signal Strength Indicator (RSSI)
+     * in dBm with ±6 dB accuracy of device as recognized at discovery and connect.
+     * <p>
+     * BT Core Spec v5.2: Vol 4, Part E HCI: 7.5.4 Read RSSI command
+     * </p>
+     * <p>
+     * Any positive RSSI value indicates how many dB the RSSI is above the upper limit,
+     * any negative value indicates how many dB the RSSI is below the lower limit.
+     * The value zero indicates that the RSSI is inside the Golden Receive Power Range.
+     * </p>
+     * <p>
+     * LE range [-127..20] with 0 inside the Golden Receive Power Range
+     * and 127 as "not available" value (core spec).
+     * </p>
+     * <pre>
+     * pathloss = Tx Power Level – RSSI
+     * </pre>
+     * @see #getTxPower()
+     */
     short getRSSI();
 
     /**
@@ -936,9 +953,19 @@ public interface BTDevice extends BTObject
      */
     BTRole getRole();
 
-    /** Returns the transmission power level (0 means unknown).
-      * @return the transmission power level (0 means unknown).
-      */
+    /**
+     * Return Tx Power Level in dBm with ±6 dB accuracy of device as recognized at discovery and connect.
+     * <p>
+     * Core Specification Supplement, Part A, Section 1.5.
+     * </p>
+     * <p>
+     * Range [-127..20] with 127 as "not available" value (core spec).
+     * </p>
+     * <pre>
+     * pathloss = Tx Power Level – RSSI
+     * </pre>
+     * @see #getRSSI()
+     */
     short getTxPower();
 
     /**