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 android.ranging.raw; 18 19 import android.annotation.FlaggedApi; 20 import android.annotation.IntDef; 21 import android.annotation.NonNull; 22 import android.annotation.Nullable; 23 import android.os.Parcel; 24 import android.os.Parcelable; 25 import android.ranging.RangingDevice; 26 import android.ranging.ble.cs.BleCsRangingParams; 27 import android.ranging.ble.rssi.BleRssiRangingParams; 28 import android.ranging.uwb.UwbRangingCapabilities; 29 import android.ranging.uwb.UwbRangingParams; 30 import android.ranging.wifi.rtt.RttRangingCapabilities; 31 import android.ranging.wifi.rtt.RttRangingParams; 32 33 import com.android.ranging.flags.Flags; 34 35 import java.lang.annotation.ElementType; 36 import java.lang.annotation.Retention; 37 import java.lang.annotation.RetentionPolicy; 38 import java.lang.annotation.Target; 39 import java.util.Objects; 40 import java.util.stream.Stream; 41 42 /** 43 * Represents a device participating in ranging operations. 44 * This class supports multiple ranging technologies, including UWB, BLE CS, BLE RSSI and Wi-Fi 45 * NAN-RTT. The configuration for each technology is provided through corresponding parameter 46 * objects. 47 */ 48 @FlaggedApi(Flags.FLAG_RANGING_STACK_ENABLED) 49 public final class RawRangingDevice implements Parcelable { 50 51 /** 52 * Defines the configuration IDs for different ranging scenarios. 53 * 54 * @hide 55 */ 56 @Retention(RetentionPolicy.SOURCE) 57 @Target({ElementType.TYPE_USE}) 58 @IntDef({ 59 UPDATE_RATE_NORMAL, 60 UPDATE_RATE_INFREQUENT, 61 UPDATE_RATE_FREQUENT, 62 }) 63 public @interface RangingUpdateRate { 64 } 65 66 /** 67 * Normal ranging interval (Default). 68 * <ul> 69 * <li> UWB - 200 milliseconds for config ids {@link UwbRangingParams#getConfigId()} with 70 * multicast ranging, 240 milliseconds for unicast. </li> 71 * <li> BLE RSSI - 1 second. </li> 72 * <li> BLE CS - 200 ms. </li> 73 * <li> WiFi Rtt - 256 milliseconds if 74 * {@link RttRangingCapabilities#hasPeriodicRangingHardwareFeature()} is true, 512 75 * milliseconds otherwise. </li> 76 * </ul> 77 */ 78 public static final int UPDATE_RATE_NORMAL = 1; 79 80 /** 81 * Infrequent ranging interval. 82 * <ul> 83 * <li> UWB - 600 milliseconds. </li> 84 * <li> BLE RSSI - 3 seconds. </li> 85 * <li> BLE CS - 5 seconds. </li> 86 * <li> WiFi Rtt - 8192 milliseconds otherwise. </li> 87 * </ul> 88 */ 89 public static final int UPDATE_RATE_INFREQUENT = 2; 90 91 /** 92 * Frequent ranging interval. 93 * <ul> 94 * <li> UWB - 96 milliseconds for config id 95 * {@link UwbRangingParams#CONFIG_PROVISIONED_UNICAST_DS_TWR_VERY_FAST}, 120 milliseconds 96 * otherwise. See {@link UwbRangingCapabilities#getSupportedRangingUpdateRates()} to verify 97 * Frequent update rate is supported. </li> 98 * <li> BLE RSSI - 500 milliseconds. </li> 99 * <li> BLE CS - 100 milliseconds. </li> 100 * <li> WiFi Rtt - 128 milliseconds if 101 * {@link RttRangingCapabilities#hasPeriodicRangingHardwareFeature()} is true, 256 102 * milliseconds otherwise. </li> 103 * </ul> 104 */ 105 public static final int UPDATE_RATE_FREQUENT = 3; 106 private final RangingDevice mRangingDevice; 107 private final UwbRangingParams mUwbRangingParams; 108 private final BleCsRangingParams mBleCsRangingParams; 109 private final RttRangingParams mRttRangingParams; 110 private final BleRssiRangingParams mBleRssiRangingParams; 111 112 RawRangingDevice(Builder builder)113 private RawRangingDevice(Builder builder) { 114 mRangingDevice = builder.mRangingDevice; 115 mUwbRangingParams = builder.mUwbRangingParams; 116 mBleCsRangingParams = builder.mBleCsRangingParams; 117 mRttRangingParams = builder.mRttRangingParams; 118 mBleRssiRangingParams = builder.mBleRssiRangingParams; 119 } 120 121 RawRangingDevice(Parcel in)122 private RawRangingDevice(Parcel in) { 123 mRangingDevice = in.readParcelable(RangingDevice.class.getClassLoader(), RangingDevice.class 124 ); 125 mUwbRangingParams = in.readParcelable(UwbRangingParams.class.getClassLoader(), 126 UwbRangingParams.class); 127 mBleCsRangingParams = in.readParcelable(BleCsRangingParams.class.getClassLoader(), 128 BleCsRangingParams.class 129 ); 130 mRttRangingParams = in.readParcelable(RttRangingParams.class.getClassLoader(), 131 RttRangingParams.class); 132 mBleRssiRangingParams = in.readParcelable(BleRssiRangingParams.class.getClassLoader(), 133 BleRssiRangingParams.class); 134 } 135 136 @Override writeToParcel(@onNull Parcel dest, int flags)137 public void writeToParcel(@NonNull Parcel dest, int flags) { 138 dest.writeParcelable(mRangingDevice, flags); 139 dest.writeParcelable(mUwbRangingParams, flags); 140 dest.writeParcelable(mBleCsRangingParams, flags); 141 dest.writeParcelable(mRttRangingParams, flags); 142 dest.writeParcelable(mBleRssiRangingParams, flags); 143 } 144 145 @NonNull 146 public static final Creator<RawRangingDevice> CREATOR = new Creator<RawRangingDevice>() { 147 @Override 148 public RawRangingDevice createFromParcel(Parcel in) { 149 return new RawRangingDevice(in); 150 } 151 152 @Override 153 public RawRangingDevice[] newArray(int size) { 154 return new RawRangingDevice[size]; 155 } 156 }; 157 158 /** 159 * Returns the {@link RangingDevice} associated with this instance. 160 * 161 * @return the ranging device. 162 */ 163 @NonNull getRangingDevice()164 public RangingDevice getRangingDevice() { 165 return mRangingDevice; 166 } 167 168 /** 169 * Returns the UWB ranging parameters, if applicable. 170 * 171 * @return the {@link UwbRangingParams}, or {@code null} if not set. 172 */ 173 @Nullable getUwbRangingParams()174 public UwbRangingParams getUwbRangingParams() { 175 return mUwbRangingParams; 176 } 177 178 /** 179 * Returns the CS ranging parameters, if applicable. 180 * 181 * @return the {@link BleCsRangingParams}, or {@code null} if not set. 182 */ 183 @Nullable getCsRangingParams()184 public BleCsRangingParams getCsRangingParams() { 185 return mBleCsRangingParams; 186 } 187 188 /** 189 * Returns the RTT ranging parameters, if applicable. 190 * 191 * @return the {@link RttRangingParams}, or {@code null} if not set. 192 */ 193 @Nullable getRttRangingParams()194 public RttRangingParams getRttRangingParams() { 195 return mRttRangingParams; 196 } 197 198 /** 199 * Returns the BLE rssi ranging parameters, if applicable. 200 * 201 * @return the {@link BleRssiRangingParams}, or {@code null} if not set. 202 */ 203 @Nullable getBleRssiRangingParams()204 public BleRssiRangingParams getBleRssiRangingParams() { 205 return mBleRssiRangingParams; 206 } 207 208 @Override describeContents()209 public int describeContents() { 210 return 0; 211 } 212 213 /** 214 * Builder class for creating instances of {@link RawRangingDevice}. 215 */ 216 public static final class Builder { 217 private RangingDevice mRangingDevice; 218 private UwbRangingParams mUwbRangingParams; 219 private BleCsRangingParams mBleCsRangingParams; 220 private RttRangingParams mRttRangingParams; 221 private BleRssiRangingParams mBleRssiRangingParams; 222 223 /** 224 * Sets the ranging device. 225 * 226 * @param rangingDevice the {@link RangingDevice} to be set. 227 * @return this {@link Builder} instance for chaining calls. 228 */ 229 @NonNull setRangingDevice(@onNull RangingDevice rangingDevice)230 public Builder setRangingDevice(@NonNull RangingDevice rangingDevice) { 231 Objects.requireNonNull(rangingDevice); 232 mRangingDevice = rangingDevice; 233 return this; 234 } 235 236 /** 237 * Sets the UWB ranging parameters. 238 * 239 * @param params the {@link UwbRangingParams} to be set. 240 * @return this {@link Builder} instance for chaining calls. 241 */ 242 @NonNull setUwbRangingParams(@onNull UwbRangingParams params)243 public Builder setUwbRangingParams(@NonNull UwbRangingParams params) { 244 Objects.requireNonNull(params); 245 mUwbRangingParams = params; 246 return this; 247 } 248 249 /** 250 * Sets the WiFi NAN-RTT ranging parameters. 251 * 252 * @param params the {@link RttRangingParams} to be set. 253 * @return this {@link Builder} instance for chaining calls. 254 */ 255 @NonNull setRttRangingParams(@onNull RttRangingParams params)256 public Builder setRttRangingParams(@NonNull RttRangingParams params) { 257 Objects.requireNonNull(params); 258 mRttRangingParams = params; 259 return this; 260 } 261 262 /** 263 * Sets the BLE channel sounding ranging parameters. 264 * 265 * @param params the {@link BleCsRangingParams} to be set. 266 * @return this {@link Builder} instance for chaining calls. 267 */ 268 @NonNull setCsRangingParams(@onNull BleCsRangingParams params)269 public Builder setCsRangingParams(@NonNull BleCsRangingParams params) { 270 Objects.requireNonNull(params); 271 mBleCsRangingParams = params; 272 return this; 273 } 274 275 /** 276 * Sets the BLE rssi ranging parameters. 277 * 278 * @param params the {@link BleCsRangingParams} to be set. 279 * @return this {@link Builder} instance for chaining calls. 280 */ 281 @NonNull setBleRssiRangingParams(@onNull BleRssiRangingParams params)282 public Builder setBleRssiRangingParams(@NonNull BleRssiRangingParams params) { 283 Objects.requireNonNull(params); 284 mBleRssiRangingParams = params; 285 return this; 286 } 287 288 /** 289 * Builds and returns a new {@link RawRangingDevice} instance. 290 * 291 * @return a new {@link RawRangingDevice} configured with the specified parameters. 292 */ 293 @NonNull build()294 public RawRangingDevice build() { 295 Objects.requireNonNull(this.mRangingDevice); 296 if (Stream.of(mUwbRangingParams, mBleCsRangingParams, mBleRssiRangingParams, 297 mRttRangingParams) 298 .allMatch(Objects::isNull)) { 299 throw new IllegalArgumentException( 300 "At least one ranging params should be configured"); 301 } 302 return new RawRangingDevice(this); 303 } 304 } 305 306 @Override toString()307 public String toString() { 308 return "RawRangingDevice{ " 309 + "mRangingDevice=" 310 + mRangingDevice 311 + ", mUwbRangingParams=" 312 + mUwbRangingParams 313 + ", mBleCsRangingParams=" 314 + mBleCsRangingParams 315 + ", mRttRangingParams=" 316 + mRttRangingParams 317 + ", mBleRssiRangingParams=" 318 + mBleRssiRangingParams 319 + " }"; 320 } 321 } 322