# ESP8266/ESP32 通用的 MicroPython Web Server

###### tags: `MicroPython` `ESP32` `ESP8266`

### 緣由

如果使用 [Arduino Core](https://arduino-esp8266.readthedocs.io/en/latest/) 撰寫 ESP8266 的程式, 可以使用 [ESP8266WebServer](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer) 程式庫建立網頁伺服器, 這對於需要提供遠端遙控或是微服務 API 的應用來說非常方便, 可是如果你使用 MicroPython 撰寫 ESP8266 的程式, 就沒有簡單現成的對應模組可用, 網路上可以找到專為 ESP32 撰寫的相似功能模組, 但是卻大到無法挪到 ESP8266 上執行。

為了達到上述目的, 只好自己動手撰寫了一個輕量級的 [ESP8266WebServer](https://github.com/codemee/ESP8266WebServer) 模組來用。設計這個模組時, 有兩個基本原則：

1. 盡量模仿 Arduino Core 版本的 ESP8266WebServer 程式庫, 讓兩者的使用體驗相似。
2. 保持輕量, 原本就是為了自用, 所以這個模組只能處理 HTTP GET, 其餘功能一概不理。

由於這個模組僅使用到 MicroPython 的標準程式庫, 因此可以通用於 ESP8266/ESP32 上。

### 模組安裝方法

這個模組運作實際上只需要 [ESP8266WebServer.py](https://github.com/codemee/ESP8266WebServer/blob/master/ESP8266WebServer.py), 你可從 github 直接複製整個模組回來：

git clone https://github.com/codemee/ESP8266WebServer.git

然後透過 [ampy](https://pypi.org/project/adafruit-ampy/) 工具或是 thonny IDE 將 ESP8266WebServer.py 上傳到 ESP8266/ESP32 控制板上即可。

### 模組使用方法

要使用 ESP8266WebServer 模組, 必須依循以下步驟：

1. 匯入 ESP8266WebServer 模組：

    import ESP8266WebServer

1. 定義處理指定路徑的函式, 舉例來說, 如果我們希望透過以下路徑控制內建的 LED：

    http://控制板IP/cmd?led=on
    http://控制板IP/cmd?led=off

那麼所需要處理的路徑就是 "/cmd", "led" 就是這個路徑可附加的參數, 而 "on" 或是 "off" 則是參數內容。首先就是要撰寫一個專門處理 "/cmd" 路徑的函式：

    def handleCmd(socket, args):
        if 'led' in args:
            if args['led'] == 'on':
                pin.off()
            elif args['led'] == 'off':
                pin.on()
            ESP8266WebServer.ok(socket, "200", args["led"])

        else:
            ESP8266WebServer.err(socket, "400", "Bad Request")

處理路徑的函式必須有 2 個參數, 第 1 個參數是用來傳送資料回用戶端的物件； 第 2 個參數則是隨路徑傳入的參數字典, 這個字典會以參數名稱為索引鍵 (key)、參數內容為元素值, 只要利用字典的操作就可以判斷是否有指定名稱的參數, 並且可以取出參數內容。上例中就以參數 led 的內容為 "on" 或 "off" 來控制 pin 物件控制的腳位電位高低。

這個函式最後必須傳回狀態碼以及內容給用戶端, 若正常處理時可叫用 ESP8266WebServer.ok, 否則叫用 ESP8266WebServer.err。這 2 個方法的第 1 個引數都是路徑處理函式的第 1 個參數；第 2 個引數則是狀態碼, 可自行參考 HTTP 文件；第 3 個引數是要送回給用戶端的內容, 如果需要, 可以加上第 4 個引數, 指定內容的格式, 例如若傳回的是 HTML 內容, 則要指定為 "text/html", 如果沒有指定, 格式預設為 "text/plain" 純文字。

1. 設定特定路徑與對應的處理函式：

    ESP8266WebServer.onPath("/cmd", handleCmd)

這表示若 HTTP GET 的請求路徑是 "/cmd", 就自動叫用 handleCmd 函式來處理。

1. 啟用網頁伺服器：

    ESP8266WebServer.begin(8899)

啟用時必須指定埠號, 若指定為 80 號, 在瀏覽器中就可以不標示埠號, 例如：

    http://控制板IP/cmd?led=on

若像是上面程式指定埠號是 8899, 那麼在瀏覽器中網址就要加上埠號, 例如：

    http://控制板IP:8899/cmd?led=on

1. 不斷檢查是否接到請求, 並在必要時關閉 ESP8266WebServer:

    try:
        while True:
            # Let server process requests
            ESP8266WebServer.handleClient()
    except:
        ESP8266WebServer.close()

### 簡易範例

瞭解以上流程後, 我們就可以撰寫一個簡易的程式, 可以讓使用者透過 HTTP GET 遙控 ESP8266 上內建的 LED 了：

import ESP8266WebServer
import network
import machine

GPIO_NUM = 2 # Builtin led (D4)

# Wi-Fi configuration
STA_SSID = "MEE_MI"
STA_PSK = "PinkFloyd1969"

# Disable AP interface
ap_if = network.WLAN(network.AP_IF)
if ap_if.active():
    ap_if.active(False)
  
# Connect to Wi-Fi if not connected
sta_if = network.WLAN(network.STA_IF)
if not ap_if.active():
    sta_if.active(True)
if not sta_if.isconnected():
    sta_if.connect(STA_SSID, STA_PSK)
    # Wait for connecting to Wi-Fi
    while not sta_if.isconnected(): 
        pass

# Show IP address
print("Server started @", sta_if.ifconfig()[0])

# Get pin object for controlling builtin LED
pin = machine.Pin(GPIO_NUM, machine.Pin.OUT)
pin.on() # Turn LED off (it use sinking input)

# Handler for path "/cmd?led=[on|off]"    
def handleCmd(socket, args):
    if 'led' in args:
        if args['led'] == 'on':
            pin.off()
        elif args['led'] == 'off':
            pin.on()
        ESP8266WebServer.ok(socket, "200", args["led"])
    else:
        ESP8266WebServer.err(socket, "400", "Bad Request")

# Start the server @ port 8899
ESP8266WebServer.begin(8899)

# Register handler for each path
ESP8266WebServer.onPath("/cmd", handleCmd)

try:
    while True:
        # Let server process requests
        ESP8266WebServer.handleClient()
except:
    ESP8266WebServer.close()

執行後會看到終端機顯示控制板的 IP：

Server started @ 192.168.100.214

接著, 就可以在瀏覽器的網址列鍵入控制 LED 的網址, 例如：


就會讓 ESP8266 內建的 LED 亮起來, 瀏覽器內顯示的 "on" 就是從控制板處理 "/cmd" 路徑的 handleCmd 函式送回的, 如果使用 curl 工具可以看的更清楚：

curl -i http://192.168.100.214:8899/cmd?led=on
HTTP/1.1 200 OK
Content-Type: text/plain

on

### 結語

ESP8266WebServer 模組除了上述簡易的用法外, 也可以設定文件資料夾, 即可直接傳回 HTML 檔案, 甚至還可以在 HTML 中使用樣板, 以 Python 程式中的資料取代 HTML 文件中特定的字樣, 這些我們留待下一次的文章中說明。