阿明博士的 ESPHome 實作教室：不用 Home Assistant 的六個 ESP32-S3 案例

ESP32-S3 搭配 ESPHome，可以不依賴 Home Assistant，從區網網頁查看感測數據，再依需求接上 MQTT 與 Node-RED。這個系列用六個案例，帶你從一顆 SHT20 做到溫濕度、CO₂、粉塵、照度與 BLE 狀態的整合監測。

適合想動手做環境監測的小型商家、工作室、教學者與開發者。只想看一個數字，可以從單一案例開始；需要多房間紀錄，再走到第六課。

內容整理：台灣智能感測科技｜導讀角色：阿明博士

先選一個你想解決的問題

照什麼順序開始？

1. 先完成 SHT20：學會填 Wi-Fi、編譯、USB 燒錄和開啟主板網頁。
2. 依用途增加感測器：通風看 SCD41、粉塵看 PMS5003T、工作面採光看 BH1750。
3. 再加 BLE 與集中紀錄：先用第二塊 S3 熟悉信標，再把需要的數據接到 MQTT 與 Node-RED。

下載完整設定與元件

範例包包含七份 YAML、SHT20 本機元件、密碼設定範本，以及 MQTT／Node-RED 後端資料。接線與供電圖則放在各課文章內，可開啟大圖查看。

下載六課完整範例 ZIP。解壓縮後保留 examples/components 資料夾；把 secrets.yaml.example 複製為 secrets.yaml，再填自己的 Wi-Fi 與密碼。

第一次做？共用燒錄與後端指南

先完成一課、確認接線，再換下一課。每一課是獨立主韌體，不需要把不同 YAML 手動合併。

一、Windows 安裝固定工具版本

安裝 Python 3.12，勾選加入 PATH。PowerShell 在教學包資料夾執行：

py -3.12 -m venv .venv .\.venv\Scripts\python.exe -m pip install "esphome==2026.10.1" cd examples Copy-Item secrets.yaml.example secrets.yaml notepad secrets.yaml ..\.venv\Scripts\python.exe -m esphome config 01-sht20.yaml ..\.venv\Scripts\python.exe -m esphome compile 01-sht20.yaml

首次編譯需要下載 ESP-IDF、編譯器與相依套件，必須能連網；後續感測器運作不需要這台電腦一直開著。檔案路徑建議使用簡單英文資料夾。examples/components 不能遺漏。本包的 secrets.yaml 是無效示例，務必改成自己的值，不要把真實密碼寄回或貼到文章留言。

二、USB 接頭與日誌選擇

若板子有兩個 USB 口，先辨識標示 USB／OTG 的原生 USB，以及 UART／COM 的 USB 轉序列口。本文 YAML 日誌使用 USB_SERIAL_JTAG，對應原生 USB。它不占用 GPIO17／GPIO18 的感測器 UART。USB-UART 端通常也能燒錄，但若要從同一端看日誌，將 logger.hardware_uart 改為 UART0 後重新編譯；這會使用 UART0 的 TX／RX，勿接其他設備到該埠。

Windows 裝置管理員查看「連接埠 COM 和 LPT」。選擇實際出現的埠，範例 COM5 不一定是你的埠。USB-UART 若缺驅動，要辨識轉接晶片，再到晶片廠官網安裝，不能假設每一批都是 CP210x。

..\.venv\Scripts\python.exe -m esphome upload 01-sht20.yaml --device COM5 ..\.venv\Scripts\python.exe -m esphome logs 01-sht20.yaml --device COM5

首次 USB 燒錄可能讓原生 USB 埠重新列舉，請重新查看 COM。若連不上：換資料線、直連電腦、關閉占用序列埠的視窗，再按住 BOOT，按一下 RESET／EN，放開 RESET 後再放開 BOOT，重新選埠。燒錄後必要時按 RESET；確認沒有一直按著 BOOT。

三、已編譯 BIN 的兩種用途

自行編譯後，examples/.esphome/build/對應設備名/build/firmware.factory.bin 是初次完整燒錄檔。可在電腦以支援 Web Serial 的 Chrome／Edge 開啟 ESPHome Web，CONNECT 選擇 USB 裝置，再 INSTALL 選 factory 檔。本教學包提供完整原始設定；必須先填 secrets，再編譯自己的版本。設備名見 YAML 的 esphome.name，例如 course-01-sht20。

firmware.ota.bin 只用於已有對應 ESPHome 韌體的更新，不可當首次 factory 檔任意寫入地址。本文只啟用 ESPHome OTA，沒有開啟網頁上傳平台，網頁沒有更新按鈕是正常的。

..\.venv\Scripts\python.exe -m esphome upload 01-sht20.yaml --device 192.168.1.123

IP 改為設備實際位址。OTA 密碼需與設備目前使用的密碼相符；更換新設定密碼前，先確認目前韌體能如何驗證。更新後可能換 IP，從 DHCP 清單或 USB 日誌查詢，無需原生 API。

四、第一次啟動核對表

1. 核對 ESP32-S3 與實物 N16R8 標示。開機日誌確認 Flash／PSRAM，若 PSRAM 失敗，先查實物與 octal 設定。
2. 本包初次設定採 DEBUG 日誌，方便看到掃描與元件設定；正式運轉可改 INFO 並重新編譯。先核對每條電源與訊號電壓，確認沒有把 5V 拉到 ESP32 的 GPIO。
3. I²C 依已接模組看到 0x40、0x62、0x23。PMS5003T 走 UART，不會出現在 I²C 掃描。
4. 確認連上 2.4GHz Wi-Fi 與取得 IP。瀏覽器開 http://設備IP/，輸入網頁帳密。
5. 等待讀值及 Fresh 狀態。PMS 至少等待 30 秒，再依各課負向測試驗收。

五、第六課後端：獨立教學環境

以下後端指令從解壓縮後的主資料夾開始執行，請先回到該資料夾，再進入 backend。

以下步驟在讀者自己的 Docker 主機建立教學環境。若 1883 或 1880 已被其他服務使用，先規劃替代埠及同步調整設定；不要停掉不明的既有服務。

開啟 Docker Desktop 或 Linux Docker Engine，進入 backend 執行準備腳本。建立 Broker 的 course-sensor 帳號時互動輸入密碼，避免把密碼留在命令歷史。Node-RED MQTT 節點與 ESPHome secrets 使用同一帳密。

cd backend # Linux / macOS： sh prepare.sh # Windows PowerShell： .\prepare.ps1 docker compose up -d

Broker 1883 預設只綁 127.0.0.1。要讓實體 ESP32 連入，複製 .env.example 為 .env，把 MQTT_BIND 改為該 Docker 主機的區網 IPv4；之後重建容器，並在主機防火牆只允許預期的感測器網段。不要填路由器公網 IP，也不要直接開公網埠。不同網段／不可信鏈路應另配置 TLS，這份本地教學不含 TLS。

在該電腦瀏覽器開 http://127.0.0.1:1880，匯入 backend/flows.json，打開 MQTT broker 設定填帳密，Deploy。容器內連 Broker 用 mqtt:1883；ESP32 的 mqtt_broker 則填 Docker 主機區網 IP。開 http://127.0.0.1:1880/sensor 查看資料，紀錄保存在 Node-RED 資料卷 /data/sensor.jsonl。

Node-RED 編輯器與測試網頁僅綁本機，不供其他電腦直接開啟。若要正式開放儀表板，需要另加登入、HTTPS 與網路存取控制。此教學先驗證資料路徑，沒有把管理介面直接暴露到整個區網。

常見問題

這六課都要一次接上嗎？

不需要。每課都有自己的 YAML，先接該課需要的模組即可。第六課才把多種資料整合，別把不同課的設定片段直接堆在一起。

一定要使用 Home Assistant 嗎？

不需要。本系列使用 ESPHome 的區網網頁與 MQTT 等介面，沒有加入需要 Home Assistant 連線的原生 API 設定。

接線圖能直接當成實體排針位置嗎？

圖面依 GPIO 和端子名稱對照，實物要核對絲印、電源和模組版本。SHT20、Grove SCD41、PMS5003T 的供電安排不同，請先閱讀該課接線段落。