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.

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