Wi-Fi 無線基地台 (Soft AP)

Android 支援 Wi-Fi 無線基地台 (Soft AP)，包括透過 Wi-Fi 無線基地台和本機專用的 Wi-Fi 無線基地台網路共用功能。

軟 AP 功能可設定下列項目：

• SSID 和 BSSID
• 安全性類型 (包括 WPA3)
• 隱藏的 SSID
• 運作頻帶和頻道 (包括 ACS)
• 允許的用戶端數量上限
• 自動關閉逾時值
• 使用許可清單和封鎖清單，讓使用者控管相關聯的裝置
• 無線基地台 BSSID 的 MAC 隨機化程度
• 802.11ax 和 802.11be

裝置功能會決定這些控制項是否可用。Android 11 推出了可取得這些功能的 API。裝置製造商也可以使用疊加層指定基本裝置功能。

請注意，部分 API 是系統 API，並受到權限限制，因此只有系統的「設定」應用程式才能存取。

使用熱點 API 開發應用程式

Android 開放原始碼計畫「設定」應用程式會提供共用 Wi-Fi 無線基地台的預設實作方式，但不會執行所有 Soft AP 設定適用的 API。

如要透過無線基地台或僅限本機的無線基地台支援網路共用功能，應用程式必須執行下列功能：

1. 註冊回呼，使用 WifiManager#registerSoftApCallback 取得網路共用無線基地台，或針對僅限本機的無線基地台使用 WifiManager#registerLocalOnlyHotspotSoftApCallback 取得裝置功能。

   SoftApCallback 回呼提供下列方法：

   • SoftApCallback#onCapabilityChanged：提供裝置功能的相關資訊，包括支援的用戶端數量上限，以及是否支援 SAE 或 ACS。
   • SoftApCallback#onInfoChanged：提供執行中的軟 AP (僅在啟動後有效) 相關資訊，包括頻帶和頻率資訊。
   • SoftApCallback#onConnectedClientsChanged：提供已連線用戶端的清單。您可以為每個用戶端取得 MAC 位址。如要取得 IP 資訊，請使用 TetheringEventCallback#onClientsChanged 回呼。
   • SoftApCallback#onStateChanged：提供軟體存取點啟用和停用時的狀態更新。
   • SoftApCallback#onBlockedClientConnecting：提供遭封鎖的用戶端資訊，原因可能是下列其中一種：

使用網路共用無線基地台：

1. 呼叫 WifiManager#setSoftApConfiguration 方法並提供 SoftApConfiguration 例項，即可設定軟 AP 設定以進行 Tethering。使用 SoftApConfiguration.Builder 類別建構 SoftApConfiguration。
2. 在 TetheringManager#startTethering 中呼叫 Tethering 方法，即可啟動 Tethering。

僅限本機的無線基地台：

1. 請呼叫 WifiManager#startLocalOnlyHotspot 方法，以特定軟體存取點設定啟動僅限本機的無線基地台。

實作許可清單和封鎖清單

一般的電信業者規定是，讓使用者能夠控管哪些裝置能與 Soft AP 建立關聯。以下是執行這項操作的幾種機制：

• 使用 SoftApConfiguration.Builder#setMaxNumberOfClients 限制可與軟 AP 建立關聯的裝置數量上限。請務必指定的數字低於裝置支援的用戶端數量上限。您可以從 SoftApCapability#getMaxSupportedClients 取得上限值。

• 使用允許和封鎖清單提供動態控制功能：

  • Soft AP 的預設設定允許所有裝置與軟 AP 建立關聯，但 MAC 位址新增至 SoftApConfiguration.Builder#setBlockedClientList 的裝置除外。

  • 如果 Soft AP 設定了 SoftApConfiguration.Builder#setClientControlByUserEnabled(true)，系統會使用允許清單。

    • 所有 MAC 位址位於 SoftApConfiguration.Builder#setBlockedClientList 中的裝置都會遭到關聯封鎖。
    • 所有 MAC 位址位於 SoftApConfiguration.Builder#setAllowedClientList 中的裝置都允許建立關聯。
    • 所有其他裝置 (也就是 MAC 位址不在允許或封鎖清單中的裝置) 都會遭到關聯封鎖，但會呼叫 SoftApCallback#onBlockedClientConnecting，讓控制應用程式 (也就是「設定」應用程式) 採取行動，例如要求使用者確認，然後根據使用者的行為將裝置加入允許清單或封鎖清單。

  請注意，裝置必須支援許可清單功能，才能使用這項功能。您可以使用 SoftApCapability#areFeaturesSupported(SOFTAP_FEATURE_CLIENT_FORCE_DISCONNECT) 驗證裝置支援情形。

實作

如要支援透過無線基地台進行 Tethering 或支援僅限本機的無線基地台，裝置製造商必須提供設定應用程式、架構和 HAL/韌體支援：

• 設定應用程式：AOSP 設定應用程式提供基準，可讓您使用 SSID 和安全性憑證設定 Tethering 熱點。這個程式碼可以原封不動地使用或進行修改，以提供額外功能，如「使用無線基地台 API 開發應用程式」中所述。

• 架構：Android 開放原始碼計畫架構程式碼支援「使用無線基地台 API 開發應用程式」中所述的所有功能。

• 熱點的 HAL/韌體：HIDL IHostapd.hal 1.2 以上版本，或 AIDL IHostapd.aidl。

自訂

如要自訂實作方式，裝置製造商應設定下列疊加層和電信業者設定，這些設定已在 packages/modules/Wifi/service/ServiceWifiResources/res/values/config.xml 中說明：

• config_wifiFrameworkSoftApShutDownTimeoutMilliseconds：預設的關機逾時間隔。只有在啟用 SoftApConfiguration#setAutoShutdownEnabled 時才有效。可使用 SoftApConfiguration#setShutdownTimeoutMillis 覆寫。
• config_wifiHardwareSoftapMaxClientCount：硬體限制，適用於支援的用戶端數量上限。裝置支援的用戶端數量上限，是硬體和電信業者限制 (由 CarrierConfigManager.Wifi#KEY_HOTSPOT_MAX_CLIENT_COUNT 指定) 的最低值。最終結果會透過 SoftApCapabilities#getMaxSupportedClients 提供給應用程式。
• config_wifiSofapClientForceDisconnectSupported：裝置是否能夠強制中斷用戶端連線。啟用後即可啟用允許和封鎖清單。透過 SoftApCapabilities#areFeaturesSupported(SOFTAP_FEATURE_CLIENT_FORCE_DISCONNECT) 與控制應用程式 (「設定」應用程式) 進行通訊。
• (適用於 13 版) config_wifiSoftapPassphraseAsciiEncodableCheck： 是否要求軟 AP 通關密碼可使用 ASCII 編碼。
• config_wifiSoftapAutoUpgradeToBridgedConfigWhenSupported：在支援新裝置時，是否要在雲端設定還原期間自動將頻道設定升級為雙頻道。
• (適用於 13 以上版本) config_wifiSoftapAutoAppendLowerBandsToBandConfigurationEnabled： 架構是否會自動將較低的頻帶附加至頻帶設定，以避免共存。
• config_wifiSoftApDynamicCountryCodeUpdateSupported：裝置是否支援在 AP 模式下進行動態國家/地區代碼更新
• 支援的管道：config_wifiSoftap2gChannelList、config_wifiSoftap5gChannelList、config_wifiSoftap6gChannelList 和 config_wifiSoftap60gChannelList。
• 還原支援功能可指定在將熱點設定還原至新裝置時，是否將對應的項目重設為預設值：config_wifiSoftapResetChannelConfig、config_wifiSoftapResetHiddenConfig、config_wifiSoftapResetUserControlConfig、config_wifiSoftapResetAutoShutdownTimerConfig、config_wifiSoftapResetMaxClientSettingConfig。請注意，這些值預設為 true，也就是說會重設值。如果新裝置不支援設定，這項功能就非常重要。
• 硬體功能：
  • config_wifi_softap_acs_supported
  • config_wifi_softap_sae_supported
  • (適用於 13 歲以上) config_wifiSoftapOweTransitionSupported
  • (自 13 月起開放購買) config_wifiSoftapOweSupported
  • config_wifi_softap_ieee80211ac_supported
  • config_wifiSoftapIeee80211axSupported
  • (適用於 13 歲以上) config_wifiSoftapIeee80211beSupported
  • config_wifiSoftapMacAddressCustomizationSupported
  • config_wifiSoftapHeSuBeamformerSupported
  • config_wifiSoftapHeSuBeamformeeSupported
  • config_wifiSoftapHeMuBeamformerSupported
  • config_wifiSoftapHeTwtSupported
  • config_wifiSoftap24ghzSupported
  • config_wifiSoftap5ghzSupported
  • config_wifiSoftap6ghzSupported
  • config_wifiSoftap60ghzSupported
  • config_wifiSoftapAcsIncludeDfs

驗證

Android 提供一組單元測試和 Compatibility Test Suite (CTS) 測試，用於驗證無線基地台功能。您也可以使用供應商測試套件 (VTS) 測試熱點功能。

單元測試

使用下列測試驗證無線基地台套件。

• 服務測試：

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

• 管理員測試：

  atest packages/modules/Wifi/framework/tests/
  

Compatibility Test Suite (CTS) 測試

使用 CTS 測試驗證無線基地台功能。CTS 會偵測這項功能啟用的時間，並自動納入相關的測試。

如要觸發 CTS 測試，請執行：

atest android.net.wifi.cts.WifiManagerTest

供應商測試套件 (VTS)

如果已實作 HIDL 介面，請執行：

atest VtsHalWifiHostapdV1_2Target

如果已實作 AIDL 介面，請執行以下指令：

atest VtsHalHostapdTargetTest