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