Add UWB Ranging Measurement classes

Adds the types needed to report UWB ranging and angle of arrival
information.

Bug: 170323306
Test: Builds
Change-Id: I113e33a77202d0b8d59f48de58fcc0bda4a8bc39

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();
+    }
+}

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();
+    }
+}

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();
+    }
+}

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();
+    }
+}

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();
+    }
+}
+