From 7a60ea4c6a2e4426465acd0824cd9ca3a8b9e158 Mon Sep 17 00:00:00 2001
From: Etan Cohen <etancohen@google.com>
Date: Tue, 27 Mar 2018 09:29:12 -0700
Subject: [PATCH] [RTT] Expose new public API for number of measurements

The RTT distance and standard deviation are calculated based on a set
of N measurements. Of those M (M<=N) may be successful.

The quality of the provided results can be assessed by 2 measures:

1. The standard deviation of the results

The standard deviation is only valid if the number of successful
measurements is >1 otherwise a 0 is returned. A value of 0 cannot be
differentiated from a legitimate 0 standard deviation.

In one case (number of samples > 1) a standard deviation of 0 indicates
high confidence in the result. In the other case (number of samples = 0)
no confidence information can be derived.

2. The ratio of successful to total attempted measurements

Add API which provides the number of attempted measurements and number
of successful measurements used to calculate the final results.

Bug: 76445930
Test: N/A (unhide CL only, code verified earlier)
Change-Id: Ia7322b3abc28e83c29d0b0ae79db30fd99bb7fe1
---
 api/current.txt                                   |  2 ++
 wifi/java/android/net/wifi/rtt/RangingResult.java | 14 ++++++++++----
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/api/current.txt b/api/current.txt
index be5e3e70d0a2b..d436bf3024a14 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -28587,6 +28587,8 @@ package android.net.wifi.rtt {
     method public int getDistanceMm();
     method public int getDistanceStdDevMm();
     method public android.net.MacAddress getMacAddress();
+    method public int getNumAttemptedMeasurements();
+    method public int getNumSuccessfulMeasurements();
     method public android.net.wifi.aware.PeerHandle getPeerHandle();
     method public long getRangingTimestampMillis();
     method public int getRssi();
diff --git a/wifi/java/android/net/wifi/rtt/RangingResult.java b/wifi/java/android/net/wifi/rtt/RangingResult.java
index 5518d35eb4c7f..758a8d559e4e6 100644
--- a/wifi/java/android/net/wifi/rtt/RangingResult.java
+++ b/wifi/java/android/net/wifi/rtt/RangingResult.java
@@ -170,7 +170,9 @@ public final class RangingResult implements Parcelable {
     /**
      * @return The standard deviation of the measured distance (in mm) to the device specified by
      * {@link #getMacAddress()} or {@link #getPeerHandle()}. The standard deviation is calculated
-     * over the measurements executed in a single RTT burst.
+     * over the measurements executed in a single RTT burst. The number of measurements is returned
+     * by {@link #getNumSuccessfulMeasurements()} - 0 successful measurements indicate that the
+     * standard deviation is not valid (a valid standard deviation requires at least 2 data points).
      * <p>
      * Only valid if {@link #getStatus()} returns {@link #STATUS_SUCCESS}, otherwise will throw an
      * exception.
@@ -199,11 +201,12 @@ public final class RangingResult implements Parcelable {
 
     /**
      * @return The number of attempted measurements used in the RTT exchange resulting in this set
-     * of results.
+     * of results. The number of successful measurements is returned by
+     * {@link #getNumSuccessfulMeasurements()} which at most, if there are no errors, will be 1 less
+     * that the number of attempted measurements.
      * <p>
      * Only valid if {@link #getStatus()} returns {@link #STATUS_SUCCESS}, otherwise will throw an
      * exception.
-     * @hide
      */
     public int getNumAttemptedMeasurements() {
         if (mStatus != STATUS_SUCCESS) {
@@ -220,9 +223,12 @@ public final class RangingResult implements Parcelable {
      * returned by {@link #getDistanceStdDevMm()}, is not valid (a 0 is returned for the standard
      * deviation).
      * <p>
+     * The total number of measurement attempts is returned by
+     * {@link #getNumAttemptedMeasurements()}. The number of successful measurements will be at
+     * most 1 less then the number of attempted measurements.
+     * <p>
      * Only valid if {@link #getStatus()} returns {@link #STATUS_SUCCESS}, otherwise will throw an
      * exception.
-     * @hide
      */
     public int getNumSuccessfulMeasurements() {
         if (mStatus != STATUS_SUCCESS) {