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.uwb; 18 19 import android.annotation.FlaggedApi; 20 import android.annotation.IntDef; 21 import android.annotation.NonNull; 22 import android.os.Parcel; 23 import android.os.Parcelable; 24 25 import com.android.ranging.flags.Flags; 26 27 import java.lang.annotation.ElementType; 28 import java.lang.annotation.Retention; 29 import java.lang.annotation.RetentionPolicy; 30 import java.lang.annotation.Target; 31 import java.util.Objects; 32 import java.util.Random; 33 34 /** 35 * A Class representing the complex channel for UWB which comprises channel and preamble index 36 * negotiated between peer devices out of band before ranging. 37 * 38 * <p> PRF (Pulse Repetition Frequency) supported: 39 * <ul> 40 * <li> BPRF - Base Pulse Repetition Frequency.</li> 41 * <li> HPRF - Higher Pulse Repetition Frequency.</li> 42 * </ul> 43 * 44 * See <a href="https://groups.firaconsortium.org/wg/members/document/1949> FiRa UCI Spec.</a> 45 */ 46 @FlaggedApi(Flags.FLAG_RANGING_STACK_ENABLED) 47 public final class UwbComplexChannel implements Parcelable { 48 49 /** 50 * UWB Channel selections 51 * 52 * @hide 53 */ 54 @Retention(RetentionPolicy.SOURCE) 55 @Target({ElementType.TYPE_USE}) 56 @IntDef( 57 value = { 58 UWB_CHANNEL_5, 59 UWB_CHANNEL_6, 60 UWB_CHANNEL_8, 61 UWB_CHANNEL_9, 62 UWB_CHANNEL_10, 63 UWB_CHANNEL_12, 64 UWB_CHANNEL_13, 65 UWB_CHANNEL_14, 66 }) 67 public @interface UwbChannel { 68 } 69 70 /** UWB channel 5 */ 71 public static final int UWB_CHANNEL_5 = 5; 72 /** UWB channel 6 */ 73 public static final int UWB_CHANNEL_6 = 6; 74 /** UWB channel 8 */ 75 public static final int UWB_CHANNEL_8 = 8; 76 /** UWB channel 9 */ 77 public static final int UWB_CHANNEL_9 = 9; 78 /** UWB channel 10 */ 79 public static final int UWB_CHANNEL_10 = 10; 80 /** UWB channel 12 */ 81 public static final int UWB_CHANNEL_12 = 12; 82 /** UWB channel 13 */ 83 public static final int UWB_CHANNEL_13 = 13; 84 /** UWB channel 14 */ 85 public static final int UWB_CHANNEL_14 = 14; 86 87 /** 88 * UWB preamble selections 89 * 90 * @hide 91 */ 92 @Retention(RetentionPolicy.SOURCE) 93 @Target({ElementType.TYPE_USE}) 94 @IntDef( 95 value = { 96 UWB_PREAMBLE_CODE_INDEX_9, 97 UWB_PREAMBLE_CODE_INDEX_10, 98 UWB_PREAMBLE_CODE_INDEX_11, 99 UWB_PREAMBLE_CODE_INDEX_12, 100 UWB_PREAMBLE_CODE_INDEX_25, 101 UWB_PREAMBLE_CODE_INDEX_26, 102 UWB_PREAMBLE_CODE_INDEX_27, 103 UWB_PREAMBLE_CODE_INDEX_28, 104 UWB_PREAMBLE_CODE_INDEX_29, 105 UWB_PREAMBLE_CODE_INDEX_30, 106 UWB_PREAMBLE_CODE_INDEX_31, 107 UWB_PREAMBLE_CODE_INDEX_32, 108 }) 109 public @interface UwbPreambleCodeIndex { 110 } 111 112 /** UWB preamble code index 9 (PRF mode - BPRF). */ 113 public static final int UWB_PREAMBLE_CODE_INDEX_9 = 9; 114 /** UWB preamble code index 10 (PRF mode - BPRF). */ 115 public static final int UWB_PREAMBLE_CODE_INDEX_10 = 10; 116 /** UWB preamble code index 11 (PRF mode - BPRF). */ 117 public static final int UWB_PREAMBLE_CODE_INDEX_11 = 11; 118 /** UWB preamble code index 12 (PRF mode - BPRF). */ 119 public static final int UWB_PREAMBLE_CODE_INDEX_12 = 12; 120 /** UWB preamble code index 25 (PRF mode - HPRF). */ 121 public static final int UWB_PREAMBLE_CODE_INDEX_25 = 25; 122 /** UWB preamble code index 26 (PRF mode - HPRF). */ 123 public static final int UWB_PREAMBLE_CODE_INDEX_26 = 26; 124 /** UWB preamble code index 27 (PRF mode - HPRF). */ 125 public static final int UWB_PREAMBLE_CODE_INDEX_27 = 27; 126 /** UWB preamble code index 28 (PRF mode - HPRF). */ 127 public static final int UWB_PREAMBLE_CODE_INDEX_28 = 28; 128 /** UWB preamble code index 29 (PRF mode - HPRF). */ 129 public static final int UWB_PREAMBLE_CODE_INDEX_29 = 29; 130 /** UWB preamble code index 30 (PRF mode - HPRF). */ 131 public static final int UWB_PREAMBLE_CODE_INDEX_30 = 30; 132 /** UWB preamble code index 31 (PRF mode - HPRF). */ 133 public static final int UWB_PREAMBLE_CODE_INDEX_31 = 31; 134 /** UWB preamble code index 32 (PRF mode - HPRF). */ 135 public static final int UWB_PREAMBLE_CODE_INDEX_32 = 32; 136 137 private static final int[] PREAMBLE_INDEXES_BPRF = 138 new int[]{UWB_PREAMBLE_CODE_INDEX_9, 139 UWB_PREAMBLE_CODE_INDEX_10, 140 UWB_PREAMBLE_CODE_INDEX_11, 141 UWB_PREAMBLE_CODE_INDEX_12}; 142 @UwbChannel 143 private final int mChannel; 144 @UwbPreambleCodeIndex 145 private final int mPreambleIndex; 146 UwbComplexChannel(Builder builder)147 private UwbComplexChannel(Builder builder) { 148 mChannel = builder.mChannel; 149 mPreambleIndex = builder.mPreambleIndex; 150 } 151 UwbComplexChannel(@onNull Parcel in)152 private UwbComplexChannel(@NonNull Parcel in) { 153 mChannel = in.readInt(); 154 mPreambleIndex = in.readInt(); 155 } 156 157 @NonNull 158 public static final Creator<UwbComplexChannel> CREATOR = new Creator<UwbComplexChannel>() { 159 @Override 160 public UwbComplexChannel createFromParcel(Parcel in) { 161 return new UwbComplexChannel(in); 162 } 163 164 @Override 165 public UwbComplexChannel[] newArray(int size) { 166 return new UwbComplexChannel[size]; 167 } 168 }; 169 170 /** 171 * Gets the UWB channel associated with this configuration. 172 * 173 * @return The channel number, which is one of the predefined UWB channels: 174 */ 175 @UwbChannel getChannel()176 public int getChannel() { 177 return mChannel; 178 } 179 180 /** 181 * Gets the UWB preamble index associated with this configuration. 182 * 183 * @return The preamble index, which is one of the predefined UWB preamble indices: 184 * 185 * See <a href="https://groups.firaconsortium.org/wg/members/document/1949> FiRa UCI Spec.</a> 186 */ 187 188 @UwbPreambleCodeIndex getPreambleIndex()189 public int getPreambleIndex() { 190 return mPreambleIndex; 191 } 192 193 @Override describeContents()194 public int describeContents() { 195 return 0; 196 } 197 198 @Override writeToParcel(@onNull Parcel dest, int flags)199 public void writeToParcel(@NonNull Parcel dest, int flags) { 200 dest.writeInt(mChannel); 201 dest.writeInt(mPreambleIndex); 202 } 203 204 @Override equals(Object o)205 public boolean equals(Object o) { 206 if (this == o) return true; 207 if (!(o instanceof UwbComplexChannel other)) return false; 208 return mChannel == other.mChannel && mPreambleIndex == other.mPreambleIndex; 209 } 210 211 @Override hashCode()212 public int hashCode() { 213 return Objects.hash(mChannel, mPreambleIndex); 214 } 215 216 /** 217 * Builder for creating instances of {@link UwbComplexChannel}. 218 */ 219 public static final class Builder { 220 @UwbChannel 221 private int mChannel = UWB_CHANNEL_5; 222 @UwbPreambleCodeIndex 223 private int mPreambleIndex = PREAMBLE_INDEXES_BPRF[new Random().nextInt( 224 PREAMBLE_INDEXES_BPRF.length)]; 225 226 /** 227 * Sets the channel for the ranging device. 228 * <p> Defaults to {@link #UWB_CHANNEL_5} 229 * 230 * @param channel The channel number to be set. 231 * @return This {@link Builder} instance. 232 */ 233 @NonNull setChannel(@wbChannel int channel)234 public Builder setChannel(@UwbChannel int channel) { 235 mChannel = channel; 236 return this; 237 } 238 239 /** 240 * Sets the preamble index for the ranging device as defined in 241 * See <a href="https://groups.firaconsortium.org/wg/members/document/1949> FiRa UCI 242 * Spec.</a>} 243 * <p> PRF (Pulse Repetition Frequency) is selected based on the preamble index set here. 244 * 245 * <p> Defaults to a random BPRF preamble index. 246 * One among {@link #UWB_PREAMBLE_CODE_INDEX_9}, {@link #UWB_PREAMBLE_CODE_INDEX_10}, 247 * {@link #UWB_PREAMBLE_CODE_INDEX_11} or {@link #UWB_PREAMBLE_CODE_INDEX_12}. 248 * For better performance always use a random preamble index for each ranging session. 249 * 250 * @param preambleIndex The preamble index to be set. 251 * @return This {@link Builder} instance. 252 */ 253 @NonNull setPreambleIndex(@wbPreambleCodeIndex int preambleIndex)254 public Builder setPreambleIndex(@UwbPreambleCodeIndex int preambleIndex) { 255 mPreambleIndex = preambleIndex; 256 return this; 257 } 258 259 /** 260 * Builds and returns a new instance of {@link UwbComplexChannel}. 261 * 262 * @return A new {@link UwbComplexChannel} instance. 263 */ 264 @NonNull build()265 public UwbComplexChannel build() { 266 return new UwbComplexChannel(this); 267 } 268 } 269 270 @Override toString()271 public String toString() { 272 return "UwbComplexChannel{ mChannel=" 273 + mChannel 274 + ", mPreambleIndex=" 275 + mPreambleIndex 276 + " }"; 277 } 278 } 279