Ponto de acesso Wi-Fi (Soft AP)

O Android oferece suporte a pontos de acesso Wi-Fi (AP suave), incluindo tethering por um ponto de acesso Wi-Fi e pontos de acesso Wi-Fi somente locais.

O recurso de AP flexível permite configurar o seguinte:

  • SSID e BSSID;
  • tipo de segurança (WPA3 incluso);
  • SSID oculto;
  • banda e canal operacional (ACS incluso);
  • número máximo de clientes permitidos;
  • valor do tempo limite do encerramento automático;
  • lista de permissões e lista de bloqueio para permitir o controle do usuário dos dispositivos associados.
  • Nível de randomização de MAC para o BSSID do AP
  • 802.11ax e 802.11be

A disponibilidade desses controles depende dos recursos do dispositivo. O Android 11 introduz APIs para obter esses recursos. Os fabricantes de dispositivos também podem especificar recursos básicos usando sobreposições.

Algumas APIs são do sistema e estão restritas por permissões para que apenas o app Configurações do sistema possa acessá-las.

Desenvolver apps com APIs de hotspot

Uma implementação padrão de um ponto de acesso Wi-Fi conectado é fornecida pelo app Configurações do AOSP, mas não usa todas as APIs para configuração de Soft AP.

Para oferecer suporte ao tethering por um ponto de acesso ou um ponto de acesso somente local, o app precisa executar as seguintes funções:

  1. Registre um callback para receber os recursos do dispositivo usando WifiManager#registerSoftApCallback para um ponto de acesso conectado ou WifiManager#registerLocalOnlyHotspotSoftApCallback para um ponto de acesso somente local.

    O callback SoftApCallback fornece os seguintes métodos:

    • SoftApCallback#onCapabilityChanged: fornece informações sobre os recursos do dispositivo, incluindo o número máximo de clientes compatíveis e se o SAE ou o ACS são compatíveis.
    • SoftApCallback#onInfoChanged: fornece informações sobre o ponto de acesso de software em execução (válido apenas uma vez iniciado), incluindo informações de banda e frequência.
    • SoftApCallback#onConnectedClientsChanged: fornece uma lista de clientes conectados. Para cada cliente, é possível obter o endereço MAC. Para receber as informações de IP, use o callback TetheringEventCallback#onClientsChanged.
    • SoftApCallback#onStateChanged: fornece atualizações sobre o estado do AP suave à medida que ele é ativado e desativado.
    • SoftApCallback#onBlockedClientConnecting: fornece as informações do cliente bloqueado com um dos seguintes motivos para o bloqueio: o dispositivo atingiu o número máximo de clientes que ele pode suportar ou o cliente não está explicitamente autorizado a se conectar.
    • SoftApCallback#onClientsDisconnected: fornece uma lista dos clientes desconectados. Para cada cliente, é possível receber o motivo da desconexão.

Para um ponto de acesso conectado por tethering:

  1. Configure o AP suave para tethering chamando o método WifiManager#setSoftApConfiguration e fornecendo uma instância SoftApConfiguration. Construa SoftApConfiguration usando a classe SoftApConfiguration.Builder.
  2. Inicie o tethering chamando o método em TetheringManager#startTethering.

Para um ponto de acesso somente local:

  1. Inicie o ponto de acesso somente local com uma configuração específica de AP de software chamando o método WifiManager#startLocalOnlyHotspot.

Implementar listas de permissão e de bloqueio

Um requisito típico da operadora é fornecer ao usuário controles dos dispositivos que podem ser associados ao Soft AP. Há vários mecanismos para fazer isso:

  • Limite o número máximo de dispositivos que podem se associar ao AP usando SoftApConfiguration.Builder#setMaxNumberOfClients. Especifique um número menor que o máximo de clientes aceitos pelo dispositivo. Você pode conferir o número máximo em SoftApCapability#getMaxSupportedClients.

  • Ofereça controle dinâmico usando listas de permissões e de bloqueio:

    • A configuração padrão de um AP virtual permite que todos os dispositivos se associem a ele, exceto aqueles cujos endereços MAC são adicionados a SoftApConfiguration.Builder#setBlockedClientList.

    • Se o Soft AP estiver configurado com SoftApConfiguration.Builder#setClientControlByUserEnabled(true), a lista de permissões será usada.

      • Todos os dispositivos com endereços MAC em SoftApConfiguration.Builder#setBlockedClientList são bloqueados para associação.
      • Todos os dispositivos cujos endereços MAC estão em SoftApConfiguration.Builder#setAllowedClientList podem ser associados.
      • Todos os outros dispositivos (ou seja, aqueles cujos endereços MAC não estão na lista de permissões ou de bloqueio) são impedidos de se associar, mas SoftApCallback#onBlockedClientConnecting é chamado, permitindo que o app de controle (ou seja, o app Configurações) tome uma ação, por exemplo, pedindo confirmação ao usuário e adicionando o dispositivo à lista de permissões ou de bloqueio, dependendo do comportamento do usuário.

    Os dispositivos só podem usar a funcionalidade de lista de permissões se ela for compatível com o dispositivo. É possível verificar a compatibilidade do dispositivo usando SoftApCapability#areFeaturesSupported(SOFTAP_FEATURE_CLIENT_FORCE_DISCONNECT).

Implementação

Para oferecer suporte ao tethering por um ponto de acesso ou a um ponto de acesso somente local, os fabricantes de dispositivos precisam fornecer suporte para o app Configurações, framework e HAL/firmware:

  • App Configurações:o app Configurações do AOSP oferece uma base para configurar um hotspot de tethering com SSID e credenciais de segurança. Esse código pode ser usado como está ou modificado para oferecer recursos adicionais, conforme descrito em Desenvolver apps com APIs de hotspot.

  • Framework:o código do framework AOSP é compatível com todas as funcionalidades descritas em Desenvolver apps com APIs de hotspot.

  • HAL/firmware para hotspot:HIDL IHostapd.hal versão 1.2 ou mais recente ou AIDL IHostapd.aidl.

Personalização

Para personalizar a implementação, os fabricantes de dispositivos precisam configurar as seguintes sobreposições e configurações de operadora, que estão documentadas em packages/modules/Wifi/service/ServiceWifiResources/res/values/config.xml:

  • config_wifiFrameworkSoftApShutDownTimeoutMilliseconds: o intervalo de tempo limite de desligamento padrão. Válido apenas se SoftApConfiguration#setAutoShutdownEnabled estiver ativado. Pode ser substituído usando SoftApConfiguration#setShutdownTimeoutMillis.
  • config_wifiHardwareSoftapMaxClientCount: a limitação de hardware para o número máximo de clientes compatíveis. O número máximo de clientes que o dispositivo aceita é o mínimo das restrições de hardware e operadora (especificadas por CarrierConfigManager.Wifi#KEY_HOTSPOT_MAX_CLIENT_COUNT). O resultado final é fornecido ao app com SoftApCapabilities#getMaxSupportedClients.
  • config_wifiSofapClientForceDisconnectSupported: se o dispositivo tem a capacidade de forçar a desconexão de um cliente. Necessário para ativar listas de permissão e de bloqueio. Comunicado ao app de controle (app Configurações) por SoftApCapabilities#areFeaturesSupported(SOFTAP_FEATURE_CLIENT_FORCE_DISCONNECT).
  • (Disponível a partir da versão 13) config_wifiSoftapPassphraseAsciiEncodableCheck: Indica se a senha longa do ponto de acesso suave precisa ser codificada em ASCII.
  • config_wifiSoftapAutoUpgradeToBridgedConfigWhenSupported: se a configuração de banda será atualizada automaticamente para banda dupla durante a restauração da configuração na nuvem quando um novo dispositivo for compatível.
  • (Disponível a partir da versão 13) config_wifiSoftapAutoAppendLowerBandsToBandConfigurationEnabled: Se a estrutura anexa automaticamente bandas inferiores à configuração de banda para evitar o processamento de coexistência.
  • config_wifiSoftApDynamicCountryCodeUpdateSupported: se a atualização dinâmica do código do país no modo AP é compatível com o dispositivo.
  • Suporte a canais: config_wifiSoftap2gChannelList, config_wifiSoftap5gChannelList, config_wifiSoftap6gChannelList e config_wifiSoftap60gChannelList.
  • Suporte à restauração especificando se as entradas correspondentes são redefinidas para o padrão ao restaurar a configuração do hotspot em um novo dispositivo: config_wifiSoftapResetChannelConfig, config_wifiSoftapResetHiddenConfig, config_wifiSoftapResetUserControlConfig, config_wifiSoftapResetAutoShutdownTimerConfig, config_wifiSoftapResetMaxClientSettingConfig. Por padrão, elas são definidas como true, o que significa que os valores são redefinidos. Isso é essencial se o novo dispositivo não for compatível com a configuração.
  • Recursos de hardware:
    • config_wifi_softap_acs_supported
    • config_wifi_softap_sae_supported
    • (Disponível a partir da versão 13) config_wifiSoftapOweTransitionSupported
    • (Disponível a partir da versão 13) config_wifiSoftapOweSupported
    • config_wifi_softap_ieee80211ac_supported
    • config_wifiSoftapIeee80211axSupported
    • (Disponível a partir da versão 13) config_wifiSoftapIeee80211beSupported
    • config_wifiSoftapMacAddressCustomizationSupported
    • config_wifiSoftapHeSuBeamformerSupported
    • config_wifiSoftapHeSuBeamformeeSupported
    • config_wifiSoftapHeMuBeamformerSupported
    • config_wifiSoftapHeTwtSupported
    • config_wifiSoftap24ghzSupported
    • config_wifiSoftap5ghzSupported
    • config_wifiSoftap6ghzSupported
    • config_wifiSoftap60ghzSupported
    • config_wifiSoftapAcsIncludeDfs

Validação

O Android oferece um conjunto de testes de unidade e do conjunto de teste de compatibilidade (CTS) para validar o recurso de ponto de acesso. O recurso de hotspot também pode ser testado usando o pacote de testes de fornecedor (VTS).

Testes de unidade

Verifique o pacote de hotspot usando os testes a seguir.

  • Testes de serviço:

    atest packages/modules/Wifi/service/tests/wifitests/

  • Testes de gerente:

    atest packages/modules/Wifi/framework/tests/

Testes do conjunto de teste de compatibilidade (CTS)

Use testes do CTS para validar o recurso de ponto de acesso. O CTS detecta quando o recurso está ativado e inclui automaticamente os testes associados.

Para acionar os testes do CTS, execute:

atest android.net.wifi.cts.WifiManagerTest

Teste de fornecedor (VTS)

Se a interface HIDL estiver implementada, execute:

atest VtsHalWifiHostapdV1_2Target

Se a interface AIDL estiver implementada, execute:

atest VtsHalHostapdTargetTest