ESPHome 從零做一支溫濕度感測器：零件、接線、完整設定檔與逐步驗證

charles

這篇的內容（25 段）

1. 零件清單
2. 為什麼是 ESP32 而不是 ESP8266
3. 步驟 1：裝 ESPHome
4. framework: esp-idf
5. api.encryption.key
6. !secret
7. wifi.ap 和 captive_portal
8. 步驟 4：接線
9. 為什麼一定要接 3.3V 不能接 5V
10. 為什麼不用另外加電阻
11. 杜邦線不要用太長的
12. 不要隨便換到別的腳位
13. 步驟 5：完整的設定檔
14. 每一段在做什麼
15. 第一個要找的：I2C 掃描結果
16. 第三個要找的：Wi-Fi 和 API
17. 怎麼看到實際的溫度數值
18. 步驟 8：讓 HA 認得它
19. 步驟 9：之後都用無線更新
20. 五個第一次很容易碰到的問題
21. 一、編譯失敗
22. 二、燒完連不上 Wi-Fi
23. 三、I2C 掃不到裝置
24. 四、裝置會自己重開機
25. 五、讀數在真實溫度上下跳

這篇從「什麼都還沒買」開始，做出一支會把溫度濕度回報給 Home Assistant 的感測器。全程不用寫任何 C++，只要填 YAML。



成本：零件加起來約 NT$220 到 400。買現成的 Zigbee 溫濕度計大概 NT$300 到 500，所以自己做的價值不在省錢，在於：回報間隔你說了算（商用的常常鎖死五分鐘）、一片板子可以接好幾顆感測器、之後想加螢幕加按鈕加繼電器都行。

ESPHome 是什麼：一套「用 YAML 描述功能、它幫你編譯成韌體燒進晶片」的工具。你只要寫「GPIO21 接了一顆 I2C 溫濕度感測器」，剩下它處理。編譯出來的韌體用原生協定直接跟 HA 溝通，不經過 MQTT、不經過雲端。

這篇用 ESPHome 2026.9.0（2026-09 發布）。版本差異在下面幾個地方會影響你抄到的設定，我會標出來。

零件清單

• ESP32 開發板（ESP32-WROOM-32 DevKitC，30 或 38 腳），約 NT$150-300。蝦皮搜「ESP32 開發板 ESP32-DevKitC」或「ESP32 WROOM 30PIN」
  
• AHT20 溫濕度模組（I2C 四腳版），約 NT$60-120。搜「AHT20 溫濕度 模組 I2C」
  
• 母對母杜邦線 4 條（20 公分），一排 40 條約 NT$30-50。搜「杜邦線 母對母 20cm」
  
• 能傳資料的 USB 線。板子是 Micro-USB 還是 Type-C 要看清楚，買之前先看商品圖的接口
  

為什麼是 ESP32 而不是 ESP8266

• 記憶體多很多。之後想把它兼做藍牙代理（幫 HA 接收周邊的藍牙溫濕度計）只能用 ESP32
  
• 有藍牙
  
• 價差幾十塊
  

為什麼推薦 DevKitC 而不是更便宜的 SuperMini

ESP32-C3 SuperMini 只要 NT$85 左右，很誘人。但對第一支裝置來說 DevKitC 好很多：

• 腳位名稱直接印在板子上。SuperMini 的腳位標示小到要用放大鏡，而且不同賣家的絲印不一樣
  
• I2C 腳位是固定的（GPIO21/22）。C3 沒有預設 I2C 腳位，設定檔一定要自己指定，錯了不會有明顯提示
  
• DevKitC 板子大，杜邦線插得穩，不會做到一半接觸不良
  

便宜的板子等你做到第三支、知道自己在幹嘛的時候再買。

為什麼是 AHT20 而不是 DHT11 / DHT22

DHT11 更便宜（不到 NT$30），但它的濕度誤差是正負 5%，而且是單線協定、容易讀取失敗。AHT20 走 I2C、精度是溫度正負 0.3 度、濕度正負 2%，只貴幾十塊。

買模組板不要買裸晶片。AHT20 本體是 3x3mm 的貼片，模組板已經幫你把腳位拉出來、也把 I2C 需要的兩顆上拉電阻焊好了。買裸晶片的話你要自己焊，還要自己加兩顆 4.7k 電阻。

步驟 1：裝 ESPHome

Home Assistant OS 的使用者：

• 設定 → 應用程式 → 安裝應用程式
  
• 搜尋 ESPHome Device Builder
  
• 安裝（第一次要幾分鐘）→ 打開在側邊欄顯示 → 啟動
  

找不到「應用程式」這個選單 → HA 2026.2 把「附加元件（Add-ons）」改名成「應用程式（Apps）」，舊教學寫的「設定 → 附加元件 → 附加元件商店」在新版找不到。東西沒變，只是名字和路徑換了。

完全沒有「應用程式」這一項 → 你跑的是 Docker 版（Container）的 HA，它沒有應用程式功能。改成另外跑一個 ESPHome 容器，或者在電腦上 `pip install esphome`，後面的步驟完全一樣。

你會看到什麼：側邊欄多一個 ESPHome，點進去是一個空的裝置清單。

步驟 2：用精靈建立第一個裝置

• ESPHome → + NEW DEVICE → 選 New Device Setup（另外兩個是「匯入既有設定檔」和「空白設定」）
  
• 取名字：bedroom-sensor。只能用英文小寫、數字和減號，不能有底線、不能有中文
  
• 晶片類型選 ESP32
  
• Wi-Fi 帳號密碼填進去
  
• 最後它會問要不要馬上安裝 —— 選 Skip，我們要先改設定
  

你會看到什麼：清單裡多一張卡片，狀態是 OFFLINE（因為還沒燒錄）。

名字不要用中文：這個名字會變成裝置在網路上的主機名稱，也會變成 HA 裡實體 ID 的前綴。中文會被轉成拼音或直接出錯。

步驟 3：看懂精靈產生的設定檔

點那張卡片的 EDIT，你會看到類似這樣的內容：

以下還有約 80% 的內容
登入後即可閱讀完整教學

登入繼續閱讀使用 Google 登入