1 /*
2  * Copyright (C) 2024 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package com.android.ranging.generic.ranging;
18 
19 import android.os.RemoteException;
20 
21 import androidx.annotation.IntDef;
22 import androidx.core.uwb.backend.impl.internal.RangingCapabilities;
23 import androidx.core.uwb.backend.impl.internal.RangingParameters;
24 import androidx.core.uwb.backend.impl.internal.UwbAddress;
25 import androidx.core.uwb.backend.impl.internal.UwbComplexChannel;
26 
27 import com.android.ranging.generic.RangingTechnology;
28 
29 import com.google.common.collect.ImmutableMap;
30 import com.google.common.util.concurrent.ListenableFuture;
31 
32 import java.lang.annotation.Retention;
33 import java.lang.annotation.RetentionPolicy;
34 
35 /**
36  * PrecisionRanging provides an API for ranging with multiple ranging technologies such as
37  * Ultra-Wide Band (UWB) and Channel Sounding (CS), and fusing the ranging data with additional
38  * sensor data such as IMU and ArCore.
39  */
40 public interface PrecisionRanging {
41 
42     /**
43      * Creates a new instance of {@link PrecisionRanging}. Ranging technologies that will be used
44      * are
45      * set through the configuration. Each ranging technology that's used may require additional
46      * setup
47      * through set*RangingTech*Config before start can be called.
48      */
49     interface Factory {
create(PrecisionRangingConfig config)50         PrecisionRanging create(PrecisionRangingConfig config);
51     }
52 
53     /** Starts precision ranging, results are provided via the given callback. */
start(Callback callback)54     void start(Callback callback);
55 
56     /** Stops precision ranging. */
stop()57     void stop();
58 
59     /**
60      * Returns a map that describes the {@link RangingTechnologyAvailability} for each requested
61      * {@link RangingTechnology} for this session. {@link RangingTechnologyAvailability} is either
62      * NOT_SUPPORTED when the hardware or software doesn't support the technology, DISABLED when
63      * it's
64      * disabled due to a condition or a user switch, or ENABLED when it's available to use.
65      */
rangingTechnologiesAvailability()66     ListenableFuture<ImmutableMap<RangingTechnology, Integer>> rangingTechnologiesAvailability()
67             throws RemoteException;
68 
69     /** Returns UWB capabilities if UWB was requested. */
getUwbCapabilities()70     ListenableFuture<RangingCapabilities> getUwbCapabilities();
71 
72     /** Returns UWB address if UWB was requested. */
getUwbAddress()73     ListenableFuture<UwbAddress> getUwbAddress() throws RemoteException;
74 
75     /** Sets UWB configuration. No op if UWB was not requested. */
setUwbConfig(RangingParameters rangingParameters)76     void setUwbConfig(RangingParameters rangingParameters);
77 
78     /** Get the Uwb complex channel for the controller. */
getUwbComplexChannel()79     ListenableFuture<UwbComplexChannel> getUwbComplexChannel() throws RemoteException;
80 
81     /** Returns CS capabilities if CS was requested. */
getCsCapabilities()82     void getCsCapabilities();
83 
84     /** Sets CS configuration. No op if CS was not requested. */
setCsConfig()85     void setCsConfig();
86 
87     /** State of an individual Ranging Technology on this device. */
88     @Retention(RetentionPolicy.SOURCE)
89     @IntDef({
90             /* Ranging technology is not supported on this device. */
91             RangingTechnologyAvailability.NOT_SUPPORTED,
92             /* Ranging technology is disabled. */
93             RangingTechnologyAvailability.DISABLED,
94             /* Ranging technology is enabled. */
95             RangingTechnologyAvailability.ENABLED,
96     })
97     @interface RangingTechnologyAvailability {
98         int NOT_SUPPORTED = 0;
99         int DISABLED = 1;
100         int ENABLED = 2;
101     }
102 
103     /** Callback for {@link PrecisionRanging} operations. */
104     interface Callback {
105         /** Callback method for reporting when precision ranging has started. */
onStarted()106         void onStarted();
107 
108         /** Callback method for reporting when precision ranging has stopped. */
onStopped(@toppedReason int reason)109         void onStopped(@StoppedReason int reason);
110 
111         /** Callback for reporting precision data. */
onData(PrecisionData data)112         void onData(PrecisionData data);
113 
114         /** Reason why Precision Finding was stopped. */
115         @Retention(RetentionPolicy.SOURCE)
116         @IntDef({
117                 /* Unexpected internal error. */
118                 StoppedReason.INTERNAL_ERROR,
119                 /* Stopped as a result of calling {@link #stop()}. */
120                 StoppedReason.REQUESTED,
121                 /* Stopped due to no ranging data received timeout. */
122                 StoppedReason.NO_RANGES_TIMEOUT,
123                 /* Exceeded drift timeout due to no incoming ranges. */
124                 StoppedReason.FUSION_DRIFT_TIMEOUT,
125         })
126         @interface StoppedReason {
127             int INTERNAL_ERROR = 0;
128             int REQUESTED = 1;
129             int NO_RANGES_TIMEOUT = 2;
130             int FUSION_DRIFT_TIMEOUT = 3;
131         }
132     }
133 }
134