Localisation en Wi-Fi: portée avec DAR

Vous pouvez utiliser la fonctionnalité de localisation Wi-Fi fournie par l'API Wi-Fi RTT (Round-Trip-Time) pour mesurer la distance par rapport aux points d'accès Wi-Fi compatibles avec le RTT à proximité et aux appareils Wi-Fi Aware.

Si vous mesurez la distance à trois points d'accès ou plus, vous pouvez utiliser un algorithme de multilatération pour estimer la position de l'appareil qui correspond le mieux à ces mesures. Le résultat est généralement précis à 1 ou 2 mètres près.

Grâce à cette précision, vous pouvez développer des services basés sur la localisation précis, tels que la navigation en intérieur, les commandes vocales clarifiées (par exemple, "Allumer ce feu") et les informations basées sur la position (par exemple, "Existe-t-il des offres spéciales pour ce produit ?").

L'appareil demandeur n'a pas besoin de se connecter aux points d'accès pour mesurer la distance avec le DAR Wi-Fi. Pour des raisons de confidentialité, seul l'appareil à l'origine de la requête peut déterminer la distance jusqu'au point d'accès. Les points d'accès ne disposent pas de cette information. Les opérations RTT Wi-Fi sont illimitées pour les applications au premier plan, mais limitées pour les applications en arrière-plan.

Le DAR Wi-Fi et les fonctionnalités de mesure du temps précis (FTM) associées sont spécifiées par la norme IEEE 802.11-2016. Le RTT Wi-Fi nécessite la mesure précise du temps fournie par la FTM, car il calcule la distance entre deux appareils en mesurant le temps qu'un paquet met à effectuer un aller-retour entre les appareils et en multipliant ce temps par la vitesse de la lumière.

Android 15 (niveau d'API 35) a introduit la prise en charge de la mesure de la distance IEEE 802.11az sans déclencheur (NTB).

Différences d'implémentation en fonction de la version d'Android

Le RTT Wi-Fi a été introduit dans Android 9 (niveau d'API 28). Lorsque vous utilisez ce protocole pour déterminer la position d'un appareil à l'aide de la multilatération avec des appareils exécutant Android 9, vous devez avoir accès aux données de localisation des points d'accès (PA) prédéterminés dans votre application. C'est à vous de décider comment stocker et récupérer ces données.

Sur les appareils équipés d'Android 10 (niveau d'API 29) ou version ultérieure, les données de localisation des points d'accès peuvent être représentées sous forme d'objets ResponderLocation, qui incluent la latitude, la longitude et l'altitude. Pour les points d'accès Wi-Fi RTT compatibles avec les données LCI/LCR (Location Configuration Information/Location Civic Report), le protocole renvoie un objet ResponderLocation lors du processus de mesure de la portée.

Cette fonctionnalité permet aux applications d'interroger les points d'accès pour leur demander directement leur position, au lieu de devoir stocker ces informations à l'avance. Ainsi, votre application peut trouver des points d'accès et déterminer leur position, même si ces points d'accès n'étaient pas connus auparavant, par exemple lorsqu'un utilisateur entre dans un nouveau bâtiment.

La prise en charge de la mesure de la portée NTB IEEE 802.11az est disponible sur les appareils exécutant Android 15 (niveau d'API 35) ou version ultérieure. Cela signifie que si l'appareil est compatible avec le mode initiateur NTB IEEE 802.11az (indiqué par WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR), votre application peut trouver à la fois des points d'accès compatibles avec les normes IEEE 802.11mc et IEEE 802.11az avec une seule requête de plage. L'API RangingResult a été étendue pour fournir des informations sur la valeur minimale et maximale pouvant être utilisée pour l'intervalle entre les mesures de portée, laissant l'intervalle exact sous le contrôle de votre application.

Conditions requises

• Le matériel de l'appareil qui effectue la requête de distance doit appliquer la norme FTM 802.11-2016 ou la norme 802.11az (mise à l'échelle non basée sur un déclencheur).
• L'appareil qui envoie la requête de mesure de la distance doit être équipé d'Android 9 (niveau d'API 28) ou version ultérieure. La mesure de la distance sans déclencheur IEEE 802.11az est activée sur les appareils équipés d'Android 15 (niveau d'API 35) ou version ultérieure.
• Les services de localisation et la recherche Wi-Fi doivent être activés sur l'appareil qui envoie la requête de mesure de la distance (sous Settings > Location (Paramètres > Position)).
• Si l'application qui envoie la requête de mesure de la distance cible Android 13 (niveau d'API 33) ou version ultérieure, elle doit disposer de l'autorisation NEARBY_WIFI_DEVICES. Si une telle application cible une version antérieure d'Android, elle doit disposer de l'autorisation ACCESS_FINE_LOCATION à la place.
• L'application doit interroger la plage de points d'accès lorsqu'elle est visible ou dans un service de premier plan. L'application ne peut pas accéder aux informations de localisation en arrière-plan.
• Le point d'accès doit implémenter la norme FTM IEEE 802.11-2016 ou la norme IEEE 802.11az (mesure de la distance sans déclencheur).

Configuration

Pour configurer votre application pour qu'elle utilise le RTT Wi-Fi, procédez comme suit :

1. Demander des autorisations

Demandez les autorisations suivantes dans le fichier manifeste de votre application:

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

Les autorisations NEARBY_WIFI_DEVICES et ACCESS_FINE_LOCATION sont des autorisations dangereuses. Vous devez donc les demander au moment de l'exécution chaque fois que l'utilisateur souhaite effectuer une analyse RTT. Votre application doit demander l'autorisation de l'utilisateur si celle-ci n'a pas déjà été accordée. Pour en savoir plus sur les autorisations d'exécution, consultez la section Demander des autorisations d'application.

2. Vérifier si l'appareil est compatible avec le RTT Wi-Fi

Pour vérifier si l'appareil est compatible avec le RTT Wi-Fi, utilisez l'API PackageManager:

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

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

3. Vérifier si le RTT Wi-Fi est disponible

Le DAR Wi-Fi peut exister sur l'appareil, mais il n'est peut-être pas disponible, car l'utilisateur a désactivé le Wi-Fi. Selon leurs capacités matérielles et logicielles, certains appareils peuvent ne pas prendre en charge le RTT Wi-Fi si le point d'accès virtuel ou le partage de connexion sont utilisés. Pour vérifier si le RTT Wi-Fi est disponible, appelez isAvailable().

La disponibilité du RTT Wi-Fi peut changer à tout moment. Votre application doit enregistrer un BroadcastReceiver pour recevoir ACTION_WIFI_RTT_STATE_CHANGED, qui est envoyé lorsque la disponibilité change. Lorsque votre application reçoit l'intent de diffusion, elle doit vérifier l'état actuel de la disponibilité et ajuster son comportement en conséquence.

Exemple :

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

Pour en savoir plus, consultez la section Diffusions.

Créer une demande de télémétrie

Une requête de mesure de la portée (RangingRequest) est créée en spécifiant une liste d'AP ou de pairs Wi-Fi Aware auxquels une mesure de la portée est demandée. Vous pouvez spécifier plusieurs points d'accès ou pairs Wi-Fi Aware dans une seule requête de mesure de la portée. Les distances de tous les appareils sont mesurées et renvoyées.

Par exemple, une requête peut utiliser la méthode addAccessPoint() pour spécifier un point d'accès auquel mesurer la distance:

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

Un point d'accès est identifié par son objet ScanResult, que vous pouvez obtenir en appelant WifiManager.getScanResults(). Vous pouvez utiliser addAccessPoints(List<ScanResult>) pour ajouter plusieurs points d'accès à un lot.

Les objets ScanResult peuvent contenir à la fois des points d'accès pris en charge par les protocoles IEEE 802.11mc (is80211mcResponder()) et IEEE 802.11az avec une distance basée sur un déclencheur (is80211azNtbResponder()). Les appareils compatibles avec la norme IEEE 802.11az NTB avec une plage de valeurs 802.11mc ou 802.11az en fonction de la capacité du point d'accès, 802.11az par défaut lorsqu'il accepte les deux. Les appareils qui ne sont pas compatibles avec la norme IEEE 802.11az effectuent toutes les mesures de portée à l'aide du protocole IEEE 802.11mc.

De même, une requête de mesure de la portée peut ajouter un pair Wi-Fi Aware à l'aide de son adresse MAC ou de son PeerHandle, à l'aide des méthodes addWifiAwarePeer(MacAddress peer) et addWifiAwarePeer(PeerHandle peer), respectivement. Pour en savoir plus sur la découverte de pairs Wi-Fi Aware, consultez la documentation Wi-Fi Aware.

Portée des requêtes

Une application émet une requête de mesure de la distance à l'aide de la méthode WifiRttManager.startRanging() et fournit les éléments suivants: un RangingRequest pour spécifier l'opération, un Executor pour spécifier le contexte de rappel et un RangingResultCallback pour recevoir les résultats.

Exemple :

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) { … }
});

L'opération de mesure de la portée est effectuée de manière asynchrone, et les résultats de mesure de la portée sont renvoyés dans l'un des rappels de RangingResultCallback:

• Si l'ensemble de l'opération de mesure de la portée échoue, le rappel onRangingFailure est déclenché avec un code d'état décrit dans RangingResultCallback. Un tel échec peut se produire si le service ne peut pas exécuter une opération de mesure des distances à ce moment-là, par exemple parce que le Wi-Fi est désactivé, parce que l'application a demandé trop d'opérations de mesure et qu'elle est limitée, ou en raison d'un problème d'autorisation.
• Une fois l'opération de mesure de la portée terminée, le rappel onRangingResults est déclenché avec une liste de résultats correspondant à la liste des requêtes (un résultat pour chaque requête). L'ordre des résultats ne correspond pas nécessairement à l'ordre des requêtes. Notez que l'opération de mesure de la distance peut être terminée, mais que chaque résultat peut toujours indiquer un échec de cette mesure spécifique.

Interpréter les résultats de la mesure de la distance

Chacun des résultats renvoyés par le rappel onRangingResults est spécifié par un objet RangingResult. Pour chaque requête, procédez comme suit :

1. Identifier la demande

Identifiez la requête en fonction des informations fournies lors de la création du RangingRequest : le plus souvent, une adresse MAC fournie dans le ScanResult identifiant un point d'accès. L'adresse MAC peut être obtenue à partir du résultat de la mesure de la portée à l'aide de la méthode getMacAddress().

La liste des résultats de la mesure de la portée peut être dans un ordre différent de celui des pairs (points d'accès) spécifiés dans la requête de mesure de la portée. Vous devez donc utiliser l'adresse MAC pour identifier le pair, et non l'ordre des résultats.

2. Déterminer si chaque mesure a réussi

Pour déterminer si une mesure a réussi, utilisez la méthode getStatus(). Toute valeur autre que STATUS_SUCCESS indique un échec. Un échec signifie que tous les autres champs de ce résultat (à l'exception de l'identification de la requête ci-dessus) sont non valides, et la méthode get* correspondante échouera avec une exception IllegalStateException.

3. Obtenir les résultats de chaque mesure réussie

Pour chaque mesure réussie (RangingResult), vous pouvez récupérer les valeurs de résultat à l'aide des méthodes get respectives:

• Distance, en mm, et écart type de la mesure:

  getDistanceMm()

  getDistanceStdDevMm()

• RSSI des paquets utilisés pour les mesures:

  getRssi()

• Heure en millisecondes à laquelle la mesure a été effectuée (indiquant le temps écoulé depuis le démarrage):

  getRangingTimestampMillis()

• Nombre de mesures tentées et nombre de mesures ayant abouti (et sur lesquels sont basées les mesures de distance):

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

• Durée minimale et maximale d'attente d'un appareil client entre deux mesures NTB 11az:

  getMinTimeBetweenNtbMeasurementsMicros() et getMaxTimeBetweenNtbMeasurementsMicros() renvoient la durée minimale et maximale. Si la prochaine mesure de la portée est demandée avant que le délai minimal ne soit écoulé, l'API renvoie le résultat de la mesure de la portée mise en cache. Si la prochaine mesure de mesure est demandée une fois le délai maximal écoulé, l'API met fin à la session de mesure sans déclencheur et négocie une nouvelle session de mesure avec la station répondante. Vous devez éviter de demander une nouvelle session de mesure des distances, car cela ajoute une surcharge à la durée de la mesure des distances. Pour tirer pleinement parti de l'efficacité des plages de valeurs 802.11az non basées sur un déclencheur, déclenchez la requête de plage suivante entre la durée de mesure minimale et maximale spécifiée dans la mesure RangingResult précédente.

• Répétions du champ de formation long (LTF) que les stations de réponse et d'initiation ont utilisées dans le préambule pour le résultat NTB IEEE 802.11az:

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

• Nombre de flux temporels spatiaux (STS) d'émission et de réception que la station d'initiation a utilisés pour le résultat NTB IEEE 802.11az:

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

Appareils Android compatibles avec WiFi-RTT

Les tableaux suivants répertorient certains téléphones, points d'accès et appareils de point de vente, d'entrepôt et de centre de distribution compatibles avec le WiFi-RTT. Ces exemples ne sont pas exhaustifs. Nous vous invitons à nous contacter pour ajouter vos produits compatibles avec le RTT ici.

Points d'accès

Téléphones

Appareils pour les magasins, les entrepôts et les centres de distribution