Class RangingUpdate

java.lang.Object
com.codename1.nearby.ranging.RangingUpdate
public final class RangingUpdate extends Object

One measurement of where the peer is, delivered to RangingListener.updated(RangingUpdate) 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());
    }
}

  • Constructor Summary

    Constructors
    Constructor
    Description
    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.

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    getAzimuth()
    The horizontal angle to the peer in degrees.
    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.
    double
    getDistance(RangingUnit unit)
    The straight-line distance to the peer, in the unit you name.
    double
    getElevation()
    The vertical angle to the peer in degrees, in the range -90 to 90, where positive is above the device.
    long
    getTimestamp()
    System.currentTimeMillis() at the moment the port received this measurement.
    boolean
    hasDirection()
    true when this update carries a horizontal direction.
    boolean
    hasDistance()
    true when this update carries a distance measurement.
    boolean
    hasElevation()
    true when this update carries a vertical direction.
    String
    toString()
    Returns a string representation of the object.

    Methods inherited from class Object

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

  • 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: whether this update carries a distance
      • distanceMeters: the distance in meters, ignored when hasDistance is false
      • hasDirection: whether this update carries an azimuth
      • azimuth: horizontal angle in degrees, ignored when hasDirection is false
      • hasElevation: whether this update carries an elevation
      • elevation: vertical angle in degrees, ignored when hasElevation is false
      • vector: the platform's raw unit direction vector, or null
      • timestamp: 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: 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()
      Description copied from class: Object
      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())
      Overrides:
      toString in class Object