快速入門:以同區網 Wi-Fi 與 DHT11 溫濕度感測器實作即時儀表板
本篇教學以最常見的 同區網 Wi-Fi(WebSocket) 搭配 DHT11 溫濕度感測器 為例,帶你從打開 WizDash App 開始,一步一步完成儀表板排版、匯出 .ino 韌體程式碼、ESP32 硬體接線、Arduino IDE 燒錄,最後回到手機 App 連線並看到即時溫濕度數值跳動。
課前準備清單
Section titled “課前準備清單”開始前請先備妥以下軟硬體:
- ESP32 開發板 1 塊:本教學以最常見的 ESP32-DevKitC(38-Pin,搭載 ESP32-WROOM-32) 為基準;ESP32-S3 或 ESP32-C3 亦可通用(燒錄時選擇對應開發板型號即可)。
- DHT11 溫濕度感測器 1 顆:建議使用 3-Pin PCB 模組版(板載已內建
10kΩ上拉電阻),另備妥 3 條母對母杜邦線。若使用 4-Pin 裸裝元件,需額外準備一顆4.7kΩ–10kΩ電阻。 - 具備資料傳輸功能的 USB 傳輸線 1 條:連接電腦與 ESP32(請留意部分充電線僅供電、無資料線芯,插上電腦後將無法辨識序列埠)。
- 2.4 GHz Wi-Fi 網路環境:ESP32 僅支援 2.4 GHz 頻段(不支援純 5 GHz),且手機與 ESP32 必須連上同一個區域網路(請避開開啟「用戶端隔離 / AP Isolation」的訪客網路)。
- 電腦已安裝 Arduino IDE 2.x:並預先於開發板管理員安裝
esp32 by Espressif Systems核心套件。
步驟 1:建立第一個專案並開啟專案管理選單
Section titled “步驟 1:建立第一個專案並開啟專案管理選單”- 首次開啟 WizDash App,在「專案」首頁點選「+ 新增專案」(或空狀態畫面中央的建立按鈕),輸入專案名稱 DHT11 溫濕度監測。建立後會自動開啟「連線設定」,請接著完成步驟 2。
- 免費版可建立 1 個專案,每個專案最多可放置 10 個功能元件(圖示與間隔元件不計入額度)。
- 完成步驟 2 後,若返回「專案」首頁,可點選卡片右側的「管理」(調音圖示)開啟專案選單。以下兩圖顯示已設定 Wi-Fi、尚未綁定裝置的專案。


步驟 2:設定同區網 Wi-Fi 連線參數
Section titled “步驟 2:設定同區網 Wi-Fi 連線參數”- 新增專案後會自動開啟「連線設定」;若已返回首頁,請從「管理 → 連線設定」重新開啟。
- 點選第二張卡片 「WiFi(區域網路)」(手機與 ESP32 須在同一區網)。
- 在下方欄位填入你要讓 ESP32 連上的 2.4 GHz Wi-Fi 名稱(SSID) 與 Wi-Fi 密碼(本例以
Home_WiFi_2.4G與my-wifi-password為示範),並可選填裝置顯示名稱(如客廳溫度計)。 - 點選底部 「儲存設定」。
為什麼要先填 Wi-Fi 帳密? 這裡填寫的 SSID 與密碼會直接儲存在本機專案中;稍後在步驟 5 點選「產生 Arduino 程式碼」時,App 會自動將這組帳密寫入
.ino韌體範本的WIFI_SSID與WIFI_PASSWORD常數,省去手動改碼的時間。

步驟 3:進入儀表板並加入「垂直溫度計」與「水滴波浪球」
Section titled “步驟 3:進入儀表板並加入「垂直溫度計」與「水滴波浪球」”- 新增專案並儲存連線設定後,App 會自動進入儀表板;若已返回首頁,請點選「管理 → 進入儀表板」。尚未綁定裝置時會顯示「尚未綁定裝置」引導頁。
- 點選第二張卡片 「尚未燒錄,先設計儀表板」,App 會直接進入深藍色頂部工具列的 「編輯位置」 模式。
- 點選頂部工具列的「+」,切換至「顯示元件」分頁,點選「垂直溫度計」。面板會關閉;再次點選「+」,切換至「顯示元件」,再點選「水滴波浪球」。
- 點選頂部工具列的 格線圖示 開啟格線對齊(圖示亮起橘色),拖曳兩個元件與右下角縮放控制點,排列出舒適的版面。



步驟 4:確認元件標題、單位與 JSON Key
Section titled “步驟 4:確認元件標題、單位與 JSON Key”在「編輯位置」模式下,點選元件右上角的藍色 齒輪圖示(或雙擊元件),即可開啟該元件的參數設定視窗:
- 垂直溫度計 1 設定:
- 標籤名稱:輸入
環境溫度 - 鍵值(JSON Key):保持預設的
temp(區分大小寫) - 單位:選擇
°C - 顏色:選擇
橘色,點選「確定」。
- 標籤名稱:輸入
- 水滴波浪球 1 設定:
- 標籤名稱:輸入
環境濕度 - 鍵值(JSON Key):將預設的
humi改為hum(區分大小寫),點選「確定」。
- 標籤名稱:輸入
- 完成後點選右上角綠色 「✓」 儲存版面,並點選左上角返回鍵回到「專案」首頁。
| 儀表板元件 | 標籤名稱 | JSON Key(區分大小寫) | 數值範圍/單位 | 對應 DHT11 讀值函式 |
|---|---|---|---|---|
| 垂直溫度計(Thermo) | 環境溫度 | temp | °C | dht.readTemperature() |
| 水滴波浪球(H-Ball) | 環境濕度 | hum | 0–100 % | dht.readHumidity() |

步驟 5:綁定 DHT11 腳位並匯出 ESP32 Arduino 程式碼
Section titled “步驟 5:綁定 DHT11 腳位並匯出 ESP32 Arduino 程式碼”- 回到「專案」首頁,點選專案卡片右側 「管理」→「產生 Arduino 程式碼」。
- 因為畫布上包含溫度計與濕度球,視窗會自動顯示 「DHT11 溫濕度感測器」 設定卡片:
- GPIO 腳位:保持預設的
4(代表將 DHT11 資料腳位接在 ESP32 的GPIO 4)。 - 綁定儀表板元件:將 「✓ 溫度計『環境溫度』使用 DHT11」 與 「✓ 濕度球『環境濕度』使用 DHT11」 兩個晶片都勾選起來。
- GPIO 腳位:保持預設的
- 勾選後,下方程式碼預覽會整合
<DHT.h>與readSensors()。點選「放大檢視」確認內容,再選擇「匯出檔案」或「複製此程式碼」。Wi-Fi 模式的匯出檔名為WizDash_WiFi_<時間代碼>.ino;檢視視窗標題則固定顯示WizDash_ESP32.ino。本教學後續使用WizDash_ESP32.ino作為範例檔名,請先將匯出檔案重新命名。

![放大檢視完整 WizDash_ESP32.ino 程式碼視窗,展示 WIFI_PASSWORD、DHT_PIN 4 與 readSensors() 讀取溫濕度寫入 doc["temp"] 與 doc["hum"] 的區段](/docs-images/zh/31_qs_codegen_viewer.png)
展開 Wi-Fi + DHT11 參考程式碼(已整理註解與排版,實際產生內容以 App 匯出檔案為準)
/* ============================================================ * WizDash ESP32 (WiFi LAN) — 由 App 為你產生 * * >>> 燒錄前 3 步驟 <<< * 1) Arduino IDE → Tools → Board → 選擇與你開發板相符的 ESP32 型號 * 例:WROOM → ESP32 Dev Module;S3 → ESP32S3 Dev Module;C3 → ESP32C3 Dev Module * 2) Tools → Manage Libraries 安裝: * - WebSockets (by Markus Sattler) * - ArduinoJson (by Benoit Blanchon, v7+) * - DHT sensor library (by Adafruit) * - Adafruit Unified Sensor * 3) 接上 USB → 按 Upload (→ 箭頭) * ============================================================ */#include <WiFi.h>#include <WebSocketsServer.h>#include <ArduinoJson.h>#include <DHT.h>#include <ESPmDNS.h>#include <WiFiUdp.h>
// ════════════════════════════════════════════════════════════// ⓪ WiFi 連線設定 (產生時由 App 自動帶入)// ════════════════════════════════════════════════════════════const char* WIFI_SSID = "Home_WiFi_2.4G";const char* WIFI_PASSWORD = "my-wifi-password";const int WS_PORT = 81;const int UDP_PORT = 4210;
WebSocketsServer webSocket = WebSocketsServer(WS_PORT);WiFiUDP udp;char deviceId[20];unsigned long lastSendTime = 0;#define DHT_PIN 4DHT dht(DHT_PIN, DHT11);
// ════════════════════════════════════════════════════════════// ① 送出資料 (ESP32 → App)// ════════════════════════════════════════════════════════════void readSensors(JsonDocument& doc) { const float dhtTemperature = dht.readTemperature(); static bool dhtTemperatureErrorReported = false; if (isnan(dhtTemperature) && !dhtTemperatureErrorReported) { Serial.println("[DHT11] 溫度讀取失敗"); dhtTemperatureErrorReported = true; } const float dhtHumidity = dht.readHumidity(); static bool dhtHumidityErrorReported = false; if (isnan(dhtHumidity) && !dhtHumidityErrorReported) { Serial.println("[DHT11] 濕度讀取失敗"); dhtHumidityErrorReported = true; }
// 溫度「環境溫度」(Thermo) if (!isnan(dhtTemperature)) doc["temp"] = dhtTemperature;
// 濕度「環境濕度」(H-Ball) if (!isnan(dhtHumidity)) doc["hum"] = dhtHumidity;}
// ════════════════════════════════════════════════════════════// ② 接收指令 (App → ESP32)// ════════════════════════════════════════════════════════════void onCommand(JsonDocument& doc) { // (未發現控制型元件)}
// ════════════════════════════════════════════════════════════// 以下為框架程式 — 一般不需要修改// ════════════════════════════════════════════════════════════void webSocketEvent(uint8_t clientId, WStype_t type, uint8_t* payload, size_t length) { if (type == WStype_CONNECTED) { StaticJsonDocument<64> hs; hs["_id"] = deviceId; hs["_name"] = deviceId; String hsStr; serializeJson(hs, hsStr); webSocket.sendTXT(clientId, hsStr); } else if (type == WStype_TEXT) { JsonDocument doc; if (deserializeJson(doc, (char*)payload) == DeserializationError::Ok) { onCommand(doc); } }}
void handleUdp() { if (udp.parsePacket() == 0) return; char buf[32] = {0}; udp.read(buf, sizeof(buf) - 1); if (String(buf).indexOf("WIZDASH_DISCOVER") >= 0) { String reply = "WIZDASH_HERE:" + String(WS_PORT); udp.beginPacket(udp.remoteIP(), udp.remotePort()); udp.print(reply); udp.endPacket(); }}
void sendDataToApp() { JsonDocument doc; readSensors(doc); String json; serializeJson(doc, json); webSocket.broadcastTXT(json);}
void setup() { Serial.begin(115200); dht.begin(); WiFi.config(INADDR_NONE, INADDR_NONE, INADDR_NONE, IPAddress(8, 8, 8, 8), IPAddress(8, 8, 4, 4)); WiFi.begin(WIFI_SSID, WIFI_PASSWORD); while (WiFi.status() != WL_CONNECTED) { delay(500); Serial.print("."); } Serial.println("\nIP: " + WiFi.localIP().toString());
uint64_t mac = ESP.getEfuseMac(); snprintf(deviceId, sizeof(deviceId), "wizdash-%02x%02x", (uint8_t)(mac >> 8), (uint8_t)(mac));
MDNS.begin(deviceId); MDNS.addService("wizdash", "tcp", WS_PORT); udp.begin(UDP_PORT); webSocket.begin(); webSocket.onEvent(webSocketEvent);}
void loop() { webSocket.loop(); handleUdp(); if (millis() - lastSendTime >= 2000) { lastSendTime = millis(); sendDataToApp(); }}步驟 6:ESP32 與 DHT11 硬體接線(GPIO 4)
Section titled “步驟 6:ESP32 與 DHT11 硬體接線(GPIO 4)”接線前請先拔除 ESP32 的 USB 電源線,確認無電狀態下再連接杜邦線。以下以標準 ESP32-DevKitC(38-Pin) 與 DHT11 3-Pin PCB 模組版 對照說明:
| DHT11 模組腳位 | 杜邦線建議顏色 | ESP32-DevKitC 絲印腳位 | 電氣與韌體說明 |
|---|---|---|---|
VCC(或 +) | 紅線 | 3V3(3.3V 電源腳) | 務必使用 3.3V 供電,避免回傳 5V 訊號損壞 ESP32 GPIO |
DATA(或 OUT / S) | 黃線 | IO4(即 GPIO 4) | 對應韌體中的 #define DHT_PIN 4 |
GND(或 -) | 黑線 | GND(接地腳) | 與開發板共地 |
- 3-Pin PCB 模組 vs. 4-Pin 裸裝元件:
- 市售常見的 3-Pin PCB 模組(附有小型底板)已內建
10kΩ上拉電阻,直接以 3 條杜邦線對接即可。 - 若你使用的是無底板的 4-Pin 藍色裸裝元件(由左至右面對格柵為 Pin 1 至 Pin 4):Pin 1 接
3V3、Pin 2(DATA)接GPIO 4且必須在 Pin 1 與 Pin 2 之間並聯一顆4.7kΩ–10kΩ上拉電阻、Pin 3(NC)懸空不接、Pin 4 接GND。
- 市售常見的 3-Pin PCB 模組(附有小型底板)已內建
- 選用其他腳位時的避開清單:若你在步驟 5 修改了 GPIO 腳位,請避開僅供輸入、無內部上拉的
GPIO 34–39,以及連接內部 SPI Flash 的GPIO 6–11。
步驟 7:在 Arduino IDE 開啟程式碼、安裝函式庫並燒錄至 ESP32
Section titled “步驟 7:在 Arduino IDE 開啟程式碼、安裝函式庫並燒錄至 ESP32”完成接線後,將 ESP32 以 USB 傳輸線接上電腦,依下列四個步驟完成編譯與燒錄:
- 開啟
.ino草稿碼與確認 ESP32 開發板核心:- Arduino IDE 要求
.ino檔案必須放在同名的資料夾內(例如WizDash_ESP32/WizDash_ESP32.ino)。直接以 Arduino IDE 開啟匯出的.ino時,若跳出建立同名資料夾提示,點選「確定」即可。 - 若尚未安裝 ESP32 開發板支援套件,請先在左側開啟 Boards Manager(開發板管理員),搜尋
esp32並安裝esp32 by Espressif Systems(建議2.0.17或3.x穩定版)。
- Arduino IDE 要求
- 在 Library Manager(程式庫管理員)安裝 4 個必備函式庫:
WebSockets(作者:Markus Sattler):提供<WebSocketsServer.h>,請認明作者名稱,避免誤裝其他同名套件。ArduinoJson(作者:Benoit Blanchon):請安裝7.x版本(範本使用 v7 的JsonDocument語法,請勿安裝舊版 6.x)。DHT sensor library(作者:Adafruit):提供<DHT.h>溫濕度讀取函式。Adafruit Unified Sensor(作者:Adafruit):DHT 函式庫的底層相依套件(安裝DHT sensor library時若跳出詢問是否一併安裝相依項目,點選 Install All 即可一次裝齊)。
- 選擇開發板、序列埠並點擊「上傳(Upload)」:
- 於選單點選
Tools > Board > esp32 > ESP32 Dev Module(若使用 S3/C3 請選對應型號)。 - 於
Tools > Port選擇開發板對應的序列埠(Windows 為COM3、COM4等;Linux 為/dev/ttyUSB0或/dev/ttyACM0;macOS 為/dev/cu.usbserial-*或/dev/cu.wchusbserial-*)。 - 點選左上角 「→ 上傳(Upload)」 按鈕開始編譯並燒錄。若下方訊息持續停在
Connecting........,請按住開發板上的BOOT按鈕約 1–2 秒,直到開始顯示寫入百分比再放開。
- 於選單點選
- 開啟序列埠監控視窗(Serial Monitor)確認 IP 位址:
- 燒錄完成後,點選右上角放大鏡開啟 Serial Monitor(序列埠監控視窗),將右下角鮑率(Baud Rate)設為
115200。 - 按一下開發板上的
EN(或RST)鍵重啟,你會看到序列埠印出連上 Wi-Fi 後取得的區網 IP(例如IP: 192.168.1.108),代表 ESP32 已在 Port81啟動 WebSocket 伺服器並開始每 2 秒讀取一次 DHT11。
- 燒錄完成後,點選右上角放大鏡開啟 Serial Monitor(序列埠監控視窗),將右下角鮑率(Baud Rate)設為
步驟 8:回到 WizDash App 搜尋並連上 ESP32
Section titled “步驟 8:回到 WizDash App 搜尋並連上 ESP32”- 確認你的手機已連上與 ESP32 同一個 2.4 GHz Wi-Fi 網路。
- 打開 WizDash App,點選專案卡片右側 「管理」→「綁定裝置」(或進入儀表板後在引導頁點選 「我已燒錄韌體,連接裝置」),開啟「WiFi 連線」搜尋畫面:
- 自動搜尋(mDNS + UDP):點選右上角 「開始搜尋」,App 會自動掃描區網內的 WizDash 裝置(如
192.168.1.108,連接埠81),點選右側綠色 「連線」 按鈕完成裝置辨識,並返回上一頁完成綁定。 - 手動輸入 IP 位址:若你的家用路由器阻擋了區網廣播,也可以直接在下方「手動輸入」欄位填入剛剛從 Arduino IDE 序列埠抄下的 IP 位址(如
192.168.1.108)與連接埠81,點選 「手動連線」。
- 自動搜尋(mDNS + UDP):點選右上角 「開始搜尋」,App 會自動掃描區網內的 WizDash 裝置(如
- 若從「專案」首頁開始綁定,完成後會返回首頁,請再點選「管理 → 進入儀表板」,由儀表板建立持續連線。若從儀表板的未綁定引導頁開始,完成後會自動返回儀表板並嘗試連線。

步驟 9:在儀表板查看即時溫濕度數據!
Section titled “步驟 9:在儀表板查看即時溫濕度數據!”連上 ESP32 後,畫面右上角的 Wi-Fi 圖示會亮起藍色,代表 WebSocket 即時連線已建立。此時 ESP32 每 2 秒會將 DHT11 讀取到的溫濕度打包為 {"temp": 26.4, "hum": 63.0} 推播至手機,你可以立即看到:
- 左側 「環境溫度」垂直溫度計 即時上升至
26.4°C。 - 右側 「環境濕度」水滴波浪球 即時顯示
63.0%並呈現動態波浪高度。
你可以試著對著藍色 DHT11 感測頭輕輕呵氣,觀察約 2–4 秒後濕度球與溫度計數值隨之上升的即時反應!

常見問題與資安提醒
Section titled “常見問題與資安提醒”1. 序列埠監控視窗出現 [DHT11] 溫度讀取失敗 或 [DHT11] 濕度讀取失敗
Section titled “1. 序列埠監控視窗出現 [DHT11] 溫度讀取失敗 或 [DHT11] 濕度讀取失敗”代表 dht.readTemperature() 或 dht.readHumidity() 回傳了 NaN(無法從感測器取得有效訊號)。請依序檢查:
- 腳位是否接對:確認 DHT11 的
DATA訊號線是否確實接在 ESP32 絲印標示為IO4/G4(GPIO 4) 的腳位,而非D4或其他編號。 - 供電與共地:確認
VCC已接至3V3、GND已接至GND,且杜邦線沒有鬆脫。 - 4-Pin 裸裝元件缺少上拉電阻:若使用無 PCB 底板的 4 腳位 DHT11,必須在
VCC與DATA之間加上4.7kΩ–10kΩ上拉電阻,否則訊號無法拉高。
2. 手機 App 自動搜尋找不到裝置,或手動連線失敗
Section titled “2. 手機 App 自動搜尋找不到裝置,或手動連線失敗”- 確認手機與 ESP32 連在同一個 2.4 GHz Wi-Fi 區網,且手機沒有開啟會攔截區網封包的 VPN。
- 檢查序列埠監控視窗是否已印出
IP: 192.168.x.x;若一直印出.代表 Wi-Fi 名稱(SSID)或密碼輸入有誤,或是誤填了 5 GHz 網路名稱。
3. 區域網路連線與程式碼分享資安提醒
Section titled “3. 區域網路連線與程式碼分享資安提醒”- 區網明文傳輸:同區網 Wi-Fi 模式使用無加密的區網 WebSocket(
ws://<ESP32_IP>:81),僅適合在受信任的家庭、工作室或教室內網使用;若需跨網際網路遠端連線,請改用支援 TLS 加密(Port8883)的 MQTT(自備 Broker) 模式。 - 分享程式碼前請移除 Wi-Fi 密碼:匯出的
.ino檔案中包含明文的WIFI_SSID與WIFI_PASSWORD。若要將程式碼上傳至 GitHub 或分享給他人,請務必先將密碼欄位清空或替換為預留字串。