WLAN-Standort: Entfernung mit RTT

Mit der WLAN-Standortfunktion der Wi‑Fi RTT (Round-Trip-Time) API können Sie die Entfernung zu RTT-fähigen WLAN-Zugangspunkten und Wi‑Fi Aware-Geräten in der Nähe messen.

Wenn Sie die Entfernung zu drei oder mehr Zugangspunkten messen, können Sie Multilaterationsalgorithmus ermittle die Geräteposition, die am besten zu diesen Messungen. Das Ergebnis ist in der Regel auf 1–2 Meter genau.

Mit dieser Genauigkeit können Sie detaillierte standortbasierte Dienste entwickeln, z. B. Indoor-Navigation, eine eindeutige Sprachsteuerung (z. B. „Schalte diese Lampe ein“) und standortbasierte Informationen (z. B. „Gibt es Sonderangebote für dieses Produkt?“).

Das anfragende Gerät muss sich nicht mit den Zugangspunkten verbinden, um die Entfernung mithilfe von WLAN-RTT zu messen. Aus Datenschutzgründen kann nur das anfragende Gerät die Entfernung zum Zugangspunkt ermitteln. Die Zugangspunkte haben diese Informationen nicht. Wi‑Fi-RTT-Vorgänge sind für Apps im Vordergrund unbegrenzt, für Apps im Hintergrund jedoch gedrosselt.

Wi‑Fi-RTT und die zugehörigen FTM-Funktionen (Fine-Time-Measurement) sind im IEEE 802.11-2016-Standard spezifiziert. Für WLAN-RTT wird die genaue Zeit benötigt Messung von FTM, da es die Entfernung zwischen zwei und messen, wie lange ein Paket für einen Umlauf zwischen der und die Zeit mit der Lichtgeschwindigkeit multiplizieren.

Android 15 (API-Level 35) unterstützt jetzt nicht mehr Trigger, IEEE 802.11az (NTB).

Implementierungsunterschiede je nach Android-Version

Wi‑Fi RTT wurde in Android 9 (API-Level 28) eingeführt. Wenn Sie dieses Protokoll verwenden, um den Standort eines Geräts mithilfe von Multilateration auf Geräten mit Android 9 zu ermitteln, benötigen Sie Zugriff auf vorab festgelegte Standortdaten von Zugangspunkten in Ihrer App. Sie entscheiden selbst, wie Sie diese Daten speichern und abrufen.

Auf Geräten mit Android 10 (API-Level 29) und höher können AP-Standortdaten dargestellt als ResponderLocation -Objekte, einschließlich Breitengrad, Längengrad und Höhe. Für WLAN-RTT-ZPs, die support Location Configuration Information/Location Civic Report (LCI/LCR-Daten) gibt das Protokoll während des Vorgangs ein ResponderLocation-Objekt zurück. Bereichsbestimmung.

Mit dieser Funktion können Apps APs direkt nach ihrer Position fragen. und müssen diese Informationen nicht im Voraus speichern. Ihre App kann also AP zu finden und ihre Positionen zu ermitteln, auch wenn diese zuvor nicht bekannt waren. beispielsweise wenn Nutzende ein neues Gebäude betreten.

Die Unterstützung von IEEE 802.11az-NTB-Messungen ist auf Geräten mit Android 15 (API-Ebene 35) und höher verfügbar. Wenn das Gerät also IEEE 802.11az unterstützt, NTB-Initiatormodus (gekennzeichnet durch WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR), kann Ihre App sowohl IEEE 802.11mc- als auch IEEE 802.11az-fähige APs mit einem einzigen Bereichsanfrage. Die RangingResult API wurde erweitert, um Informationen zur Verfügung zu stellen über den Mindest- und Höchstwert, der für das Intervall zwischen Entfernungsmessungen und behält das genaue Intervall in der Steuerung deiner App über.

Voraussetzungen

• Die Hardware des Geräts, das die Anfrage für die Entfernungsmessung sendet, muss den FTM-Standard 802.11-2016 oder den Standard 802.11az (nicht triggerbasierte Entfernungsmessung) implementieren.
• Auf dem Gerät, das die Anfrage sendet, muss Android 9 (API-Ebene 28) oder höher installiert sein. Nicht Triggerbasierte Bereichserkennung gemäß IEEE 802.11az auf Geräten aktiviert mit Android 15 (API-Level 35) oder höher.
• Auf dem Gerät, das die Anfrage sendet, müssen die Standortdienste und die WLAN-Suche aktiviert sein (unter Einstellungen > Standort).
• Wenn die App, die die Anfrage zur Standortermittlung erstellt, Android 13 (API-Level 33) oder höher benötigen, NEARBY_WIFI_DEVICES Berechtigung. Wenn eine solche App auf eine frühere Android-Version ausgerichtet ist, muss sie stattdessen die Berechtigung ACCESS_FINE_LOCATION haben.
• Die App muss den Bereich der Zugangspunkte abfragen, während sie sichtbar oder in einen Dienst im Vordergrund. Die App kann nicht im Hintergrund auf Standortinformationen zugreifen.
• Der Zugangspunkt muss den FTM-Standard IEEE 802.11-2016 oder IEEE implementieren 802.11az-Standard (nicht Trigger-basierte Bereichserkennung)

Einrichten

So richten Sie Ihre App für die Verwendung von WLAN-RTT ein:

1. Berechtigungen anfordern

Fordern Sie die folgenden Berechtigungen im Manifest Ihrer App an:

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<!-- If your app targets Android 13 (API level 33)
     or higher, you must declare the NEARBY_WIFI_DEVICES permission. -->
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES"
                 <!-- If your app derives location information from Wi-Fi APIs,
                      don't include the "usesPermissionFlags" attribute. -->
                 android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
                 <!-- If any feature in your app relies on precise location
                      information, don't include the "maxSdkVersion"
                      attribute. -->
                 android:maxSdkVersion="32" />

Die Berechtigungen NEARBY_WIFI_DEVICES und ACCESS_FINE_LOCATION sind gefährliche Berechtigungen. Sie müssen sie also jedes Mal zur Laufzeit anfordern, wenn der Nutzer einen RTT-Scan ausführen möchte. Ihre App muss die Berechtigung des Nutzers anfordern, Berechtigung, wenn die Berechtigung nicht bereits gewährt wurde. Weitere Informationen zu Laufzeitberechtigungen finden Sie unter App-Berechtigungen anfordern.

2. Prüfen, ob das Gerät WLAN-RTT unterstützt

Um zu prüfen, ob das Gerät WLAN-RTT unterstützt, verwende die PackageManager API:

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

context.getPackageManager().hasSystemFeature(PackageManager.FEATURE_WIFI_RTT);

3. Prüfen, ob WLAN-RTT verfügbar ist

WLAN-RTT ist möglicherweise auf dem Gerät vorhanden, aber nicht verfügbar, weil der Nutzer WLAN deaktiviert hat. Je nach Hardware- und Firmwarefunktion Geräte unterstützen WLAN-RTT möglicherweise nicht, wenn SoftAP oder Tethering verwendet wird. Zur Überprüfung ob WLAN-RTT verfügbar ist: isAvailable()

Die Verfügbarkeit von WLAN-RTT kann sich jederzeit ändern. Ihre App sollte einen BroadcastReceiver registrieren, um ACTION_WIFI_RTT_STATE_CHANGED zu empfangen, das gesendet wird, wenn sich die Verfügbarkeit ändert. Wenn Ihre App die Broadcastabsicht empfängt, sollte sie den aktuellen Verfügbarkeitsstatus prüfen und ihr Verhalten entsprechend anpassen.

Beispiel:

val filter = IntentFilter(WifiRttManager.ACTION_WIFI_RTT_STATE_CHANGED)
val myReceiver = object: BroadcastReceiver() {

    override fun onReceive(context: Context, intent: Intent) {
        if (wifiRttManager.isAvailable) {
            …
        } else {
            …
        }
    }
}
context.registerReceiver(myReceiver, filter)

IntentFilter filter =
    new IntentFilter(WifiRttManager.ACTION_WIFI_RTT_STATE_CHANGED);
BroadcastReceiver myReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        if (wifiRttManager.isAvailable()) {
            …
        } else {
            …
        }
    }
};
context.registerReceiver(myReceiver, filter);

Weitere Informationen finden Sie unter Übertragungen.

Abfrage erstellen

Eine Anfrage für die Standortermittlung (RangingRequest) wird erstellt, indem eine Liste von ZPs oder Wi‑Fi Aware-Peers angegeben wird, für die eine Standortermittlung angefordert wird. In einem Anfrage zur Bereichserkennung; werden die Entfernungen zu allen Geräten gemessen und zurückgegeben.

In einer Anfrage kann beispielsweise die Methode addAccessPoint() verwendet werden, um einen Zugangspunkt anzugeben, zu dem die Entfernung gemessen werden soll:

val req: RangingRequest = RangingRequest.Builder().run {
    addAccessPoint(ap1ScanResult)
    addAccessPoint(ap2ScanResult)
    build()
}

RangingRequest.Builder builder = new RangingRequest.Builder();
builder.addAccessPoint(ap1ScanResult);
builder.addAccessPoint(ap2ScanResult);

RangingRequest req = builder.build();

Ein Zugangspunkt wird durch sein ScanResult-Objekt identifiziert, das durch Aufrufen von WifiManager.getScanResults() abgerufen werden kann. Sie können addAccessPoints(List<ScanResult>) um mehrere Zugangspunkte gleichzeitig hinzuzufügen.

ScanResult-Objekte können sowohl IEEE 802.11mc (is80211mcResponder()) als auch Nicht Trigger-basierte Bereichserkennung gemäß IEEE 802.11az (is80211azNtbResponder()) APs. Geräte, die IEEE 802.11az-NTB-Messungen unterstützen, führen je nach den Fähigkeiten des ZP entweder 802.11mc- oder 802.11az-Messungen durch. Standardmäßig wird 802.11az verwendet, wenn der ZP beide unterstützt. Geräte, die IEEE 802.11az nicht unterstützen, mit dem IEEE 802.11mc-Protokoll.

Genauso kann mit einer Anfrage zur Bereichserkennung ein Wi-Fi Aware-Peer über dessen MAC-Adresse hinzugefügt werden. oder seine PeerHandle-Adresse mit Hilfe von die addWifiAwarePeer(MacAddress peer) und addWifiAwarePeer(PeerHandle peer) . Weitere Informationen zum Auffinden von Wi‑Fi Aware-Peers finden Sie in der Wi‑Fi Aware-Dokumentation.

Abfragebereich

Eine Anwendung gibt mithilfe des WifiRttManager.startRanging() und Folgendes angeben: a RangingRequest zum Angeben des wird ein Executor-Vorgang zur Angabe von Callback-Kontext und eine RangingResultCallback. um die Ergebnisse zu erhalten.

Beispiel:

val mgr = context.getSystemService(Context.WIFI_RTT_RANGING_SERVICE) as WifiRttManager
val request: RangingRequest = myRequest
mgr.startRanging(request, executor, object : RangingResultCallback() {

    override fun onRangingResults(results: List<RangingResult>) { … }

    override fun onRangingFailure(code: Int) { … }
})

WifiRttManager mgr =
      (WifiRttManager) Context.getSystemService(Context.WIFI_RTT_RANGING_SERVICE);

RangingRequest request ...;
mgr.startRanging(request, executor, new RangingResultCallback() {

  @Override
  public void onRangingFailure(int code) { … }

  @Override
  public void onRangingResults(List<RangingResult> results) { … }
});

Der Abtastvorgang wird asynchron ausgeführt und die Ergebnisse werden in einem der Callbacks von RangingResultCallback zurückgegeben:

• Wenn der gesamte Abtastvorgang fehlschlägt, wird der Rückruf onRangingFailure mit einem Statuscode ausgelöst, der in RangingResultCallback beschrieben ist. Ein solcher Fehler kann auftreten, wenn der Dienst keinen Bereichserkennungsvorgang ausführen kann. aktiviert werden, z. B. weil WLAN deaktiviert ist, weil die Anwendung zu viele Bereichserkennungsvorgänge angefordert und gedrosselt wird. Berechtigungsproblem.
• Nach Abschluss des Bereichserkennungsvorgangs wird der onRangingResults Callback wird mit einer Liste von Ergebnissen ausgelöst, die mit der Liste der -Anfragen – ein Ergebnis für jede Anfrage. Die Reihenfolge der Ergebnisse unbedingt mit der Reihenfolge der Anfragen übereinstimmen. Beachten Sie, dass der Bereichserkennungsvorgang möglicherweise aber jedes Ergebnis kann immer noch darauf hinweisen, zu messen.

Bereichsergebnisse interpretieren

Jedes der vom onRangingResults-Callback zurückgegebenen Ergebnisse wird durch ein RangingResult-Objekt angegeben. Gehen Sie bei jeder Anfrage so vor:

1. Anfrage identifizieren

Identifizieren Sie den Antrag anhand der Informationen, die beim Erstellen des RangingRequest: Meistens eine MAC-Adresse im ScanResult, die einen Zugriff identifiziert Punkt. Die MAC-Adresse kann mithilfe der Methode getMacAddress() .

Die Liste der Ergebnisse der Standortbestimmung kann sich von der Reihenfolge der in der Standortbestimmungsanfrage angegebenen Peers (Zugangspunkte) unterscheiden. Verwenden Sie daher die MAC-Adresse, um den Peer zu identifizieren, und nicht die Reihenfolge der Ergebnisse.

2. Prüfen, ob jede Messung erfolgreich war

Um festzustellen, ob eine Messung erfolgreich war, verwenden Sie das getStatus() . Alle Werte außer STATUS_SUCCESS zeigt einen Fehler an. Ein Fehler bedeutet, dass alle anderen Felder dieses Ergebnisses (mit Ausnahme der oben genannten Anforderungsidentifikation) ungültig sind und die entsprechenden Die Methode get* schlägt fehl mit: IllegalStateException-Ausnahme.

3. Ergebnisse für jede erfolgreiche Messung abrufen

Für jede erfolgreiche Messung (RangingResult) können Sie Ergebnisse abrufen -Werte durch die entsprechenden get-Methoden an:

• Entfernung in mm und Standardabweichung der Messung:

  getDistanceMm()

  getDistanceStdDevMm()

• RSSI der für die Messungen verwendeten Pakete:

  getRssi()

• Die Zeit in Millisekunden, zu der die Messung durchgeführt wurde (Zeit seit dem Start):

  getRangingTimestampMillis()

• Anzahl der versuchten Messungen sowie deren Anzahl die erfolgreich waren (und auf denen die Entfernungsmessungen basieren):

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

• Mindest- und Höchstzeit, die ein Clientgerät zwischen zwei 11az-NTB-Messungen warten muss:

  getMinTimeBetweenNtbMeasurementsMicros() und getMaxTimeBetweenNtbMeasurementsMicros() geben die minimale und maximale Zeit zurück. Wenn die nächste Bereichsmessung vor Ablauf der Mindestzeit angefordert haben, gibt die API den Fehlerwert im Cache gespeichertes Bereichsergebnis. Wenn die nächste Bereichsmessung nach dem die maximale Zeit verstrichen ist, beendet die API den Vorgang ohne Trigger und verhandelt eine neue Auswahlsitzung mit den antwortenden Sender. Sie sollten es vermeiden, eine neue Bereichssitzung anzufordern, da dadurch bis zur Zeitspanne der Messung. Um alle Vorteile von 802.11az zu nutzen nicht Trigger-basierte Bereichserkennung, die nächste Entfernungsanfrage auslösen zwischen der Mindest- und der maximalen Messzeit, die im vorherigen Schritt Messung von RangingResult.

• LF-Wiederholungen (Long Training Field), bei denen Teilnehmer- und Initiatorstationen in der Präambel des IEEE 802.11az-NTB-Ergebnisses verwendet:

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

• Anzahl der gesendeten und empfangenen räumlichen Zeitstreams (STS), die die Initiatorstation für das IEEE 802.11az-NTB-Ergebnis verwendet hat:

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

Android-Geräte, die WiFi-RTT unterstützen

In den folgenden Tabellen sind einige Smartphones, Zugangspunkte und Geräte für Einzelhandel, Lagerhäuser und Vertriebszentren aufgeführt, die WiFi-RTT unterstützen. Diese sind bei weitem nicht vollständig. Wir empfehlen Ihnen, wenden Sie sich einfach an uns um Ihre RTT-fähigen Produkte hier aufzulisten.

Zugangspunkte

Smartphones

Geräte für Einzelhandel, Lagerhäuser und Vertriebszentren