Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 7952df19 authored by Brian Stack's avatar Brian Stack
Browse files

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
parent 4bde2ef7

core/java/android/uwb/AngleMeasurement.java

0 → 100644
+65 −0
Original line number Diff line number Diff line 
/*

 * 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 → 100644
+63 −0
Original line number Diff line number Diff line 
/*

 * 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 → 100644
+61 −0
Original line number Diff line number Diff line 
/*

 * 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 → 100644
+113 −0
Original line number Diff line number Diff line 
/*

 * 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 → 100644
+44 −0
Original line number Diff line number Diff line 
/*

 * 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();

    }

}