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,
RangingSessionCallback callback)
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 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.
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.
One UwbClient 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.