【冷氣遙控 2/7】第一份韌體：確認硬體真的會動

charles

這篇的內容（21 段）

1. 做完這篇你會有什麼
2. 步驟 1：選一條燒錄的路
3. A：Home Assistant 的應用程式版
4. C：Docker 版
5. D：瀏覽器版（web.esphome.io）
6. 步驟 2：USB 線與驅動程式
7. 2-1 USB 線挑不對的症狀
8. 2-2 驅動程式要不要裝
9. Windows 怎麼確認已經抓到
10. 步驟 3：用精靈建立裝置
11. 步驟 4：貼上完整的設定檔
12. 這份設定檔裡，每一段在幹嘛
13. 步驟 5：第一次燒錄
14. 四個最常見的卡關
15. 步驟 6：逐行讀開機日誌
16. 一行一行對照
17. 還有一條後路：fallback 熱點
18. 步驟 9：測接收頭收不收得到
19. 步驟 11：確認無線更新可以用
20. 通過這篇的標準
21. 這個系列的七篇

上一篇你把 ESP32、紅外線發射 LED、接收頭接好了。這一篇要燒第一份韌體進去，然後用兩個實驗證明「發射真的在發、接收真的在收」。

這篇還不會控制冷氣。 冷氣的協定是下一篇的事。這一篇只回答一個問題：硬體到底有沒有活著。

會分這麼細是有原因的。紅外線壞掉的時候是完全安靜的 —— 沒有錯誤訊息、沒有紅字、冷氣就只是沒反應。如果你在「硬體沒驗過」的狀態下直接去試冷氣協定，你會有兩個未知數同時在動，而且永遠分不出是哪一個。

做完這篇你會有什麼

• 一台在你家 Wi-Fi 上、可以無線更新的 ESP32
  
• 親眼確認過發射 LED 在閃（用手機前鏡頭看）
  
• 日誌裡看得到你家冷氣遙控器按下去的原始訊號
  
• 這台裝置已經出現在 Home Assistant 的裝置清單裡
  

這篇用的版本：ESPHome 2026.9.0、Home Assistant Core 2026.9.3。下面所有的選單名稱和設定寫法都是照這兩個版本寫的，如果你看到的畫面對不上，先確認版本。

步驟 1：選一條燒錄的路

ESPHome 有一個叫 Device Builder 的網頁面板，負責編譯設定檔、把韌體燒進板子、以及看日誌。你必須先有一個 Device Builder。

它有四種裝法，先選一種再往下走 —— 這一步選錯的話，後面每一步的畫面都會對不上。

• 你家 HA 是 HA OS（HA Green、HA Yellow、或自己裝在樹莓派／迷你主機上的 HAOS） → 選 A：HA 的應用程式版。最省事，日誌、燒錄、HA 整合全在同一個瀏覽器分頁裡
  
• 你家 HA 是用 Docker 跑的（Container 版） → HA 的應用程式機制在這種安裝方式上不存在，選 B：桌面版 或 C：Docker 版
  
• 你還沒有 Home Assistant，只是想先讓板子動起來 → 選 B：桌面版。它是獨立程式，跟 HA 完全無關
  
• 你只想花三分鐘確認板子沒壞 → 選 D：瀏覽器版，但它燒不了這篇的設定檔，看完下面的說明再決定
  

A：Home Assistant 的應用程式版

在 Home Assistant 裡走 設定 → 應用程式 → 安裝應用程式（英文介面是 Settings → Apps → Install App）。

⚠ 這個選單名稱在 2026.2 改過。 舊教學寫的是「設定 → 附加元件 → 附加元件商店」，那是 2026.2 之前的名字。功能完全一樣，只是「附加元件（Add-ons）」正式改名成「應用程式（Apps）」了。看到舊名稱的教學不代表它錯，只是它的選單路徑要自己換算。

在清單裡找 ESPHome Device Builder，點進去按安裝，再按啟動，然後把在側邊欄顯示打開。

你會看到：左邊側邊欄多出一個 ESPHome 的項目，點進去是一片空的裝置清單。

清單裡根本找不到 ESPHome Device Builder → 代表 ESPHome 的存放庫還沒註冊。按右上角的 ⋮ 選 存放庫（Repositories），貼上 https://github.com/esphome/home-assistant-addon 按新增，關掉對話框再找一次。

看不到側邊欄的項目 → 「在側邊欄顯示」那個開關沒打開，回應用程式頁面再確認一次。

B：桌面版（Windows / macOS / Linux）

這是比較新的選項，很多 2025 年的教學還沒提到它。到 esphome.io 的安裝頁選你的作業系統，下載安裝檔：

• Windows —— 下載 .exe，雙擊安裝。跳出「Windows 已保護您的電腦」時按其他資訊 → 仍要執行。裝完從開始功能表開啟
  
• macOS —— 下載 .dmg，把 ESPHome Device Builder 拖進應用程式資料夾。第一次開啟時 macOS 會問，按開啟。需要 10.15 以上
  
• Linux —— 有 .deb、.rpm、AUR 套件和 AppImage 四種。用 AppImage 的話記得 chmod +x
  

你會看到：一個視窗，裡面就是 Device Builder 的網頁介面，跟 A 的內容一模一樣。

Linux 上序列埠抓不到 → 把自己加進 dialout 群組（`sudo usermod -a -G dialout $USER`），登出再登入。

C：Docker 版

1. docker run --rm --net=host -v "${PWD}":/config -it ghcr.io/esphome/esphome

複製代碼

跑起來之後開 http://localhost:6052。

--net=host 不能省。 Device Builder 需要 mDNS 才能自己發現裝置、才能用 ac-ir.local 這種名字連線。在 Docker Desktop 上沒有 host 網路模式，只能改成 -p 6052:6052 —— 面板照樣會跑，但之後每次連裝置都得手動打 IP。

D：瀏覽器版（web.esphome.io）

用 Chrome 或 Edge 打開 web.esphome.io，插上板子，按 Connect 選序列埠，再按 Prepare for First Use → Install，最後填 Wi-Fi 帳密。

⚠ 這條路有一個硬限制，而且很多教學沒講清楚：它只能燒一份通用的空白韌體，沒有辦法燒本篇的設定檔（沒有 remote_transmitter、沒有 remote_receiver、沒有測試按鈕）。它的用途是「先讓板子上網」，然後在 Device Builder 的 Discovered 區塊把它收編進來，再套用你的設定檔。

所以 D 不能取代 A/B/C，只能當 A/B/C 的前置。 如果你只是想確認板子沒壞，它三分鐘就能給你答案；但做完這篇你還是需要 A、B、C 其中一個。

另外它只在 Chromium 核心的瀏覽器（Chrome、Edge、Opera）上能用，Safari 不行。

步驟 2：USB 線與驅動程式

第一次燒錄一定要用 USB 線接電腦，沒有例外。 板子上現在還沒有 ESPHome，沒有任何東西在聽無線更新的要求 —— 「無線」是靠已經跑起來的 ESPHome 提供的服務，雞生蛋蛋生雞。

線要接到哪一台電腦：接到你現在操作瀏覽器的這一台，不是 Home Assistant 主機。Device Builder 是透過瀏覽器的序列埠功能去燒的，所以板子要插在你面前這台。

2-1 USB 線挑不對的症狀

市面上很多 USB 線只有電源線、沒有資料線（充電器附的短線特別多）。用到這種線的症狀非常容易誤判：

• 板子上的電源燈會亮（電是通的）
  
• 電腦完全看不到任何序列埠
  
• 你會以為是驅動程式的問題，然後花一小時裝驅動
  

判別方法：拿一條你確定可以用來傳檔案的線（例如平常接手機傳照片那條）試一次。或者反過來，用這條線接手機，電腦看得到手機的檔案就是資料線。

2-2 驅動程式要不要裝

ESP32 開發板上有一顆「USB 轉序列」的小晶片，電腦要有對應的驅動才看得到它。板子上印的型號決定你要裝哪一個：

• CH340 / CH341 —— 最常見、最便宜的板子用這顆。Windows 10/11 大多要自己裝驅動
  
• CP2102 / CP2104 —— 稍貴的板子用這顆。Windows 通常會自動抓到
  
• PL2303 —— 比較舊的板子。注意市面上很多仿冒品，新版驅動會故意讓仿品不能用
  

怎麼知道自己是哪一顆：把板子翻到 USB 座旁邊，找一顆比 ESP32 小很多的方形晶片，上面用雷射印著型號，需要的話用手機拍起來放大看。

Windows 怎麼確認已經抓到

插上板子，按 Win + X 選裝置管理員，展開連接埠 (COM 和 LPT)：

• 你會看到一個像 USB-SERIAL CH340 (COM5) 或 Silicon Labs CP210x USB to UART Bridge (COM3) 的項目。COM 後面的號碼每台電腦不同
  
• 什麼都沒有 → 先換線（回 2-1）。線確定沒問題就是缺驅動
  
• 看得到但前面有一個黃色驚嘆號 → 驅動裝錯或沒裝好。在那個項目上按右鍵解除安裝，勾「刪除驅動程式軟體」，拔掉重插再裝一次
  
• 項目在「其他裝置」底下而不是「連接埠」底下 → 同上，缺驅動
  

驅動去哪裡拿：搜尋 CH340 driver 或 CP210x driver，認明晶片廠商的官網（CH340 是 WCH、CP210x 是 Silicon Labs）。裝完把板子拔掉重插，不用重開機。

macOS：新版 macOS 內建 CH34x 和 CP210x 的驅動，多半插上就好。要確認的話開終端機打 `ls /dev/cu.*`，你會看到 像 `/dev/cu.usbserial-0001` 或 `/dev/cu.SLAB_USBtoUART` 的項目。

Linux：核心內建驅動。`ls /dev/ttyUSB*`，你會看到 `/dev/ttyUSB0`。看得到卻沒權限存取的話，把自己加進 dialout 群組。

步驟 3：用精靈建立裝置

在 Device Builder 的空清單上按 Create device。

精靈會先問你要怎麼建立設定，有三個選項：

• New Device Setup —— 帶你選晶片型號、填 Wi-Fi，產生一份能跑的基礎設定。選這個
  
• Import from File —— 上傳現成的 .yaml，用在備份還原
  
• Empty Configuration —— 產生一份最小的設定檔，給想自己從頭寫的人
  

選 New Device Setup，照著走：

• 名稱填 ac-ir（小寫、用減號，不要用中文也不要用底線。這個名字之後會變成它在網路上的主機名稱 ac-ir.local）
  
• 裝置類型選 ESP32
  
• 填 Wi-Fi 名稱與密碼
  

你會看到：畫面跳出一段 Encryption key（一長串英數字，是 32 位元組的 base64），下面寫著稍後 Home Assistant 會跟你要這串。

先把它複製起來貼到記事本。 等一下步驟 9 要用。它其實是存在 secrets.yaml 裡的，弄丟還找得回來，但當場存起來省事很多。

精靈跑完會在裝置清單出現一張卡片，上面是 ac-ir。

卡片上有這幾個動作（後面每一步都會用到，先認一下）：

• Edit —— 打開設定檔編輯器
  
• Install（上傳圖示）—— 編譯 + 燒錄
  
• Logs（文件圖示）—— 看裝置的日誌
  
• ⋮ —— 裡面有 Validate（只檢查設定檔語法、不編譯，很快）和 Clean build files（清掉編譯產物，編譯錯誤查不出原因時先試這個）
  

步驟 4：貼上完整的設定檔

在 ac-ir 那張卡片上按 Edit，把裡面原本的內容整份刪掉，換成下面這份。

1. esphome:
2.   name: ac-ir
3.   friendly_name: 冷氣紅外線
4.   min_version: 2026.9.0
6. esp32:
7.   board: esp32dev
8.   framework:
9.     type: esp-idf
11. logger:
12.   level: DEBUG
14. api:
15.   encryption:
16.     key: !secret api_encryption_key
18. ota:
19.   - platform: esphome
20.     encryption:
22. wifi:
23.   ssid: !secret wifi_ssid
24.   password: !secret wifi_password
25.   ap:
26.     ssid: "AC-IR Fallback"
27.     password: "12345678"
29. captive_portal:
31. status_led:
32.   pin: GPIO2
34. remote_transmitter:
35.   id: ir_tx
36.   pin: GPIO14
37.   carrier_duty_percent: 50%
39. remote_receiver:
40.   id: ir_rx
41.   pin:
42.     number: GPIO16
43.     inverted: true
44.     mode:
45.       input: true
46.       pullup: true
47.   tolerance: 55%
48.   filter: 250us
49.   idle: 25ms
50.   dump: all
52. button:
53.   - platform: template
54.     name: "紅外線發射測試"
55.     on_press:
56.       - remote_transmitter.transmit_raw:
57.           code: [9000, -4500, 9000, -4500, 9000, -4500, 9000, -4500, 9000, -4500]
58.           carrier_frequency: 38000
59.           repeat:
60.             times: 20
61.             wait_time: 30ms
63.   - platform: restart
64.     name: "重新啟動"

複製代碼

貼完先按 Save，再按 ⋮ → Validate。你會看到最後一行是 INFO Configuration is valid!。

看到紅色的錯誤訊息，九成是縮排。YAML 用空白縮排，一個 Tab 都不能有，而且從別的地方複製貼上最容易帶進 Tab。錯誤訊息會告訴你第幾行。

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

登入繼續閱讀使用 Google 登入