UWB and Nearby Devices: Distance, Direction, Association, and Transport

Ultra-wideband (UWB) technology offers precise location and direction information, unlike Bluetooth, which only provides a general idea of distance and direction. UWB can determine the exact distance down to 42 centimeters and the angle relative to the device's orientation. However, UWB capabilities vary between operating systems, with Apple's local transport being incompatible with Google's.

To address this, Codename One, an open-source framework, has introduced three packages under com.codename1.nearby to handle distance, direction, association, and transport between nearby devices.

The API is divided into three packages: ranging, companion, and transport. Ranging focuses on determining the distance and direction to a nearby device. Companion deals with associating a specific accessory or device with the app. Transport handles the exchange of data payloads between nearby instances. Developers opt-in to these packages individually, ensuring that only the necessary functionality is included in the app.

Before using ranging capabilities, the app must check if UWB is supported by the device. If not, the app should provide alternative methods for finding nearby devices. Ranging begins after both devices exchange a token, typically over a Bluetooth Low Energy (BLE) channel. Once the token is received, the session can be prepared and a listener set up to track distance and direction updates.

The RangingUpdate field contains various optional data points, including distance and direction. Distance is reported in centimeters, while direction is provided as an azimuth angle, with zero pointing straight ahead and positive values to the right. On Android, azimuth ranges from -90 to 90 degrees, while iOS provides a direction vector.

Elevation is available on both platforms when applicable. Each session tracks only one peer, reflecting Apple's limit on the number of nearby peer configurations. Multiple sessions can be used to track several peers simultaneously.

Accessory ranging has specific handshakes for iOS and Android. iOS uses the Nearby Interaction Accessory Protocol and forwards specific bytes to the accessory, while Android incorporates the UWB address, channel, preamble, session ID, and accessory-specific key. Tokens serialized on one platform may not be compatible with other platforms, leading to compatibility issues.

Association with a device is not Bluetooth pairing but rather a chooser interface provided by the operating system, allowing the user to select the desired accessory. Once associated, the app receives a durable association ID, which is stored for future use.