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:
Register a callback to obtain the device capabilities using
WifiManager#registerSoftApCallback
. TheSoftApCallback
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 theTetheringEventCallback#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.
Configure the Soft AP configuration to be used for tethering by calling the
WifiManager#setSoftApConfiguration
method and providing aSoftApConfiguration
instance. You can constructSoftApConfiguration
using theSoftApConfiguration.Builder
class.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 fromSoftApCapability#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.
- All devices whose MAC addresses are in
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)
.- 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
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 ifSoftApConfiguration#setAutoShutdownEnabled
is enabled. Can be overridden usingSoftApConfiguration#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 byCarrierConfigManager.Wifi#KEY_HOTSPOT_MAX_CLIENT_COUNT
). The final result is provided to the app withSoftApCapabilities#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) throughSoftApCapabilities#areFeaturesSupported(SOFTAP_FEATURE_CLIENT_FORCE_DISCONNECT)
.- Channel support:
config_wifiSoftap2gChannelList
,config_wifiSoftap5gChannelList
, andconfig_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 totrue
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