Wi-Fi hotspot (Soft AP)

Android provides support for Wi-Fi hotspot (Soft AP) including tethering through a Wi-FI hotspot and local-only Wi-Fi hotspots.

The soft AP feature allows for the configuration of the following:

  • SSID and BSSID
  • Security type (including WPA3)
  • Hidden SSID
  • Operating band and channel (including ACS)
  • Maximum number of allowed clients
  • Autoshutdown timeout value
  • Allowlist and blocklist to allow user control of associated devices
  • Level of MAC randomization for the AP BSSID
  • 802.11ax and 802.11be

Device capabilities determine the availability of these controls. Android 11 introduces APIs to obtain these capabilities. Device manufacturers can also specify base device capabilities using overlays.

Note that some of the APIs are system APIs and are restricted through permissions so that only the system's Settings app can access them.

Develop apps with hotspot APIs

A default implementation of a tethered Wi-Fi hotspot is provided by the AOSP Settings app, however it doesn't exercise all of the APIs for Soft AP configuration.

To support tethering through a hotspot or a local-only hotspot, the app must perform the following functions:

  1. Register a callback to obtain the device capabilities using WifiManager#registerSoftApCallback for a tethered hotspot or WifiManager#registerLocalOnlyHotspotSoftApCallback for a local-only hotspot.

    The SoftApCallback callback provides the following methods:

    • SoftApCallback#onCapabilityChanged: Provides information about device capabilities, including the maximum number of supported clients, and whether SAE or ACS are supported.
    • SoftApCallback#onInfoChanged: Provides information about the running Soft AP (only valid once started), including band and frequency information.
    • SoftApCallback#onConnectedClientsChanged: Provides a list of connected clients. For each client, you can obtain the MAC address. To obtain the IP information, use the TetheringEventCallback#onClientsChanged callback.
    • SoftApCallback#onStateChanged: Provides updates on the state of the Soft AP as it gets enabled and disabled.
    • SoftApCallback#onBlockedClientConnecting: Provides the blocked client information with one of the following reasons for the block: the device reached the maximum number of clients that it can support or the client isn't explicitly authorized to connect.

For a tethered hotspot:

  1. Configure the soft AP configuration for tethering by calling the WifiManager#setSoftApConfiguration method and providing a SoftApConfiguration instance. Construct SoftApConfiguration using the SoftApConfiguration.Builder class.
  2. Start the tethering by calling the tethering method at TetheringManager#startTethering.

For local-only hotspot:

  1. Start the local-only hotspot with a specific soft AP configuration by calling the WifiManager#startLocalOnlyHotspot method.

Implement allow and block lists

A typical carrier requirement is to provide the user with controls of the devices that are allowed to associate to the Soft AP. There are several mechanisms to do this:

  • Limit the maximum number of devices that can associate to the soft AP using SoftApConfiguration.Builder#setMaxNumberOfClients. Make sure to specify a number that's lower than the maximum number of clients supported by the device. You can obtain the maximum number from SoftApCapability#getMaxSupportedClients.

  • Provide dynamic control using allow and block lists:

    • The default configuration of a Soft AP allows all devices to associate to the soft AP except for devices whose MAC addresses are added to SoftApConfiguration.Builder#setBlockedClientList.

    • If the Soft AP is configured with SoftApConfiguration.Builder#setClientControlByUserEnabled(true), the allow list is used.

      • All devices whose MAC addresses are in SoftApConfiguration.Builder#setBlockedClientList are blocked from association.
      • All devices whose MAC addresses are in SoftApConfiguration.Builder#setAllowedClientList are allowed association.
      • All other devices (that is, devices whose MAC addresses aren't in the allow or block list) are blocked from association but SoftApCallback#onBlockedClientConnecting is called, allowing the controlling app (that is, the Settings app) to take an action, for example, asking the user for confirmation and then adding the device to the allow list or to the block list depending on the user's behavior.

    Note that devices can only use the allow list functionality if it's supported on the device. You can verify device support using SoftApCapability#areFeaturesSupported(SOFTAP_FEATURE_CLIENT_FORCE_DISCONNECT).

Implementation

To support tethering through a hotspot or to support a local-only hotspot, device manufacturers must provide Settings app, framework, and HAL/firmware support:

  • Settings app: The AOSP Settings app provides a baseline for configuring a tethering hotspot with SSID and security credentials. This code can be used as is or modified to provide additional capabilities as described in Developing apps with hotspot APIs.

  • Framework: The AOSP framework code supports all of the functionality described in Developing apps with hotspot APIs.

  • HAL/firmware for hotspot: Either the HIDL IHostapd.hal version 1.2 or higher, or the AIDL IHostapd.aidl.

Customization

To customize the implementation, device manufacturers should configure the following overlays and carrier configurations, which are documented in packages/modules/Wifi/service/ServiceWifiResources/res/values/config.xml:

  • config_wifiFrameworkSoftApShutDownTimeoutMilliseconds: The default shutdown timeout interval. Only valid if SoftApConfiguration#setAutoShutdownEnabled is enabled. Can be overridden using SoftApConfiguration#setShutdownTimeoutMillis.
  • config_wifiHardwareSoftapMaxClientCount: The hardware limitation for the maximum number of supported clients. The maximum number of clients that the device supports is the minimum of the hardware and carrier constraints (specified by CarrierConfigManager.Wifi#KEY_HOTSPOT_MAX_CLIENT_COUNT). The final result is provided to the app with SoftApCapabilities#getMaxSupportedClients.
  • config_wifiSofapClientForceDisconnectSupported: Whether the device has the ability to force disconnect a client. Required to enable allow and block lists. Communicated to the controlling app (Settings app) through SoftApCapabilities#areFeaturesSupported(SOFTAP_FEATURE_CLIENT_FORCE_DISCONNECT).
  • (Available from 13) config_wifiSoftapPassphraseAsciiEncodableCheck: Whether or not the soft AP passphrase is required to be ASCII encodable.
  • config_wifiSoftapAutoUpgradeToBridgedConfigWhenSupported: Whether or not to automatically upgrade band setting configuration to dual bands during cloud configuration restore when a new device is supported.
  • (Available from 13) config_wifiSoftapAutoAppendLowerBandsToBandConfigurationEnabled: Whether the framework automatically appends lower bands to band configuration for avoiding coexistence handling.
  • config_wifiSoftApDynamicCountryCodeUpdateSupported: Whether or not dynamic country code update in AP mode are supported on the device
  • Channel support: config_wifiSoftap2gChannelList, config_wifiSoftap5gChannelList, config_wifiSoftap6gChannelList and config_wifiSoftap60gChannelList.
  • Restore support specifying whether the corresponding entries are reset to default when restoring the hotspot configuration to a new device: config_wifiSoftapResetChannelConfig, config_wifiSoftapResetHiddenConfig, config_wifiSoftapResetUserControlConfig, config_wifiSoftapResetAutoShutdownTimerConfig, config_wifiSoftapResetMaxClientSettingConfig. Note that these are set to true by default, meaning that the values are reset. This is critical if the new device doesn't support the configuration.
  • Hardware capabilities:
    • config_wifi_softap_acs_supported
    • config_wifi_softap_sae_supported
    • (Available from 13) config_wifiSoftapOweTransitionSupported
    • (Available from 13) config_wifiSoftapOweSupported
    • config_wifi_softap_ieee80211ac_supported
    • config_wifiSoftapIeee80211axSupported
    • (Available from 13) config_wifiSoftapIeee80211beSupported
    • config_wifiSoftapMacAddressCustomizationSupported
    • config_wifiSoftapHeSuBeamformerSupported
    • config_wifiSoftapHeSuBeamformeeSupported
    • config_wifiSoftapHeMuBeamformerSupported
    • config_wifiSoftapHeTwtSupported
    • config_wifiSoftap24ghzSupported
    • config_wifiSoftap5ghzSupported
    • config_wifiSoftap6ghzSupported
    • config_wifiSoftap60ghzSupported
    • config_wifiSoftapAcsIncludeDfs

Validation

Android provides a set of unit tests and Compatibility Test Suite (CTS) tests to validate the hotspot feature. The hotspot feature can also be tested using the Vendor Test Suite (VTS).

Unit tests

Verify the hotspot package using the following tests.

  • Service tests:

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

  • Manager tests:

    atest packages/modules/Wifi/framework/tests/

Compatibility Test Suite (CTS) tests

Use CTS tests to validate the hotspot feature. CTS detects when the feature is enabled and automatically includes the associated tests.

To trigger the CTS tests, run:

atest android.net.wifi.cts.WifiManagerTest

Vendor Test Suite (VTS)

If the HIDL interface is implemented, run:

atest VtsHalWifiHostapdV1_2Target

If the AIDL interface is implemented, run:

atest VtsHalHostapdTargetTest