RangingParameters

public final class RangingParameters


Set of parameters which should be passed to the UWB chip to start ranging.

Summary

Constants

static final int

Pre-defined one-to-many STATIC STS DS-TWR ranging

static final int

Same as CONFIG_MULTICAST_DS_TWR, except P-STS individual controlee key mode is enabled.

static final int

Same as CONFIG_MULTICAST_DS_TWR, except P-STS security mode is enabled.

static final int

Same as CONFIG_UNICAST_DS_TWR, except P-STS security mode is enabled.

static final int

Pre-defined unicast STATIC STS DS-TWR ranging.

static final long

1 millisecond slot duration

static final long

2 millisecond slot duration

static final int

When the screen is on, the reporting interval is hundreds of milliseconds.

static final int

The reporting interval is the same as in the AUTOMATIC screen-on case.

static final int

The reporting interval is the same as in the AUTOMATIC screen-off case.

Public constructors

RangingParameters(
    int uwbConfigType,
    int sessionId,
    int subSessionId,
    byte[] sessionKeyInfo,
    byte[] subSessionKeyInfo,
    UwbComplexChannel complexChannel,
    @NonNull List<@NonNull UwbDevice> peerDevices,
    int updateRateType,
    UwbRangeDataNtfConfig uwbRangeDataNtfConfig,
    @IntRange(from = 1, to = 2) long slotDurationMillis,
    boolean isAoaDisabled
)

Public methods

final UwbComplexChannel

Optional.

final @NonNull List<@NonNull UwbDevice>

The peers to perform ranging with.

final int

The ID of the ranging session.

final byte[]

The session key info to use for the ranging.

final long

The slot duration of the ranging session in millisecond.

final int

The ID of the ranging sub-session.

final byte[]

The sub-session key info to use for the ranging.

final int

The update rate type of the ranging data.

final int

The UWB configuration type.

final UwbRangeDataNtfConfig

Configurable range data notification reports for a UWB session.

final boolean

The indicator of whether angle of arrival (AoA) is disabled.

Constants

CONFIG_MULTICAST_DS_TWR

public static final int CONFIG_MULTICAST_DS_TWR = 2

Pre-defined one-to-many STATIC STS DS-TWR ranging

deferred mode, ranging interval = 200 ms, slot duration = 2400 RSTU, slots per ranging round = 20

All other MAC parameters use FiRa/UCI default values.

Typical use case: smart phone interacts with many smart devices

CONFIG_PROVISIONED_INDIVIDUAL_MULTICAST_DS_TWR

public static final int CONFIG_PROVISIONED_INDIVIDUAL_MULTICAST_DS_TWR = 7

Same as CONFIG_MULTICAST_DS_TWR, except P-STS individual controlee key mode is enabled.

CONFIG_PROVISIONED_MULTICAST_DS_TWR

public static final int CONFIG_PROVISIONED_MULTICAST_DS_TWR = 5

Same as CONFIG_MULTICAST_DS_TWR, except P-STS security mode is enabled.

CONFIG_PROVISIONED_UNICAST_DS_TWR

public static final int CONFIG_PROVISIONED_UNICAST_DS_TWR = 4

Same as CONFIG_UNICAST_DS_TWR, except P-STS security mode is enabled.

CONFIG_UNICAST_DS_TWR

public static final int CONFIG_UNICAST_DS_TWR = 1

Pre-defined unicast STATIC STS DS-TWR ranging.

deferred mode, ranging interval = 240 ms, slot duration = 2400 RSTU, slots per ranging round = 6

All other MAC parameters use FiRa/UCI default values.

Typical use case: device tracking tags

RANGING_SLOT_DURATION_1_MILLIS

public static final long RANGING_SLOT_DURATION_1_MILLIS = 1

1 millisecond slot duration

RANGING_SLOT_DURATION_2_MILLIS

public static final long RANGING_SLOT_DURATION_2_MILLIS = 2

2 millisecond slot duration

RANGING_UPDATE_RATE_AUTOMATIC

public static final int RANGING_UPDATE_RATE_AUTOMATIC = 1

When the screen is on, the reporting interval is hundreds of milliseconds. When the screen is off, the reporting interval is a few seconds.

RANGING_UPDATE_RATE_FREQUENT

public static final int RANGING_UPDATE_RATE_FREQUENT = 3

The reporting interval is the same as in the AUTOMATIC screen-on case.

The actual reporting interval is UwbConfigId related. Different configuration may use different values. (The default reporting interval at INFREQUENT mode is 4 seconds)

RANGING_UPDATE_RATE_INFREQUENT

public static final int RANGING_UPDATE_RATE_INFREQUENT = 2

The reporting interval is the same as in the AUTOMATIC screen-off case. The The power consumption is optimized by turning off the radio between ranging reports. (The implementation is hardware and software dependent and it may change between different versions.)

Public constructors

RangingParameters

Added in 1.0.0-alpha08
public RangingParameters(
    int uwbConfigType,
    int sessionId,
    int subSessionId,
    byte[] sessionKeyInfo,
    byte[] subSessionKeyInfo,
    UwbComplexChannel complexChannel,
    @NonNull List<@NonNull UwbDevice> peerDevices,
    int updateRateType,
    UwbRangeDataNtfConfig uwbRangeDataNtfConfig,
    @IntRange(from = 1, to = 2) long slotDurationMillis,
    boolean isAoaDisabled
)

Public methods

getComplexChannel

Added in 1.0.0-alpha08
public final UwbComplexChannel getComplexChannel()

Optional. If device type is ROLE_CONTROLEE then complex channel should be set.

getPeerDevices

Added in 1.0.0-alpha08
public final @NonNull List<@NonNull UwbDevicegetPeerDevices()

The peers to perform ranging with. If using unicast, length should be 1.

getSessionId

Added in 1.0.0-alpha08
public final int getSessionId()

The ID of the ranging session. If the value is SESSION_ID_UNSET (0), it will be created from the hash of controller address and complex channel values.

The same session IDs should be used at both ends (Controller and controlee).

getSessionKeyInfo

Added in 1.0.0-alpha08
public final byte[] getSessionKeyInfo()

The session key info to use for the ranging. If the profile uses STATIC STS, this byte array is 8-byte long with first two bytes as Vendor_ID and next six bytes as STATIC_STS_IV. If the profile uses PROVISIONED STS, this byte array is 16 or 32-byte long which represent session key.

The same session keys should be used at both ends (Controller and controlee).

getSlotDurationMillis

Added in 1.0.0-alpha08
public final long getSlotDurationMillis()

The slot duration of the ranging session in millisecond. The available slot durations are RANGING_SLOT_DURATION_1_MILLIS and RANGING_SLOT_DURATION_2_MILLIS. Default to RANGING_SLOT_DURATION_2_MILLIS.

getSubSessionId

Added in 1.0.0-alpha08
public final int getSubSessionId()

The ID of the ranging sub-session. This value should be set when the Provisioned STS individual responder case is used. If other config is used, it should remain SUB_SESSION_UNSET (0)

getSubSessionKeyInfo

Added in 1.0.0-alpha08
public final byte[] getSubSessionKeyInfo()

The sub-session key info to use for the ranging. This byte array is 16 or 32-byte long when the profile uses PROVISIONED STS individual responder cases. If other STS is used, this field should remain null.

getUpdateRateType

Added in 1.0.0-alpha08
public final int getUpdateRateType()

The update rate type of the ranging data. The update rate types include RANGING_UPDATE_RATE_AUTOMATIC, RANGING_UPDATE_RATE_FREQUENT, and RANGING_UPDATE_RATE_INFREQUENT.

getUwbConfigType

Added in 1.0.0-alpha08
public final int getUwbConfigType()

The UWB configuration type. One type specifies one fixed set of pre-defined parameters. The UWB config type includes CONFIG_UNICAST_DS_TWR and CONFIG_MULTICAST_DS_TWR.

getUwbRangeDataNtfConfig

Added in 1.0.0-alpha08
public final UwbRangeDataNtfConfig getUwbRangeDataNtfConfig()

Configurable range data notification reports for a UWB session.

isAoaDisabled

Added in 1.0.0-alpha08
public final boolean isAoaDisabled()

The indicator of whether angle of arrival (AoA) is disabled. Default to false.