Wi-Fi network selection

This page outlines the algorithms and procedures used in Android 12 for selecting and switching between Wi-Fi networks. Android continuously evaluates the quality of the connected network and assesses the quality of available networks.

Life of an automatic connection

This describes the process of how an Android device assesses and connects to available Wi-Fi networks.

  1. The device scans for available networks in one of the following ways depending on whether the screen is on or off.

    • Screen on (connected): The Android connectivity subsystem regularly evaluates whether the current connection is good enough to skip scanning (as defined in screen-on scans). If the connection isn't good enough to skip scanning, the connectivity subsystem triggers a scan to detect available networks. These scans can also be triggered by other system components such as the location system or an app (including the Settings app).
    • Screen on (disconnected): The Android connectivity subsystem issues periodic scans following an exponential backoff schedule. The module evaluates all scan results received and tries to select the best network to connect to.
    • Screen off (disconnected): The host CPU programs the firmware with a list of preferred networks using preferred network offload (PNO) scans as soon as the screen goes off. The firmware wakes the host if it finds any of the preferred networks. AOSP assumes that PNO is supported on the device.

    The WifiManager#allowAutojoinGlobal(boolean) method can be used to disable automatic connections. This is a privileged API that can be used by device manufacturers in limited circumstances (for example, a nonmobile, preconfigured device).

    If the device is connected and the config_wifi_framework_enable_associated_network_selection overlay is set to false, no connectivity scans are performed and scan results don't trigger network selection. This setting has no effect when the device is disconnected, meaning that connectivity scans and network selection still occur.

  2. Scan results are evaluated.

    • If the device is connected to a Wi-Fi network, the framework evaluates whether the current network is good enough to skip network selection.

      A network is defined as good enough to skip network selection if any of the following requirements are met:

      • Less than 10 seconds have elapsed since the last network selection.
      • The user recently manually connected to the network (where recently is configurable using the config_wifiSufficientDurationAfterUserSelectionMilliseconds overlay).
      • The device is connected to an online sign up (OSU) connection.

      • All of the following requirements are met:

        • The RSSI is above the required RSSI threshold or sufficient traffic is flowing over the connection (see screen-on scans for RSSI and traffic thresholds).
        • The network is validated (connected to the internet) or is user-approved for use without internet access.
        • The network is unmetered.

    • If the network is good enough to skip network selection, no further action is taken.

    • If the connected Wi-Fi network isn't good enough or if the device isn't connected to a network, the framework calls the network nominators to generate a list of candidate Wi-Fi networks to connect to based on filtered scan results. The network nominators find existing Wi-Fi configurations or create new configurations for the candidate networks.

    • The scan results are filtered to remove BSSIDs that have an RSSI below the entry RSSI (configurable using the config_wifi_framework_wifi_score_entry_rssi_threshold_24GHz, config_wifi_framework_wifi_score_entry_rssi_threshold_5GHz, and config_wifiFrameworkScoreEntryRssiThreshold6ghz overlays). Additionally, blocked BSSIDs are filtered. BSSIDs can be blocked based on repeated connection failures, frequent disconnects, and explicit requests from the AP to not attempt association for a certain period of time (MBO-OCE). BSSID blocking is described below in SSID and BSSID blocking.

    • When the device is rapidly moving, the scan results are optionally further filtered to remove BSSIDs whose RSSI varies rapidly (indication that they aren't moving along with the device). This optimization is configurable using config_wifiHighMovementNetworkSelectionOptimizationEnabled (enabling/disabling the optimization), and the config_wifiHighMovementNetworkSelectionOptimizationScanDelayMs and config_wifiHighMovementNetworkSelectionOptimizationRssiDelta overlays, which configure the stability requirement on scan results (RSSI change over scan results sufficiently separated in time).

  3. The framework runs the candidate scorer to generate a score for each service set identifier (SSID) candidate. The SSID candidates can include multiple basic service set identifier (BSSID) candidates (generated by the network nominators). The candidate with the highest score is the winning candidate.

  4. The framework executes the user connect choice algorithm, which might make a user-selected network the new winning candidate instead of using the winning candidate from the candidate scorer.

  5. The framework determines whether the winning candidate matches the currently connected network. To be considered a match, one of the following must be met:

    • The winning candidate and the connected Wi-Fi network have the same BSSID.
    • If firmware roaming is available (including BSSID blacklist capability), the winning candidate and the connected network have the same SSID and security type.

    If the winning candidate matches the currently connected network, no further action is taken. If the winning candidate doesn't match the network, the device is associated to the winning candidate.

Note that automatic network connection is disabled while an app uses the Wi-Fi Network Request API, which overrides the system and creates a no-internet LAN, except on devices that support dual concurrent stations.

Evaluation of a connected network

The Android framework or firmware periodically evaluates the quality of the connected network. This section describes how the connected network is evaluated when the screen is on or off.

This evaluation is done in addition to the network selection discussed above.

Screen on

The Android framework evaluates the connected network in the following way:

  1. The Wi-Fi service polls RSSI and link-layer stats every 3 seconds (configurable using the config_wifiPollRssiIntervalMilliseconds overlay).

    If dynamic interval adjustment is enabled using the config_wifiAdjustPollRssiIntervalEnabled overlay, the polling interval changes dynamically based on the device mobility state and RSSI.

    • The polling interval is extended to 6 seconds (configured by the config_wifiPollRssiLongIntervalMilliseconds overlay) when the device is stationary and RSSI is above -68 dBm (configured by the config_wifiClientRssiMonitorThresholdDbm and config_wifiClientRssiMonitorHysteresisDb overlays).
    • The polling interval is reduced back to 3 seconds (configured by the config_wifiPollRssiIntervalMilliseconds overlay) when the device is non-stationary or RSSI is below -73 dBm (configured by the config_wifiClientRssiMonitorThresholdDbm overlay).

  2. The Wi-Fi service calculates a connected score based on the RSSI and link-layer stats.

  3. The Wi-Fi service passes the score to the connectivity service, which uses the score to determine whether to connect to a Wi-Fi network or to another available network type, such as a cellular network.

Screen off

The framework doesn't initiate an evaluation on the connected network, but the network selection process might still occur if scans are initiated by other components (for example, location services). The firmware evaluates the network quality and if the network quality is bad, the firmware might roam or (eventually) disassociate from the network and wake up the host.

Connectivity scans

Scans are performed automatically based on whether the device has the screen on, has the screen off and is connected to Wi-Fi, or has the screen off and isn't connected to Wi-Fi.

Screen on

The framework triggers scan decisions at increasing intervals when the screen is turned on. The scan decision intervals are configured with the config_wifiDisconnectedScanIntervalScheduleSec, config_wifiConnectedScanIntervalScheduleSec, and config_wifiSingleSavedNetworkConnectedScanIntervalScheduleSec overlays (which are arrays of integers). By default, scans occur using exponential backoff intervals of 20, 40, 80, and 160 seconds, with subsequent scans possibly performed at 160 second intervals (these are the default values of these overlays).

The exponential backoff scan intervals are reset and restart at 20 seconds whenever the screen state changes, that is, when the screen is toggled on or off.

(Android 13+) If different scan intervals are needed at runtime, an OEM privileged app can call the WifiManager#setScreenOnScanSchedule(screenOnScanSchedule) API to dynamically set the screen-on scan schedule.

A decision whether to execute or skip a scan is based on whether the current network connection is good enough to skip scanning. A connection is good enough to skip scanning if any of the following requirements are met:

  • The device is connected to an online sign up (OSU) connection.
  • Sufficient traffic is flowing through the connection (see traffic thresholds below).
  • The RSSI is above the required RSSI threshold (see RSSI thresholds below), and network selection was performed recently (10 minutes by default but can be configured using the config_wifiConnectedHighRssiScanMinimumWindowSizeSec overlay), and either the network is validated (connected to the internet) or user-approved for use without internet access.

The RSSI and traffic thresholds are:

  • RSSI is above -73 dBm for the 2.4 GHz band, configured with the config_wifi_framework_wifi_score_low_rssi_threshold_24GHz overlay, or -70 dBm for the 5 GHz and 6 GHz bands, configured with the config_wifi_framework_wifi_score_low_rssi_threshold_5GHz and config_wifiFrameworkScoreLowRssiThreshold6ghz overlays.
  • Traffic (transmit or receive) is above 16 packets per second (pps) configured with the config_wifiFrameworkMinPacketPerSecondActiveTraffic overlay.

When the device is connected and screen is on. A connected scorer periodically monitors Wi-Fi quality by looking at signals such as RSSI and the number of packets transferred. If Wi-Fi quality is determined to be bad (as specified below) and the device supports dual concurrent stations, then a scan will get triggered. The config_wifiLowConnectedScoreThresholdToTriggerScanForMbb overlay can be used to configure the score threshold that triggers scanning. The config_wifiLowConnectedScoreScanPeriodSeconds overlay can be used to configure the period of these scans.

Screen off and connected to Wi-Fi

When the screen is off and the device is connected to a Wi-Fi network, the firmware (Wi-Fi SoC) performs roaming scans. The framework doesn't perform any scans when the screen is off.

Screen off and not connected to Wi-Fi (disconnected state)

When the screen is off and Wi-Fi is disconnected, the firmware performs PNO scans for SSIDs. The framework configures the firmware with a list of SSIDs to scan for and a list of channels on which to scan. If a configured SSID is found, the firmware wakes the framework.

The framework also configures the interval at which the firmware is to perform PNO scans, using the device mobility state to select different scan intervals. In a low mobility state (the device is stationary) the interval is 60 seconds for the first three scans (controlled by the config_wifiStationaryPnoScanIntervalMillis overlay), and 180 seconds (a fixed 3x multiplier of the overlay) for subsequent scans. In a high mobility state the interval is 20 seconds for the first three scans (controlled by the config_wifiMovingPnoScanIntervalMillis overlay), and 60 (a fixed 3x multiplier of the overlay) seconds for subsequent scans.

Network nominators

The network nominators find or create configurations (WifiConfiguration) for networks that are:

  • Available (based on scan results) or the connected network (which sometimes is missing from flaky scan results).
  • Have a minimal RSSI. Minimal RSSI is -80 dBm for the 2.4 GHz band and -77 dBm for the 5 GHz and 6 GHz bands, configurable using the config_wifi_framework_wifi_score_entry_rssi_threshold_24GHz, config_wifi_framework_wifi_score_entry_rssi_threshold_5GHz, and config_wifiFrameworkScoreEntryRssiThreshold6ghz overlays.
  • Not blocked, for example, due to previous connection failures.
  • The network doesn't indicate it's unusable (for example, using MBO/OCE).
  • Can be associated to using the credentials available on the device.

The following network nominators are used:

  • Saved network nominator: Evaluates all saved networks (including saved Passpoint subscriptions).
  • Suggested network nominator: Evaluates all networks provided by apps using the Suggestion API (including suggested Passpoint subscriptions).
  • Externally scored network nominator: OEM mechanism to provide network connectivity options to the device. For more information, see External network rating provider.

Candidate scorers

Candidate scorers evaluate and provide a score for each candidate. The score for ThroughputScorer (the default scorer) is based on the following:

  • A base score is computed based on RSSI where RSSI is capped at -73 dBm for the 2.4 GHz band or -70 dBm for the 5 GHz and 6 GHz bands (configured with the config_wifi_framework_wifi_score_low_rssi_threshold_24GHz, config_wifi_framework_wifi_score_low_rssi_threshold_5GHz, and config_wifiFrameworkScoreLowRssiThreshold6ghz overlays).
  • A score boost is computed based on a throughput estimate derived from the technology, channel frequency, bandwidth, RSSI, channel conditions, the maximum number of spatial streams, and other parameters. The score boost is configurable using the config_wifiFrameworkThroughputBonusNumerator and config_wifiFrameworkThroughputBonusDenominator overlays, and is limited to a max value specified using the config_wifiFrameworkThroughputBonusLimit overlay.
  • A candidate network that was recently selected by the user or by an app gets a large score boost for a duration configurable using the config_wifiFrameworkLastSelectionMinutes overlay (for that duration the network is guaranteed to be selected over nonuser-selected networks).
  • A candidate that matches the current network gets a score boost configured by the config_wifiFrameworkCurrentNetworkBonusMin and config_wifiFrameworkCurrentNetworkBonusPercent overlays (it gets an extra bonus based on a percentage of its RSSI and throughput-based score, down to the configurable minimum).
  • A secure network is scored higher than an open network. The bonus is configured using the config_wifiFrameworkSecureNetworkBonus overlay.
  • An unmetered (free) network is scored higher than a metered (paid) network. The bonus is configured using the config_wifiFrameworkUnmeteredNetworkBonus overlay.
  • A saved network is scored higher than a network suggested using the Suggestion API. The bonus is configured using the config_wifiFrameworkSavedNetworkBonus overlay.
  • Untrusted networks (which can be requested as part of the Suggestion API) are scored lower than any other network.
  • A network that was previously detected to have no internet gets a score of 0 if the device is currently connected to another network that has internet access.

The default bonus for saved versus suggestion and unmetered versus metered (that is, the default overlay values) produce a strict priority order for saved, suggested, metered, and unmetered:

  1. Saved unmetered networks
  2. Suggested unmetered networks
  3. Saved metered networks
  4. Suggested metered networks

This means a saved unmetered (free) network is always selected before a saved metered (paid) network. The recently selected (by user or app) score bonus may override that strict priority.

The framework can have several candidate scorers installed but only one can be active at a time. The other scorers can be used for metrics (to investigate alternative algorithms). In Android 11, the default scorer is ThroughputScorer.

SSID and BSSID blocking

The framework may block SSIDs or BSSIDs, that is, not consider them for connections either temporarily or permanently.

BSSID blocking

BSSID blocking works by keeping two failure counters, a continuous failure counter and a streak counter, per specific failure type (see below for a list of failure types). When a failure occurs:

  • The counter for the corresponding failure type is incremented.
  • If the failure threshold for that failure type is reached:
    • The BSSID is blocked.
    • The streak counter for the failure is incremented.

The duration a BSSID is blocked for starts off at a (configurable) base value (specified by the config_wifiBssidBlocklistMonitorBaseBlockDurationMs or config_wifiBssidBlocklistMonitorBaseLowRssiBlockDurationMs overlays, depending on the RSSI), and exponentially increases up to a configurable upper bound (specified by the config_wifiBssidBlocklistMonitorFailureStreakCap overlay). The duration increases if failures continuously occur on the same BSSID. The duration is the base duration exponentially increased by the failure streak, that is, a failure streak of 2 implies 4x base block duration.

The thresholds for BSSID blocking depend on the failure reason and are each customizable using overlays:

  • AP rejects association using the MBO/OCE Unable to handle new STA code: config_wifiBssidBlocklistMonitorApUnableToHandleNewStaThreshold.
  • Internet validation through this network failed: config_wifiBssidBlocklistMonitorNetworkValidationFailureThreshold.
  • Wrong password authentication failure code: config_wifiBssidBlocklistMonitorWrongPasswordThreshold.
  • EAP failure authentication failure code for EAP networks: config_wifiBssidBlocklistMonitorEapFailureThreshold.
  • Association rejection, other general association rejections: config_wifiBssidBlocklistMonitorAssociationRejectionThreshold.
  • Association timeout: config_wifiBssidBlocklistMonitorAssociationTimeoutThreshold.
  • Authentication failure, other general authentication failures: config_wifiBssidBlocklistMonitorAuthenticationFailureThreshold.
  • DHCP failure, failure to provision DHCP: config_wifiBssidBlocklistMonitorDhcpFailureThreshold.
  • Abnormal disconnect, the device has disconnected from the network within a very short period after connecting: config_wifiBssidBlocklistMonitorAbnormalDisconnectThreshold. The time window is configurable with config_wifiBssidBlocklistAbnormalDisconnectTimeWindowMs.

BSSID blocklist clearing conditions

A BSSID is cleared from the blocklist when:

  • Wi-Fi is toggled: All BSSIDs are removed from the blocklist.
  • The user taps on a network in the Wi-Fi picker: All BSSIDs of the user-selected network are removed from the blocklist.
  • Timeout: BSSIDs are removed from the blocklist when the block duration is reached.
  • Reboot: All blocklists are cleared.
  • Network removed: All BSSIDs associated with this network are removed from the blocklist.

Failure and streak counters reset conditions:

  • Reboot: Reset for all BSSIDs.
  • Network removed: Reset for BSSIDs associated with the network.

  • L2 connection success: Reset for the following error codes.

    • REASON_AP_UNABLE_TO_HANDLE_NEW_STA
    • REASON_WRONG_PASSWORD
    • REASON_EAP_FAILURE
    • REASON_ASSOCIATION_REJECTION
    • REASON_ASSOCIATION_TIMEOUT
    • REASON_AUTHENTICATION_FAILURE
    • REASON_ABNORMAL_DISCONNECT (conditionally cleared only if the last time the device connected to this BSSID was more than 3 hours ago)
    • REASON_NONLOCAL_DISCONNECT_CONNECTING

  • Network validation success: Resets for the following error code.

    • REASON_NETWORK_VALIDATION_FAILURE

  • DHCP provisioning success: Resets for the following error code.

    • REASON_DHCP_FAILURE

SSID blocking

SSID blocking works similarly to BSSID blocking. A failure counter per failure type per network gets incremented when connection failures (of that type) occur. When the failure count of a particular type exceeds a threshold, the SSID is permanently or temporarily blocked based on a configuration. The configuration for each failure type is coded in WifiConfiguration.NetworkSelectionStatus.DISABLE_REASON_INFOS and is summarized below.

* For temporarily disabled networks, the disable duration changes dynamically based on the number of consecutive connection failures experienced on the network. After a network consecutively fails to connect five times, each subsequent failure results in a disable duration twice as long as the previous duration. For example, a network with five consecutive failures gets disabled for 5 minutes, then 10 minutes on the sixth failure, 20 minutes for the seventh failure, and so on up to the maximum limit of 18 hours.

Failure code Description Threshold Base disable duration* Disable type
DISABLED_DHCP_FAILURE Failure to provision DHCP 5 5 minutes Temporary
DISABLED_NO_INTERNET_TEMPORARY Network validation failed but the user states that they want to keep connecting to this network in the future 1 10 minutes Temporary
DISABLED_AUTHENTICATION_NO_CREDENTIALS Supplicant lacks credentials to connect to the network 1 NA Permanent
DISABLED_NO_INTERNET_PERMANENT Default for network validation failure 1 NA Permanent
DISABLED_BY_WIFI_MANAGER Deprecated and unused 1 NA Permanent
DISABLED_BY_WRONG_PASSWORD The password is incorrect, and this network has never been successfully connected to 1 NA Permanent
DISABLED_AUTHENTICATION_NO_SUBSCRIPTION EAP failure where the SIM card is not subscribed 1 NA Permanent
DISABLED_ASSOCIATION_REJECTION Association rejection failures 5 5 minutes Temporary
DISABLED_AUTHENTICATION_FAILURE Other authentication failures (that is, not a wrong password or an EAP failure) 5 5 minutes Temporary
DISABLED_AUTHENTICATION_PRIVATE_EAP_ERROR Provider-specific (private) EAP failure. 1 NA Permanent
DISABLED_NETWORK_NOT_FOUND The supplicant failed to find a network in the scan results that matches the network requested by the framework for connection (including network capabilities). 2 5 minutes Temporary
DISABLED_CONSECUTIVE_FAILURES The network failed to connect five or more times consecutively. The failure type for these failures includes but isn't limited to the failure types listed in this table.
 5 5 minutes Temporary

A temporarily disabled network is reenabled when:

  • The disable duration has passed.
  • The user manually selects the network to connect.
  • The user toggles Wi-Fi.
  • The system is rebooted.
  • The network was disabled at a very low RSSI, but the network is later detected again at moderate or higher RSSI.

A permanently disabled network is reenabled when:

  • The user manually selects the network to connect.

Failure counters for a network are reset when:

  • The network is removed.
  • Device has successfully connected to the network.
  • The network has been re-enabled after the disable duration timed out.
  • User manually selects the network to connect.
  • The system is rebooted.

Score cards

Score cards, introduced in Android 10, record on-device statistics about BSSIDs. Score cards are persisted using the IpMemoryStore service.

Score cards aren't used in Android 11 network selection.

User connect choice

Android has a user connect choice algorithm that allows the selection process to prefer Wi-Fi networks that a user has explicitly connected to, for example, a home network. Users might prefer such networks over public networks even when the performance is lower than a public network because they provide additional services such as the ability to control home devices.

The user's preference for a network is captured by marking all the visible Wi-Fi configurations and their signal strengths at the time the user selects a network. If one of the marked Wi-Fi configurations is selected during the automatic selection process and a user-selected network is available, the user connect choice algorithm overrides the selection with the user-selected network if the following conditions are met:

  • The user connect choice network had internet access the last time it was used
  • The user connect choice has a signal strength that's no worse than when it was originally selected with an error margin. This error margin can be configured using the overlay config_wifiEstimateRssiErrorMarginDb.

The user connect choice network persists after a reboot. The user connect choice works for saved networks, Passpoint networks, and suggestions networks.

Dual concurrent stations

This section describes Wi-Fi network selection when a device supports connecting to two Wi-Fi networks concurrently.

Make-before-break

If the make-before-break function is enabled, the device attempts to connect to the new network before disconnecting from the old network. The make-before-break flow uses the same network selection algorithm as break-before-make network switching (which is when the device disconnects from the old network before connecting to the new one). If the network selection algorithm chooses a network that cannot be switched using make-before-break, the device automatically falls back to break-before-make.

Concurrent restricted and internet connection

If the concurrent restricted and internet connection function is enabled, the device can connect to a secondary restricted Wi-Fi network that is only available to select apps configured by the device manufacturer. Instructions for device manufacturers to configure this is in Concurrent restricted and internet connection.

When the network selection algorithm detects scan results matching the OEM paid or private suggestion, it automatically connects to it as a second network. Network selection for the primary Wi-Fi network (which provides internet connection to regular apps) occurs normally in parallel.

Frequently asked questions (FAQ)

  1. Do secure networks always have priority over open networks?

    No. Saved versus suggested and metered versus unmetered are primary categories in which networks are evaluated. Within each category, secure networks have some priority over open networks but much higher weight is given to the quality of the connection.

    The reason is that actual user data security is provided by end-to-end encryption (for example, TLS). Secure networks encrypt only the first leg of communication, and even then for networks with preshared keys, don’t provide much privacy.

  2. Why are saved networks prioritized over suggested networks?

    Saved free (unmetered) networks are prioritized over suggested free networks and saved metered networks are prioritized over suggested metered networks.

    Saved networks are prioritized over suggested networks because saved networks are networks that the user added to the device explicitly. That implies a preference to connect to these networks when possible.

    Note that users can disable the auto-connection behavior for individual saved networks, that is, indicate that these networks are only to be used manually and not to be considered automatically by the device.

  3. Can I change the strict priority order or remove it completely?

    The device manufacturer can modify the network selection decisions by modifying the bonus overlays listed in the above sections. However, changing the default values isn't recommended as they have been chosen after careful consideration of multiple use cases.