RangingParameters

class RangingParameters

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

Summary

Constants
const Int

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

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

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

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

Pre-defined unicast STATIC STS DS-TWR ranging.
const Long

1 millisecond slot duration
const Long

2 millisecond slot duration
const Int

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

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

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

Public constructors
RangingParameters(
    uwbConfigType: Int,
    sessionId: Int,
    subSessionId: Int,
    sessionKeyInfo: ByteArray?,
    subSessionKeyInfo: ByteArray?,
    complexChannel: UwbComplexChannel?,
    peerDevices: List<UwbDevice>,
    updateRateType: Int,
    uwbRangeDataNtfConfig: UwbRangeDataNtfConfig?,
    slotDurationMillis: @IntRange(from = 1, to = 2) Long,
    isAoaDisabled: Boolean
)

Public properties
UwbComplexChannel?

Optional.
Boolean

The indicator of whether angle of arrival (AoA) is disabled.
List<UwbDevice>

The peers to perform ranging with.
Int

The ID of the ranging session.
ByteArray?

The session key info to use for the ranging.
Long

The slot duration of the ranging session in millisecond.
Int

The ID of the ranging sub-session.
ByteArray?

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

The update rate type of the ranging data.
Int

The UWB configuration type.
UwbRangeDataNtfConfig?

Configurable range data notification reports for a UWB session.

Constants

CONFIG_MULTICAST_DS_TWR

const val CONFIG_MULTICAST_DS_TWR = 2: Int

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, hopping mode is enabled

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

const val CONFIG_PROVISIONED_INDIVIDUAL_MULTICAST_DS_TWR = 7: Int

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

CONFIG_PROVISIONED_MULTICAST_DS_TWR

const val CONFIG_PROVISIONED_MULTICAST_DS_TWR = 5: Int

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

CONFIG_PROVISIONED_UNICAST_DS_TWR

const val CONFIG_PROVISIONED_UNICAST_DS_TWR = 4: Int

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

CONFIG_UNICAST_DS_TWR

const val CONFIG_UNICAST_DS_TWR = 1: Int

Pre-defined unicast STATIC STS DS-TWR ranging.

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

All other MAC parameters use FiRa/UCI default values.

Typical use case: device tracking tags

RANGING_SLOT_DURATION_1_MILLIS

const val RANGING_SLOT_DURATION_1_MILLIS = 1: Long

1 millisecond slot duration

RANGING_SLOT_DURATION_2_MILLIS

const val RANGING_SLOT_DURATION_2_MILLIS = 2: Long

2 millisecond slot duration

RANGING_UPDATE_RATE_AUTOMATIC

const val RANGING_UPDATE_RATE_AUTOMATIC = 1: Int

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

const val RANGING_UPDATE_RATE_FREQUENT = 3: Int

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

const val RANGING_UPDATE_RATE_INFREQUENT = 2: Int

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-alpha09
RangingParameters(
    uwbConfigType: Int,
    sessionId: Int,
    subSessionId: Int,
    sessionKeyInfo: ByteArray?,
    subSessionKeyInfo: ByteArray?,
    complexChannel: UwbComplexChannel?,
    peerDevices: List<UwbDevice>,
    updateRateType: Int,
    uwbRangeDataNtfConfig: UwbRangeDataNtfConfig? = null,
    slotDurationMillis: @IntRange(from = 1, to = 2) Long = RANGING_SLOT_DURATION_2_MILLIS,
    isAoaDisabled: Boolean = false
)

Public properties

complexChannel

Added in 1.0.0-alpha09
val complexChannel: UwbComplexChannel?

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

isAoaDisabled

Added in 1.0.0-alpha09
val isAoaDisabled: Boolean

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

peerDevices

Added in 1.0.0-alpha09
val peerDevices: List<UwbDevice>

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

sessionId

Added in 1.0.0-alpha09
val sessionId: Int

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

sessionKeyInfo

Added in 1.0.0-alpha09
val sessionKeyInfo: ByteArray?

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

slotDurationMillis

Added in 1.0.0-alpha09
val slotDurationMillis: Long

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.

subSessionId

Added in 1.0.0-alpha09
val subSessionId: Int

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)

subSessionKeyInfo

Added in 1.0.0-alpha09
val subSessionKeyInfo: ByteArray?

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.

updateRateType

Added in 1.0.0-alpha09
val updateRateType: Int

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.

uwbConfigType

Added in 1.0.0-alpha09
val uwbConfigType: Int

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.

uwbRangeDataNtfConfig

Added in 1.0.0-alpha09
val uwbRangeDataNtfConfig: UwbRangeDataNtfConfig?

Configurable range data notification reports for a UWB session.