Ponto de acesso Wi-Fi (Soft AP)

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

O recurso Soft AP 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 ordem aleatória de MAC para o BSSID do AP;
  • 802.11ax e 802.11be.

Os recursos do dispositivo determinam a disponibilidade desses controles. O Android 11 introduziu APIs para receber esses recursos. Os fabricantes de dispositivos também podem especificar recursos básicos do dispositivo usando sobreposições.

Desenvolver apps com APIs de ponto de acesso

Uma implementação padrão de um ponto de acesso Wi-Fi com tethering é fornecida pelo app Configurações do Android Open Source Project (AOSP), mas ela não usa todas as APIs para configuração do 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 com tethering 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 com suporte e se o SAE ou o ACS são compatíveis.
    • SoftApCallback#onInfoChanged: fornece informações sobre o Soft AP em execução (válido apenas após o início), incluindo informações de banda e frequência.
    • SoftApCallback#onConnectedClientsChanged: fornece uma lista de clientes conectados. Para cada cliente, é possível receber 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 Soft AP à 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 pode oferecer suporte 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 com tethering:

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

Para um ponto de acesso somente local:

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

Implementar listas de permissões e de bloqueio

Um requisito comum das operadoras é 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 ser associados ao Soft AP usando SoftApConfiguration.Builder#setMaxNumberOfClients. Especifique um número menor que o máximo de clientes com suporte no dispositivo. É possível receber o número máximo de SoftApCapability#getMaxSupportedClients.

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

    • A configuração padrão de um Soft AP permite que todos os dispositivos sejam associados ao Soft AP, 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 cujos endereços MAC estão em SoftApConfiguration.Builder#setBlockedClientList são bloqueados da associação.
      • Todos os dispositivos cujos endereços MAC estão em SoftApConfiguration.Builder#setAllowedClientList têm permissão para associação.
      • 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 bloqueados da associação, 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 à lista de bloqueio, dependendo do comportamento do usuário.

    Os dispositivos só podem usar a funcionalidade da lista de permissões se ela for compatível com o dispositivo. É possível verificar o suporte 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 um app de configurações, framework e suporte a HAL/firmware:

  • App Configurações:o app Configurações do Android Open Source Project (AOSP) fornece uma linha de base para configurar um ponto de acesso com tethering com SSID e credenciais de segurança. Esse código pode ser usado no estado em que se encontra ou modificado para fornecer recursos adicionais, conforme descrito em Desenvolver apps com APIs de ponto de acesso.

  • Framework: O código do framework do AOSP oferece suporte a todas as funcionalidades descritas em Desenvolver apps com APIs de ponto de acesso.

  • HAL/firmware para ponto de acesso: a versão 1.2 ou mais recente do HIDL IHostapd.hal ou o AIDL IHostapd.aidl.

Personalização

Para personalizar a implementação, recomendamos que os fabricantes de dispositivos configurem 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. Só é válido 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 com suporte. O número máximo de clientes com suporte no dispositivo é o mínimo das restrições de hardware e de operadora (especificadas por CarrierConfigManager.Wifi#KEY_HOTSPOT_MAX_CLIENT_COUNT). O resultado final é fornecido ao app com SoftApCapabilities#getMaxSupportedClients.
  • config_wifiSofapClientForceDisconnectSupported: indica se o dispositivo tem a capacidade de forçar a desconexão de um cliente. Necessário para ativar listas de permissões e de bloqueio. Comunicado ao app de controle (app Configurações) por SoftApCapabilities#areFeaturesSupported(SOFTAP_FEATURE_CLIENT_FORCE_DISCONNECT).
  • (Disponível a partir do Android 13) config_wifiSoftapPassphraseAsciiEncodableCheck: indica se a senha do Soft AP precisa ser codificável em ASCII.
  • config_wifiSoftapAutoUpgradeToBridgedConfigWhenSupported: indica se a configuração de banda deve ser atualizada automaticamente para bandas duplas durante a restauração da configuração da nuvem quando um novo dispositivo é compatível.
  • (Disponível a partir do Android 13) config_wifiSoftapAutoAppendLowerBandsToBandConfigurationEnabled: indica se o framework anexa automaticamente bandas mais baixas à configuração de banda para evitar o processamento de coexistência.
  • config_wifiSoftApDynamicCountryCodeUpdateSupported: indica 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 ponto de acesso para um novo dispositivo: config_wifiSoftapResetChannelConfig, config_wifiSoftapResetHiddenConfig, config_wifiSoftapResetUserControlConfig, config_wifiSoftapResetAutoShutdownTimerConfig, config_wifiSoftapResetMaxClientSettingConfig. Esses valores são definidos como true por padrão, o que significa que os valores são redefinidos. Isso é fundamental se o novo dispositivo não oferecer suporte à configuração.
  • Recursos de hardware:
    • config_wifi_softap_acs_supported
    • config_wifi_softap_sae_supported
    • (Disponível a partir do Android 13) config_wifiSoftapOweTransitionSupported
    • (Disponível a partir do Android 13) config_wifiSoftapOweSupported
    • config_wifi_softap_ieee80211ac_supported
    • config_wifiSoftapIeee80211axSupported
    • (Disponível a partir do Android 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 fornece um conjunto de testes de unidade e testes do conjunto de testes de compatibilidade (CTS) para validar o recurso de ponto de acesso. O recurso de ponto de acesso também pode ser testado usando o conjunto de testes de fornecedor (VTS).

Testes de unidade

Verifique o pacote de ponto de acesso usando os seguintes testes.

  • Testes de serviço:

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

  • Testes de administrador:

    atest packages/modules/Wifi/framework/tests/

Testes do conjunto de testes de compatibilidade (CTS)

Use os 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

Conjunto de testes de fornecedor (VTS)

Se a interface HIDL estiver implementada, execute:

atest VtsHalWifiHostapdV1_2Target

Se a interface AIDL estiver implementada, execute:

atest VtsHalHostapdTargetTest