Wi-Fi Hotspot (Soft AP) Support for Tethering

Android supports tethering through a Wi-Fi hotspot (Soft AP). From Android 11, the Soft AP configuration available to device manufacturers supports more carrier use cases and customizations, including 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

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.

Examples and source

A default implementation is provided by the AOSP Settings app, however it doesn't exercise all of the APIs for Soft AP configuration. A calling app must perform these three functions:

  1. Register a callback to obtain the device capabilities using WifiManager#registerSoftApCallback. The SoftApCallback callback provides several 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.

  2. Configure the Soft AP configuration to be used for tethering by calling the WifiManager#setSoftApConfiguration method and providing a SoftApConfiguration instance. You can construct SoftApConfiguration using the SoftApConfiguration.Builder class.

  3. Start the tethering by calling the tethering method at TetheringManager#startTethering.

Implementing 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 Wi-Fi hotspot (Soft AP), 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 Examples and source.

  • Framework: The AOSP framework code supports all of the functionality described in Examples and source.

  • HAL/firmware for hotspot: IHostapd.HAL version 1.2 or higher.

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).
  • Channel support: config_wifiSoftap2gChannelList, config_wifiSoftap5gChannelList, and config_wifiSoftap6gChannelList.
  • 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
    • config_wifi_softap_ieee80211ac_supported
    • config_wifiSoftapIeee80211axSupported
    • config_wifiSoftapHeSuBeamformerSupported
    • config_wifiSoftapHeSuBeamformeeSupported
    • config_wifiSoftapHeMuBeamformerSupported
    • config_wifiSoftapHeTwtSupported
    • config_wifiSoftap6ghzSupported
    • config_wifiSoftapAcsIncludeDfs

Validation

Android provides a set of unit tests, integration tests (Android Connectivity Test Suite, or ACTS), 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/

Integration tests (ACTS)

The ACTS hotspot test suite, located in tools/test/connectivity/acts/tests/google/wifi/WifiSoftApTest.py, implements functional tests of the hotspot feature.

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)

To run the VTS tests, run:

atest VtsHalWifiHostapdV1_2Target