1 /*
2  * Copyright 2020 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.uwb;
18 
19 import android.content.AttributionSource;
20 import android.os.IBinder;
21 import android.os.PersistableBundle;
22 import android.uwb.IUwbAdapterStateCallbacks;
23 import android.uwb.IUwbAdfProvisionStateCallbacks;
24 import android.uwb.IUwbRangingCallbacks;
25 import android.uwb.SessionHandle;
26 import android.uwb.UwbAddress;
27 import android.uwb.IUwbVendorUciCallback;
28 import android.uwb.IUwbOemExtensionCallback;
29 import android.uwb.IOnUwbActivityEnergyInfoListener;
30 
31 /**
32  * @hide
33  * TODO(b/211025367): Remove all the duplicate javadocs here.
34  */
35 interface IUwbAdapter {
36   /*
37    * Register the callbacks used to notify the framework of events and data
38    *
39    * The provided callback's IUwbAdapterStateCallbacks#onAdapterStateChanged
40    * function must be called immediately following registration with the current
41    * state of the UWB adapter.
42    *
43    * @param callbacks callback to provide range and status updates to the framework
44    */
registerAdapterStateCallbacks(in IUwbAdapterStateCallbacks adapterStateCallbacks)45   void registerAdapterStateCallbacks(in IUwbAdapterStateCallbacks adapterStateCallbacks);
46 
47    /*
48     * Register the callbacks used to notify the framework of events and data
49     *
50     * The provided callback's IUwbUciVendorCallback#onVendorNotificationReceived
51     * function must be called immediately following vendorNotification received
52     *
53     * @param callbacks callback to provide Notification data updates to the framework
54     */
registerVendorExtensionCallback(in IUwbVendorUciCallback callbacks)55    void registerVendorExtensionCallback(in IUwbVendorUciCallback callbacks);
56 
57    /*
58     * Unregister the callbacks used to notify the framework of events and data
59     *
60     * Calling this function with an unregistered callback is a no-op
61     *
62     * @param callbacks callback to unregister
63     */
unregisterVendorExtensionCallback(in IUwbVendorUciCallback callbacks)64    void unregisterVendorExtensionCallback(in IUwbVendorUciCallback callbacks);
65 
66    /*
67    * Unregister the callbacks used to notify the framework of events and data
68    *
69    * Calling this function with an unregistered callback is a no-op
70    *
71    * @param callbacks callback to unregister
72    */
unregisterAdapterStateCallbacks(in IUwbAdapterStateCallbacks callbacks)73   void unregisterAdapterStateCallbacks(in IUwbAdapterStateCallbacks callbacks);
74 
registerOemExtensionCallback(in IUwbOemExtensionCallback callbacks)75   void registerOemExtensionCallback(in IUwbOemExtensionCallback callbacks);
76 
unregisterOemExtensionCallback(in IUwbOemExtensionCallback callbacks)77   void unregisterOemExtensionCallback(in IUwbOemExtensionCallback callbacks);
78 
79   /**
80    * Get the accuracy of the ranging timestamps
81    *
82    * @param chipId identifier of UWB chip for multi-HAL devices
83    *
84    * @return accuracy of the ranging timestamps in nanoseconds
85    */
getTimestampResolutionNanos(in String chipId)86   long getTimestampResolutionNanos(in String chipId);
87 
88   /**
89    * Provides the capabilities and features of the device
90    *
91    * @param chipId identifier of UWB chip for multi-HAL devices
92    *
93    * @return specification specific capabilities and features of the device
94    */
getSpecificationInfo(in String chipId)95   PersistableBundle getSpecificationInfo(in String chipId);
96 
97   /**
98    * Request to open a new ranging session
99    *
100    * This function does not start the ranging session, but all necessary
101    * components must be initialized and ready to start a new ranging
102    * session prior to calling IUwbAdapterCallback#onRangingOpened.
103    *
104    * IUwbAdapterCallbacks#onRangingOpened must be called within
105    * RANGING_SESSION_OPEN_THRESHOLD_MS milliseconds of #openRanging being
106    * called if the ranging session is opened successfully.
107    *
108    * IUwbAdapterCallbacks#onRangingOpenFailed must be called within
109    * RANGING_SESSION_OPEN_THRESHOLD_MS milliseconds of #openRanging being called
110    * if the ranging session fails to be opened.
111    *
112    * If the provided sessionHandle is already open for the calling client, then
113    * #onRangingOpenFailed must be called and the new session must not be opened.
114    *
115    * @param attributionSource AttributionSource to use for permission enforcement.
116    * @param sessionHandle the session handle to open ranging for
117    * @param rangingCallbacks the callbacks used to deliver ranging information
118    * @param parameters the configuration to use for ranging
119    * @param chipId identifier of UWB chip for multi-HAL devices
120    */
openRanging(in AttributionSource attributionSource, in SessionHandle sessionHandle, in IUwbRangingCallbacks rangingCallbacks, in PersistableBundle parameters, in String chipId)121   void openRanging(in AttributionSource attributionSource,
122                    in SessionHandle sessionHandle,
123                    in IUwbRangingCallbacks rangingCallbacks,
124                    in PersistableBundle parameters,
125                    in String chipId);
126 
127   /**
128    * Request to start ranging
129    *
130    * IUwbAdapterCallbacks#onRangingStarted must be called within
131    * RANGING_SESSION_START_THRESHOLD_MS milliseconds of #startRanging being
132    * called if the ranging session starts successfully.
133    *
134    * IUwbAdapterCallbacks#onRangingStartFailed must be called within
135    * RANGING_SESSION_START_THRESHOLD_MS milliseconds of #startRanging being
136    * called if the ranging session fails to be started.
137    *
138    * @param sessionHandle the session handle to start ranging for
139    * @param parameters additional configuration required to start ranging
140    */
startRanging(in SessionHandle sessionHandle, in PersistableBundle parameters)141   void startRanging(in SessionHandle sessionHandle,
142                     in PersistableBundle parameters);
143 
144   /**
145    * Request to reconfigure ranging
146    *
147    * IUwbAdapterCallbacks#onRangingReconfigured must be called after
148    * successfully reconfiguring the session.
149    *
150    * IUwbAdapterCallbacks#onRangingReconfigureFailed must be called after
151    * failing to reconfigure the session.
152    *
153    * A session must not be modified by a failed call to #reconfigureRanging.
154    *
155    * @param sessionHandle the session handle to start ranging for
156    * @param parameters the parameters to reconfigure and their new values
157    */
reconfigureRanging(in SessionHandle sessionHandle, in PersistableBundle parameters)158   void reconfigureRanging(in SessionHandle sessionHandle,
159                           in PersistableBundle parameters);
160 
161   /**
162    * Request to stop ranging
163    *
164    * IUwbAdapterCallbacks#onRangingStopped must be called after
165    * successfully stopping the session.
166    *
167    * IUwbAdapterCallbacks#onRangingStopFailed must be called after failing
168    * to stop the session.
169    *
170    * @param sessionHandle the session handle to stop ranging for
171    */
stopRanging(in SessionHandle sessionHandle)172   void stopRanging(in SessionHandle sessionHandle);
173 
174   /**
175    * Close ranging for the session associated with the given handle
176    *
177    * Calling with an invalid handle or a handle that has already been closed
178    * is a no-op.
179    *
180    * IUwbAdapterCallbacks#onRangingClosed must be called within
181    * RANGING_SESSION_CLOSE_THRESHOLD_MS of #closeRanging being called.
182    *
183    * @param sessionHandle the session handle to close ranging for
184    */
closeRanging(in SessionHandle sessionHandle)185   void closeRanging(in SessionHandle sessionHandle);
186 
187   /**
188    * Add a new controlee to an ongoing session.
189    * <p>This call may be made when the session is open.
190    *
191    * <p>On successfully adding a new controlee to the session
192    * {@link RangingSession.Callback#onControleeAdded(PersistableBundle)} is invoked.
193    *
194    * <p>On failure to add a new controlee to the session,
195    * {@link RangingSession.Callback#onControleeAddFailed(int, PersistableBundle)}is invoked.
196    *
197    * @param sessionHandle the session handle to close ranging for
198    * @param params the parameters for the new controlee.
199    */
addControlee(in SessionHandle sessionHandle, in PersistableBundle params)200   void addControlee(in SessionHandle sessionHandle, in PersistableBundle params);
201 
202   /**
203    * Remove an existing controlee from an ongoing session.
204    * <p>This call may be made when the session is open.
205    *
206    * <p>On successfully removing an existing controlee from the session
207    * {@link RangingSession.Callback#onControleeRemoved(PersistableBundle)} is invoked.
208    *
209    * <p>On failure to remove an existing controlee from the session,
210    * {@link RangingSession.Callback#onControleeRemoveFailed(int, PersistableBundle)}is invoked.
211    *
212    * @param sessionHandle the session handle to close ranging for
213    * @param params the parameters for the existing controlee.
214    */
removeControlee(in SessionHandle sessionHandle, in PersistableBundle params)215   void removeControlee(in SessionHandle sessionHandle, in PersistableBundle params);
216 
217   /**
218    * Suspends an ongoing ranging session.
219    *
220    * <p>A session that has been pauseed may be resumed by calling
221    * {@link RangingSession#resume(PersistableBundle)} without the need to open a new session.
222    *
223    * <p>Suspending a {@link RangingSession} is useful when the lower layers should skip a few
224    * ranging rounds for a session without stopping it.
225    *
226    * <p>If the {@link RangingSession} is no longer needed, use {@link RangingSession#stop()} or
227    * {@link RangingSession#close()} to completely close the session.
228    *
229    * <p>On successfully pauseing the session,
230    * {@link RangingSession.Callback#onPaused(PersistableBundle)} is invoked.
231    *
232    * <p>On failure to pause the session,
233    * {@link RangingSession.Callback#onPauseFailed(int, PersistableBundle)} is invoked.
234    *
235    * @param sessionHandle the session handle to close ranging for
236    * @param params protocol specific parameters for pauseing the session.
237    */
pause(in SessionHandle sessionHandle, in PersistableBundle params)238   void pause(in SessionHandle sessionHandle, in PersistableBundle params);
239 
240   /**
241    * Resumes a pauseed ranging session.
242    *
243    * <p>A session that has been previously pauseed using
244    * {@link RangingSession#pause(PersistableBundle)} can be resumed by calling
245    * {@link RangingSession#resume(PersistableBundle)}.
246    *
247    * <p>On successfully resuming the session,
248    * {@link RangingSession.Callback#onResumed(PersistableBundle)} is invoked.
249    *
250    * <p>On failure to pause the session,
251    * {@link RangingSession.Callback#onResumeFailed(int, PersistableBundle)} is invoked.
252    *
253    * @param sessionHandle the session handle to close ranging for
254    * @param params protocol specific parameters the resuming the session.
255    */
resume(in SessionHandle sessionHandle, in PersistableBundle params)256   void resume(in SessionHandle sessionHandle, in PersistableBundle params);
257 
258   /**
259    * Send data to a remote device which is part of this ongoing session.
260    * The data is sent by piggybacking the provided data over RRM (initiator -> responder) or
261    * RIM (responder -> initiator).
262    * <p>This is only functional on a FIRA 2.0 compliant device.
263    *
264    * <p>On successfully sending the data,
265    * {@link RangingSession.Callback#onDataSent(UwbAddress, PersistableBundle)} is invoked.
266    *
267    * <p>On failure to send the data,
268    * {@link RangingSession.Callback#onDataSendFailed(UwbAddress, int, PersistableBundle)} is
269    * invoked.
270    *
271    * @param sessionHandle the session handle to close ranging for
272    * @param remoteDeviceAddress remote device's address.
273    * @param params protocol specific parameters the sending the data.
274    * @param data Raw data to be sent.
275    */
sendData(in SessionHandle sessionHandle, in UwbAddress remoteDeviceAddress, in PersistableBundle params, in byte[] data)276   void sendData(in SessionHandle sessionHandle, in UwbAddress remoteDeviceAddress,
277           in PersistableBundle params, in byte[] data);
278 
279   /**
280     * Set data transfer phase configuration during ranging as well as dedicated data transfer.
281     * <p>This is only functional on a FIRA 2.0 compliant device.
282     *
283     * <p>On successfully sending the data transfer phase config,
284     * {@link RangingSession.Callback#onDataTransferPhaseConfigured(PersistableBundle)} is
285     * invoked.
286     *
287     * <p>On failure to send the data transfer phase config,
288     * {@link RangingSession.Callback#onDataTransferPhaseConfigFailed(int, PersistableBundle)} is
289     * invoked.
290     *
291     * @param params Protocol specific data transfer phase configuration parameters
292     */
setDataTransferPhaseConfig(in SessionHandle sessionHandle, in PersistableBundle params)293   void setDataTransferPhaseConfig(in SessionHandle sessionHandle, in PersistableBundle params);
294 
295   /**
296    * Disables or enables UWB for a user
297    *
298    * The provided callback's IUwbAdapterStateCallbacks#onAdapterStateChanged
299    * function must be called immediately following state change.
300    *
301    * @param enabled value representing intent to disable or enable UWB. If
302    * true, any subsequent calls to #openRanging will be allowed. If false,
303    * all active ranging sessions will be closed and subsequent calls to
304    * #openRanging will be disallowed.
305    */
setEnabled(boolean enabled)306   void setEnabled(boolean enabled);
307 
308   /**
309    * Returns the current enabled/disabled UWB state.
310    *
311    * Possible values are:
312    * IUwbAdapterState#STATE_DISABLED
313    * IUwbAdapterState#STATE_ENABLED_ACTIVE
314    * IUwbAdapterState#STATE_ENABLED_INACTIVE
315    *
316    * @return value representing enabled/disabled UWB state.
317    */
getAdapterState()318   int getAdapterState();
319 
isHwIdleTurnOffEnabled()320   boolean isHwIdleTurnOffEnabled();
requestHwEnabled(boolean enabled, in AttributionSource attributionSource, IBinder binder)321   void requestHwEnabled(boolean enabled, in AttributionSource attributionSource, IBinder binder);
isHwEnableRequested(in AttributionSource attributionSource)322   boolean isHwEnableRequested(in AttributionSource attributionSource);
323 
324   /**
325    * Returns a list of UWB chip infos in a {@link PersistableBundle}.
326    *
327    * Callers can invoke methods on a specific UWB chip by passing its {@code chipId} to the
328    * method, which can be determined by calling:
329    * <pre>
330    * List<PersistableBundle> chipInfos = getChipInfos();
331    * for (PersistableBundle chipInfo : chipInfos) {
332    *     String chipId = ChipInfoParams.fromBundle(chipInfo).getChipId();
333    * }
334    * </pre>
335    *
336    * @return list of {@link PersistableBundle} containing info about UWB chips for a multi-HAL
337    * system, or a list of info for a single chip for a single HAL system.
338    */
getChipInfos()339   List<PersistableBundle> getChipInfos();
340 
getChipIds()341   List<String> getChipIds();
342 
343   /**
344    * Returns the default UWB chip identifier.
345    *
346    * If callers do not pass a specific {@code chipId} to UWB methods, then the method will be
347    * invoked on the default chip, which is determined at system initialization from a configuration
348    * file.
349    *
350    * @return default UWB chip identifier for a multi-HAL system, or the identifier of the only UWB
351    * chip in a single HAL system.
352    */
getDefaultChipId()353   String getDefaultChipId();
354 
addServiceProfile(in PersistableBundle parameters)355   PersistableBundle addServiceProfile(in PersistableBundle parameters);
356 
removeServiceProfile(in PersistableBundle parameters)357   int removeServiceProfile(in PersistableBundle parameters);
358 
getAllServiceProfiles()359   PersistableBundle getAllServiceProfiles();
360 
getAdfProvisioningAuthorities(in PersistableBundle parameters)361   PersistableBundle getAdfProvisioningAuthorities(in PersistableBundle parameters);
362 
getAdfCertificateAndInfo(in PersistableBundle parameters)363   PersistableBundle getAdfCertificateAndInfo(in PersistableBundle parameters);
364 
provisionProfileAdfByScript(in PersistableBundle serviceProfileBundle, in IUwbAdfProvisionStateCallbacks callback)365   void provisionProfileAdfByScript(in PersistableBundle serviceProfileBundle,
366             in IUwbAdfProvisionStateCallbacks callback);
367 
removeProfileAdf(in PersistableBundle serviceProfileBundle)368   int removeProfileAdf(in PersistableBundle serviceProfileBundle);
369 
370   /**
371    * Updates the device pose. This helps the filter engine distinguish position noise from device
372    * motion. The device pose would typically come from ARCore. This requires that an application
373    * pose source was indicated in the call to openSession.
374    */
updatePose(in SessionHandle sessionHandle, in PersistableBundle params)375   void updatePose(in SessionHandle sessionHandle, in PersistableBundle params);
376 
sendVendorUciMessage(int mt, int gid, int oid, in byte[] payload)377   int sendVendorUciMessage(int mt, int gid, int oid, in byte[] payload);
378 
379   /**
380    * @hide
381    * Sets the Hybrid UWB Session Controller Configuration
382    *
383    * @param SessionHandle Primary session handle
384    * @param params protocol specific parameters to initiate the hybrid session for controller.
385    */
setHybridSessionControllerConfiguration(in SessionHandle sessionHandle, in PersistableBundle params)386   void setHybridSessionControllerConfiguration(in SessionHandle sessionHandle,
387         in PersistableBundle params);
388 
389   /**
390    * @hide
391    * Sets the Hybrid UWB Session Controlee Configuration
392    *
393    * @param SessionHandle Primary session handle
394    * @param params protocol specific parameters to initiate the hybrid session for controlee.
395    */
setHybridSessionControleeConfiguration(in SessionHandle sessionHandle, in PersistableBundle params)396   void setHybridSessionControleeConfiguration(in SessionHandle sessionHandle,
397         in PersistableBundle params);
398 
updateRangingRoundsDtTag(in SessionHandle sessionHandle, in PersistableBundle parameters)399   void updateRangingRoundsDtTag(in SessionHandle sessionHandle, in PersistableBundle parameters);
400 
getUwbActivityEnergyInfoAsync(in IOnUwbActivityEnergyInfoListener listener)401   void getUwbActivityEnergyInfoAsync(in IOnUwbActivityEnergyInfoListener listener);
402 
403   /**
404    * Returns the max Application Data payload size that can be sent by the UWBS in one ranging
405    * round.
406    */
queryMaxDataSizeBytes(in SessionHandle sessionHandle)407   int queryMaxDataSizeBytes(in SessionHandle sessionHandle);
408 
409   /**
410    * @hide
411    *
412    * @return timestamp in microseconds
413    */
queryUwbsTimestampMicros()414    long queryUwbsTimestampMicros();
415 
416   /**
417    * The maximum allowed time to open a ranging session.
418    */
419   const int RANGING_SESSION_OPEN_THRESHOLD_MS = 3000; // Value TBD
420 
421   /**
422    * The maximum allowed time to start a ranging session.
423    */
424   const int RANGING_SESSION_START_THRESHOLD_MS = 3000; // Value TBD
425 
426   /**
427    * The maximum allowed time to notify the framework that a session has been
428    * closed.
429    */
430   const int RANGING_SESSION_CLOSE_THRESHOLD_MS = 3000; // Value TBD
431 
432   /**
433    * The maximum allowed time to configure ranging rounds update for DT Tag
434    */
435   const int RANGING_ROUNDS_UPDATE_DT_TAG_THRESHOLD_MS = 3000; // Value TBD
436 
437   /**
438    * The maximum allowed time to configure session data transfer phase config
439    */
440   const int SESSION_DATA_TRANSFER_PHASE_CONFIG_THRESHOLD_MS = 3000; // Value TBD
441 
442   /**
443    * The maximum allowed time to configure hybrid session
444    */
445   const int SESSION_CONFIGURATION_THRESHOLD_MS = 3000; // Value TBD
446 }
447