| /* |
| * Copyright 2020 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.uwb; |
| |
| import static com.android.internal.util.Preconditions.checkNotNull; |
| |
| import android.Manifest.permission; |
| import android.annotation.CallbackExecutor; |
| import android.annotation.FlaggedApi; |
| import android.annotation.IntDef; |
| import android.annotation.IntRange; |
| import android.annotation.NonNull; |
| import android.annotation.Nullable; |
| import android.annotation.RequiresPermission; |
| import android.annotation.SuppressLint; |
| import android.annotation.SystemApi; |
| import android.annotation.SystemService; |
| import android.content.Context; |
| import android.os.Binder; |
| import android.os.Build; |
| import android.os.CancellationSignal; |
| import android.os.PersistableBundle; |
| import android.os.RemoteException; |
| import android.util.Log; |
| |
| import androidx.annotation.RequiresApi; |
| |
| import com.android.internal.annotations.GuardedBy; |
| |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.RetentionPolicy; |
| import java.util.List; |
| import java.util.Objects; |
| import java.util.concurrent.Executor; |
| import java.util.function.Consumer; |
| |
| /** |
| * This class provides a way to perform Ultra Wideband (UWB) operations such as querying the |
| * device's capabilities and determining the distance and angle between the local device and a |
| * remote device. |
| * |
| * <p>To get a {@link UwbManager}, call the <code>Context.getSystemService(UwbManager.class)</code>. |
| * |
| * <p> Note: This API surface uses opaque {@link PersistableBundle} params. These params are to be |
| * created using the provided UWB support library. The support library is present in this |
| * location on AOSP: <code>packages/modules/Uwb/service/support_lib/</code> |
| * |
| * @hide |
| */ |
| @SystemApi |
| @SystemService(Context.UWB_SERVICE) |
| public final class UwbManager { |
| private static final String TAG = "UwbManager"; |
| |
| private final Context mContext; |
| private final IUwbAdapter mUwbAdapter; |
| private final AdapterStateListener mAdapterStateListener; |
| private final RangingManager mRangingManager; |
| private final UwbVendorUciCallbackListener mUwbVendorUciCallbackListener; |
| private final UwbOemExtensionCallbackListener mUwbOemExtensionCallbackListener; |
| |
| /** |
| * Interface for receiving UWB adapter state changes |
| */ |
| public interface AdapterStateCallback { |
| /** |
| * @hide |
| */ |
| @Retention(RetentionPolicy.SOURCE) |
| @IntDef(value = { |
| STATE_CHANGED_REASON_SESSION_STARTED, |
| STATE_CHANGED_REASON_ALL_SESSIONS_CLOSED, |
| STATE_CHANGED_REASON_SYSTEM_POLICY, |
| STATE_CHANGED_REASON_SYSTEM_BOOT, |
| STATE_CHANGED_REASON_ERROR_UNKNOWN, |
| STATE_CHANGED_REASON_SYSTEM_REGULATION}) |
| @interface StateChangedReason {} |
| |
| /** |
| * @hide |
| */ |
| @Retention(RetentionPolicy.SOURCE) |
| @IntDef(value = { |
| STATE_ENABLED_INACTIVE, |
| STATE_ENABLED_ACTIVE, |
| STATE_DISABLED, |
| STATE_ENABLED_HW_IDLE}) |
| @interface State {} |
| |
| /** |
| * Indicates that the state change was due to opening of first UWB session |
| */ |
| int STATE_CHANGED_REASON_SESSION_STARTED = 0; |
| |
| /** |
| * Indicates that the state change was due to closure of all UWB sessions |
| */ |
| int STATE_CHANGED_REASON_ALL_SESSIONS_CLOSED = 1; |
| |
| /** |
| * Indicates that the state change was due to changes in system policy |
| */ |
| int STATE_CHANGED_REASON_SYSTEM_POLICY = 2; |
| |
| /** |
| * Indicates that the current state is due to a system boot |
| */ |
| int STATE_CHANGED_REASON_SYSTEM_BOOT = 3; |
| |
| /** |
| * Indicates that the state change was due to some unknown error |
| */ |
| int STATE_CHANGED_REASON_ERROR_UNKNOWN = 4; |
| |
| /** |
| * Indicates that the state change is due to a system regulation. |
| */ |
| int STATE_CHANGED_REASON_SYSTEM_REGULATION = 5; |
| |
| /** |
| * Indicates that UWB is disabled on device |
| */ |
| int STATE_DISABLED = 0; |
| /** |
| * Indicates that UWB is enabled on device but has no active ranging sessions |
| */ |
| int STATE_ENABLED_INACTIVE = 1; |
| |
| /** |
| * Indicates that UWB is enabled and has active ranging session |
| */ |
| int STATE_ENABLED_ACTIVE = 2; |
| |
| /** |
| * The state when UWB is enabled by user but the hardware is not enabled since no clients |
| * have requested for it. |
| * Only sent if the device supports {@link #isUwbHwIdleTurnOffEnabled()} feature. |
| */ |
| @FlaggedApi("com.android.uwb.flags.hw_state") |
| int STATE_ENABLED_HW_IDLE = 3; |
| |
| /** |
| * Invoked when underlying UWB adapter's state is changed |
| * <p>Invoked with the adapter's current state after registering an |
| * {@link AdapterStateCallback} using |
| * {@link UwbManager#registerAdapterStateCallback(Executor, AdapterStateCallback)}. |
| * |
| * <p>Possible reasons for the state to change are |
| * {@link #STATE_CHANGED_REASON_SESSION_STARTED}, |
| * {@link #STATE_CHANGED_REASON_ALL_SESSIONS_CLOSED}, |
| * {@link #STATE_CHANGED_REASON_SYSTEM_POLICY}, |
| * {@link #STATE_CHANGED_REASON_SYSTEM_BOOT}, |
| * {@link #STATE_CHANGED_REASON_ERROR_UNKNOWN}. |
| * {@link #STATE_CHANGED_REASON_SYSTEM_REGULATION}. |
| * |
| * <p>Possible values for the UWB state are |
| * {@link #STATE_ENABLED_INACTIVE}, |
| * {@link #STATE_ENABLED_ACTIVE}, |
| * {@link #STATE_DISABLED}. |
| * |
| * @param state the UWB state; inactive, active or disabled |
| * @param reason the reason for the state change |
| */ |
| void onStateChanged(@State int state, @StateChangedReason int reason); |
| } |
| |
| /** |
| * Abstract class for receiving ADF provisioning state. |
| * Should be extended by applications and set when calling |
| * {@link UwbManager#provisionProfileAdfByScript(PersistableBundle, Executor, |
| * AdfProvisionStateCallback)} |
| */ |
| public abstract static class AdfProvisionStateCallback { |
| private final AdfProvisionStateCallbackProxy mAdfProvisionStateCallbackProxy; |
| |
| public AdfProvisionStateCallback() { |
| mAdfProvisionStateCallbackProxy = new AdfProvisionStateCallbackProxy(); |
| } |
| |
| /** |
| * @hide |
| */ |
| @Retention(RetentionPolicy.SOURCE) |
| @IntDef(value = { |
| REASON_INVALID_OID, |
| REASON_SE_FAILURE, |
| REASON_UNKNOWN |
| }) |
| @interface Reason { } |
| |
| /** |
| * Indicates that the OID provided was not valid. |
| */ |
| public static final int REASON_INVALID_OID = 1; |
| |
| /** |
| * Indicates that there was some SE (secure element) failure while provisioning. |
| */ |
| public static final int REASON_SE_FAILURE = 2; |
| |
| /** |
| * No known reason for the failure. |
| */ |
| public static final int REASON_UNKNOWN = 3; |
| |
| /** |
| * Invoked when {@link UwbManager#provisionProfileAdfByScript(PersistableBundle, Executor, |
| * AdfProvisionStateCallback)} is successful. |
| * |
| * @param params protocol specific params that provide the caller with provisioning info |
| **/ |
| public abstract void onProfileAdfsProvisioned(@NonNull PersistableBundle params); |
| |
| /** |
| * Invoked when {@link UwbManager#provisionProfileAdfByScript(PersistableBundle, Executor, |
| * AdfProvisionStateCallback)} fails. |
| * |
| * @param reason Reason for failure |
| * @param params protocol specific parameters to indicate failure reason |
| */ |
| public abstract void onProfileAdfsProvisionFailed( |
| @Reason int reason, @NonNull PersistableBundle params); |
| |
| /*package*/ |
| @NonNull |
| AdfProvisionStateCallbackProxy getProxy() { |
| return mAdfProvisionStateCallbackProxy; |
| } |
| |
| private static class AdfProvisionStateCallbackProxy extends |
| IUwbAdfProvisionStateCallbacks.Stub { |
| private final Object mLock = new Object(); |
| @Nullable |
| @GuardedBy("mLock") |
| private Executor mExecutor; |
| @Nullable |
| @GuardedBy("mLock") |
| private AdfProvisionStateCallback mCallback; |
| |
| AdfProvisionStateCallbackProxy() { |
| mCallback = null; |
| mExecutor = null; |
| } |
| |
| /*package*/ void initProxy(@NonNull Executor executor, |
| @NonNull AdfProvisionStateCallback callback) { |
| synchronized (mLock) { |
| mExecutor = executor; |
| mCallback = callback; |
| } |
| } |
| |
| /*package*/ void cleanUpProxy() { |
| synchronized (mLock) { |
| mExecutor = null; |
| mCallback = null; |
| } |
| } |
| |
| @Override |
| public void onProfileAdfsProvisioned(@NonNull PersistableBundle params) { |
| Log.v(TAG, "AdfProvisionStateCallbackProxy: onProfileAdfsProvisioned : " + params); |
| AdfProvisionStateCallback callback; |
| Executor executor; |
| synchronized (mLock) { |
| executor = mExecutor; |
| callback = mCallback; |
| } |
| if (callback == null || executor == null) { |
| return; |
| } |
| Binder.clearCallingIdentity(); |
| executor.execute(() -> callback.onProfileAdfsProvisioned(params)); |
| cleanUpProxy(); |
| } |
| |
| @Override |
| public void onProfileAdfsProvisionFailed(@AdfProvisionStateCallback.Reason int reason, |
| @NonNull PersistableBundle params) { |
| Log.v(TAG, "AdfProvisionStateCallbackProxy: onProfileAdfsProvisionFailed : " |
| + reason + ", " + params); |
| AdfProvisionStateCallback callback; |
| Executor executor; |
| synchronized (mLock) { |
| executor = mExecutor; |
| callback = mCallback; |
| } |
| if (callback == null || executor == null) { |
| return; |
| } |
| Binder.clearCallingIdentity(); |
| executor.execute(() -> callback.onProfileAdfsProvisionFailed(reason, params)); |
| cleanUpProxy(); |
| } |
| } |
| } |
| |
| /** |
| * Interface for receiving vendor UCI responses and notifications. |
| */ |
| public interface UwbVendorUciCallback { |
| /** |
| * Invoked when a vendor specific UCI response is received. |
| * |
| * @param gid Group ID of the command. This needs to be one of the vendor reserved GIDs from |
| * the UCI specification. |
| * @param oid Opcode ID of the command. This is left to the OEM / vendor to decide. |
| * @param payload containing vendor Uci message payload. |
| */ |
| void onVendorUciResponse( |
| @IntRange(from = 0, to = 15) int gid, int oid, @NonNull byte[] payload); |
| |
| /** |
| * Invoked when a vendor specific UCI notification is received. |
| * |
| * @param gid Group ID of the command. This needs to be one of the vendor reserved GIDs from |
| * the UCI specification. |
| * @param oid Opcode ID of the command. This is left to the OEM / vendor to decide. |
| * @param payload containing vendor Uci message payload. |
| */ |
| void onVendorUciNotification( |
| @IntRange(from = 9, to = 15) int gid, int oid, @NonNull byte[] payload); |
| } |
| |
| |
| /** |
| * @hide |
| * Vendor configuration successful for the session |
| */ |
| public static final int VENDOR_SET_SESSION_CONFIGURATION_SUCCESS = 0; |
| |
| /** |
| * @hide |
| * Failure to set vendor configuration for the session |
| */ |
| public static final int VENDOR_SET_SESSION_CONFIGURATION_FAILURE = 1; |
| |
| /** |
| * @hide |
| */ |
| @Retention(RetentionPolicy.SOURCE) |
| @IntDef(value = { |
| VENDOR_SET_SESSION_CONFIGURATION_SUCCESS, |
| VENDOR_SET_SESSION_CONFIGURATION_FAILURE, |
| }) |
| @interface VendorConfigStatus {} |
| |
| |
| /** |
| * Interface for Oem extensions on ongoing session |
| */ |
| @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) |
| public interface UwbOemExtensionCallback { |
| /** |
| * Invoked when session status changes. |
| * |
| * @param sessionStatusBundle session related info |
| */ |
| void onSessionStatusNotificationReceived(@NonNull PersistableBundle sessionStatusBundle); |
| |
| /** |
| * Invoked when DeviceStatusNotification is received from UCI. |
| * |
| * @param deviceStatusBundle device state |
| */ |
| void onDeviceStatusNotificationReceived(@NonNull PersistableBundle deviceStatusBundle); |
| |
| /** |
| * Invoked when session configuration is complete. |
| * |
| * @param openSessionBundle Session Params |
| * @return Error code |
| */ |
| @NonNull @VendorConfigStatus int onSessionConfigurationComplete( |
| @NonNull PersistableBundle openSessionBundle); |
| |
| /** |
| * Invoked when ranging report is generated. |
| * |
| * @param rangingReport ranging report generated |
| * @return Oem modified ranging report |
| */ |
| @NonNull RangingReport onRangingReportReceived( |
| @NonNull RangingReport rangingReport); |
| |
| /** |
| * Invoked to check pointed target decision by Oem. |
| * |
| * @param pointedTargetBundle pointed target params |
| * @return Oem pointed status |
| */ |
| boolean onCheckPointedTarget(@NonNull PersistableBundle pointedTargetBundle); |
| } |
| |
| /** |
| * Use <code>Context.getSystemService(UwbManager.class)</code> to get an instance. |
| * |
| * @param ctx Context of the client. |
| * @param adapter an instance of an {@link android.uwb.IUwbAdapter} |
| * @hide |
| */ |
| public UwbManager(@NonNull Context ctx, @NonNull IUwbAdapter adapter) { |
| mContext = ctx; |
| mUwbAdapter = adapter; |
| mAdapterStateListener = new AdapterStateListener(adapter); |
| mRangingManager = new RangingManager(adapter); |
| mUwbVendorUciCallbackListener = new UwbVendorUciCallbackListener(adapter); |
| mUwbOemExtensionCallbackListener = new UwbOemExtensionCallbackListener(adapter); |
| } |
| |
| /** |
| * Register an {@link AdapterStateCallback} to listen for UWB adapter state changes |
| * <p>The provided callback will be invoked by the given {@link Executor}. |
| * |
| * <p>When first registering a callback, the callbacks's |
| * {@link AdapterStateCallback#onStateChanged(int, int)} is immediately invoked to indicate |
| * the current state of the underlying UWB adapter with the most recent |
| * {@link AdapterStateCallback.StateChangedReason} that caused the change. |
| * |
| * @param executor an {@link Executor} to execute given callback |
| * @param callback user implementation of the {@link AdapterStateCallback} |
| */ |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public void registerAdapterStateCallback(@NonNull @CallbackExecutor Executor executor, |
| @NonNull AdapterStateCallback callback) { |
| mAdapterStateListener.register(executor, callback); |
| } |
| |
| /** |
| * Unregister the specified {@link AdapterStateCallback} |
| * <p>The same {@link AdapterStateCallback} object used when calling |
| * {@link #registerAdapterStateCallback(Executor, AdapterStateCallback)} must be used. |
| * |
| * <p>Callbacks are automatically unregistered when application process goes away |
| * |
| * @param callback user implementation of the {@link AdapterStateCallback} |
| */ |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public void unregisterAdapterStateCallback(@NonNull AdapterStateCallback callback) { |
| mAdapterStateListener.unregister(callback); |
| } |
| |
| /** |
| * Register an {@link UwbVendorUciCallback} to listen for UWB vendor responses and notifications |
| * <p>The provided callback will be invoked by the given {@link Executor}. |
| * |
| * <p>When first registering a callback, the callbacks's |
| * {@link UwbVendorUciCallback#onVendorUciCallBack(byte[])} is immediately invoked to |
| * notify the vendor notification. |
| * |
| * @param executor an {@link Executor} to execute given callback |
| * @param callback user implementation of the {@link UwbVendorUciCallback} |
| */ |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public void registerUwbVendorUciCallback(@NonNull @CallbackExecutor Executor executor, |
| @NonNull UwbVendorUciCallback callback) { |
| mUwbVendorUciCallbackListener.register(executor, callback); |
| } |
| |
| /** |
| * Unregister the specified {@link UwbVendorUciCallback} |
| * |
| * <p>The same {@link UwbVendorUciCallback} object used when calling |
| * {@link #registerUwbVendorUciCallback(Executor, UwbVendorUciCallback)} must be used. |
| * |
| * <p>Callbacks are automatically unregistered when application process goes away |
| * |
| * @param callback user implementation of the {@link UwbVendorUciCallback} |
| */ |
| public void unregisterUwbVendorUciCallback(@NonNull UwbVendorUciCallback callback) { |
| mUwbVendorUciCallbackListener.unregister(callback); |
| } |
| |
| /** |
| * Register an {@link UwbOemExtensionCallback} to listen for UWB oem extension callbacks |
| * <p>The provided callback will be invoked by the given {@link Executor}. |
| * |
| * @param executor an {@link Executor} to execute given callback |
| * @param callback oem implementation of {@link UwbOemExtensionCallback} |
| */ |
| @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public void registerUwbOemExtensionCallback(@NonNull @CallbackExecutor Executor executor, |
| @NonNull UwbOemExtensionCallback callback) { |
| mUwbOemExtensionCallbackListener.register(executor, callback); |
| } |
| |
| /** |
| * Unregister the specified {@link UwbOemExtensionCallback} |
| * |
| * <p>The same {@link UwbOemExtensionCallback} object used when calling |
| * {@link #registerUwbOemExtensionCallback(Executor, UwbOemExtensionCallback)} must be used. |
| * |
| * <p>Callbacks are automatically unregistered when an application process goes away |
| * |
| * @param callback oem implementation of {@link UwbOemExtensionCallback} |
| */ |
| @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public void unregisterUwbOemExtensionCallback(@NonNull UwbOemExtensionCallback callback) { |
| mUwbOemExtensionCallbackListener.unregister(callback); |
| } |
| |
| /** |
| * Get a {@link PersistableBundle} with the supported UWB protocols and parameters. |
| * <p>The {@link PersistableBundle} should be parsed using a support library |
| * |
| * <p>Android reserves the '^android.*' namespace</p> |
| * |
| * @return {@link PersistableBundle} of the device's supported UWB protocols and parameters |
| */ |
| @NonNull |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public PersistableBundle getSpecificationInfo() { |
| return getSpecificationInfoInternal(/* chipId= */ null); |
| } |
| |
| /** |
| * Get a {@link PersistableBundle} with the supported UWB protocols and parameters. |
| * |
| * @see #getSpecificationInfo() if you don't need multi-HAL support |
| * |
| * @param chipId identifier of UWB chip for multi-HAL devices |
| * |
| * @return {@link PersistableBundle} of the device's supported UWB protocols and parameters |
| */ |
| // TODO(b/205614701): Add documentation about how to find the relevant chipId |
| @NonNull |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public PersistableBundle getSpecificationInfo(@NonNull String chipId) { |
| checkNotNull(chipId); |
| return getSpecificationInfoInternal(chipId); |
| } |
| |
| private PersistableBundle getSpecificationInfoInternal(String chipId) { |
| try { |
| return mUwbAdapter.getSpecificationInfo(chipId); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * Get uwbs timestamp in micros. |
| * |
| * @return uwb device timestamp in micros. |
| */ |
| @NonNull |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| @FlaggedApi("com.android.uwb.flags.query_timestamp_micros") |
| public long queryUwbsTimestampMicros() { |
| try { |
| return mUwbAdapter.queryUwbsTimestampMicros(); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * Get the timestamp resolution for events in nanoseconds |
| * <p>This value defines the maximum error of all timestamps for events reported to |
| * {@link RangingSession.Callback}. |
| * |
| * @return the timestamp resolution in nanoseconds |
| */ |
| @SuppressLint("MethodNameUnits") |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public long elapsedRealtimeResolutionNanos() { |
| return elapsedRealtimeResolutionNanosInternal(/* chipId= */ null); |
| } |
| |
| /** |
| * Get the timestamp resolution for events in nanoseconds |
| * |
| * @see #elapsedRealtimeResolutionNanos() if you don't need multi-HAL support |
| * |
| * @param chipId identifier of UWB chip for multi-HAL devices |
| * |
| * @return the timestamp resolution in nanoseconds |
| */ |
| @SuppressLint("MethodNameUnits") |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public long elapsedRealtimeResolutionNanos(@NonNull String chipId) { |
| checkNotNull(chipId); |
| return elapsedRealtimeResolutionNanosInternal(chipId); |
| } |
| |
| private long elapsedRealtimeResolutionNanosInternal(String chipId) { |
| try { |
| return mUwbAdapter.getTimestampResolutionNanos(chipId); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * Open a {@link RangingSession} with the given parameters |
| * <p>The {@link RangingSession.Callback#onOpened(RangingSession)} function is called with a |
| * {@link RangingSession} object used to control ranging when the session is successfully |
| * opened. |
| * |
| * if this session uses FIRA defined profile (not custom profile), this triggers: |
| * - OOB discovery using service UUID |
| * - OOB connection establishment after discovery for session params |
| * negotiation. |
| * - Secure element interactions needed for dynamic STS based session establishment. |
| * - Setup the UWB session based on the parameters negotiated via OOB. |
| * - Note: The OOB flow requires additional BLE Permissions |
| * {permission.BLUETOOTH_ADVERTISE/permission.BLUETOOTH_SCAN |
| * and permission.BLUETOOTH_CONNECT}. |
| * |
| * <p>If a session cannot be opened, then |
| * {@link RangingSession.Callback#onClosed(int, PersistableBundle)} will be invoked with the |
| * appropriate {@link RangingSession.Callback.Reason}. |
| * |
| * <p>An open {@link RangingSession} will be automatically closed if client application process |
| * dies. |
| * |
| * <p>A UWB support library must be used in order to construct the {@code parameter} |
| * {@link PersistableBundle}. |
| * |
| * @param parameters the parameters that define the ranging session |
| * @param executor {@link Executor} to run callbacks |
| * @param callbacks {@link RangingSession.Callback} to associate with the |
| * {@link RangingSession} that is being opened. |
| * |
| * @return an {@link CancellationSignal} that is able to be used to cancel the opening of a |
| * {@link RangingSession} that has been requested through {@link #openRangingSession} |
| * but has not yet been made available by |
| * {@link RangingSession.Callback#onOpened(RangingSession)}. |
| */ |
| @NonNull |
| @RequiresPermission(allOf = { |
| permission.UWB_PRIVILEGED, |
| permission.UWB_RANGING |
| }) |
| public CancellationSignal openRangingSession(@NonNull PersistableBundle parameters, |
| @NonNull @CallbackExecutor Executor executor, |
| @NonNull RangingSession.Callback callbacks) { |
| return openRangingSessionInternal(parameters, executor, callbacks, /* chipId= */ null); |
| } |
| |
| /** |
| * Open a {@link RangingSession} with the given parameters on a specific UWB subsystem |
| * |
| * @see #openRangingSession(PersistableBundle, Executor, RangingSession.Callback) if you don't |
| * need multi-HAL support |
| * |
| * @param parameters the parameters that define the ranging session |
| * @param executor {@link Executor} to run callbacks |
| * @param callbacks {@link RangingSession.Callback} to associate with the |
| * {@link RangingSession} that is being opened. |
| * @param chipId identifier of UWB chip for multi-HAL devices |
| * |
| * @return an {@link CancellationSignal} that is able to be used to cancel the opening of a |
| * {@link RangingSession} that has been requested through {@link #openRangingSession} |
| * but has not yet been made available by |
| * {@link RangingSession.Callback#onOpened(RangingSession)}. |
| */ |
| @NonNull |
| @RequiresPermission(allOf = { |
| permission.UWB_PRIVILEGED, |
| permission.UWB_RANGING |
| }) |
| public CancellationSignal openRangingSession(@NonNull PersistableBundle parameters, |
| @NonNull @CallbackExecutor Executor executor, |
| @NonNull RangingSession.Callback callbacks, |
| @SuppressLint("ListenerLast") @NonNull String chipId) { |
| checkNotNull(chipId); |
| return openRangingSessionInternal(parameters, executor, callbacks, chipId); |
| } |
| |
| private CancellationSignal openRangingSessionInternal(PersistableBundle parameters, |
| Executor executor, RangingSession.Callback callbacks, String chipId) { |
| return mRangingManager.openSession( |
| mContext.getAttributionSource(), parameters, executor, callbacks, chipId); |
| } |
| |
| /** |
| * Returns the current enabled/disabled state for UWB. |
| * |
| * Possible values are: |
| * AdapterStateCallback#STATE_DISABLED |
| * AdapterStateCallback#STATE_ENABLED_INACTIVE |
| * AdapterStateCallback#STATE_ENABLED_ACTIVE |
| * |
| * @return value representing current enabled/disabled state for UWB. |
| */ |
| public @AdapterStateCallback.State int getAdapterState() { |
| return mAdapterStateListener.getAdapterState(); |
| } |
| |
| /** |
| * Whether UWB is enabled or disabled. |
| * |
| * <p> |
| * If disabled, this could indicate that either |
| * <li> User has toggled UWB off from settings, OR </li> |
| * <li> UWB subsystem has shut down due to a fatal error. </li> |
| * </p> |
| * |
| * @return true if enabled, false otherwise. |
| * |
| * @see #getAdapterState() |
| * @see #setUwbEnabled(boolean) |
| */ |
| public boolean isUwbEnabled() { |
| int adapterState = getAdapterState(); |
| return adapterState != AdapterStateCallback.STATE_DISABLED; |
| } |
| |
| /** |
| * Disables or enables UWB by the user. |
| * |
| * If enabled any subsequent calls to |
| * {@link #openRangingSession(PersistableBundle, Executor, RangingSession.Callback)} will be |
| * allowed. If disabled, all active ranging sessions will be closed and subsequent calls to |
| * {@link #openRangingSession(PersistableBundle, Executor, RangingSession.Callback)} will be |
| * disallowed. |
| * |
| * @param enabled value representing intent to disable or enable UWB. |
| */ |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public void setUwbEnabled(boolean enabled) { |
| mAdapterStateListener.setEnabled(enabled); |
| } |
| |
| /** |
| * Whether UWB hardware will automatically turn off when there are no clients requesting it. |
| * This feature is only turned on non-phone form factor devices which needs to keep the UWB |
| * hardware turned to avoid battery drain. |
| * |
| * <p> |
| * If the device supports automatically turning off UWB hardware, the state of UWB hardware |
| * is controlled by: |
| * <li> UWB user toggle state or Airplane mode state, AND </li> |
| * <li> Whether any clients are actively enabling UWB </li> |
| * </p> |
| * |
| * @return true if enabled, false otherwise. |
| * |
| * @see #isUwbHwEnableRequested() |
| * @see #requestUwbHwEnable(boolean) |
| */ |
| @FlaggedApi("com.android.uwb.flags.hw_state") |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public boolean isUwbHwIdleTurnOffEnabled() { |
| try { |
| return mUwbAdapter.isHwIdleTurnOffEnabled(); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * Whether this client has requested for UWB hardware to be enabled or disabled. |
| * Only supported on devices which supports hw idle turn off (indicated by |
| * {@link #isUwbHwIdleTurnOffEnabled()}) |
| * |
| * <p> |
| * This does not indicate the global state of UWB, this only indicates whether this app |
| * (identified by {@link Context#getAttributionSource()}) has requested for UWB hardware to be |
| * enabled or disabled. |
| * </p> |
| * |
| * @return true if enabled, false otherwise. |
| * @throws IllegalStateException if the device does not support this feature |
| * |
| * @see #isUwbHwIdleTurnOffEnabled() |
| * @see #requestUwbHwEnable(boolean) |
| */ |
| @FlaggedApi("com.android.uwb.flags.hw_state") |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public boolean isUwbHwEnableRequested() { |
| try { |
| return mUwbAdapter.isHwEnableRequested(mContext.getAttributionSource()); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * This client has requested for UWB hardware to be enabled or disabled. |
| * Only supported on devices which supports hw idle turn off (indicated by |
| * {@link #isUwbHwIdleTurnOffEnabled()}) |
| * |
| * <p> |
| * This does not indicate the global state of UWB, this only indicates whether this app |
| * (identified by {@link Context#getAttributionSource()}) has requested for UWB hardware to be |
| * enabled or disabled. |
| * If UWB is enabled by the user and has at least 1 privileged client requesting UWB toggle on, |
| * then UWB hardware is enabled, else the UWB hardware is disabled. |
| * </p> |
| * |
| * @param enabled value representing intent to disable or enable UWB. |
| * @throws IllegalStateException if the device does not support this feature |
| * |
| * @see #isUwbHwIdleTurnOffEnabled() |
| * @see #isUwbHwEnableRequested() () |
| */ |
| @FlaggedApi("com.android.uwb.flags.hw_state") |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public void requestUwbHwEnabled(boolean enabled) { |
| try { |
| mUwbAdapter.requestHwEnabled( |
| enabled, mContext.getAttributionSource(), |
| new Binder(mContext.getPackageName())); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * Returns a list of UWB chip infos in a {@link PersistableBundle}. |
| * |
| * Callers can invoke methods on a specific UWB chip by passing its {@code chipId} to the |
| * method, which can be determined by calling: |
| * <pre> |
| * List<PersistableBundle> chipInfos = getChipInfos(); |
| * for (PersistableBundle chipInfo : chipInfos) { |
| * String chipId = ChipInfoParams.fromBundle(chipInfo).getChipId(); |
| * } |
| * </pre> |
| * |
| * @return list of {@link PersistableBundle} containing info about UWB chips for a multi-HAL |
| * system, or a list of info for a single chip for a single HAL system. |
| */ |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| @NonNull |
| public List<PersistableBundle> getChipInfos() { |
| try { |
| return mUwbAdapter.getChipInfos(); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * Returns the default UWB chip identifier. |
| * |
| * If callers do not pass a specific {@code chipId} to UWB methods, then the method will be |
| * invoked on the default chip, which is determined at system initialization from a |
| * configuration file. |
| * |
| * @return default UWB chip identifier for a multi-HAL system, or the identifier of the only UWB |
| * chip in a single HAL system. |
| */ |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| @NonNull |
| public String getDefaultChipId() { |
| try { |
| return mUwbAdapter.getDefaultChipId(); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * Register the UWB service profile. |
| * This profile instance is persisted by the platform until explicitly removed |
| * using {@link #removeServiceProfile(PersistableBundle)} |
| * |
| * @param parameters the parameters that define the service profile. |
| * @return Protocol specific params to be used as handle for triggering the profile. |
| */ |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| @NonNull |
| public PersistableBundle addServiceProfile(@NonNull PersistableBundle parameters) { |
| try { |
| return mUwbAdapter.addServiceProfile(parameters); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * Successfully removed the service profile. |
| */ |
| public static final int REMOVE_SERVICE_PROFILE_SUCCESS = 0; |
| |
| /** |
| * Failed to remove service since the service profile is unknown. |
| */ |
| public static final int REMOVE_SERVICE_PROFILE_ERROR_UNKNOWN_SERVICE = 1; |
| |
| /** |
| * Failed to remove service due to some internal error while processing the request. |
| */ |
| public static final int REMOVE_SERVICE_PROFILE_ERROR_INTERNAL = 2; |
| |
| /** |
| * @hide |
| */ |
| @Retention(RetentionPolicy.SOURCE) |
| @IntDef(value = { |
| REMOVE_SERVICE_PROFILE_SUCCESS, |
| REMOVE_SERVICE_PROFILE_ERROR_UNKNOWN_SERVICE, |
| REMOVE_SERVICE_PROFILE_ERROR_INTERNAL |
| }) |
| @interface RemoveServiceProfile {} |
| |
| /** |
| * Remove the service profile registered with {@link #addServiceProfile} and |
| * all related resources. |
| * |
| * @param parameters the parameters that define the service profile. |
| * |
| * @return true if the service profile is removed, false otherwise. |
| */ |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public @RemoveServiceProfile int removeServiceProfile(@NonNull PersistableBundle parameters) { |
| try { |
| return mUwbAdapter.removeServiceProfile(parameters); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * Get all service profiles initialized with {@link #addServiceProfile} |
| * |
| * @return the parameters that define the service profiles. |
| */ |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| @NonNull |
| public PersistableBundle getAllServiceProfiles() { |
| try { |
| return mUwbAdapter.getAllServiceProfiles(); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * Get the list of ADF (application defined file) provisioning authorities available for the UWB |
| * applet in SE (secure element). |
| * |
| * @param serviceProfileBundle Parameters representing the profile to use. |
| * @return The list of key information of ADF provisioning authority defined in FiRa |
| * CSML 8.2.2.7.2.4 and 8.2.2.14.4.1.2. |
| */ |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| @NonNull |
| public PersistableBundle getAdfProvisioningAuthorities( |
| @NonNull PersistableBundle serviceProfileBundle) { |
| try { |
| return mUwbAdapter.getAdfProvisioningAuthorities(serviceProfileBundle); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * Get certificate information for the UWB applet in SE (secure element) that can be used to |
| * provision ADF (application defined file). |
| * |
| * @param serviceProfileBundle Parameters representing the profile to use. |
| * @return The Fira applet certificate information defined in FiRa CSML 7.3.4.3 and |
| * 8.2.2.14.4.1.1 |
| */ |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| @NonNull |
| public PersistableBundle getAdfCertificateInfo( |
| @NonNull PersistableBundle serviceProfileBundle) { |
| try { |
| return mUwbAdapter.getAdfCertificateAndInfo(serviceProfileBundle); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * Mechanism to provision ADFs (application defined file) in the UWB applet present in SE |
| * (secure element) for a profile instance. |
| * |
| * @param serviceProfileBundle Parameters representing the profile to use. |
| * @param executor an {@link Executor} to execute given callback |
| * @param callback user implementation of the {@link AdapterStateCallback} |
| */ |
| public void provisionProfileAdfByScript(@NonNull PersistableBundle serviceProfileBundle, |
| @NonNull @CallbackExecutor Executor executor, |
| @NonNull AdfProvisionStateCallback callback) { |
| if (executor == null) throw new IllegalArgumentException("executor must not be null"); |
| if (callback == null) throw new IllegalArgumentException("callback must not be null"); |
| AdfProvisionStateCallback.AdfProvisionStateCallbackProxy proxy = callback.getProxy(); |
| proxy.initProxy(executor, callback); |
| try { |
| mUwbAdapter.provisionProfileAdfByScript(serviceProfileBundle, proxy); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * Successfully removed the profile ADF. |
| */ |
| public static final int REMOVE_PROFILE_ADF_SUCCESS = 0; |
| |
| /** |
| * Failed to remove ADF since the service profile is unknown. |
| */ |
| public static final int REMOVE_PROFILE_ADF_ERROR_UNKNOWN_SERVICE = 1; |
| |
| /** |
| * Failed to remove ADF due to some internal error while processing the request. |
| */ |
| public static final int REMOVE_PROFILE_ADF_ERROR_INTERNAL = 2; |
| |
| /** |
| * @hide |
| */ |
| @Retention(RetentionPolicy.SOURCE) |
| @IntDef(value = { |
| REMOVE_PROFILE_ADF_SUCCESS, |
| REMOVE_PROFILE_ADF_ERROR_UNKNOWN_SERVICE, |
| REMOVE_PROFILE_ADF_ERROR_INTERNAL |
| }) |
| @interface RemoveProfileAdf {} |
| |
| /** |
| * Remove the ADF (application defined file) provisioned by {@link #provisionProfileAdfByScript} |
| * |
| * @param serviceProfileBundle Parameters representing the profile to use. |
| * @return true if the ADF is removed, false otherwise. |
| */ |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public @RemoveProfileAdf int removeProfileAdf(@NonNull PersistableBundle serviceProfileBundle) { |
| try { |
| return mUwbAdapter.removeProfileAdf(serviceProfileBundle); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * Successfully sent the UCI message. |
| */ |
| public static final int SEND_VENDOR_UCI_SUCCESS = 0; |
| |
| /** |
| * Failed to send the UCI message because of an error returned from the HAL interface. |
| */ |
| public static final int SEND_VENDOR_UCI_ERROR_HW = 1; |
| |
| /** |
| * Failed to send the UCI message since UWB is toggled off. |
| */ |
| public static final int SEND_VENDOR_UCI_ERROR_OFF = 2; |
| |
| /** |
| * Failed to send the UCI message since UWB UCI command is malformed. |
| * GID. |
| */ |
| public static final int SEND_VENDOR_UCI_ERROR_INVALID_ARGS = 3; |
| |
| /** |
| * Failed to send the UCI message since UWB GID used is invalid. |
| */ |
| public static final int SEND_VENDOR_UCI_ERROR_INVALID_GID = 4; |
| |
| /** |
| * @hide |
| */ |
| @Retention(RetentionPolicy.SOURCE) |
| @IntDef(value = { |
| SEND_VENDOR_UCI_SUCCESS, |
| SEND_VENDOR_UCI_ERROR_HW, |
| SEND_VENDOR_UCI_ERROR_OFF, |
| SEND_VENDOR_UCI_ERROR_INVALID_ARGS, |
| SEND_VENDOR_UCI_ERROR_INVALID_GID, |
| }) |
| @interface SendVendorUciStatus {} |
| |
| /** |
| * Message Type for UCI Command. |
| */ |
| public static final int MESSAGE_TYPE_COMMAND = 1; |
| /** |
| * Message Type for C-APDU (Command - Application Protocol Data Unit), |
| * used for communication with secure component. |
| */ |
| public static final int MESSAGE_TYPE_TEST_1 = 4; |
| |
| /** |
| * Message Type for R-APDU (Response - Application Protocol Data Unit), |
| * used for communication with secure component. |
| */ |
| public static final int MESSAGE_TYPE_TEST_2 = 5; |
| |
| /** |
| * @hide |
| */ |
| @Retention(RetentionPolicy.SOURCE) |
| @IntDef(value = { |
| MESSAGE_TYPE_COMMAND, |
| MESSAGE_TYPE_TEST_1, |
| MESSAGE_TYPE_TEST_2, |
| }) |
| @interface MessageType {} |
| |
| /** |
| * Send Vendor specific Uci Messages. |
| * |
| * The format of the UCI messages are defined in the UCI specification. The platform is |
| * responsible for fragmenting the payload if necessary. |
| * |
| * @param gid Group ID of the command. This needs to be one of the vendor reserved GIDs from |
| * the UCI specification. |
| * @param oid Opcode ID of the command. This is left to the OEM / vendor to decide. |
| * @param payload containing vendor Uci message payload. |
| */ |
| @NonNull |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public @SendVendorUciStatus int sendVendorUciMessage( |
| @IntRange(from = 0, to = 15) int gid, int oid, @NonNull byte[] payload) { |
| Objects.requireNonNull(payload, "Payload must not be null"); |
| try { |
| return mUwbAdapter.sendVendorUciMessage(MESSAGE_TYPE_COMMAND, gid, oid, payload); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * Send Vendor specific Uci Messages with custom message type. |
| * |
| * The format of the UCI messages are defined in the UCI specification. The platform is |
| * responsible for fragmenting the payload if necessary. |
| * |
| * Note that mt (message type) is added at the beginning of method parameters as it is more |
| * distinctive than other parameters and was requested from vendor. |
| * |
| * @param mt Message Type of the command |
| * @param gid Group ID of the command. This needs to be one of the vendor reserved GIDs from |
| * the UCI specification |
| * @param oid Opcode ID of the command. This is left to the OEM / vendor to decide |
| * @param payload containing vendor Uci message payload |
| */ |
| @NonNull |
| @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public @SendVendorUciStatus int sendVendorUciMessage(@MessageType int mt, |
| @IntRange(from = 0, to = 15) int gid, int oid, @NonNull byte[] payload) { |
| Objects.requireNonNull(payload, "Payload must not be null"); |
| try { |
| return mUwbAdapter.sendVendorUciMessage(mt, gid, oid, payload); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| |
| private static class OnUwbActivityEnergyInfoProxy |
| extends IOnUwbActivityEnergyInfoListener.Stub { |
| private final Object mLock = new Object(); |
| @Nullable @GuardedBy("mLock") private Executor mExecutor; |
| @Nullable @GuardedBy("mLock") private Consumer<UwbActivityEnergyInfo> mListener; |
| |
| OnUwbActivityEnergyInfoProxy(Executor executor, |
| Consumer<UwbActivityEnergyInfo> listener) { |
| mExecutor = executor; |
| mListener = listener; |
| } |
| |
| @Override |
| public void onUwbActivityEnergyInfo(UwbActivityEnergyInfo info) { |
| Executor executor; |
| Consumer<UwbActivityEnergyInfo> listener; |
| synchronized (mLock) { |
| if (mExecutor == null || mListener == null) { |
| return; |
| } |
| executor = mExecutor; |
| listener = mListener; |
| // null out to allow garbage collection, prevent triggering listener more than once |
| mExecutor = null; |
| mListener = null; |
| } |
| Binder.clearCallingIdentity(); |
| executor.execute(() -> listener.accept(info)); |
| } |
| } |
| |
| /** |
| * Request to get the current {@link UwbActivityEnergyInfo} asynchronously. |
| * |
| * @param executor the executor that the listener will be invoked on |
| * @param listener the listener that will receive the {@link UwbActivityEnergyInfo} object |
| * when it becomes available. The listener will be triggered at most once for |
| * each call to this method. |
| */ |
| @RequiresPermission(permission.UWB_PRIVILEGED) |
| public void getUwbActivityEnergyInfoAsync( |
| @NonNull @CallbackExecutor Executor executor, |
| @NonNull Consumer<UwbActivityEnergyInfo> listener) { |
| Objects.requireNonNull(executor, "executor cannot be null"); |
| Objects.requireNonNull(listener, "listener cannot be null"); |
| try { |
| mUwbAdapter.getUwbActivityEnergyInfoAsync( |
| new OnUwbActivityEnergyInfoProxy(executor, listener)); |
| } catch (RemoteException e) { |
| throw e.rethrowFromSystemServer(); |
| } |
| } |
| } |
