WiFi Manager（二）：無線網路設置入口的基本程式碼以及WiFiManager類別物件的方法

設定ESP開發板Wi-Fi連線的網頁，叫做「設置入口（Configure Portal）」，由「WiFi管理員」程式庫的“WiFiManager”類別物件建立的HTTP伺服器提供服務，“WiFiManager”類別物件在範例程式中命名為wm，透過按鍵啟動「設置入口」的基本程式碼如下：

#include <WiFiManager.h> // 引用「WiFi管理員」程式庫
#define TRIGGER_PIN 0   // 啟動「設置入口」的接腳

WiFiManager wm;         // 宣告WiFi管理員物件

unsigned int  timeout   = 120; // 設置入口的逾時秒數
unsigned int  startTime = millis();  // 紀錄設置入口的啟動時間
bool portalRunning      = false;     // 設置入口是否執行中，預設「否」。

void doWiFiManager() {   // 執行WiFi管理員的工作
  if (portalRunning) {   // 若「設置入口」執行中…
    wm.process();        // 處理「設置入口」的用戶端連結請求
    // 如果「設置入口」已啟用超過預設時間（120秒）…
    if ((millis() - startTime) > (timeout * 1000)) {
      Serial.println("「Wi-Fi設置入口」操作逾時…");
      portalRunning = false;   // 設成「非執行中」
      wm.stopConfigPortal();   // 停止「設置入口」
     }
  }

  // 若啟用「設置入口」的接腳被按一下
  // 而且portalRunning變數值不為true…
  if (digitalRead(TRIGGER_PIN) == LOW && (!portalRunning)) {
    Serial.println("按鈕被按下了，啟動設置入口。");
    wm.setConfigPortalBlocking(false);      // 設成「非擱置」模式
    wm.startConfigPortal(AP_SSID, AP_PWD);  // 啟用Wi-Fi AP

    portalRunning = true;   // 設成「設置入口」執行中
    startTime = millis();   // 紀錄目前的時間
  }
}

void setup() {
  WiFi.mode(WIFI_STA);
  Serial.begin(115200);
  delay(1000);
  pinMode(TRIGGER_PIN, INPUT_PULLUP);

  wm.autoConnect();  // 處理Wi-Fi連線
  // 你的程式碼放在這裡…
}

void loop() {
  doWiFiManager();  // 執行WiFi管理員的工作
  // 你的程式碼放在這裡…
}

WiFiManager物件的方法

底下列舉WiFiManager物件（wm）的一些方法：

setDebugOutput(是否顯示訊息)
是否輸出除錯訊息，預設為true。上傳ESP程式之後，開啟序列埠監控視窗（傳輸率設為115200bps），將能看見類似這樣的除錯訊息：

等程式開發完畢、測試無誤，請在程式中加入底下的敘述關閉除錯訊息，避免使用者透過序列埠讀取到連線密碼之類的資料。

wm.setDebugOutput(false);  // 停止輸出除錯訊息 

startConfigPortal(SSID, 密碼)
把晶片的網路切換到AP（無線存取點）模式，並啟動設置入口，讓使用者透過192.168.4.1位址連入。AP的SSID名稱預設為“ESP”+MAC位址，沒有密碼。

startConfigPortal()可接受兩個選擇性參數，第1個參數是自訂的SSID名稱，第2個參數是密碼。例如：

• startConfigPortal (“JarvisAP”)：建立名稱名叫“JarvisAP”的無線存取點，沒有密碼。
• startConfigPortal (“JarvisAP”, “12345678”)：建立名稱名叫“JarvisAP”的無線存取點，密碼：12345678。讓你指定SSID名稱和密碼。

autoConnect(SSID, 密碼)
檢查ESP開發板是否有儲存本地無線路由器的連線資料（credential），如果有，則連線到之前設定的Wi-Fi無線路由器；如果沒有，則執行上面的startConfigPortal()方法啟動AP模式。

因此，autoConnect()也可接受兩個選擇性參數，讓你設定AP模式的SSID和密碼。

setConfigPortalBlocking(是否擱置)
設定啟用「設置入口」時，是否擱置其他連線請求，傳入false代表不擱置，也就是在設置或檢視Wi-Fi連線設定期間，我們自訂的網站伺服器仍可提供服務。

process()
處理「設置入口」的用戶端連結請求。如果上面的setConfigPortalBlocking()方法設成false，就要持續呼叫這個方法。

stopConfigPortal()
停止「設置入口」。若setConfigPortalBlocking()傳入false（不擱置），則必須執行這個方法才能停止「設置入口」。

startWebPortal()
啟動網路設置入口，跟startConfigPortal()方法的差別在於這個方法不會啟動AP模式。

stopWebPortal()
停止網路設置入口。

getWiFiIsSaved()
確認開發板是否存有Wi-Fi路由器的連線資料，若有則傳回true。

setHostname(主機名稱)
設定主機名稱，方便使用者透過“jarvis.local”之類的本地域名連接ESP開發板。

setAPCallback(回呼函式)
設定啟動AP模式時的回呼函式。底下的敘述將在ESP晶片啟動AP模式時，觸發執行“APCallback”函式：

// 回呼函式要接收一個WiFiManager類型的指標參數
void APCallback (WiFiManager *ptWM) {
  Serial.print("啟動AP模式，AP的SSID：");
  Serial.println(ptWM->getConfigPortalSSID());
  Serial.print("IP位址：");
  Serial.println(WiFi.softAPIP());
}
wm.setAPCallback(APCallback);

它將在序列埠監控視窗顯示AP的SSID識別名稱以及IP位址，像這樣：

setWiFiAPChannel(頻道編號)
設定AP的Wi-Fi頻道。

setAPStaticIPConfig(IP位址, 閘道器位址, 子網路遮罩)
設定AP模式的靜態IP位址（位址的資料類型是IPAddress）。AP模式的預設IP位址是192.168.4.1，改成10.0.1.2的敘述如下：

wm.setAPStaticIPConfig(IPAddress(10,0,1,2),  IPAddress(10,0,1,1), IPAddress(255,255,255,0));

setSTAStaticIPConfig(IP位址, 閘道器位址, 子網路遮罩, DNS位址)
設定STA模式的靜態IP位址，第4個DNS位址是選擇性參數。

setHttpPort(埠號)
設定WiFI管理員的伺服器埠號，預設為80。底下的敘述將把埠號設成3333：

wm.setHttpPort(3333);

如此，連線到此AP時，需要輸入埠號，像這樣：

setShowStaticFields(是否顯示靜態欄位)
顯示設定靜態（手動輸入）IP位址的欄位，預設為false（否）。

setShowDnsFields(是否顯示DNS欄位)
顯示設定靜態（手動輸入）DNS位址的欄位，預設為false（否）。

Wi-Fi分享器通常都是以DHCP（動態）分配IP位址模式運作，底下兩行敘述將在WiFi管理員的Wi-Fi設置入口頁面顯示，讓你手動設定IP位址：

wm.setShowStaticFields(true); // 顯示靜態IP設定欄位 
wm.setShowDnsFields(true);    // 顯示DNS設定欄位 

實際的運作畫面如下：

setScanDispPerc(是否百分比顯示)
設定以百分比數值顯示Wi-Fi分享器的訊號強度，預設為false，代表使用「柱狀格」圖示顯示訊號強度。

setMinimumSignalQuality(百分比數字)
設定最低訊號強度百分比，預設為8，低於此數字的Wi-Fi分享器將不會被列舉出來。底下敘述設定採用百分比顯示訊號強度，最低訊號設為10%：

wm.setScanDispPerc(true);
wm.setMinimumSignalQuality(10);

實際的運作畫面如下：

setCustomHeadElement(HTML檔頭字串)
設定自訂的HTML檔頭區（head）元素。底下敘述將在檔頭區插入自訂的CSS樣式，把網頁的背景色改成Tiffany藍（#E3FFFF）：

wm.setCustomHeadElement ("<style>body  {background-color: #E3FFFF;}</style>");

實際的運作畫面如下：

reboot()
重置ESP開發板。