1 /*
2  * Copyright 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.bluetooth.le;
18 
19 import android.annotation.FlaggedApi;
20 import android.annotation.IntDef;
21 import android.annotation.NonNull;
22 import android.annotation.SystemApi;
23 import android.os.Parcel;
24 import android.os.Parcelable;
25 
26 import com.android.bluetooth.flags.Flags;
27 
28 import java.lang.annotation.Retention;
29 import java.lang.annotation.RetentionPolicy;
30 
31 /**
32  * The {@link ChannelSoundingParams} provide a way to adjust distance measurement preferences for
33  * {@link DISTANCE_MEASUREMENT_METHOD_CHANNEL_SOUNDING}. Use {@link ChannelSoundingParams.Builder}
34  * to create an instance of this class.
35  *
36  * @hide
37  */
38 @FlaggedApi(Flags.FLAG_CHANNEL_SOUNDING)
39 @SystemApi
40 public final class ChannelSoundingParams implements Parcelable {
41 
42     /** @hide */
43     @Retention(RetentionPolicy.SOURCE)
44     @IntDef(
45             value = {
46                 SIGHT_TYPE_UNKNOWN,
47                 SIGHT_TYPE_LINE_OF_SIGHT,
48                 SIGHT_TYPE_NON_LINE_OF_SIGHT,
49             })
50     @interface SightType {}
51 
52     /** @hide */
53     @Retention(RetentionPolicy.SOURCE)
54     @IntDef(value = {LOCATION_TYPE_UNKNOWN, LOCATION_TYPE_INDOOR, LOCATION_TYPE_OUTDOOR})
55     @interface LocationType {}
56 
57     /** @hide */
58     @Retention(RetentionPolicy.SOURCE)
59     @IntDef(
60             value = {
61                 CS_SECURITY_LEVEL_UNKNOWN,
62                 CS_SECURITY_LEVEL_ONE,
63                 CS_SECURITY_LEVEL_TWO,
64                 CS_SECURITY_LEVEL_THREE,
65                 CS_SECURITY_LEVEL_FOUR
66             })
67     @interface CsSecurityLevel {}
68 
69     /**
70      * Sight type is unknown.
71      *
72      * @hide
73      */
74     @SystemApi public static final int SIGHT_TYPE_UNKNOWN = 0;
75 
76     /**
77      * Remote device is in line of sight.
78      *
79      * @hide
80      */
81     @SystemApi public static final int SIGHT_TYPE_LINE_OF_SIGHT = 1;
82 
83     /**
84      * Remote device is not in line of sight.
85      *
86      * @hide
87      */
88     @SystemApi public static final int SIGHT_TYPE_NON_LINE_OF_SIGHT = 2;
89 
90     /**
91      * Location type is unknown.
92      *
93      * @hide
94      */
95     @SystemApi public static final int LOCATION_TYPE_UNKNOWN = 0;
96 
97     /**
98      * The location of the usecase is indoor.
99      *
100      * @hide
101      */
102     @SystemApi public static final int LOCATION_TYPE_INDOOR = 1;
103 
104     /**
105      * The location of the usecase is outdoor.
106      *
107      * @hide
108      */
109     @SystemApi public static final int LOCATION_TYPE_OUTDOOR = 2;
110 
111     /**
112      * Return value for {@link
113      * DistanceMeasurementManager#getChannelSoundingMaxSupportedSecurityLevel(BluetoothDevice)} and
114      * {@link DistanceMeasurementManager#getLocalChannelSoundingMaxSupportedSecurityLevel()} when
115      * Channel Sounding is not supported, or encounters an internal error.
116      *
117      * @hide
118      */
119     @SystemApi public static final int CS_SECURITY_LEVEL_UNKNOWN = 0;
120 
121     /**
122      * Either CS tone or CS RTT.
123      *
124      * @hide
125      */
126     @SystemApi public static final int CS_SECURITY_LEVEL_ONE = 1;
127 
128     /**
129      * 150 ns CS RTT accuracy and CS tones.
130      *
131      * @hide
132      */
133     @SystemApi public static final int CS_SECURITY_LEVEL_TWO = 2;
134 
135     /**
136      * 10 ns CS RTT accuracy and CS tones.
137      *
138      * @hide
139      */
140     @SystemApi public static final int CS_SECURITY_LEVEL_THREE = 3;
141 
142     /**
143      * Level 3 with the addition of CS RTT sounding sequence or random sequence payloads, and
144      * support of the Normalized Attack Detector Metric requirements.
145      *
146      * @hide
147      */
148     @SystemApi public static final int CS_SECURITY_LEVEL_FOUR = 4;
149 
150     private int mSightType;
151     private int mLocationType;
152     private int mCsSecurityLevel;
153 
154     /** @hide */
ChannelSoundingParams(int sightType, int locationType, int csSecurityLevel)155     public ChannelSoundingParams(int sightType, int locationType, int csSecurityLevel) {
156         mSightType = sightType;
157         mLocationType = locationType;
158         mCsSecurityLevel = csSecurityLevel;
159     }
160 
161     /**
162      * Returns sight type of this ChannelSoundingParams.
163      *
164      * @hide
165      */
166     @SystemApi
167     @SightType
getSightType()168     public int getSightType() {
169         return mSightType;
170     }
171 
172     /**
173      * Returns location type of this ChannelSoundingParams.
174      *
175      * @hide
176      */
177     @SystemApi
178     @LocationType
getLocationType()179     public int getLocationType() {
180         return mLocationType;
181     }
182 
183     /**
184      * Returns CS security level of this ChannelSoundingParams.
185      *
186      * @hide
187      */
188     @SystemApi
189     @CsSecurityLevel
getCsSecurityLevel()190     public int getCsSecurityLevel() {
191         return mCsSecurityLevel;
192     }
193 
194     /**
195      * {@inheritDoc}
196      *
197      * @hide
198      */
199     @Override
describeContents()200     public int describeContents() {
201         return 0;
202     }
203 
204     /**
205      * {@inheritDoc}
206      *
207      * @hide
208      */
209     @Override
writeToParcel(@onNull Parcel out, int flags)210     public void writeToParcel(@NonNull Parcel out, int flags) {
211         out.writeInt(mSightType);
212         out.writeInt(mLocationType);
213         out.writeInt(mCsSecurityLevel);
214     }
215 
216     /** A {@link Parcelable.Creator} to create {@link ChannelSoundingParams} from parcel. */
217     public static final @NonNull Parcelable.Creator<ChannelSoundingParams> CREATOR =
218             new Parcelable.Creator<ChannelSoundingParams>() {
219                 @Override
220                 public @NonNull ChannelSoundingParams createFromParcel(@NonNull Parcel in) {
221                     Builder builder = new Builder();
222                     builder.setSightType(in.readInt());
223                     builder.setLocationType(in.readInt());
224                     builder.setCsSecurityLevel(in.readInt());
225                     return builder.build();
226                 }
227 
228                 @Override
229                 public @NonNull ChannelSoundingParams[] newArray(int size) {
230                     return new ChannelSoundingParams[size];
231                 }
232             };
233 
234     /**
235      * Builder for {@link ChannelSoundingParams}.
236      *
237      * @hide
238      */
239     @SystemApi
240     public static final class Builder {
241         private int mSightType = SIGHT_TYPE_UNKNOWN;
242         private int mLocationType = LOCATION_TYPE_UNKNOWN;
243         private int mCsSecurityLevel = CS_SECURITY_LEVEL_ONE;
244 
245         /**
246          * Set sight type for the ChannelSoundingParams.
247          *
248          * @param sightType sight type of this ChannelSoundingParams
249          * @return the same Builder instance
250          * @hide
251          */
252         @SystemApi
setSightType(@ightType int sightType)253         public @NonNull Builder setSightType(@SightType int sightType) {
254             switch (sightType) {
255                 case SIGHT_TYPE_UNKNOWN:
256                 case SIGHT_TYPE_LINE_OF_SIGHT:
257                 case SIGHT_TYPE_NON_LINE_OF_SIGHT:
258                     mSightType = sightType;
259                     break;
260                 default:
261                     throw new IllegalArgumentException("unknown sight type " + sightType);
262             }
263             return this;
264         }
265 
266         /**
267          * Set location type for the ChannelSoundingParams.
268          *
269          * @param locationType location type of this ChannelSoundingParams
270          * @return the same Builder instance
271          * @hide
272          */
273         @SystemApi
setLocationType(@ocationType int locationType)274         public @NonNull Builder setLocationType(@LocationType int locationType) {
275             switch (locationType) {
276                 case LOCATION_TYPE_UNKNOWN:
277                 case LOCATION_TYPE_INDOOR:
278                 case LOCATION_TYPE_OUTDOOR:
279                     mLocationType = locationType;
280                     break;
281                 default:
282                     throw new IllegalArgumentException("unknown location type " + locationType);
283             }
284             return this;
285         }
286 
287         /**
288          * Set CS security level for the ChannelSoundingParams.
289          *
290          * <p>See: https://bluetooth.com/specifications/specs/channel-sounding-cr-pr/
291          *
292          * @param csSecurityLevel cs security level of this ChannelSoundingParams
293          * @return the same Builder instance
294          * @hide
295          */
296         @SystemApi
setCsSecurityLevel(@sSecurityLevel int csSecurityLevel)297         public @NonNull Builder setCsSecurityLevel(@CsSecurityLevel int csSecurityLevel) {
298             switch (csSecurityLevel) {
299                 case CS_SECURITY_LEVEL_ONE:
300                 case CS_SECURITY_LEVEL_TWO:
301                 case CS_SECURITY_LEVEL_THREE:
302                 case CS_SECURITY_LEVEL_FOUR:
303                     mCsSecurityLevel = csSecurityLevel;
304                     break;
305                 default:
306                     throw new IllegalArgumentException(
307                             "unknown CS security level " + csSecurityLevel);
308             }
309             return this;
310         }
311 
312         /**
313          * Build the {@link ChannelSoundingParams} object.
314          *
315          * @hide
316          */
317         @SystemApi
build()318         public @NonNull ChannelSoundingParams build() {
319             return new ChannelSoundingParams(mSightType, mLocationType, mCsSecurityLevel);
320         }
321     }
322 }
323