Reichweite zwischen Geräten

Mit Android 16 (API-Level 36) wird das Ranging-Modul eingeführt, das eine einheitliche und standardisierte Schnittstelle für die präzise Entfernungsmessung zwischen Geräten bietet. Mit dieser API-Oberfläche können Sie die Entfernung und Position von Peer-Geräten messen, ohne jede Entfernungsmessungstechnologie einzeln verarbeiten zu müssen.

Das Ranging-Modul unterstützt die folgenden Technologien:

Funktionen und Verfügbarkeit von UWB

Die Klasse RangingManager stellt Apps Informationen zu den vom lokalen Gerät unterstützten Technologien zur Entfernungsmessung sowie zur Verfügbarkeit und den Funktionen der einzelnen Technologien zur Verfügung. Apps können eine RangingCapabilitiesCallback-Schnittstelle registrieren, um Updates zu Änderungen an der Verfügbarkeit oder den Funktionen unterstützter Technologien zu erhalten.

Geräterollen

Ein Gerät, das an einer Entfernungsmessungssitzung teilnimmt, muss ein Initiator, ein Responder oder ein Downlink-TDoA-Tag (DT-Tag) für UWB-Downlink-TDoA-Sitzungen unter Android 17 (API-Level 37) und höher sein. Das Initiatorgerät startet die Entfernungsmessung mit einem oder mehreren Respondergeräten. Ein Responder-Gerät antwortet jeweils nur auf Entfernungsanfragen von einem Initiator. In einer UWB-DL-TDoA-Sitzung (Downlink Time Difference of Arrival) verwendet das Gerät die Rolle DEVICE_ROLE_DT_TAG, um Signale von mehreren UWB-Ankern zu empfangen. Mit der Klasse RangingPreference kannst du die Rolle für ein bestimmtes Gerät in einer Entfernungsmessungssitzung angeben.

Arten von Entfernungsmessungssitzungen

Wenn du eine Entfernungsmessung zwischen Geräten startest, ist es oft erforderlich, einen Out-of-Band-Datentransport (OOB) einzurichten, um Parameter für die Sitzung auszutauschen.

Das Ranging-Modul kann OOB-Verhandlungen für dich übernehmen, unterstützt aber auch benutzerdefinierte OOB-Implementierungen.

Abbildung 1. OOB-Ablauf für Sitzungstypen.

Standard-OOB-Implementierung

Bei diesem Sitzungstyp (RANGING_SESSION_OOB) übernimmt das Entfernungsmessungsmodul die OOB-Verhandlungen, um eine Entfernungsmessungssitzung zu starten. Es wählt geeignete Parameter basierend auf den von der App bereitgestellten Einstellungen für die Entfernungsmessung aus und verwendet die entsprechenden Technologien basierend auf den von beiden Geräten unterstützten Funktionen. Dieser Sitzungstyp verwendet eine standardisierte OOB-Spezifikation. Unter Android 16 QPR2 (API-Level 36.1) und höher können Initiatoren einschränken, welche Technologien ausgehandelt werden, indem sie setRangingTechnologyFilter für OobInitiatorRangingConfig.Builder aufrufen.

Das Ranging-Modul definiert nur das OOB-Datenformat und die Sequenz, die für die Interaktion mit einem Peer-Gerät verwendet werden sollen. Es übernimmt nicht die Erkennung von Peer-Geräten oder den Verbindungsaufbau.

Benutzerdefinierte OOB-Implementierung

In diesem Sitzungstyp (RANGING_SESSION_RAW) umgeht die App den OOB-Ablauf des Ranging-Moduls und verarbeitet ihre eigene OOB-Aushandlung und ihre eigenen Parameter. Das bedeutet, dass die App ermitteln muss, welche Technologien das Peer-Gerät unterstützt, Entfernungsmessungsparameter aushandeln und die Entfernungsmessungssitzung starten muss.

Einstellungen für die Entfernungsmessung

Verwenden Sie ein RangingPreference-Objekt, um die ausgewählten Parameter für eine Entfernungsmessungssitzung anzugeben. Das bedeutet:

  • Geräterolle: Gibt an, ob das Gerät der Initiator, der Responder oder ein DT-Tag auf Android 17 (API-Level 37) und höher ist.
  • Entfernungsmessungskonfiguration Ein RangingConfig-Objekt gibt den Typ der Entfernungsmessungssitzung und andere Parameter an, die zum Starten einer Entfernungsmessungssitzung erforderlich sind.
  • Sitzungskonfiguration. Ein SessionConfig-Objekt gibt Parameter an, die für die Entfernungsmessungssitzung erzwungen werden sollen, z. B. Messlimit, Sensorfusion, Geofence-Konfiguration und mehr. Unter Android 17 (API-Level 37) und höher können Sie auch den Antennenmodus (ANTENNA_MODE_DIRECTIONAL oder ANTENNA_MODE_OMNI) mit setAntennaMode in SessionConfig.Builder konfigurieren, nachdem Sie die unterstützten Modi mit getSupportedAntennaModes in UwbRangingCapabilities geprüft haben.

Berechtigung zur Entfernungsmessung

Das Ranging-Modul verwendet eine einheitliche Berechtigung (android.permission.RANGING) für Peer-to-Peer-Ranging-Technologien. Diese Berechtigung ist in der Liste NEARBY_DEVICES_PERMISSIONS enthalten.

<uses-permission android:name="android.permission.RANGING" />

Limits und Einschränkungen

Das Ranging-Modul kann die Entfernungsmessung aus verschiedenen Gründen einschränken, darunter:

  • Drittanbieter-Apps dürfen die Entfernungsmessung im Hintergrund nur mit Ultrabreitband und nur auf unterstützten Geräten durchführen. Die Entfernungsmessung im Hintergrund mit anderen Technologien ist nicht zulässig.
  • Die Entfernungsmessung ist nicht zulässig, wenn die maximale Anzahl gleichzeitiger Entfernungsmessungssitzungen pro Gerät erreicht wurde.
  • Die Entfernungsmessung kann aufgrund von Systemzustandsproblemen wie Akku, Leistung oder Arbeitsspeicher eingeschränkt sein.

Für das Ranging-Modul gelten außerdem die folgenden bekannten Einschränkungen:

  • Das Ranging-Modul unterstützt nur die Übermittlung von Entfernungsmessungsdaten an Peer-Geräte für Ultrabreitband. Bei anderen Technologien liefert das Ranging-Modul nur Entfernungsmessdaten an das Initiatorgerät.
  • Das Ranging-Modul unterstützt nur das dynamische Hinzufügen von Geräten im Roh-Ranging-Modus und nur für Ultrabreitband.
  • Das Ranging-Modul unterstützt keine 1:n-Ultrabreitband-Sitzungen für OOB-Standardimplementierungen. Wenn du mehrere Geräte-Handles übergibst, erstellt das Modul eine Eins-zu-eins-Sitzung für jedes Peer-Gerät, das Ultrabreitband unterstützt.

Entfernungsmessung durchführen

So führen Sie eine Entfernungsmessung mit dem Modul „Ranging“ durch:

  1. Prüfen Sie, ob auf allen Geräten Android 16 (API-Level 36) oder höher ausgeführt wird.
  2. Fordern Sie die Berechtigung android.permission.RANGING im App-Manifest an.
  3. Bewerten Sie die Funktionen und die Verfügbarkeit von Technologien zur Entfernungsmessung.
  4. Ein Peer-Gerät für Entfernungsmessungen finden.
  5. Stelle eine Verbindung für einen Out-of-Band-Austausch her. Verwende dazu einen der Sitzungstypen, die unter Sitzungstypen für die Entfernungsmessung beschrieben sind.
  6. Entfernungsmessung initiieren und kontinuierlich Daten zur Entfernungsmessung erfassen.
  7. Beendet die Entfernungsmessung.

Das folgende Codebeispiel zeigt diese Schritte sowohl für die Initiator- als auch für die Responder-Rolle.

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()
    }
}

Entfernungsmessungsergebnisse und Bewegungen von Peers verarbeiten

Wenn eine Sitzung aktiv ist, liefert RangingSession.Callback Messungen der Entfernung und des Einfallswinkels in RangingData-Objekten über onResults:

  • Entfernungsunsicherheit: Unter Android 16 QPR2 (API-Level 36.1) und höher können Sie hasDistanceStandardDeviation und getDistanceStandardDeviationMeters für RangingData aufrufen, um die Standardabweichung der Entfernungsmessungen zu prüfen, sofern verfügbar.
  • Technologiespezifische Extras Rufen Sie unter Android 17 (API-Level 37) und höher getRangingDataExtras für RangingData auf, um ein RangingDataExtras-Objekt mit technologiespezifischen Metadaten wie BleSpecificData, UwbSpecificData oder WifiRttSpecificData abzurufen.
  • Bewegungsstatus des Peers. Überschreiben Sie unter Android 17 (API-Level 37) und höher onMotionReceived in RangingSession.Callback, um MotionState-Updates (MOTION_NOT_DETECTED, MOTION_SLIGHT, MOTION_MODERATE oder MOTION_LARGE) zu erhalten, wenn sich die Bewegung eines Peer-Geräts ändert.

UWB-Interoperabilität mit iOS-Geräten

Das Ranging-Modul unterstützt die Interoperabilität mit iOS-Geräten über Ultrabreitband (UWB). Wenn du die Entfernungsmessung mit einem iOS-Gerät nutzen möchtest, musst du eine benutzerdefinierte OOB-Implementierung verwenden und die Entfernungsmessungssitzung mit bestimmten Parametern konfigurieren, die dem Apple Nearby Interaction Accessory Protocol entsprechen. Ein Beispiel finden Sie in der Beispiel-App.

Verwenden Sie beim Erstellen des RangingPreference die Optionen RawRangingDevice und UwbRangingParams, um die Konfiguration anzugeben. Die folgenden Parameter sind für die iOS-Interoperabilität entscheidend:

  • Konfigurations-ID: Verwenden Sie UwbRangingParams.CONFIG_UNICAST_DS_TWR.
  • Sitzungsschlüsselinformationen: Gib ein Byte-Array mit der Anbieter-ID und dem statischen STS-IV an.
  • Komplexer Kanal. Legen Sie die Kanalnummer und den Präambelindex so fest, dass sie mit der Konfiguration des iOS-Geräts übereinstimmen.

Das folgende Code-Snippet zeigt, wie ein RangingPreference für ein Initiatorgerät erstellt wird, das mit einem iOS-Responder kommuniziert:

// 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

Unter Android 17 (API-Level 37) und höher können Geräte mit der Downlink Time Difference of Arrival (DL-TDoA) ihre Position relativ zu mehreren UWB-Ankern bestimmen, indem sie die relativen Ankunftszeiten von Signalen messen.

Das folgende Snippet zeigt, wie Sie mit RangingManager die DL-TDoA-Unterstützung prüfen, DlTdoaRangingParams und RawDtTagRangingConfig konfigurieren, um eine Sitzung zu starten, und DlTdoaMeasurement-Ergebnisse erhalten:

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-Konfigurationen (OOB)

Das folgende Snippet enthält ein Beispiel für DL-TDoA-OOB-Konfigurationsdaten für WLAN und 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)
)

Wenn Sie eine OOB-Konfiguration nicht verwenden können, weil sie fehlt, oder wenn Sie Standardwerte ändern müssen, die nicht in der OOB-Konfiguration enthalten sind, können Sie Parameter mit DlTdoaRangingParams.Builder erstellen, anstatt DlTdoaRangingParams.createFromFiraConfigPacket aufzurufen:

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()

Beispiel-App

Ein End-to-End-Beispiel für die Verwendung des Ranging-Moduls finden Sie in der Beispiel-App im AOSP. Diese Beispiel-App deckt alle vom Ranging-Modul unterstützten Ranging-Technologien ab und enthält Abläufe für beide unterstützten Sitzungstypen.

UWB-Interoperabilität mit iOS-Geräten

Die Android-Beispiel-App unterstützt das Starten einer UWB-Entfernungsmessung mit der iOS-Beispiel-App.

Abbildung 2. UWB-Nutzung unter Android und iOS