# Package com.codename1.nearby

package com.codename1.nearby

Nearby devices: how far away one is, which one is yours, and how to send it something.

The three questions are answered by three sub-packages, and they are separate packages rather than one because referencing a package is the only opt-in there is. The build server decides what native machinery an app gets by scanning bytecode for these prefixes, and it has no way to express an exclusion -- so an app that only wants to know how far away its keyring tag is must not pay for the Play Services dependency and the Wi-Fi permissions that device-to-device transport costs.

- `com.codename1.nearby.ranging` -- ultra-wideband precision ranging. Distance to within about ten centimeters, and direction on hardware that has the antennas for it.
- `com.codename1.nearby.companion` -- the OS-managed association between this app and one particular accessory, which buys background presence notifications and scanning that does not need location permission.
- `com.codename1.nearby.transport` -- moving bytes and files to a device in the same room, with no access point and no internet. Same-ecosystem only; the package documentation says why and what to use instead.

This package itself holds only what all three share: `NearbyError`, `NearbyException`, `NearbyAvailability` and `NearbyPermission`. Referencing it alone costs nothing.

##### How this relates to what was already here

Ranging is not a replacement for `com.codename1.bluetooth` -- it needs it. Both platforms require the two devices to swap a token over some channel they already share before any radio ranging can start, and a GATT characteristic is the usual channel. The two APIs are designed to be used together.

Nor does any of this replace RSSI-based proximity: an app that only needs "near or far" can read the signal strength of a `com.codename1.bluetooth.le` advertisement on every device ever made, where UWB needs hardware from 2019 onward.

- Related Packages
  Package
  Description
  com.codename1.nearby.companion
  Companion-device association: telling the operating system which accessory is yours, and getting privileges back for it.
  com.codename1.nearby.ranging
  Ultra-wideband precision ranging: how far away another device is, and in which direction.
  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
  NearbyAvailability
  How much of a `com.codename1.nearby` feature is really usable right now.
  NearbyError
  Typed error codes carried by every `NearbyException` thrown through the failure path of the `com.codename1.nearby` APIs.
  NearbyException
  Thrown through the failure path of every `AsyncResource` returned by the `com.codename1.nearby` APIs, and passed to the failure callbacks of the ranging and transport listeners.
  NearbyPermission
  The runtime permissions the `com.codename1.nearby` APIs may need, named by what the app is trying to do rather than by any one platform's permission string.