UwbClient

public interface UwbClient implements HasApiKey<UwbOptions>

Interface for getting UWB capabilities and interacting with nearby UWB devices to perform ranging.

Public Method Summary

abstract Task<UwbComplexChannel>
getComplexChannel()
Gets the local device's complex channel which can be used for ranging, if it exists.
abstract Task<UwbAddress>
getLocalAddress()
Gets the local device's UWB address, if it exists.
abstract Task<RangingCapabilities>
getRangingCapabilities()
Returns the RangingCapabilities which the device supports.
abstract Task<Boolean>
isAvailable()
Returns whether UWB is currently usable.
abstract Task<Void>
startRanging(RangingParameters parameters, RangingSessionCallback callback)
Initiates a ranging session and start ranging.
abstract Task<Void>
stopRanging(RangingSessionCallback callback)
Closes a ranging session.

Public Methods

public abstract Task<UwbComplexChannel> getComplexChannel ()

Gets the local device's complex channel which can be used for ranging, if it exists. If UWB is not supported, or the role is set to ROLE_CONTROLLEE in UwbOptions, then the call will fail.

A complex channel can only be used for a single ranging session. After a ranging session is ended through stopRanging(RangingSessionCallback), a new channel will be allocated and clients should get the new channel via this method before attempting to start another ranging session.

Ranging session duration may also be limited to prevent channels from being used for too long. In this case, your ranging session would be suspended and clients would need to exchange the new channel with their peer before starting again.

public abstract Task<UwbAddress> getLocalAddress ()

Gets the local device's UWB address, if it exists. If UWB is not supported, then the call will fail.

A local address can only be used for a single ranging session. After a ranging session is ended through stopRanging(RangingSessionCallback)), a new address will be allocated and clients should get the new address via this method before attempting to start another ranging session.

Ranging session duration may also be limited to prevent addresses from being used for too long. In this case, your ranging session would be suspended and clients would need to exchange the new address with their peer before starting again.

public abstract Task<RangingCapabilities> getRangingCapabilities ()

Returns the RangingCapabilities which the device supports.

public abstract Task<Boolean> isAvailable ()

Returns whether UWB is currently usable. Possible reasons for which it isn’t usable include airplane mode, or location disabled, or UWB hardware is busy.

public abstract Task<Void> startRanging (RangingParameters parameters, RangingSessionCallback callback)

Initiates a ranging session and start ranging.

Ranging requires the android.permission.UWB_RANGING permission. Apps must have been granted this permission before calling this method, otherwise the task will return with ApiException

If the client is ranging before this call, the task will return with ApiException

If the client starts a controlee session without setting complex channel and peer address, the task will return with ApiException

Otherwise, this method will return successfully, then clients are expected to handle both RangingSessionCallback.onRangingInitialized(UwbDevice) and RangingSessionCallback.onRangingSuspended(UwbDevice, int) to listen for starts or failures.

Parameters
parameters uwbConfigId and peer devices must be set explicitly. For Controlee sessions, complex channel must be set.
callback

public abstract Task<Void> stopRanging (RangingSessionCallback callback)

Closes a ranging session. If a session was opened successfully, (startRanging returns successfully and RangingSessionCallback.onRangingInitialized(UwbDevice) was called), then make sure this function is called to close the session properly.

Ranging requires the android.permission.UWB_RANGING permission. Apps must requested and been granted this permission before calling this method, otherwise the task will return with ApiException

If the client hasn't started ranging before this call, the task will return with ApiException

If the ranging can't be stopped due to hardware or firmware issues, the task will return with ApiException

Otherwise, this method will return successfully and RangingSessionCallback.onRangingSuspended(UwbDevice, int) will be called.