public final class RangingUpdate

Object
RangingUpdate

One measurement of where the peer is, delivered to RangingListener.updated on the EDT.

Every field except the timestamp is optional, and they drop out independently: a peer directly behind the phone commonly reports a distance with no direction, and a peer at the edge of range reports neither. Guard each read with its has method rather than assuming a sentinel value.

public void updated(RangingUpdate u) {
    if (u.hasDistance()) {
        label.setText(String.format("%.1f m", u.getDistance(RangingUnit.METERS)));
    }
    if (u.hasDirection()) {
        arrow.setAngle(u.getAzimuth());
    }
}

Constructors

public RangingUpdate(boolean hasDistance, double distanceMeters, boolean hasDirection, double azimuth, boolean hasElevation, double elevation, float[] vector, long timestamp) Ports construct these; application code receives them through RangingListener.

Methods

`public boolean hasDistance()`	`true` when this update carries a distance measurement.
`public double getDistance(RangingUnit unit)`	The straight-line distance to the peer, in the unit you name.
`public boolean hasDirection()`	`true` when this update carries a horizontal direction.
`public double getAzimuth()`	The horizontal angle to the peer in degrees.
`public boolean hasElevation()`	`true` when this update carries a vertical direction.
`public double getElevation()`	The vertical angle to the peer in degrees, in the range -90 to 90, where positive is above the device.
`public float[] getDirectionVector()`	The platform’s raw unit direction vector as `{x, y, z}` – x to the right, y up, z toward the user, so the forward direction is negative z. iOS only; `null` everywhere else and `null` on iOS whenever `hasDirection()` is `false`.
`public long getTimestamp()`	`System.currentTimeMillis()` at the moment the port received this measurement.
`public` `String toString()`	Returns a string representation of the object.

Inherited methods

From Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait, clone

Constructor details

RangingUpdate

public RangingUpdate(boolean hasDistance, double distanceMeters, boolean hasDirection, double azimuth, boolean hasElevation, double elevation, float[] vector, long timestamp)

Ports construct these; application code receives them through RangingListener.

Parameters

hasDistance boolean: whether this update carries a distance
distanceMeters double: the distance in meters, ignored when hasDistance is false
hasDirection boolean: whether this update carries an azimuth
azimuth double: horizontal angle in degrees, ignored when hasDirection is false
hasElevation boolean: whether this update carries an elevation
elevation double: vertical angle in degrees, ignored when hasElevation is false
vector float[]: the platform’s raw unit direction vector, or null
timestamp long: System.currentTimeMillis() when the port received the measurement

Method details

hasDistance

public boolean hasDistance()

true when this update carries a distance measurement.

getDistance

public double getDistance(RangingUnit unit)

The straight-line distance to the peer, in the unit you name.

Undefined when hasDistance() is false – check first. There is no zero-argument form on purpose; see RangingUnit.

Parameters

unit RangingUnit: the unit to read the distance in

Returns

the distance expressed in unit

hasDirection

public boolean hasDirection()

true when this update carries a horizontal direction.

getAzimuth

public double getAzimuth()

The horizontal angle to the peer in degrees. Zero is straight ahead – out of the top of a phone held upright – and positive is to the right.

Undefined when hasDirection() is false.

The range is platform-dependent, and the difference is meaningful. Apple reports a unit direction vector, which the port folds with atan2(x, -z) into -180 to 180 – so it distinguishes a peer in front from one directly behind. Jetpack UWB reports the angle itself, in degrees, but only over -90 to 90, which does not. Code that needs to know which side of the device a peer is on cannot get that from azimuth alone on Android.

getDirectionVector() still hands back Apple’s untouched vector for code that wants it.

hasElevation

public boolean hasElevation()

true when this update carries a vertical direction.

getElevation

public double getElevation()

The vertical angle to the peer in degrees, in the range -90 to 90, where positive is above the device.

Undefined when hasElevation() is false. Fewer devices report elevation than azimuth, so this drops out on its own.

getDirectionVector

public float[] getDirectionVector()

The platform’s raw unit direction vector as {x, y, z} – x to the right, y up, z toward the user, so the forward direction is negative z. iOS only; null everywhere else and null on iOS whenever hasDirection() is false.

Prefer getAzimuth() and getElevation(), which are derived from this on iOS and reported natively on Android, so they work on both. A fresh copy is returned each call.

getTimestamp

public long getTimestamp()

System.currentTimeMillis() at the moment the port received this measurement. The platforms disagree on what clock their own timestamps use – Android reports elapsed realtime nanoseconds and iOS reports nothing at all – so this is stamped on arrival rather than translated, and is comparable only with other values from this same clock.

toString

public String toString()

Returns a string representation of the object. In general, the toString method returns a string that “textually represents” this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@’, and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: getClass().getName() + ‘@’ + Integer.toHexString(hashCode())