loading...

ESP8266/ESP32 通用的 MicroPython Web Server

codemee profile image 黃昕暐 ・2 min read

緣由

如果使用 Arduino Core 撰寫 ESP8266 的程式, 可以使用 ESP8266WebServer 程式庫建立網頁伺服器, 這對於需要提供遠端遙控或是微服務 API 的應用來說非常方便, 可是如果你使用 MicroPython 撰寫 ESP8266 的程式, 就沒有簡單現成的對應模組可用, 網路上可以找到專為 ESP32 撰寫的相似功能模組, 但是卻大到無法挪到 ESP8266 上執行。

為了達到上述目的, 只好自己動手撰寫了一個輕量級的 ESP8266WebServer 模組來用。設計這個模組時, 有兩個基本原則:

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

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

模組安裝方法

這個模組運作實際上只需要 ESP8266WebServer.py, 你可從 github 直接複製整個模組回來:

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

然後透過 ampy 工具或是 thonny IDE 將 ESP8266WebServer.py 上傳到 ESP8266/ESP32 控制板上即可。

模組使用方法

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

  1. 匯入 ESP8266WebServer 模組:

    import ESP8266WebServer
    
  2. 定義處理指定路徑的函式, 舉例來說, 如果我們希望透過以下路徑控制內建的 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" 純文字。

  3. 設定特定路徑與對應的處理函式:

    ESP8266WebServer.onPath("/cmd", handleCmd)
    

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

  4. 啟用網頁伺服器:

    ESP8266WebServer.begin(8899)
    

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

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

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

    http://控制板IP:8899/cmd?led=on
    
  5. 不斷檢查是否接到請求, 並在必要時關閉 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 文件中特定的字樣, 這些我們留待下一次的文章中說明。

Posted on by:

codemee profile

黃昕暐

@codemee

An engineer who's interested in explaining technology.

Discussion

markdown guide