Android 16 (API level 36) introduces the Ranging module, which provides a unified and standardized interface for precise ranging between devices. You can use this API surface to measure the distance and position of peer devices without needing to handle each ranging technology individually.
The Ranging module supports the following technologies:
- Ultra-wideband
- Bluetooth channel sounding
- Wi-Fi NAN RTT
- Bluetooth RSSI ranging
- Wi-Fi Proximity Detection on Android 17 (API level 37) and higher
Ranging capabilities and availability
The RangingManager class provides apps with information about the ranging
technologies supported by the local device, as well as the availability and
capabilities of each technology. Apps can register a
RangingCapabilitiesCallback interface to receive updates on any changes
to the availability or capabilities of any supported technologies.
Device roles
A device participating in a ranging session must be an initiator, a responder,
or a Downlink-TDoA Tag (DT-Tag) for UWB Downlink-TDoA sessions on
Android 17 (API level 37) and higher. The initiator device starts the ranging
session with one or more responder devices. A responder device responds to
ranging requests from only one initiator at a time. In a UWB Downlink Time
Difference of Arrival (DL-TDoA) session, the device uses the
DEVICE_ROLE_DT_TAG role to receive signals from multiple UWB anchors.
You can specify the role for a given device in a ranging session with the
RangingPreference class.
Ranging session types
When starting a ranging session between devices, it's often necessary to establish an out-of-band (OOB) data transport to exchange parameters for the session.
The Ranging module can handle OOB negotiations for you, but it also supports custom OOB implementations.
Default OOB implementation
In this session type (RANGING_SESSION_OOB), the Ranging module handles
OOB negotiations to start a ranging session. It selects suitable parameters
based on the ranging preferences provided by the app, and it uses the
appropriate technologies based on what both devices support. This session type
uses a standardized OOB specification. On Android 16 QPR2 (API level 36.1)
and higher, initiators can restrict which technologies are negotiated by
calling setRangingTechnologyFilter on
OobInitiatorRangingConfig.Builder.
The Ranging module only defines the OOB data format and sequence to be used to interact with a peer device. It doesn't handle peer device discovery or connection establishment.
Custom OOB implementation
In this session type (RANGING_SESSION_RAW), the app bypasses the Ranging
module's OOB flow and handles its own OOB negotiation and parameters. That means
the app must determine which technologies the peer device supports, negotiate
ranging parameters, and begin the ranging session.
Ranging preferences
Use a RangingPreference object to specify the selected parameters for a
ranging session. This includes the following:
- Device role. This indicates whether the device is the initiator, the responder, or a DT-Tag on Android 17 (API level 37) and higher.
- Ranging configuration. A
RangingConfigobject specifies the ranging session type and other parameters needed to start a ranging session. - Session configuration. A
SessionConfigobject specifies parameters to be enforced on the ranging session such as measurement limit, sensor fusion, geofence configuration, and more. On Android 17 (API level 37) and higher, you can also configure the antenna mode (ANTENNA_MODE_DIRECTIONALorANTENNA_MODE_OMNI) withsetAntennaModeonSessionConfig.Builderafter checking supported modes withgetSupportedAntennaModesonUwbRangingCapabilities.
Ranging permission
The Ranging module uses a unified permission (android.permission.RANGING) for
peer-to-peer ranging technologies. This permission is in the
NEARBY_DEVICES_PERMISSIONS list.
<uses-permission android:name="android.permission.RANGING" />
Restrictions and limitations
The Ranging module might restrict ranging for several reasons, including the following:
- Third-party apps are only allowed to perform background ranging with ultra-wideband, and only on supported devices. Ranging in the background with other technologies is not allowed.
- Ranging is not allowed when the maximum number of concurrent ranging sessions by device has been reached.
- Ranging might be restricted due to system health concerns such as battery, performance, or memory.
The Ranging module also has the following known limitations:
- The Ranging module only supports delivery of ranging data to peer devices for ultra-wideband. For other technologies, the Ranging module only delivers ranging data to the initiator device.
- The Ranging module only supports dynamic addition of devices in raw ranging mode, and only for ultra-wideband.
- The Ranging module doesn't support one-to-many ultra-wideband sessions for default OOB implementations. If you pass in multiple device handles, the module creates a one-to-one session for each peer device that supports ultra-wideband.
Conduct a ranging session
To conduct a ranging session using the Ranging module, follow these steps:
- Verify that all devices run Android 16 (API level 36) and higher.
- Request the
android.permission.RANGINGpermission in the app manifest. - Assess the capabilities and availability of ranging technologies.
- Discover a peer device for ranging operations.
- Establish a connection for an out-of-band exchange, using either of the session types described in Ranging session types.
- Initiate ranging and continuously acquire ranging data.
- Terminate the ranging session.
The following code sample demonstrates these steps for both the initiator role and the responder role.
class RangingApp { // Starts a ranging session on the initiator side. fun startRangingInitiator( context: Context, deviceHandle: DeviceHandle, executor: Executor, callback: RangingSession.Callback ): RangingSession? { // Get the RangingManager which is the entry point for ranging module. val manager = context.getSystemService(RangingManager::class.java) // Create a new RangingSession using the provided executor and callback. val session = manager.createRangingSession(executor, callback) ?: return null // Create an OobInitiatorRangingConfig, which specifies the ranging parameters for // the initiator role. val config = OobInitiatorRangingConfig.Builder() .setFastestRangingInterval(Duration.ofMillis(100)) .setSlowestRangingInterval(Duration.ofMillis(5000)) .setRangingMode(RANGING_MODE_AUTO) .setSecurityLevel(SECURITY_LEVEL_BASIC) .addDeviceHandle(deviceHandle) .build() // Create a RangingPreference, which specifies the role (initiator) and // configuration for the ranging session. val preference = RangingPreference.Builder(DEVICE_ROLE_INITIATOR, config).build() // Start ranging session. Ranging data is delivered asynchronously through // callback.onResults; call stopRanging(session) when ranging is no longer needed. session.start(preference) return session } // Starts a ranging session on the responder side. fun startRangingResponder( context: Context, deviceHandle: DeviceHandle, executor: Executor, callback: RangingSession.Callback ): RangingSession? { // Get the RangingManager which is the entry point for ranging module. val manager = context.getSystemService(RangingManager::class.java) // Create a new RangingSession using the provided executor and callback. val session = manager.createRangingSession(executor, callback) ?: return null // Create an OobResponderRangingConfig, which specifies the ranging parameters for // the responder role. val config = OobResponderRangingConfig.Builder(deviceHandle).build() // Create a RangingPreference, which specifies the role (responder) and // configuration for the ranging session. val preference = RangingPreference.Builder(DEVICE_ROLE_RESPONDER, config).build() // Start the ranging session. Call stopRanging(session) when finished. session.start(preference) return session } // Stops an active ranging session. fun stopRanging(session: RangingSession) { session.stop() } }
Handle ranging results and peer motion
When a session is active, RangingSession.Callback delivers distance and
angle-of-arrival measurements in RangingData objects through
onResults:
- Distance uncertainty. On Android 16 QPR2 (API level 36.1) and higher,
call
hasDistanceStandardDeviationandgetDistanceStandardDeviationMetersonRangingDatato inspect the standard deviation of distance measurements when available. - Technology-specific extras. On Android 17 (API level 37) and higher,
call
getRangingDataExtrasonRangingDatato retrieve aRangingDataExtrasobject containing technology-specific metadata, such asBleSpecificData,UwbSpecificData, orWifiRttSpecificData. - Peer motion state. On Android 17 (API level 37) and higher, override
onMotionReceivedinRangingSession.Callbackto receiveMotionStateupdates (MOTION_NOT_DETECTED,MOTION_SLIGHT,MOTION_MODERATE, orMOTION_LARGE) when a peer device's movement changes.
UWB interoperability with iOS devices
The Ranging module supports interoperability with iOS devices using ultra-wideband (UWB). To range with an iOS device, you must use a custom OOB implementation and configure the ranging session with specific parameters that match the Apple Nearby Interaction Accessory Protocol. For an example, see the sample app.
When creating the RangingPreference, use RawRangingDevice and
UwbRangingParams to specify the configuration. The following parameters are
crucial for iOS interoperability:
- Configuration ID. Use
UwbRangingParams.CONFIG_UNICAST_DS_TWR. - Session Key Info. Provide a byte array containing the Vendor ID and the Static STS IV.
- Complex Channel. Set the channel number and preamble index to match the iOS device's configuration.
The following code snippet demonstrates how to create a RangingPreference for
an initiator device ranging with an iOS responder:
// Create UwbRangingParams with iOS-specific configuration. val uwbRangingParams = UwbRangingParams.Builder( sessionId, UwbRangingParams.CONFIG_UNICAST_DS_TWR, sourceAddress, destinationAddress ) .setComplexChannel( UwbComplexChannel.Builder() .setChannel(channelNumber) .setPreambleIndex(preambleIndex) .build() ) .setRangingUpdateRate(updateRate) .setSessionKeyInfo(sessionKeyInfo) // Vendor ID + STS IV .setSlotDuration(slotDuration) .build() // Create RawRangingDevice. val rawRangingDevice = RawRangingDevice.Builder() .setRangingDevice(RangingDevice.Builder().build()) .setUwbRangingParams(uwbRangingParams) .build() // Create SessionConfig. val sessionConfig = SessionConfig.Builder() .setAngleOfArrivalNeeded(true) .setDataNotificationConfig( DataNotificationConfig.Builder() .setNotificationConfigType(DataNotificationConfig.NOTIFICATION_CONFIG_ENABLE) .build() ) .build() // Create RangingPreference for the initiator. val preference = RangingPreference.Builder( RangingPreference.DEVICE_ROLE_INITIATOR, RawInitiatorRangingConfig.Builder() .addRawRangingDevice(rawRangingDevice) .build() ) .setSessionConfig(sessionConfig) .build()
UWB Downlink-TDoA API
On Android 17 (API level 37) and higher, Downlink Time Difference of Arrival (DL-TDoA) ranging lets a device determine its position relative to multiple UWB anchors by measuring the relative arrival times of signals.
The following snippet demonstrates how to use RangingManager to verify
DL-TDoA support, configure DlTdoaRangingParams and
RawDtTagRangingConfig to start a session, and receive
DlTdoaMeasurement results:
class RangingApp { fun initDlTdoa(context: Context) { // Initialize the Ranging Manager. val rangingManager = context.getSystemService(RangingManager::class.java) // Register for device capabilities. val capabilitiesCallback = object : RangingManager.RangingCapabilitiesCallback { override fun onRangingCapabilities(capabilities: RangingCapabilities) { // Make sure DL-TDoA is supported before starting the session. if (capabilities.uwbCapabilities?.isDlTdoaSupported == true) { startDlTDoASession(context) } } } rangingManager.registerCapabilitiesCallback(Executors.newSingleThreadExecutor(), capabilitiesCallback) } fun startDlTDoASession(context: Context) { // Initialize the Ranging Manager. val rangingManager = context.getSystemService(RangingManager::class.java) // Create session and configure parameters. val executor = Executors.newSingleThreadExecutor() val rangingSession = rangingManager.createRangingSession(executor, RangingSessionCallback()) val rangingRoundIndexes = byteArrayOf(0) val config: ByteArray = byteArrayOf() // OOB config data val params = DlTdoaRangingParams.createFromFiraConfigPacket(config, rangingRoundIndexes) val rangingDevice = RangingDevice.Builder().build() val rawTagDevice = RawRangingDevice.Builder() .setRangingDevice(rangingDevice) .setDlTdoaRangingParams(params) .build() val dtTagConfig = RawDtTagRangingConfig.Builder(rawTagDevice).build() val preference = RangingPreference.Builder(DEVICE_ROLE_DT_TAG, dtTagConfig) .setSessionConfig(SessionConfig.Builder().build()) .build() // Start the ranging session. rangingSession?.start(preference) } } private class RangingSessionCallback : RangingSession.Callback { override fun onDlTdoaResults(peer: RangingDevice, measurement: DlTdoaMeasurement) { // Process measurement results here. } override fun onOpened() { // ... } override fun onOpenFailed(reason: Int) { // ... } override fun onStarted(peer: RangingDevice, technology: Int) { // ... } override fun onStopped(peer: RangingDevice, technology: Int) { // ... } override fun onResults(peer: RangingDevice, data: RangingData) { // ... } override fun onClosed(reason: Int) { // ... } }
Out-of-band (OOB) configurations
The following snippet provides an example of DL-TDoA OOB configuration data for Wi-Fi and BLE:
// Wi-Fi Configuration (Vendor-Specific IE, FiRa CID 0x5A18FF, Config 0) val wifiConfig = byteArrayOf( 0xDD.toByte(), 0x30, 0x5A, 0x18, 0xFF.toByte(), // Wi-Fi VSE Header 0x5F, 0x1C, // UWB Configuration Sub-Element 0x02, 0x00, // Profile ID (Untracked Navigation), Config ID 0 0x06, 0x02, 0x20, 0x08, // Device MAC Address 0x14, 0x01, 0x0A, // Preamble Code Index (10) 0x27, 0x02, 0x08, 0x07, // Vendor ID 0x28, 0x06, 0xA1.toByte(), 0xB2.toByte(), 0xC3.toByte(), 0xD4.toByte(), 0xE5.toByte(), 0xF6.toByte(), // Static STS IV 0x08, 0x02, 0x60, 0x09, // Slot Duration (2400 RSTU = 2 ms) 0x1B, 0x01, 0x0A, // Slots per Ranging Round (10) 0x09, 0x04, 0xFA.toByte(), 0x00, 0x00, 0x00, // Ranging Duration (250 ms) 0x52, 0x01, 0x00, // Initiator DT-Anchor Round Index (0) 0x9F.toByte(), 0x04, 0xAA.toByte(), 0xBB.toByte(), 0xCC.toByte(), 0xDD.toByte() // Session ID (0xDDCCBBAA) ) // BLE Configuration (ADV_NONCONN_IND Service Data UUID 0xFFF3, Config 0) val bleConfig = byteArrayOf( 0x1E, 0x16, 0xF3.toByte(), 0xFF.toByte(), // BLE Service Data Header 0xF0.toByte(), // Fragment Indication Sub-Element (unfragmented) 0x5F, 0x09, // UWB Configuration Sub-Element 0x02, 0x00, // Profile ID (Untracked Navigation), Config ID 0 0x06, 0x02, 0x20, 0x08, // Device MAC Address 0x27, 0x02, 0x08, 0x07, // Vendor ID 0x28, 0x06, 0xA1.toByte(), 0xB2.toByte(), 0xC3.toByte(), 0xD4.toByte(), 0xE5.toByte(), 0xF6.toByte(), // Static STS IV 0x9F.toByte(), 0x04, 0xAA.toByte(), 0xBB.toByte(), 0xCC.toByte(), 0xDD.toByte() // Session ID (0xDDCCBBAA) )
If you can't use an OOB configuration because it's missing, or if you need to
change default values that aren't in the OOB configuration, you can build
parameters with DlTdoaRangingParams.Builder instead of calling
DlTdoaRangingParams.createFromFiraConfigPacket:
val dlTdoaParams = DlTdoaRangingParams.Builder(1) .setComplexChannel( UwbComplexChannel.Builder() .setChannel(9).setPreambleIndex(10).build() ) .setDeviceAddress(deviceAddress) .setSessionKeyInfo(byteArrayOf(0x01, 0x02, 0x03, 0x04)) .setRangingIntervalMillis(240) .setSlotDuration(UwbRangingParams.DURATION_2_MS) .setSlotsPerRangingRound(20) .setRangingRoundIndexes(byteArrayOf(0x01, 0x05)) .build()
Sample app
For an end-to-end example of how to use the Ranging module, see the sample app in AOSP. This sample app covers all ranging technologies supported by the Ranging module and includes flows for both supported session types.
UWB interoperability with iOS devices
The Android sample app supports starting a UWB ranging session with the iOS sample app.