Reichweite zwischen Geräten

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Android 16 führt das Ranging-Modul ein, 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 Entfernungstechnologie einzeln verarbeiten zu müssen.

Das Rangierungsmodul unterstützt die folgenden Technologien:

• Ultrabreitband
• Bluetooth-Kanalton
• Wi‑Fi NAN RTT
• Bluetooth-RSSI-Messung

Reichweitenfunktionen und Verfügbarkeit

Die Klasse RangingManager stellt Apps Informationen zu den vom lokalen Gerät unterstützten Ortungstechnologien sowie zur Verfügbarkeit und zu den Funktionen der einzelnen Technologien zur Verfügung. Apps können sich für einen Callback registrieren, um über Änderungen an der Verfügbarkeit oder den Funktionen unterstützter Technologien informiert zu werden.

Geräterollen

Ein Gerät, das an einer Positionsbestimmungssitzung teilnimmt, muss entweder ein Initiator oder ein Responder sein. Das Initiatorgerät startet die Abstandsmessung mit einem oder mehreren Responder-Geräten. Ein Antwortgerät antwortet jeweils nur auf eine Anfrage eines Initiators. Sie können die Rolle für ein bestimmtes Gerät in einer Positionserfassungssitzung mit der Klasse RangingPreference angeben.

Sitzungstypen für Ranglisten

Wenn Sie eine Messsitzung zwischen Geräten starten, 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 Sie übernehmen, unterstützt aber auch benutzerdefinierte OOB-Implementierungen.

Standard-OOB-Implementierung

Bei diesem Sitzungstyp (RANGING_SESSION_OOB) übernimmt das Ranging-Modul die OOB-Verhandlungen, um eine Ranging-Sitzung 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, die von beiden Geräten unterstützt werden. Für diesen Sitzungstyp wird ein standardisierter OOB specification verwendet.

Das Ranging-Modul definiert nur das OOB-Datenformat und die Sequenz, die für die Interaktion mit einem Peer-Gerät verwendet werden soll. Es werden keine Peer-Geräte erkannt und keine Verbindungen hergestellt.

Benutzerdefinierte OOB-Implementierung

Bei diesem Sitzungstyp (RANGING_SESSION_RAW) umgeht die App den OOB-Ablauf des Rangierungsmoduls und verarbeitet eigene OOB-Verhandlungen und ‑Parameter. Das bedeutet, dass die App ermitteln muss, welche Technologien das Peer-Gerät unterstützt, die Abstandsmessungsparameter aushandeln und die Abstandsmessung starten muss.

Einstellungen für die Reichweite

Verwenden Sie ein RangingPreference-Objekt, um die gewünschten Parameter für eine Positionsbestimmungssitzung anzugeben. Das bedeutet:

• Geräterolle Hier wird angegeben, ob das Gerät der Initiator oder der Responder ist.
• Konfiguration der Reichweite. Ein RangingConfig-Objekt gibt den Typ der Abstandsmessung und andere Parameter an, die zum Starten einer Abstandsmessung erforderlich sind.
• Sitzungskonfiguration In einem SessionConfig-Objekt werden Parameter für die Entfernungsmessung angegeben, z. B. das Messlimit, die Sensorfusion und die Geofence-Konfiguration.

Berechtigung für die Standortermittlung

Für das Ranging-Modul ist eine neue einheitliche Berechtigung (android.permission.RANGING) erforderlich, um auf alle aktuellen und zukünftigen Ranging-Technologien zuzugreifen. Diese Berechtigung ist in der Liste NEARBY_DEVICES_PERMISSIONS enthalten.

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

Einschränkungen

Das Abstandsmodul kann das Abtasten aus verschiedenen Gründen einschränken, z. B.:

• Drittanbieter-Apps dürfen nur auf unterstützten Geräten und nur im Hintergrund Ultrabreitband-Triangulation durchführen. Die Positionsbestimmung im Hintergrund mit anderen Technologien ist nicht zulässig.
• Die Rangierung ist nicht zulässig, wenn die maximale Anzahl gleichzeitiger Rangierungssitzungen pro Gerät erreicht wurde.
• Die Reichweite kann aufgrund von Problemen mit der Systemintegrität wie Akku, Leistung oder Speicher eingeschränkt sein.

Das Rangierungsmodul hat außerdem die folgenden bekannten Einschränkungen:

• Das Ranging-Modul unterstützt nur die Übermittlung von Ranging-Daten an Peer-Geräte für Ultrabreitband. Bei anderen Technologien liefert das Ranging-Modul nur Ranging-Daten an das Initiatorgerät.
• Das Ranging-Modul unterstützt das dynamische Hinzufügen von Geräten nur im Raw-Ranging-Modus und nur für Ultrabreitband.
• Das Ranging-Modul unterstützt keine 1:n-Ultrabreitbandsitzungen für standardmäßige OOB-Implementierungen. Wenn Sie mehrere Geräte-Handle übergeben, erstellt das Modul eine Eins-zu-Eins-Sitzung für jedes Peer-Gerät, das Ultrabreitband unterstützt.

Abstandsmessung durchführen

So führen Sie eine Abstandsmessung mit dem Abstandsmessungsmodul durch:

1. Prüfen Sie, ob auf allen Geräten Android 16 oder höher installiert ist.
2. Fordern Sie die android.permission.RANGING-Berechtigung im App-Manifest an.
3. Bewerten Sie die Funktionen und Verfügbarkeit verschiedener Technologien.
4. Ein Peer-Gerät für die Positionsbestimmung finden
5. Stellen Sie eine Verbindung für einen Out-of-Band-Austausch her, indem Sie einen der in Sitzungstypen für die Rangfolge beschriebenen Sitzungstypen verwenden.
6. Starten Sie die Entfernungsmessung und erfassen Sie kontinuierlich Entfernungsdaten.
7. Beenden Sie die Abfragesitzung.

Das folgende Codebeispiel veranschaulicht diese Schritte sowohl für die Rolle des Initiators als auch für die Rolle des Responders.

class RangingApp {

    // Starts a ranging session on the initiator side.
    fun startRangingInitiator(
        context: Context,
        deviceHandle: DeviceHandle,
        executor: Executor,
        callback: RangingSessionCallback
    ) {

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

        // 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.
        session.start(preference)

        // If successful, the ranging data will be sent through callback#onResults

        // Stop ranging session
        session.stop()
    }

    // Starts a ranging session on the responder side.
    fun startRangingResponder(
        context: Context,
        deviceHandle: DeviceHandle,
        executor: Executor,
        callback: RangingSessionCallback
    ) {

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

        // 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.
        session.start(preference)

        // Stop the ranging session
        session.stop()
    }
}

public class RangingApp {

    // Starts a ranging session on the initiator side.
    void startRangingInitiator(Context context, DeviceHandle deviceHandle, Executor executor, RangingSessionCallback callback) {

        // Get the RangingManager which is the entry point for ranging module.
        RangingManager manager = context.getSystemService(RangingManager.class);

        // Create a new RangingSession using the provided executor and callback.
        RangingSession session = manager.createRangingSession(executor, callback);

        // Create an OobInitiatorRangingConfig, which specifies the ranging parameters for
        // the initiator role.
        OobInitiatorRangingConfig config = new 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.
        RangingPreference preference =
                new RangingPreference.Builder(DEVICE_ROLE_INITIATOR, config).build();

        // Start ranging session.
        session.start(preference);

        // If successful, the ranging data will be sent through callback#onResults

        // Stop ranging session
        session.stop();

    }

    // Starts a ranging session on the responder side.
    void startRangingResponder(Context context,  DeviceHandle deviceHandle, Executor executor, RangingSessionCallback callback) {

        // Get the RangingManager which is the entry point for ranging module.
        RangingManager manager = context.getSystemService(RangingManager.class);

        // Create a new RangingSession using the provided executor and callback.
        RangingSession session = manager.createRangingSession(executor, callback);

        // Create an OobResponderRangingConfig, which specifies the ranging parameters for
        // the responder role.
        OobResponderRangingConfig config = new OobResponderRangingConfig.Builder(  deviceHandle).build();

        // Create a RangingPreference, which specifies the role (responder) and
        // configuration for the ranging session.
        RangingPreference preference =
                new RangingPreference.Builder(DEVICE_ROLE_RESPONDER, config).build();

        // Start the ranging session.
        session.start(preference);

        // Stop the ranging session
        session.stop();
    }
}

Beispiel-App

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