Localização de Wi-Fi: alcance com RTT

Você pode usar o recurso de localização de Wi-Fi fornecido pela API Wi-Fi RTT (Round-Trip-Time) para medir a distância dos pontos de acesso e dos dispositivos Wi-Fi Aware próximos e compatíveis com RTT.

Ao medir a distância de até três ou mais pontos de acesso, será possível usar um algoritmo de multilateração para estimar a posição do dispositivo que melhor se encaixa nessas medidas. Normalmente, o resultado é preciso a uma distância de 1 a 2 metros.

Com esse nível de precisão, é possível criar serviços aprimorados baseados na localização, como a navegação interna, o controle de voz sem ambiguidades (por exemplo, "acenda esta luz") e informações baseadas na localização (por exemplo, "este produto tem ofertas especiais?").

O dispositivo que faz a solicitação não precisa se conectar aos pontos de acesso para medir a distância com o Wi-Fi RTT. Para manter a privacidade, somente o dispositivo solicitante pode para determinar a distância até o ponto de acesso; os pontos de acesso não têm essas informações. As operações de Wi-Fi RTT são ilimitadas para aplicativos em primeiro plano, mas não para os em segundo plano.

O RTT do Wi-Fi e os recursos de Medição de tempo fino (FTM, na sigla em inglês) relacionados são especificados pela norma IEEE 802.11-2016. O Wi-Fi RTT exige o uso da medição de tempo precisa fornecida pelo FTM, já que ele calcula a distância medindo o tempo que um pacote leva para fazer uma viagem de ida e volta entre dois dispositivos e depois multiplica esse tempo pela velocidade da luz.

O Android 15 (nível 35 da API) introduziu suporte a IEEE 802.11az sem gatilho (NTB).

Diferenças de implementação baseadas na versão Android

O Wi-Fi RTT foi introduzido no Android 9 (API de nível 28). Para usar esse protocolo para determinar a posição de um dispositivo usando multilateration com dispositivos que executam o Android 9, você precisará ter acesso aos dados de localização do ponto de acesso (AP, na sigla em inglês) predeterminados no seu aplicativo. Você pode decidir a melhor forma de armazenar e recuperar esses dados.

Em dispositivos que executam Android 10 (API de nível 29) e versões mais recentes, os dados da localização do ponto de acesso podem ser representados por objetos ResponderLocation, que incluem latitude, longitude e altitude. Para os pontos de acesso do Wi-Fi RTT compatíveis com informações de configuração da localização/relatório cívico de localização (dados de LCI/LCR), o protocolo retornará um objeto ResponderLocation durante o processo de alcance.

Esse recurso permite que os aplicativos consultem diretamente os pontos de acesso para solicitar a posição deles, em vez de precisar armazenar essas informações antecipadamente. Dessa forma, seu aplicativo poderá encontrar pontos de acesso e determinar as posições relacionadas, mesmo que esses pontos sejam desconhecidos. Por exemplo, quando um usuário entra em um novo prédio.

O suporte ao alcance NTB IEEE 802.11az está disponível em dispositivos com o Android 15 (nível 35 da API) e mais recentes. Isso significa que, se o dispositivo oferecer suporte a IEEE 802.11az, Modo de resposta do NTB (indicado por WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_STA_RESPONDER), seu app poderá encontrar APs compatíveis com IEEE 802.11mc e IEEE 802.11az com um único de intervalo de endereços IP. A API RangingResult foi estendida para fornecer informações sobre os valores mínimo e máximo que podem ser usados para o intervalo entre o alcance de medições, deixando o intervalo exato no controle do aplicativo.

Requisitos

• O hardware do dispositivo que faz a solicitação de alcance deve implementar a Padrão FTM 802.11-2016 ou padrão 802.11az (variação não baseada em gatilhos).
• O dispositivo que faz a solicitação de alcance precisa executar o Android 9 (API de nível 28) ou versão mais recente. O alcance não baseado em acionador do IEEE 802.11az está ativado nos dispositivos com o Android 15 (nível 35 da API) e versões mais recentes.
• O dispositivo que faz a solicitação de alcance precisa ter a busca por Wi-Fi e os serviços de localização ativados (em Configurações > Localização).
• Se o app que faz a solicitação de alcance segmentar Android 13 (nível 33 da API) ou versões mais recentes, precisa ter a NEARBY_WIFI_DEVICES permissão. Se um aplicativo é direcionado a uma versão anterior do Android, ele precisa têm os ACCESS_FINE_LOCATION no lugar da permissão.
• O aplicativo deve consultar o alcance de pontos de acesso enquanto o aplicativo está visível ou em um serviço em primeiro plano. O aplicativo não pode acessar as informações de localização em segundo plano.
• O ponto de acesso precisa implementar o padrão FTM IEEE 802.11-2016 ou IEEE Padrão 802.11az (intervalo não baseado em gatilho).

Configurar

Se você quiser configurar o aplicativo para usar o Wi-Fi RTT, siga estas etapas:

1. Solicite permissões

Solicite as seguintes permissões no manifesto do 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" />

As permissões NEARBY_WIFI_DEVICES e ACCESS_FINE_LOCATION são perigosas portanto, você precisa solicitá-las no momento da execução sempre que o usuário quiser executar uma operação de verificação de RTT. Seu app precisará solicitar a permissão se ela ainda não tiver sido concedida. Para mais informações sobre permissões de execução, consulte Solicite permissões do app.

2. Verifique se o dispositivo é compatível com Wi-Fi RTT

Para verificar se o dispositivo é compatível com Wi-Fi RTT, use o API PackageManager:

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

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

3. Verifique se o Wi-Fi RTT está disponível

O Wi-Fi RTT pode estar presente no dispositivo, mas não estar disponível porque o usuário desativou o Wi-Fi. Dependendo dos recursos de hardware e firmware, alguns Os dispositivos podem não oferecer suporte ao Wi-Fi RTT se o SoftAP ou o tethering estiverem em uso. Para verificar se o Wi-Fi RTT está disponível, ligue isAvailable()

A disponibilidade do Wi-Fi RTT pode mudar a qualquer momento. Seu aplicativo deve registrar um BroadcastReceiver para receber ACTION_WIFI_RTT_STATE_CHANGED, que é enviado quando a disponibilidade muda. Ao receber o intent de transmissão, seu aplicativo deverá verificar o estado atual da disponibilidade e ajustar o próprio comportamento de acordo com essa informação.

Por exemplo:

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

Para mais informações, consulte Visão geral de transmissões.

Criar uma solicitação de alcance

Uma solicitação de alcance (RangingRequest) é criado especificando uma lista de APs ou pontos Wi-Fi Aware aos quais um intervalo é solicitado. É possível especificar vários pontos de acesso ou pontos do Wi-Fi Aware em uma única solicitação. As distâncias para todos os dispositivos são medidas e retornadas.

Por exemplo, uma solicitação pode usar addAccessPoint() para especificar um ponto de acesso para medir a distância:

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

Um ponto de acesso é identificado pela objeto ScanResult, que pode ser conseguido chamando WifiManager.getScanResults() Você pode usar addAccessPoints(List<ScanResult>) para adicionar vários pontos de acesso em um lote.

Objetos ScanResult podem conter IEEE 802.11mc (is80211mcResponder()) e Compatível com alcance não baseado em gatilho (is80211azNtbResponder()) IEEE 802.11az APs. Os dispositivos compatíveis com o intervalo NTB IEEE 802.11az executam 802.11mc ou 802.11az variando dependendo da capacidade do AP, deixando o padrão 802.11az quando o AP oferece suporte a ambos. Dispositivos que não têm suporte a IEEE 802.11az realizam todas usando o protocolo IEEE 802.11mc.

Da mesma forma, uma solicitação de alcance pode adicionar um ponto Wi-Fi Aware usando o MAC ou o PeerHandle dele, usando as addWifiAwarePeer(MacAddress peer) e addWifiAwarePeer(PeerHandle peer) , respectivamente. Para mais informações sobre como descobrir pontos do Wi-Fi Aware, consulte a documentação do Wi-Fi Aware.

Solicitar o alcance

Um app emite uma solicitação de alcance usando o WifiRttManager.startRanging() e forneça o seguinte: RangingRequest para especificar operação, um Executor para especificar o contexto de callback e uma RangingResultCallback para receber os resultados.

Exemplo:

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

A operação de alcance é executada de forma assíncrona, e os resultados de alcance são retornado em um dos callbacks RangingResultCallback:

• Se toda a operação de alcance falhar, o onRangingFailure callback é acionado com um código de status descrito em RangingResultCallback Esse erro ocorrerá caso o serviço não possa executar uma operação de alcance no momento. Por exemplo, o Wi-Fi está desativado, o aplicativo ultrapassou o limite de solicitações de alcance ou devido a um problema de permissão.
• Quando a operação de alcance for concluída, o onRangingResults callback é acionado com uma lista de resultados que corresponde à lista de solicitações, um resultado para cada solicitação. A ordem dos resultados não corresponderá necessariamente à das solicitações. A operação de alcance talvez seja concluída, mas cada resultado ainda poderá indicar uma falha nessa medição específica.

Interpretar os resultados de alcance

Cada um dos resultados retornados pelo onRangingResults callback é especificado por um RangingResult. objeto. Em cada solicitação, faça o seguinte:

1. Identifique a solicitação

Identifique a solicitação com base nas informações fornecidas ao criar o RangingRequest: na maioria das vezes, um endereço MAC fornecido no ScanResult identificando um ponto O endereço MAC pode ser obtido a partir do resultado de alcance usando o getMacAddress() .

A lista de resultados de alcance pode estar em ordem diferente dos pontos (pontos de acesso) especificados na solicitação. Por isso, use o endereço MAC para identificar o ponto, não a ordem dos resultados.

2. Determine se cada medição foi concluída

Para determinar se uma medição foi bem-sucedida, use o getStatus() . Qualquer valor que não seja STATUS_SUCCESS indica uma falha. Uma falha significa que todos os outros campos deste resultado (exceto a identificação da solicitação acima) são inválidos, e o O método get* vai falhar com uma IllegalStateException.

3. Veja os resultados para cada medição concluída

Para cada medição bem-sucedida (RangingResult), é possível recuperar o resultado com os respectivos métodos get:

• Confira a distância em mm e o desvio padrão da medição:

  getDistanceMm()

  getDistanceStdDevMm()

• Veja o RSSI dos pacotes utilizados para as medições:

  getRssi()

• Confira o tempo em milissegundos da mediação (indicando o tempo desde a inicialização):

  getRangingTimestampMillis()

• Saiba o número de tentativas de medição e quantos processos foram concluídos (e em quais ocorrências a medição da distância se baseia):

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

• Tempo mínimo e máximo que um dispositivo cliente deve aguardar entre 11 az NTB medições:

  getMinTimeBetweenNtbMeasurementsMicros() e getMaxTimeBetweenNtbMeasurementsMicros() para retornar os tempos mínimo e máximo. Se a próxima medição de alcance for solicitado antes que o tempo mínimo tenha decorrido, a API retornará o resultado de alcance armazenado em cache. Se a próxima medição de alcance for solicitada após o tempo máximo decorrido, a API encerra o não acionador de alcance e negocia uma nova sessão com o responsável estação Evite solicitar uma nova sessão de alcance, porque isso adiciona sobre o intervalo de tempo de medição. Para aproveitar ao máximo a 802.11az eficiência de alcance com base em gatilhos, acionar a próxima solicitação de alcance entre os tempos mínimo e máximo de medição especificados nos intervalos anteriores RangingResult medida.

• Repetições de Long Training Field (LTF) que as estações de início e de resposta usado no preâmbulo do resultado do NTB de IEEE 802.11az:

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

• Número de fluxos de tempo espacial (STS) de transmissão e recebimento que o iniciador estação usada no resultado do IEEE 802.11az NTB:

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

Dispositivos Android compatíveis com Wi-Fi RTT

As tabelas a seguir listam alguns smartphones, pontos de acesso e dispositivos de centros de distribuição, armazenamento e varejo. compatíveis com Wi-Fi-RTT. Elas não abrangem todos os dispositivos compatíveis. Recomendamos que você entre em contato conosco para listar seus produtos compatíveis com RTT aqui.

Pontos de acesso

Smartphones

Dispositivos para centros de distribuição, armazenamento e varejo