Android 16(API レベル 36)では、デバイス間の正確な距離測定のための統合された標準化されたインターフェースを提供する Ranging モジュールが導入されています。この API サーフェスを使用すると、各測距技術を個別に処理することなく、ピアデバイスの距離と位置を測定できます。
Ranging モジュールは、次のテクノロジーをサポートしています。
- 超広帯域無線
- Bluetooth チャネル サウンディング
- Wi-Fi NAN RTT
- Bluetooth RSSI 測距
- Android 17(API レベル 37)以降の Wi-Fi 近接検出
測距機能と提供状況
RangingManager クラスは、ローカル デバイスでサポートされている測距技術に関する情報と、各技術の可用性と機能に関する情報をアプリに提供します。アプリは RangingCapabilitiesCallback インターフェースを登録して、サポートされているテクノロジーの可用性や機能の変更に関する最新情報を受け取ることができます。
デバイスの役割
レンジング セッションに参加するデバイスは、Android 17(API レベル 37)以降の UWB ダウンリンク TDoA セッションのイニシエーター、レスポンダー、またはダウンリンク TDoA タグ(DT-Tag)である必要があります。イニシエーター デバイスは、1 台以上のレスポンダー デバイスとのレンジング セッションを開始します。レスポンダー デバイスは、一度に 1 つのイニシエーターからのレンジング リクエストにのみ応答します。UWB ダウンリンク到着時間差(DL-TDoA)セッションでは、デバイスは DEVICE_ROLE_DT_TAG ロールを使用して複数の UWB アンカーから信号を受信します。RangingPreference クラスを使用して、レンジング セッションで特定のデバイスのロールを指定できます。
レンジング セッションのタイプ
デバイス間でレンジング セッションを開始する際、セッションのパラメータを交換するために、帯域外(OOB)データ転送を確立することが必要になることがよくあります。
Ranging モジュールは OOB ネゴシエーションを処理できますが、カスタム OOB 実装もサポートしています。
デフォルトの OOB 実装
このセッション タイプ(RANGING_SESSION_OOB)では、Ranging モジュールが OOB ネゴシエーションを処理して、レンジング セッションを開始します。アプリが提供するレンジング設定に基づいて適切なパラメータを選択し、両方のデバイスがサポートするテクノロジーに基づいて適切なテクノロジーを使用します。このセッション タイプでは、標準化された OOB 仕様が使用されます。Android 16 QPR2(API レベル 36.1)以降では、イニシエーターは OobInitiatorRangingConfig.Builder で setRangingTechnologyFilter を呼び出すことで、ネゴシエーションされるテクノロジーを制限できます。
Ranging モジュールは、ピアデバイスとのやり取りに使用される OOB データ形式とシーケンスのみを定義します。ピアデバイスの検出や接続の確立は処理しません。
カスタム OOB 実装
このセッション タイプ(RANGING_SESSION_RAW)では、アプリは Ranging モジュールの OOB フローをバイパスし、独自の OOB ネゴシエーションとパラメータを処理します。つまり、アプリは、ピアデバイスがサポートしているテクノロジーを判断し、測距パラメータをネゴシエートして、測距セッションを開始する必要があります。
測距の設定
RangingPreference オブジェクトを使用して、レンジング セッションに選択したパラメータを指定します。これには次のものが含まれます。
- デバイスの役割。これは、デバイスがイニシエーター、レスポンダー、または Android 17(API レベル 37)以降の DT-Tag であるかどうかを示します。
- 測距構成。
RangingConfigオブジェクトは、レンジング セッション タイプと、レンジング セッションの開始に必要なその他のパラメータを指定します。 - セッション構成。
SessionConfigオブジェクトは、測定制限、センサー フュージョン、ジオフェンス構成など、レンジング セッションに適用されるパラメータを指定します。Android 17(API レベル 37)以降では、UwbRangingCapabilitiesのgetSupportedAntennaModesでサポートされているモードを確認した後、SessionConfig.BuilderのsetAntennaModeでアンテナモード(ANTENNA_MODE_DIRECTIONALまたはANTENNA_MODE_OMNI)を構成することもできます。
測距権限
Ranging モジュールは、ピアツーピア測距技術に統合された権限(android.permission.RANGING)を使用します。この権限は NEARBY_DEVICES_PERMISSIONS リストにあります。
<uses-permission android:name="android.permission.RANGING" />
制限事項
レンジング モジュールは、次のような理由でレンジングを制限することがあります。
- サードパーティ製アプリは、サポートされているデバイスでのみ、超広帯域無線を使用したバックグラウンド測距を実行できます。他のテクノロジーを使用したバックグラウンドでの測距は許可されていません。
- デバイスによる同時レンジング セッションの最大数に達している場合、レンジングは許可されません。
- バッテリー、パフォーマンス、メモリなどのシステム ヘルスに関する懸念により、レンジングが制限されることがあります。
Ranging モジュールには、以下に示す既知の制限事項もあります。
- Ranging モジュールは、超広帯域無線でのピアデバイスへの測距データの配信のみをサポートしています。他のテクノロジーの場合、Ranging モジュールはイニシエーター デバイスにのみ測距データを配信します。
- Ranging モジュールは、raw 測距モードでのデバイスの動的な追加のみをサポートしています。また、超広帯域無線のみをサポートしています。
- Ranging モジュールは、デフォルトの OOB 実装で 1 対多の超広帯域無線セッションをサポートしていません。複数のデバイス ハンドルを渡すと、モジュールは、超広帯域無線をサポートするピアデバイスごとに 1 対 1 のセッションを作成します。
レンジング セッションを実施する
Ranging モジュールを使用してレンジング セッションを実施する手順は次のとおりです。
- すべてのデバイスで Android 16(API レベル 36)以降が搭載されていることを確認します。
- アプリ マニフェストで
android.permission.RANGING権限をリクエストします。 - 測距技術の機能と可用性を評価する。
- レンジング オペレーション用のピアデバイスを検出する。
- レンジング セッション タイプで説明されているセッション タイプのいずれかを使用して、帯域外交換の接続を確立します。
- レンジングを開始し、レンジング データを継続的に取得します。
- レンジング セッションを終了します。
次のコードサンプルは、イニシエーター ロールとレスポンダー ロールの両方でこれらの手順を示しています。
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() } }
レンジング結果とピアの動きを処理する
セッションがアクティブな場合、RangingSession.Callback は onResults を介して RangingData オブジェクトで距離と到来角の測定値を配信します。
- 距離の不確実性。Android 16 QPR2(API レベル 36.1)以降では、
RangingDataでhasDistanceStandardDeviationとgetDistanceStandardDeviationMetersを呼び出して、距離測定の標準偏差を調べます(利用可能な場合)。 - テクノロジー固有の追加機能。Android 17(API レベル 37)以降では、
RangingDataでgetRangingDataExtrasを呼び出して、テクノロジー固有のメタデータ(BleSpecificData、UwbSpecificData、WifiRttSpecificDataなど)を含むRangingDataExtrasオブジェクトを取得します。 - ピアのモーション状態。Android 17(API レベル 37)以降では、
RangingSession.CallbackのonMotionReceivedをオーバーライドして、ピアデバイスの動きが変化したときにMotionStateの更新(MOTION_NOT_DETECTED、MOTION_SLIGHT、MOTION_MODERATE、MOTION_LARGE)を受信します。
iOS デバイスとの UWB 相互運用性
Ranging モジュールは、超広帯域無線(UWB)を使用する iOS デバイスとの相互運用性をサポートしています。iOS デバイスでレンジングを行うには、カスタム OOB 実装を使用し、Apple Nearby Interaction Accessory Protocol に一致する特定のパラメータでレンジング セッションを構成する必要があります。例については、サンプルアプリをご覧ください。
RangingPreference を作成するときに、RawRangingDevice と UwbRangingParams を使用して構成を指定します。次のパラメータは、iOS の相互運用性に不可欠です。
- 構成 ID。
UwbRangingParams.CONFIG_UNICAST_DS_TWRを使用します。 - セッションキー情報。ベンダー ID と静的 STS IV を含むバイト配列を指定します。
- 複雑なチャネル。iOS デバイスの構成に合わせて、チャンネル番号とプリアンブル インデックスを設定します。
次のコード スニペットは、iOS レスポンダーでレンジングするイニシエーター デバイスの RangingPreference を作成する方法を示しています。
// 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
Android 17(API レベル 37)以降では、ダウンリンク到着時間差(DL-TDoA)測距により、デバイスは信号の相対的な到着時間を測定して、複数の UWB アンカーに対する相対的な位置を特定できます。
次のスニペットは、RangingManager を使用して DL-TDoA のサポートを確認し、DlTdoaRangingParams と RawDtTagRangingConfig を構成してセッションを開始し、DlTdoaMeasurement の結果を受け取る方法を示しています。
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) { // ... } }
帯域外(OOB)構成
次のスニペットは、Wi-Fi と BLE の DL-TDoA OOB 構成データの例を示しています。
// 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) )
OOB 構成がないために OOB 構成を使用できない場合や、OOB 構成にないデフォルト値を変更する必要がある場合は、DlTdoaRangingParams.createFromFiraConfigPacket を呼び出す代わりに DlTdoaRangingParams.Builder を使用してパラメータをビルドできます。
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()
サンプルアプリ
Ranging モジュールの使用方法のエンドツーエンドの例については、AOSP のサンプルアプリをご覧ください。このサンプルアプリは、Ranging モジュールでサポートされているすべての測距技術をカバーしており、サポートされている両方のセッション タイプのフローが含まれています。
iOS デバイスとの UWB 相互運用性
Android サンプルアプリは、iOS サンプルアプリとの UWB 測距セッションの開始をサポートしています。