Alcance entre dispositivos

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O Android 16 apresenta o módulo de alcance, que fornece uma interface unificada e padronizada para alcance preciso entre dispositivos. É possível usar essa API para medir a distância e a posição de dispositivos pares sem precisar processar cada tecnologia de medição de distância individualmente.

O módulo de medição de distância é compatível com as seguintes tecnologias:

• Banda ultralarga
• Som de canal Bluetooth
• Wi-Fi NAN RTT
• Faixa de RSSI do Bluetooth

Recursos e disponibilidades de medição de distância

A classe RangingManager fornece aos apps informações sobre as tecnologias de medição de distância compatíveis com o dispositivo local, além da disponibilidade e os recursos de cada tecnologia. Os apps podem se registrar para um Callback e receber atualizações sobre mudanças na disponibilidade ou nos recursos de tecnologias com suporte.

Papéis do dispositivo

Um dispositivo que participa de uma sessão de medição precisa ser um iniciador ou um respondedor. O dispositivo iniciador inicia a sessão de medição com um ou mais dispositivos respondentes. Um dispositivo de resposta responde a solicitações de medição de distância de apenas um iniciador por vez. É possível especificar o papel de um determinado dispositivo em uma sessão de medição com a classe RangingPreference.

Tipos de sessões de alcance

Ao iniciar uma sessão de medição entre dispositivos, muitas vezes é necessário estabelecer um transporte de dados fora da banda (OOB) para trocar parâmetros da sessão.

O módulo de determinação de distância pode processar negociações OOB para você, mas também oferece suporte a implementações OOB personalizadas.

Implementação padrão de OOB

Nesse tipo de sessão (RANGING_SESSION_OOB), o módulo de medição de distância processa as negociações OOB para iniciar uma sessão de medição de distância. Ele seleciona parâmetros adequados com base nas preferências de alcance fornecidas pelo app e usa as tecnologias adequadas com base no que os dois dispositivos oferecem suporte. Esse tipo de sessão usa um OOB specification padronizado.

O módulo de medição de distância define apenas o formato e a sequência de dados OOB a serem usados para interagir com um dispositivo par. Ele não processa a descoberta de dispositivos pares ou o estabelecimento de conexão.

Implementação personalizada de OOB

Nesse tipo de sessão (RANGING_SESSION_RAW), o app ignora o fluxo OOB do módulo de medição de distância e lida com a própria negociação e os parâmetros OOB. Isso significa que o app precisa determinar quais tecnologias o dispositivo peer oferece suporte, negociar parâmetros de medição e iniciar a sessão de medição.

Preferências de classificação

Use um objeto RangingPreference para especificar os parâmetros desejados para uma sessão de medição. Isso inclui o seguinte:

• Função do dispositivo. Isso indica se o dispositivo será o iniciador ou o respondente.
• Configuração de medição de distância. Um objeto RangingConfig especifica o tipo de sessão de medição e outros parâmetros necessários para iniciar uma sessão de medição.
• Configuração da sessão. Um objeto SessionConfig especifica parâmetros a serem aplicados na sessão de medição, como limite de medição, fusão de sensores, configuração de geofence e muito mais.

Permissão de alcance

O módulo de medição de distância precisa de uma nova permissão unificada (android.permission.RANGING) para acessar todas as tecnologias de medição de distância atuais e futuras. Essa permissão está na lista NEARBY_DEVICES_PERMISSIONS.

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

Restrições e limitações

O módulo de medição de distância pode restringir a medição por vários motivos, incluindo:

• Os apps de terceiros só podem realizar a faixa de segundo plano com ultrabanda larga e apenas em dispositivos compatíveis. Não é permitido fazer a medição de distância em segundo plano com outras tecnologias.
• A detecção de alcance não é permitida quando o número máximo de sessões de detecção simultâneas por dispositivo é atingido.
• A medição de distância pode ser restrita devido a problemas de integridade do sistema, como bateria, desempenho ou memória.

O módulo de medição de distância também tem as seguintes limitações conhecidas:

• O módulo de medição de distância só oferece suporte ao envio de dados de medição de distância para dispositivos pares em banda ultralarga. Para outras tecnologias, o módulo de medição de distância só envia dados de medição de distância para o dispositivo iniciador.
• O módulo de medição de distância só oferece suporte à adição dinâmica de dispositivos no modo de medição de distância bruto e apenas para a banda ultralarga.
• O módulo de posicionamento não oferece suporte a sessões de banda ultralarga um-para-muitos para implementações OOB padrão. Se você transmitir vários identificadores de dispositivo, o módulo vai criar uma sessão individual para cada dispositivo peer compatível com ultra-banda.

Realizar uma sessão de medição de distância

Para realizar uma sessão de medição de distância usando o módulo de medição de distância, siga estas etapas:

1. Verifique se todos os dispositivos estão operando no Android 16 ou em uma versão mais recente.
2. Solicite a permissão android.permission.RANGING no manifesto do app.
3. Avalie os recursos e a disponibilidade das tecnologias de medição de distância.
4. Detectar um dispositivo par para operações de medição de distância.
5. Estabeleça uma conexão para uma troca fora de banda usando um dos tipos de sessão descritos em Tipos de sessão de alcance.
6. Iniciar a medição e adquirir dados de medição continuamente.
7. Encerre a sessão de medição.

O exemplo de código abaixo demonstra essas etapas para a função de iniciador e a função de respondente.

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

App de exemplo

Para um exemplo completo de como usar o módulo de medição de distância, consulte o app de exemplo no AOSP. Esse app de exemplo abrange todas as tecnologias de medição com suporte do módulo de medição e inclui fluxos para os dois tipos de sessão com suporte.