Merge changes Ie238e8e5,I113e33a7

* changes:
  Add UWB RangingParameters
  Add UWB Ranging Measurement classes

6 files changed, 521 insertions, 0 deletions

diff --git a/core/java/android/uwb/AngleMeasurement.java b/core/java/android/uwb/AngleMeasurement.java
new file mode 100644
index 000000000000..7ef145cfe470
--- /dev/null
+++ b/core/java/android/uwb/AngleMeasurement.java
@@ -0,0 +1,65 @@
+/*
+ * Copyright 2020 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.uwb;
+
+import android.annotation.FloatRange;
+
+/**
+ * Angle measurement
+ *
+ * <p>The actual angle is interpreted as:
+ *   {@link #getRadians()} +/- {@link #getErrorRadians()} ()} at {@link #getConfidenceLevel()}
+ *
+ * @hide
+ */
+public final class AngleMeasurement {
+    /**
+     * Angle measurement in radians
+    *
+     * @return angle in radians
+     */
+    @FloatRange(from = -Math.PI, to = +Math.PI)
+    public double getRadians() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Error of angle measurement in radians
+     *
+     * <p>Must be a positive value
+     *
+     * @return angle measurement error in radians
+     */
+    @FloatRange(from = 0.0, to = +Math.PI)
+    public double getErrorRadians() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Angle measurement confidence level expressed as a value between
+     * 0.0 to 1.0.
+     *
+     * <p>A value of 0.0 indicates there is no confidence in the measurement. A value of 1.0
+     * indicates there is maximum confidence in the measurement.
+     *
+     * @return the confidence level of the angle measurement
+     */
+    @FloatRange(from = 0.0, to = 1.0)
+    public double getConfidenceLevel() {
+        throw new UnsupportedOperationException();
+    }
+}
diff --git a/core/java/android/uwb/AngleOfArrivalMeasurement.java b/core/java/android/uwb/AngleOfArrivalMeasurement.java
new file mode 100644
index 000000000000..030d5299d53b
--- /dev/null
+++ b/core/java/android/uwb/AngleOfArrivalMeasurement.java
@@ -0,0 +1,63 @@
+/*
+ * Copyright 2020 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.uwb;
+
+import android.annotation.NonNull;
+import android.annotation.Nullable;
+
+/**
+ * Represents an angle of arrival measurement between two devices using Ultra Wideband
+ *
+ * @hide
+ */
+public final class AngleOfArrivalMeasurement {
+    /**
+     * Azimuth angle measurement
+     * <p>Azimuth {@link AngleMeasurement} of remote device in horizontal coordinate system, this is
+     * the angle clockwise from the meridian when viewing above the north pole.
+     *
+     * <p>See: https://en.wikipedia.org/wiki/Horizontal_coordinate_system
+     *
+     * <p>On an Android device, azimuth north is defined as the angle perpendicular away from the
+     * back of the device when holding it in portrait mode upright.
+     *
+     * <p>Azimuth angle must be supported when Angle of Arrival is supported
+     *
+     * @return the azimuth {@link AngleMeasurement}
+     */
+    @NonNull
+    public AngleMeasurement getAzimuth() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Altitude angle measurement
+     * <p>Altitude {@link AngleMeasurement} of remote device in horizontal coordinate system, this
+     * is the angle above the equator when the north pole is up.
+     *
+     * <p>See: https://en.wikipedia.org/wiki/Horizontal_coordinate_system
+     *
+     * <p>On an Android device, altitude is defined as the angle vertical from ground when holding
+     * the device in portrait mode upright.
+     *
+     * @return altitude {@link AngleMeasurement} or null when this is not available
+     */
+    @Nullable
+    public AngleMeasurement getAltitude() {
+        throw new UnsupportedOperationException();
+    }
+}
diff --git a/core/java/android/uwb/DistanceMeasurement.java b/core/java/android/uwb/DistanceMeasurement.java
new file mode 100644
index 000000000000..f4e6d3ed644b
--- /dev/null
+++ b/core/java/android/uwb/DistanceMeasurement.java
@@ -0,0 +1,61 @@
+/*
+ * Copyright 2020 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.uwb;
+
+import android.annotation.FloatRange;
+
+/**
+ * A data point for the distance measurement
+ *
+ * <p>The actual distance is interpreted as:
+ *   {@link #getMeters()} +/- {@link #getErrorMeters()} at {@link #getConfidenceLevel()}
+ *
+ * @hide
+ */
+public final class DistanceMeasurement {
+    /**
+     * Distance measurement in meters
+     *
+     * @return distance in meters
+     */
+    public double getMeters() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Error of distance measurement in meters
+     * <p>Must be positive
+     *
+     * @return error of distance measurement in meters
+     */
+    public double getErrorMeters() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Distance measurement confidence level expressed as a value between 0.0 to 1.0.
+     *
+     * <p>A value of 0.0 indicates no confidence in the measurement. A value of 1.0 represents
+     * maximum confidence in the measurement
+     *
+     * @return confidence level
+     */
+    @FloatRange(from = 0.0, to = 1.0)
+    public double getConfidenceLevel() {
+        throw new UnsupportedOperationException();
+    }
+}
diff --git a/core/java/android/uwb/RangingMeasurement.java b/core/java/android/uwb/RangingMeasurement.java
new file mode 100644
index 000000000000..a249802366e0
--- /dev/null
+++ b/core/java/android/uwb/RangingMeasurement.java
@@ -0,0 +1,113 @@
+/*
+ * Copyright 2020 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.uwb;
+
+import android.annotation.IntDef;
+import android.annotation.NonNull;
+import android.annotation.Nullable;
+import android.annotation.SuppressLint;
+import android.os.SystemClock;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * Representation of a ranging measurement between the local device and a remote device
+ *
+ * @hide
+ */
+public final class RangingMeasurement {
+    /**
+     * Get the remote device's {@link UwbAddress}
+     *
+     * @return the remote device's {@link UwbAddress}
+     */
+    @NonNull
+    public UwbAddress getRemoteDeviceAddress() {
+        throw new UnsupportedOperationException();
+    }
+
+    @Retention(RetentionPolicy.SOURCE)
+    @IntDef(value = {
+            RANGING_STATUS_SUCCESS,
+            RANGING_STATUS_FAILURE_OUT_OF_RANGE,
+            RANGING_STATUS_FAILURE_UNKNOWN_ERROR})
+    public @interface Status {}
+
+    /**
+     * Ranging attempt was successful for this device
+     */
+    public static final int RANGING_STATUS_SUCCESS = 0;
+
+    /**
+     * Ranging failed for this device because it is out of range
+     */
+    public static final int RANGING_STATUS_FAILURE_OUT_OF_RANGE = 1;
+
+    /**
+     * Ranging failed for this device because of unknown error
+     */
+    public static final int RANGING_STATUS_FAILURE_UNKNOWN_ERROR = -1;
+
+    /**
+     * Get the status of this ranging measurement
+     *
+     * <p>Possible values are
+     * {@link #RANGING_STATUS_SUCCESS},
+     * {@link #RANGING_STATUS_FAILURE_OUT_OF_RANGE},
+     * {@link #RANGING_STATUS_FAILURE_UNKNOWN_ERROR}.
+     *
+     * @return the status of the ranging measurement
+     */
+    @Status
+    public int getStatus() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Timestamp of this ranging measurement in time since boot nanos in the same namespace as
+     * {@link SystemClock#elapsedRealtimeNanos()}
+     *
+     * @return timestamp of ranging measurement in nanoseconds
+     */
+    @SuppressLint("MethodNameUnits")
+    public long getElapsedRealtimeNanos() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Get the distance measurement
+     *
+     * @return a {@link DistanceMeasurement} or null if {@link #getStatus()} !=
+     *         {@link #RANGING_STATUS_SUCCESS}
+     */
+    @Nullable
+    public DistanceMeasurement getDistance() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Get the angle of arrival measurement
+     *
+     * @return an {@link AngleOfArrivalMeasurement} or null if {@link #getStatus()} !=
+     *         {@link #RANGING_STATUS_SUCCESS}
+     */
+    @Nullable
+    public AngleOfArrivalMeasurement getAngleOfArrival() {
+        throw new UnsupportedOperationException();
+    }
+}
diff --git a/core/java/android/uwb/RangingParams.java b/core/java/android/uwb/RangingParams.java
new file mode 100644
index 000000000000..9727696f0391
--- /dev/null
+++ b/core/java/android/uwb/RangingParams.java
@@ -0,0 +1,175 @@
+/*
+ * Copyright 2020 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.uwb;
+
+import android.annotation.IntDef;
+import android.annotation.NonNull;
+import android.annotation.Nullable;
+import android.os.PersistableBundle;
+import android.util.Duration;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.util.List;
+
+/**
+ * An object used when requesting to open a new {@link RangingSession}.
+ * <p>Use {@link RangingParams.Builder} to create an instance of this class.
+ *
+ *  @hide
+ */
+public final class RangingParams {
+    /**
+     * Standard builder interface as the class is not modifiable
+     */
+    public static class Builder {
+        // TODO implement
+    }
+
+    /**
+     * Get if the local device is the initiator
+     *
+     * @return true if the device is the initiator
+     */
+    public boolean isInitiator() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Get if the local device is the controller
+     *
+     * @return true if the device is the controller
+     */
+    public boolean isController() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * The desired amount of time between two adjacent samples of measurement
+     *
+     * @return the ranging sample period
+     */
+    @NonNull
+    public Duration getSamplingPeriod() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Local device's {@link UwbAddress}
+     *
+     * <p>Simultaneous {@link RangingSession}s on the same device can have different results for
+     * {@link #getLocalDeviceAddress()}.
+     *
+     * @return the local device's {@link UwbAddress}
+     */
+    @NonNull
+    public UwbAddress getLocalDeviceAddress() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Gets a list of all remote device's {@link UwbAddress}
+     *
+     * @return a {@link List} of {@link UwbAddress} representing the remote devices
+     */
+    @NonNull
+    public List<UwbAddress> getRemoteDeviceAddresses() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Channel number used between this device pair as defined by 802.15.4z
+     *
+     * Range: -1, 0-15
+     *
+     * @return the channel to use
+     */
+    public int getChannelNumber() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Preamble index used between this device pair as defined by 802.15.4z
+     *
+     * Range: 0, 0-32
+     *
+     * @return the preamble index to use for transmitting
+     */
+    public int getTxPreambleIndex() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * preamble index used between this device pair as defined by 802.15.4z
+     *
+     * Range: 0, 13-16, 21-32
+     *
+     * @return the preamble index to use for receiving
+     */
+    public int getRxPreambleIndex() {
+        throw new UnsupportedOperationException();
+    }
+
+    @Retention(RetentionPolicy.SOURCE)
+    @IntDef(value = {
+            STS_PHY_PACKET_TYPE_SP0,
+            STS_PHY_PACKET_TYPE_SP1,
+            STS_PHY_PACKET_TYPE_SP2,
+            STS_PHY_PACKET_TYPE_SP3})
+    public @interface StsPhyPacketType {}
+
+    /**
+     * PHY packet type SP0 when STS is used as defined by 802.15.4z
+     */
+    public static final int STS_PHY_PACKET_TYPE_SP0 = 0;
+
+    /**
+     * PHY packet type SP1 when STS is used as defined by 802.15.4z
+     */
+    public static final int STS_PHY_PACKET_TYPE_SP1 = 1;
+
+    /**
+     * PHY packet type SP2 when STS is used as defined by 802.15.4z
+     */
+    public static final int STS_PHY_PACKET_TYPE_SP2 = 2;
+
+    /**
+     * PHY packet type SP3 when STS is used as defined by 802.15.4z
+     */
+    public static final int STS_PHY_PACKET_TYPE_SP3 = 3;
+
+    /**
+     * Get the type of PHY packet when STS is used as defined by 802.15.4z
+     *
+     * @return the {@link StsPhyPacketType} to use
+     */
+    @StsPhyPacketType
+    public int getStsPhyPacketType() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Parameters for a specific UWB protocol constructed using a support library.
+     *
+     * <p>Android reserves the '^android.*' namespace
+     *
+     * @return a {@link PersistableBundle} of protocol specific parameters
+     */
+    public @Nullable PersistableBundle getSpecificationParameters() {
+        throw new UnsupportedOperationException();
+    }
+}
diff --git a/core/java/android/uwb/RangingReport.java b/core/java/android/uwb/RangingReport.java
new file mode 100644
index 000000000000..037bdfd5f224
--- /dev/null
+++ b/core/java/android/uwb/RangingReport.java
@@ -0,0 +1,44 @@
+/*
+ * Copyright 2020 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.uwb;
+
+import android.annotation.NonNull;
+
+import java.util.List;
+
+/**
+ * This class contains the UWB ranging data
+ *
+ * @hide
+ */
+public final class RangingReport {
+    /**
+     * Get a {@link List} of {@link RangingMeasurement} objects in the last measurement interval
+     * <p>The underlying UWB adapter may choose to do multiple measurements in each ranging
+     * interval.
+     *
+     * <p>The entries in the {@link List} are ordered in ascending order based on
+     * {@link RangingMeasurement#getElapsedRealtimeNanos()}
+     *
+     * @return a {@link List} of {@link RangingMeasurement} objects
+     */
+    @NonNull
+    public List<RangingMeasurement> getMeasurements() {
+        throw new UnsupportedOperationException();
+    }
+}
+