UwbClient

public interfaceUwbClientimplementsHasApiKey<UwbOptions>

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

Public Method Summary

abstract Task<Void>
addControlee(UwbAddress address)
Dynamically adds a controlee to an active ranging session.
abstract Task<Void>
addControleeWithSessionParams(RangingControleeParameters params)
Dynamically adds a controlee to an active ranging session.
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 RangingCapabilitieswhich the device supports.
abstract Task<Boolean>
isAvailable()
Returns whether UWB is currently usable.
abstract Task<Void>
reconfigureRangeDataNtf(int configType, int proximityNear, int proximityFar)
Dynamically reconfigures range data notification config to an active ranging session.
abstract Task<Void>
reconfigureRangingInterval(int intervalSkipCount)
Dynamically reconfigures ranging interval to an active ranging session.
abstract Task<Void>
removeControlee(UwbAddress address)
Dynamically removes a controlee from an active ranging session.
abstract Task<Void>
startRanging(RangingParameters parameters, RangingSessionCallbackcallback)
Initiates a ranging session and start ranging.
abstract Task<Void>
stopRanging(RangingSessionCallback callback)
Closes a ranging session.
abstract Task<Void>
subscribeToUwbAvailability(UwbAvailabilityObserver observer)
Subscribes to UWB availability events.
abstract Task<Void>
unsubscribeFromUwbAvailability()
Unsubscribes from UWB availability events.

Public Methods

public abstract Task<Void>addControlee(UwbAddress address)

Dynamically adds a controlee to an active ranging session. This method can only be called by a controller. The controlee to be added must be configured with the a set of parameters that can join the existing connection.

If the method is called by a controlee, or the profile is a unicast profile, or UWB_RANGINGpermission is not granted, the Task will return with ApiException.

Otherwise, this method will return successfully, then clients are expected to handle either RangingSessionCallback.onRangingInitialized(UwbDevice)or RangingSessionCallback.onRangingSuspended(UwbDevice, int)to listen for starts or failures. The controlee is used as the first parameter of these callbacks.

public abstract Task<Void>addControleeWithSessionParams(RangingControleeParameters params)

Dynamically adds a controlee to an active ranging session. This method can only be called by a controller. This method is for Provisioned STS individual key case. SubSessionId and subSessionKey should be provided by the controlees.

If the method is called by a controlee, or the profile is a unicast profile, or UWB_RANGINGpermission is not granted, the Task will return with ApiException.

Otherwise, this method will return successfully, then clients are expected to handle either RangingSessionCallback.onRangingInitialized(UwbDevice)or RangingSessionCallback.onRangingSuspended(UwbDevice, int)to listen for starts or failures. The controlee is used as the first parameter of these callbacks.

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 toROLE_CONTROLLEEin 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 theRangingCapabilities 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>reconfigureRangeDataNtf(int configType, int proximityNear, int proximityFar)

Dynamically reconfigures range data notification config to an active ranging session.

If the method is called whenUWB_RANGINGpermission is not granted, the Task will return withApiException.

Otherwise, this method will reconfigure range data notification configuration with UwbRangeDataNtfConfig.RangeDataNtfConfig.All the supported notification configs are obtained by RangingCapabilities.getSupportedNtfConfigs().

Parameters
configType the type of range data notification configuration to apply. Valid values are defined by the UwbRangeDataNtfConfig.RangeDataNtfConfig.If UwbRangeDataNtfConfig.RangeDataNtfConfig.RANGE_DATA_NTF_DISABLEor UwbRangeDataNtfConfig.RangeDataNtfConfig.RANGE_DATA_NTF_ENABLEis used, below parameters are ignored
proximityNear the proximity near value in centimeters for range data notification config. This value must be within the range of 0 to 20000 (inclusive). Default is 0.
proximityFar the proximity far value in centimeters for range data notification config. This value must be within the range of 0 to 20000 (inclusive). Default is 20000.
Throws
IllegalArgumentException if any of the parameters are outside the valid range.

public abstract Task<Void>reconfigureRangingInterval(int intervalSkipCount)

Dynamically reconfigures ranging interval to an active ranging session. This method can only be called by a controller.

If the method is called by a controlee, orUWB_RANGINGpermission is not granted, the Task will return withApiException.

Otherwise, this method will return successfully with the ranging session reconfigured to skip number of ranging intervals set inintervalSkipCount. IfintervalSkipCountis set to 0, the ranging interval will be set to the interval used when startRanging(RangingParameters, RangingSessionCallback)was called.

Example: If ranging interval is 200ms,intervalSkipCount=3 would skip 3*200=600ms, then the effective interval would be 800ms.

Parameters
intervalSkipCount the number of intervals to skip between range measurements. The value must be within the range of 0 to 255 (inclusive).
Throws
IllegalArgumentException if theintervalSkipCountis outside the valid range.

public abstract Task<Void>removeControlee(UwbAddress address)

Dynamically removes a controlee from an active ranging session. This method can only be called by a controller.

If the method is called by a controlee, or the address doesn't belong to an active controlee, or the profile is a unicast profile, orUWB_RANGINGpermission is not granted, or the operation failed due to hardware or firmware issues, the Task will return withApiException.

Otherwise, this method will return successfully, then clients are expected to handle RangingSessionCallback.onRangingSuspended(UwbDevice, int)with the controlee as parameter of the callback.

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

Initiates a ranging session and start ranging.

Ranging requires theandroid.permission.UWB_RANGINGpermission. Apps must have been granted this permission before calling this method, otherwise the task will return withApiException

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

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

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 theandroid.permission.UWB_RANGINGpermission. Apps must have been granted this permission before calling this method, otherwise the task will return withApiException

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 withApiException

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

public abstract Task<Void>subscribeToUwbAvailability(UwbAvailabilityObserver observer)

Subscribes to UWB availability events. The event will be sent back through UwbAvailabilityObserver when UWB state is toggled.

OneUwbClientcan only have one subscription. If a new subscription is added, the older one will be unsubscribed. The subscription will be cleared if the app is closed or inactive for a few minutes.

public abstract Task<Void>unsubscribeFromUwbAvailability()

Unsubscribes from UWB availability events.UwbClientwill not receive callback events any more if successfully unsubscribed.