Interface for getting UWB capabilities and interacting with nearby UWB devices to perform ranging.
Public Method Summary
abstract Task<Void> | |
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> | |
abstract Task<Void> |
startRanging(RangingParameters
parameters,
RangingSessionCallbackcallback)
Initiates a ranging session and start ranging.
|
abstract Task<Void> | |
abstract Task<Void> | |
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_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 toROLE_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 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_RANGING
permission 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_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, orUWB_RANGING
permission 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
.
IfintervalSkipCount
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 theintervalSkipCount 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, orUWB_RANGING
permission
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_RANGING
permission. 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_RANGING
permission. 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.
OneUwbClient
can 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.UwbClient
will not receive
callback events any more if successfully unsubscribed.