# Package com.codename1.nearby.ranging

package com.codename1.nearby.ranging

Ultra-wideband precision ranging: how far away another device is, and in which direction.

UWB measures distance by timing a radio round trip, which is worth about ten centimeters. That is a different kind of answer from a Bluetooth signal-strength estimate, which is worth a few meters on a good day and swings wildly when someone puts a hand over the phone -- so this is what makes "unlock as I walk up to the door" and "point me at my bag" work at all.

Start at `Ranging`. The shape of a session, and why it takes two steps, is documented there.

##### What it costs to reference this package

On iOS the build links NearbyInteraction.framework and injects the two Nearby Interaction privacy strings. On Android it adds the `androidx.core.uwb` dependency and the `UWB_RANGING` permission, and declares the UWB hardware feature as optional so the app still installs on devices without the radio.

##### Hardware, not just platform

`Ranging.isSupported()` answers `false` on plenty of current phones -- iPhones before the 11, and most Android devices. Treat ranging as an enhancement to a feature that also works without it rather than as the feature itself.

- Related Packages
  Package
  Description
  com.codename1.nearby
  Nearby devices: how far away one is, which one is yours, and how to send it something.
  com.codename1.nearby.companion
  Companion-device association: telling the operating system which accessory is yours, and getting privileges back for it.
  com.codename1.nearby.spi
  The service-provider interface each port implements to carry `com.codename1.nearby` onto the platform's short-range stacks.
  com.codename1.nearby.transport
  Sending bytes and files to a device in the same room, with no access point, no pairing and no internet.
- Class
  Description
  Ranging
  Precision ranging: how far away another device is, and in which direction.
  RangingAdapter
  A `RangingListener` whose methods all do nothing, so a caller interested in one event overrides one method.
  RangingCapabilities
  What the current device can actually measure.
  RangingListener
  Receives everything a `RangingSession` has to say.
  RangingRemovalReason
  Why a peer stopped being ranged, delivered to `RangingListener.peerRemoved(RangingRemovalReason)`.
  RangingRole
  Which end of a UWB session this device is.
  RangingSession
  One ranging conversation with one peer or accessory, obtained from `Ranging.prepareSession(RangingRole)`.
  RangingToken
  The handle one device publishes so another can range against it.
  RangingUnit
  The unit a distance is read in.
  RangingUpdate
  One measurement of where the peer is, delivered to `RangingListener.updated(RangingUpdate)` on the EDT.