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<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 RangingCapabilities which 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, RangingSessionCallback callback)
Initiates a ranging session and start ranging.
abstract Task<Void>
stopRanging(RangingSessionCallback callback)
Closes a ranging session.

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

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

If the method is called when UWB_RANGING permission is not granted, the Task will return with ApiException.

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_DISABLE or UwbRangeDataNtfConfig.RangeDataNtfConfig.RANGE_DATA_NTF_ENABLE is 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, or UWB_RANGING permission is not granted, the Task will return with ApiException.

Otherwise, this method will return successfully with the ranging session reconfigured to skip number of ranging intervals set in intervalSkipCount. If intervalSkipCount is 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 the intervalSkipCount is 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, or UWB_RANGING permission is not granted, or the operation failed due to hardware or firmware issues, the Task will return with ApiException.

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 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 have 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.