329 lines
11 KiB
Java
329 lines
11 KiB
Java
|
/*
|
||
|
|
* Copyright 2022 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.bluetooth.le;
|
||
|
|
|
||
|
|
import android.annotation.FlaggedApi;
|
||
|
|
import android.annotation.IntDef;
|
||
|
|
import android.annotation.IntRange;
|
||
|
|
import android.annotation.NonNull;
|
||
|
|
import android.annotation.Nullable;
|
||
|
|
import android.annotation.SystemApi;
|
||
|
|
import android.bluetooth.BluetoothDevice;
|
||
|
|
import android.bluetooth.le.DistanceMeasurementMethod.DistanceMeasurementMethodId;
|
||
|
|
import android.os.Parcel;
|
||
|
|
import android.os.Parcelable;
|
||
|
|
|
||
|
|
import com.android.bluetooth.flags.Flags;
|
||
|
|
|
||
|
|
import java.lang.annotation.Retention;
|
||
|
|
import java.lang.annotation.RetentionPolicy;
|
||
|
|
import java.util.Objects;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The {@link DistanceMeasurementParams} provide a way to adjust distance measurement preferences.
|
||
|
|
* Use {@link DistanceMeasurementParams.Builder} to create an instance of this class.
|
||
|
|
*
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@SystemApi
|
||
|
|
public final class DistanceMeasurementParams implements Parcelable {
|
||
|
|
|
||
|
|
/** @hide */
|
||
|
|
@Retention(RetentionPolicy.SOURCE)
|
||
|
|
@IntDef(value = {REPORT_FREQUENCY_LOW, REPORT_FREQUENCY_MEDIUM, REPORT_FREQUENCY_HIGH})
|
||
|
|
@interface ReportFrequency {}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Perform distance measurement in low frequency. This is the default frequency as it consumes
|
||
|
|
* the least power.
|
||
|
|
*
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@SystemApi public static final int REPORT_FREQUENCY_LOW = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Perform distance measurement in medium frequency. Provides a good trade-off between report
|
||
|
|
* frequency and power consumption.
|
||
|
|
*
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@SystemApi public static final int REPORT_FREQUENCY_MEDIUM = 1;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Perform distance measurement in high frequency. It's recommended to only use this mode when
|
||
|
|
* the application is running in the foreground.
|
||
|
|
*
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@SystemApi public static final int REPORT_FREQUENCY_HIGH = 2;
|
||
|
|
|
||
|
|
private static final int REPORT_DURATION_DEFAULT = 60;
|
||
|
|
private static final int REPORT_DURATION_MAX = 3600;
|
||
|
|
|
||
|
|
private BluetoothDevice mDevice = null;
|
||
|
|
private int mDuration;
|
||
|
|
private int mFrequency;
|
||
|
|
private int mMethodId;
|
||
|
|
private ChannelSoundingParams mChannelSoundingParams = null;
|
||
|
|
|
||
|
|
/** @hide */
|
||
|
|
public DistanceMeasurementParams(
|
||
|
|
BluetoothDevice device,
|
||
|
|
int duration,
|
||
|
|
int frequency,
|
||
|
|
int methodId,
|
||
|
|
ChannelSoundingParams channelSoundingParams) {
|
||
|
|
mDevice = Objects.requireNonNull(device);
|
||
|
|
mDuration = duration;
|
||
|
|
mFrequency = frequency;
|
||
|
|
mMethodId = methodId;
|
||
|
|
mChannelSoundingParams = channelSoundingParams;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns device of this DistanceMeasurementParams.
|
||
|
|
*
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@SystemApi
|
||
|
|
public @NonNull BluetoothDevice getDevice() {
|
||
|
|
return mDevice;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns duration in seconds of this DistanceMeasurementParams. Once the distance measurement
|
||
|
|
* successfully started, the Bluetooth process will keep reporting the measurement result until
|
||
|
|
* this time has been reached or the session is explicitly stopped with {@link
|
||
|
|
* DistanceMeasurementSession#stopSession}
|
||
|
|
*
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@SystemApi
|
||
|
|
public @IntRange(from = 0) int getDurationSeconds() {
|
||
|
|
return mDuration;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns frequency of this DistanceMeasurementParams. The Bluetooth process uses this value to
|
||
|
|
* determine report frequency of the measurement result.
|
||
|
|
*
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@SystemApi
|
||
|
|
public @ReportFrequency int getFrequency() {
|
||
|
|
return mFrequency;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns method id of this DistanceMeasurementParams.
|
||
|
|
*
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@SystemApi
|
||
|
|
public @DistanceMeasurementMethodId int getMethodId() {
|
||
|
|
return mMethodId;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns {@link ChannelSoundingParams} of this DistanceMeasurementParams.
|
||
|
|
*
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@FlaggedApi(Flags.FLAG_CHANNEL_SOUNDING)
|
||
|
|
@SystemApi
|
||
|
|
public @Nullable ChannelSoundingParams getChannelSoundingParams() {
|
||
|
|
return mChannelSoundingParams;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Get the default duration in seconds of the parameter.
|
||
|
|
*
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@SystemApi
|
||
|
|
public static int getDefaultDurationSeconds() {
|
||
|
|
return REPORT_DURATION_DEFAULT;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Get the maximum duration in seconds that can be set for the parameter.
|
||
|
|
*
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@SystemApi
|
||
|
|
public static int getMaxDurationSeconds() {
|
||
|
|
return REPORT_DURATION_MAX;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* {@inheritDoc}
|
||
|
|
*
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@Override
|
||
|
|
public int describeContents() {
|
||
|
|
return 0;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* {@inheritDoc}
|
||
|
|
*
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@Override
|
||
|
|
public void writeToParcel(Parcel out, int flags) {
|
||
|
|
out.writeParcelable(mDevice, 0);
|
||
|
|
out.writeInt(mDuration);
|
||
|
|
out.writeInt(mFrequency);
|
||
|
|
out.writeInt(mMethodId);
|
||
|
|
out.writeParcelable(mChannelSoundingParams, 0);
|
||
|
|
}
|
||
|
|
|
||
|
|
/** A {@link Parcelable.Creator} to create {@link DistanceMeasurementParams} from parcel. */
|
||
|
|
public static final @NonNull Parcelable.Creator<DistanceMeasurementParams> CREATOR =
|
||
|
|
new Parcelable.Creator<DistanceMeasurementParams>() {
|
||
|
|
@Override
|
||
|
|
public @NonNull DistanceMeasurementParams createFromParcel(@NonNull Parcel in) {
|
||
|
|
Builder builder = new Builder((BluetoothDevice) in.readParcelable(null));
|
||
|
|
builder.setDurationSeconds(in.readInt());
|
||
|
|
builder.setFrequency(in.readInt());
|
||
|
|
builder.setMethodId(in.readInt());
|
||
|
|
builder.setChannelSoundingParams(
|
||
|
|
(ChannelSoundingParams) in.readParcelable(null));
|
||
|
|
return builder.build();
|
||
|
|
}
|
||
|
|
|
||
|
|
@Override
|
||
|
|
public @NonNull DistanceMeasurementParams[] newArray(int size) {
|
||
|
|
return new DistanceMeasurementParams[size];
|
||
|
|
}
|
||
|
|
};
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Builder for {@link DistanceMeasurementParams}.
|
||
|
|
*
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@SystemApi
|
||
|
|
public static final class Builder {
|
||
|
|
private BluetoothDevice mDevice = null;
|
||
|
|
private int mDuration = REPORT_DURATION_DEFAULT;
|
||
|
|
private int mFrequency = REPORT_FREQUENCY_LOW;
|
||
|
|
private int mMethodId = DistanceMeasurementMethod.DISTANCE_MEASUREMENT_METHOD_RSSI;
|
||
|
|
private ChannelSoundingParams mChannelSoundingParams = null;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Constructor of the Builder.
|
||
|
|
*
|
||
|
|
* @param device the remote device for the distance measurement
|
||
|
|
*/
|
||
|
|
public Builder(@NonNull BluetoothDevice device) {
|
||
|
|
mDevice = Objects.requireNonNull(device);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Set duration in seconds for the DistanceMeasurementParams. Once the distance measurement
|
||
|
|
* successfully started, the Bluetooth process will keep reporting the measurement result
|
||
|
|
* until this time has been reached or the session is explicitly stopped with {@link
|
||
|
|
* DistanceMeasurementSession#stopSession}.
|
||
|
|
*
|
||
|
|
* @param duration duration in seconds of this DistanceMeasurementParams
|
||
|
|
* @return the same Builder instance
|
||
|
|
* @throws IllegalArgumentException if duration greater than {@link
|
||
|
|
* DistanceMeasurementParams#getMaxDurationSeconds()} or less than zero.
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@SystemApi
|
||
|
|
public @NonNull Builder setDurationSeconds(@IntRange(from = 0) int duration) {
|
||
|
|
if (duration < 0 || duration > getMaxDurationSeconds()) {
|
||
|
|
throw new IllegalArgumentException("illegal duration " + duration);
|
||
|
|
}
|
||
|
|
mDuration = duration;
|
||
|
|
return this;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Set frequency for the DistanceMeasurementParams. The Bluetooth process uses this value to
|
||
|
|
* determine report frequency of the measurement result.
|
||
|
|
*
|
||
|
|
* @param frequency frequency of this DistanceMeasurementParams
|
||
|
|
* @return the same Builder instance
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@SystemApi
|
||
|
|
public @NonNull Builder setFrequency(@ReportFrequency int frequency) {
|
||
|
|
switch (frequency) {
|
||
|
|
case REPORT_FREQUENCY_LOW:
|
||
|
|
case REPORT_FREQUENCY_MEDIUM:
|
||
|
|
case REPORT_FREQUENCY_HIGH:
|
||
|
|
mFrequency = frequency;
|
||
|
|
break;
|
||
|
|
default:
|
||
|
|
throw new IllegalArgumentException("unknown frequency " + frequency);
|
||
|
|
}
|
||
|
|
return this;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Set method id for the DistanceMeasurementParams.
|
||
|
|
*
|
||
|
|
* @param methodId method id of this DistanceMeasurementParams
|
||
|
|
* @return the same Builder instance
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@SystemApi
|
||
|
|
public @NonNull Builder setMethodId(@DistanceMeasurementMethodId int methodId) {
|
||
|
|
switch (methodId) {
|
||
|
|
case DistanceMeasurementMethod.DISTANCE_MEASUREMENT_METHOD_AUTO:
|
||
|
|
case DistanceMeasurementMethod.DISTANCE_MEASUREMENT_METHOD_RSSI:
|
||
|
|
case DistanceMeasurementMethod.DISTANCE_MEASUREMENT_METHOD_CHANNEL_SOUNDING:
|
||
|
|
mMethodId = methodId;
|
||
|
|
break;
|
||
|
|
default:
|
||
|
|
throw new IllegalArgumentException("unknown method id " + methodId);
|
||
|
|
}
|
||
|
|
return this;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Set {@link ChannelSoundingParams} for the DistanceMeasurementParams.
|
||
|
|
*
|
||
|
|
* @param channelSoundingParams parameters for Channel Sounding
|
||
|
|
* @return the same Builder instance
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@FlaggedApi(Flags.FLAG_CHANNEL_SOUNDING)
|
||
|
|
@SystemApi
|
||
|
|
public @NonNull Builder setChannelSoundingParams(
|
||
|
|
@NonNull ChannelSoundingParams channelSoundingParams) {
|
||
|
|
mChannelSoundingParams = channelSoundingParams;
|
||
|
|
return this;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Build the {@link DistanceMeasurementParams} object.
|
||
|
|
*
|
||
|
|
* @hide
|
||
|
|
*/
|
||
|
|
@SystemApi
|
||
|
|
public @NonNull DistanceMeasurementParams build() {
|
||
|
|
return new DistanceMeasurementParams(
|
||
|
|
mDevice, mDuration, mFrequency, mMethodId, mChannelSoundingParams);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|