Posizione Wi-Fi: disponibile con RTT

Puoi utilizzare la funzionalità di geolocalizzazione della rete Wi-Fi fornita API Wi-Fi RTT (Round-Trip-Time) per misurare la distanza da punti di accesso Wi-Fi compatibili con RTT nelle vicinanze e Dispositivi Wi-Fi Aware.

Se misuri la distanza da tre o più punti di accesso, puoi utilizzare un algoritmo di trilaterazione per stimare la posizione del dispositivo più adatta a queste misurazioni. Il risultato è in genere preciso entro 1-2 metri.

Con questa precisione, puoi sviluppare servizi granulari basati sulla posizione geografica, come come navigazione di interni, controllo vocale con ambiguità (ad esempio, "Attiva luce") e informazioni basate sulla località (ad esempio, "Ci sono offerte speciali) per questo prodotto?").

Il dispositivo richiedente non deve necessariamente connettersi ai punti di accesso per eseguire la misurazione distanza con RTT Wi-Fi. Per garantire la privacy, solo il dispositivo che ha inviato la richiesta è in grado di per determinare la distanza dal punto di accesso. i punti di accesso non hanno queste informazioni. Le operazioni RTT Wi-Fi sono illimitate per le app in primo piano, ma limitata per le app in background.

La tecnologia RTT Wi-Fi e le relative funzionalità di misurazione fine (FTM) sono specificato dallo standard IEEE 802.11-2016. Il RTT Wi-Fi richiede la misurazione precisa del tempo fornita da FTM perché calcola la distanza tra due dispositivi misurando il tempo impiegato da un pacchetto per fare un viaggio di andata e ritorno tra i dispositivi e moltiplicando questo tempo per la velocità della luce.

Android 15 (livello API 35) ha introdotto il supporto della misurazione della distanza basata su trigger (NTB) IEEE 802.11az.

Differenze di implementazione in base alla versione di Android

La RTT Wi-Fi è stata introdotta in Android 9 (livello API 28). Quando utilizzi questo protocollo per determinare la posizione di un dispositivo mediante la trilaterazione con dispositivi che eseguono Android 9, devi avere accesso ai dati predeterminati relativi alla posizione dei punti di accesso (AP) nella tua app. Sta a te decidere come memorizzare e recuperare questi dati.

Sui dispositivi con Android 10 (livello API 29) e versioni successive, i dati sulla posizione AP possono essere rappresentato come ResponderLocation oggetti, tra cui latitudine, longitudine e altitudine. Per gli AP RTT Wi-Fi che supportano i dati LCI/LCR (Location Configuration Information/Location Civic Report), il protocollo restituirà un oggetto ResponderLocation durante la procedura di misurazione della distanza.

Questa funzionalità consente alle app di interrogare gli AP per chiedere direttamente la loro posizione anziché doverli archiviare preventivamente. In questo modo, la tua app può trovare gli AP e determinare le relative posizioni anche se non erano noti in precedenza, ad esempio quando un utente entra in un nuovo edificio.

Il supporto della misurazione della distanza NTB IEEE 802.11az è disponibile sui dispositivi con Android 15 (livello API 35) e versioni successive. Ciò significa che se il dispositivo supporta lo standard IEEE 802.11az Modalità iniziatore NTB (indicata da WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR), l'app può trovare sia gli AP compatibili con IEEE 802.11mc che IEEE 802.11az con un di una richiesta di intervallo. L'API RangingResult è stata estesa per fornire informazioni sul valore minimo e massimo che può essere utilizzato per l'intervallo misurazioni, lasciando l'intervallo esatto nel controllo dell'app.

Requisiti

• L'hardware del dispositivo che effettua la richiesta di misurazione della distanza deve implementare lo standard FTM 802.11-2016 o lo standard 802.11az (misurazione della distanza non basata su trigger).
• Sul dispositivo che effettua la richiesta di portata deve essere installato Android 9 (livello API) 28) o versioni successive. Il raggio d'azione non basato su trigger IEEE 802.11az è abilitato sui dispositivi con Android 15 (livello API 35) e versioni successive.
• Sul dispositivo che effettua la richiesta di misurazione della distanza devono essere attivati i servizi di geolocalizzazione e la ricerca di reti Wi-Fi (in Impostazioni > Posizione).
• Se l'app che effettua le richieste di portata target Android 13 (livello API 33) o versioni successive, deve avere il NEARBY_WIFI_DEVICES autorizzazione. Se un'app di questo tipo ha come target una versione precedente di Android, deve invece avere l'autorizzazione ACCESS_FINE_LOCATION.
• L'app deve eseguire query sull'intervallo di punti di accesso mentre è visibile o in un servizio in primo piano. L'app non può accedere alle informazioni sulla posizione da lo sfondo.
• Il punto di accesso deve implementare lo standard FTM IEEE 802.11-2016 o lo standard IEEE 802.11az (roaming non basato su trigger).

Configura

Per configurare l'app per l'utilizzo di Wi-Fi RTT, svolgi i passaggi che seguono.

1. Richiedi autorizzazioni

Richiedi le seguenti autorizzazioni nel file manifest dell'app:

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

Le autorizzazioni NEARBY_WIFI_DEVICES e ACCESS_FINE_LOCATION sono autorizzazioni pericolose, quindi devi richiederle in fase di runtime ogni volta che l'utente vuole eseguire un'operazione di scansione RTT. La tua app dovrà richiedere all'utente se l'autorizzazione non è già stata concessa. Per ulteriori informazioni sulle autorizzazioni di runtime, vedi Richiedere le autorizzazioni per le app.

2. Verificare se il dispositivo supporta il RTT Wi-Fi

Per verificare se il dispositivo supporta il RTT Wi-Fi, utilizza l'API PackageManager:

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

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

3. Verificare se la funzionalità RTT Wi-Fi è disponibile

La funzionalità RTT Wi-Fi potrebbe essere presente sul dispositivo, ma potrebbe non essere disponibile perché l'utente ha disattivato il Wi-Fi. A seconda delle funzionalità hardware e firmware, i dispositivi potrebbero non supportare la funzionalità Wi-Fi RTT se sono in uso SoftAP o il tethering. Per verificare se la funzionalità RTT Wi-Fi è disponibile, chiama isAvailable().

La disponibilità del RTT Wi-Fi può variare in qualsiasi momento. L'app deve registrare un BroadcastReceiver per ricevere ACTION_WIFI_RTT_STATE_CHANGED, che viene inviato quando la disponibilità cambia. Quando l'app riceve l'intent di trasmissione, deve controllare lo stato corrente della disponibilità e modificare il proprio comportamento di conseguenza.

Ad esempio:

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

Per ulteriori informazioni, vedi Trasmissioni.

Crea una richiesta con intervallo

Una richiesta vagante (RangingRequest) è stata creata specificando un elenco di punti di accesso o peer Wi-Fi Aware a cui . È possibile specificare più punti di accesso o peer Wi-Fi Aware in un una richiesta singola; vengono misurate e restituite le distanze da tutti i dispositivi.

Ad esempio, una richiesta può utilizzare addAccessPoint() per specificare un punto di accesso a cui misurare la distanza:

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 punto di accesso è identificato dal suo ScanResult, che può essere ottenuto chiamando WifiManager.getScanResults(). Puoi utilizzare addAccessPoints(List<ScanResult>) per aggiungere più punti di accesso in un batch.

Gli oggetti ScanResult possono contenere AP supportati sia con IEEE 802.11mc (is80211mcResponder()) sia con misurazione della distanza basata su trigger non IEEE 802.11az (is80211azNtbResponder()). I dispositivi che supportano la misurazione della distanza NTB IEEE 802.11az eseguono la misurazione della distanza 802.11mc o 802.11az a seconda della funzionalità dell'AP, per impostazione predefinita viene utilizzata la misurazione della distanza 802.11az se l'AP supporta entrambe. I dispositivi che non supportano IEEE 802.11az eseguono tutte le misurazioni di distanza utilizzando il protocollo IEEE 802.11mc.

Allo stesso modo, una richiesta di portata può aggiungere un peer Wi-Fi Aware utilizzando il suo MAC o relativo PeerHandle, utilizzando il addWifiAwarePeer(MacAddress peer) e addWifiAwarePeer(PeerHandle peer) rispettivamente. Per ulteriori informazioni sulla rilevazione dei peer Wi-Fi Aware, consulta la documentazione di Wi-Fi Aware.

Ricerca di intervalli

Un'app emette una richiesta di portata utilizzando WifiRttManager.startRanging() e fornendo quanto segue: RangingRequest per specificare operativa, un Executor per specificare il contesto del callback RangingResultCallback per ricevere i risultati.

Ad esempio:

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'operazione di misurazione della distanza viene eseguita in modo asincrono e i risultati vengono resi in uno dei callback di RangingResultCallback:

• Se l'intera operazione di misurazione della distanza non va a buon fine, il callback onRangingFailure viene attivato con un codice di stato descritto in RangingResultCallback. Questo tipo di errore può verificarsi se il servizio non è in grado di eseguire un'operazione di misurazione in quel momento, ad esempio perché il Wi-Fi è disattivato, perché l'applicazione ha richiesto troppe operazioni di misurazione ed è limitata o a causa di un problema di autorizzazione.
• Quando l'operazione di rilevamento della distanza viene completata, onRangingResults il callback viene attivato con un elenco di risultati che corrispondono all'elenco di richieste, un risultato per ogni richiesta. L'ordine dei risultati non corrisponde necessariamente all'ordine delle richieste. Tieni presente che l'operazione di misurazione della distanza potrebbe essere completata, ma ogni risultato potrebbe comunque indicare un errore di quella misurazione specifica.

Interpreta i risultati della misurazione

Ciascuno dei risultati restituiti onRangingResults è specificato da un RangingResult . Per ogni richiesta, procedi nel seguente modo.

1. Identifica la richiesta

Identifica la richiesta in base alle informazioni fornite durante la creazione del RangingRequest: spesso un indirizzo MAC fornito nel ScanResult che identifica un punto di accesso. L'indirizzo MAC può essere ottenuto dal risultato del rilevamento utilizzando il metodo getMacAddress().

L'elenco dei risultati di misurazione della distanza potrebbe essere in un ordine diverso rispetto ai peer (punti di accesso) specificati nella richiesta di misurazione della distanza, pertanto devi utilizzare l'indirizzo MAC per identificare il peer, non l'ordine dei risultati.

2. Determina se ogni misurazione è andata a buon fine

Per determinare se una misurazione è riuscita, utilizza la classe getStatus() . Qualsiasi valore diverso da STATUS_SUCCESS indica un errore. Un errore indica che tutti gli altri campi di questo risultato (tranne l'identificazione della richiesta sopra riportata) non sono validi e il metodo corrispondente get* non andrà a buon fine con un'eccezione IllegalStateException.

3. Visualizzare i risultati di ogni misurazione riuscita

Per ogni misurazione riuscita (RangingResult), puoi recuperare i valori risultato con i rispettivi metodi get:

• Distanza in mm e deviazione standard della misurazione:

  getDistanceMm()

  getDistanceStdDevMm()

• RSSI dei pacchetti utilizzati per le misurazioni:

  getRssi()

• Tempo in millisecondi in cui è stata effettuata la misurazione (che indica il tempo dall'avvio):

  getRangingTimestampMillis()

• Numero di misurazioni tentate e numero di misurazioni che hanno avuto esito positivo (e su cui si basano le misurazioni della distanza):

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

• Tempo minimo e massimo che un dispositivo client deve attendere tra due misurazioni NTB di 11 az:

  getMinTimeBetweenNtbMeasurementsMicros() e getMaxTimeBetweenNtbMeasurementsMicros() restituisce il tempo minimo e massimo. Se la misura successiva è richiesto prima che sia trascorso il tempo minimo, l'API restituisce risultato con intervallo memorizzato nella cache. Se la misurazione di ranging successiva viene richiesta dopo il tempo massimo, l'API termina la sessione di ranging non attivata e negozia una nuova sessione di ranging con la stazione di risposta. Dovresti evitare di richiedere una nuova sessione di rilevamento, perché aggiunge dall'overhead al tempo di misurazione della distanza. Per sfruttare al meglio 802.11az efficienza con intervallo non basato su attivatore, attiva la richiesta di intervallo successiva tra il tempo di misurazione minimo e massimo specificato nella precedente Misurazione di RangingResult.

• Ripetizioni del campo di addestramento lungo (LTF) che le stazioni di risposta e di iniziativa hanno utilizzato nel preambolo per il risultato NTB IEEE 802.11az:

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

• Numero di flussi di tempo spaziali (STS) di trasmissione e ricezione che l'iniziatore stazione utilizzata per il risultato dello standard IEEE 802.11az NTB:

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

Dispositivi Android che supportano WiFi-RTT

Le seguenti tabelle elencano alcuni smartphone, punti di accesso e dispositivi per negozi, magazzini e centri di distribuzione che supportano WiFi-RTT. Questi dati sono tutt'altro che esaustivi. Ti invitiamo a contattarci per elencare i tuoi prodotti compatibili con RTT qui.

Punti di accesso

Smartphone

Dispositivi per negozi, magazzini e centri di distribuzione