【輕鬆工作家】在 Windows 11 編譯並燒錄 ESPHome 韌體(ESP32-S3 實作)


前言

把 ESPHome 的編譯搬到 Windows 11 電腦,第一次完整編譯約 10–20 分鐘,之後每次只要幾分鐘。若用 Raspberry Pi 4 上的 Home Assistant 編譯 ESP-IDF 框架的韌體,往往要等上半小時以上。

本文以 Waveshare ESP32-S3 2.06 吋 AMOLED 開發板為例,軟體設定為「藍牙代理(Bluetooth Proxy)」,用來接收小米溫濕度計等 BLE 裝置的資料轉給 Home Assistant,螢幕同時顯示 Wi-Fi 狀態、IP 位址與電池電量。其他 ESP32 板子的流程完全相同,只是 yaml 內容不同。

準備工作

項目說明
電腦Windows 11,硬碟預留 3 GB 以上空間
開發板ESP32-S3(本例為 Waveshare 2.06 吋 AMOLED)
傳輸線可傳輸資料的 USB-C 線(不是只能充電的線)
軟體Python 3.12 或 3.13、ESPHome
網路第一次編譯需下載約 1–2 GB 工具鏈

ESP32-S3 使用晶片內建的原生 USB,Windows 11 會自動辨識,不需要另外安裝 CP210x 或 CH340 驅動程式。

安裝 Python 與 ESPHome

  1. 到 python.org 下載 Python 3.12 或 3.13 安裝檔。
  2. 執行安裝檔時,務必勾選「Add python.exe to PATH」,再按 Install Now。
  3. 開啟 PowerShell,安裝 ESPHome:
pip install esphome
  1. 確認安裝成功,會顯示版本號:
esphome version

之後要升級 ESPHome,執行 pip install -U esphome 即可。

建立專案與 secrets.yaml

專案資料夾要放在短、純英文的路徑,例如 C:\esphome\。ESP-IDF 遇到中文路徑或過長路徑(例如雲端硬碟同步資料夾)容易編譯失敗。

資料夾裡放兩個檔案:

  • esp32-s3-bluetooth-proxy.yaml:裝置設定
  • secrets.yaml:密碼與金鑰,讓主設定檔可以安心分享

主設定檔用 !secret 引用機密資料:

api:
  encryption:
    key: !secret api_key

ota:
  - platform: esphome
    password: !secret ota_password

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

secrets.yaml 內容範例(引號要用半形 "):

wifi_ssid: "你的Wi-Fi名稱"
wifi_password: "你的Wi-Fi密碼"
api_key: "44 字元的 base64 金鑰"
ota_password: "自訂一組密碼"

產生 API 金鑰:API 金鑰必須是 32 bytes 的 base64 字串,共 44 個字元、結尾為 =。在 PowerShell 執行:

$b = New-Object byte[] 32; [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b); [Convert]::ToBase64String($b)

也可以用 Python 產生:

python -c "import secrets,base64;print(base64.b64encode(secrets.token_bytes(32)).decode())"

OTA 密碼沒有格式限制,建議用 12 個字元以上的英數混合字串。它只存在 secrets.yaml,無線更新時 ESPHome 會自動讀取,不必背起來。

第一次編譯與 USB 燒錄

第一次燒錄一定要用 USB,因為板子上還沒有可以接收無線更新的韌體。

  1. 用 USB-C 線把開發板接上電腦。
  2. 在 PowerShell 進入專案資料夾並執行:
cd C:\esphome
esphome run esp32-s3-bluetooth-proxy.yaml
  1. ESPHome 會先檢查設定、下載工具鏈並編譯。第一次約需 10–20 分鐘。
  2. 編譯完成後會列出可用的連接埠,輸入對應 COM 埠的編號即開始燒錄。
  3. 燒錄完成後會自動重開機並顯示 log,按 Ctrl+C 離開。

找不到 COM 埠時:按住板子上的 BOOT 鍵再插上 USB,或按住 BOOT 再按一下 RESET,進入下載模式後重試。

如果只想燒錄、不看 log,可以改用:

esphome upload esp32-s3-bluetooth-proxy.yaml

OTA 無線更新與加入 Home Assistant

第一次 USB 燒錄完成、板子連上 Wi-Fi 後,之後的更新就不必再接線。再執行一次 esphome run,在選單中選擇裝置的 IP 位址,就會透過 Wi-Fi 上傳新韌體。

加入 Home Assistant:

  1. 裝置上線後,Home Assistant 通常會自動發現,在 設定 → 裝置與服務 出現「已發現」提示。
  2. 按 設定,輸入 secrets.yaml 裡的 api_key。
  3. 完成後,IP 位址、電池電量、按鍵狀態等實體就會出現在 Home Assistant,藍牙代理也會開始轉發 BLE 裝置的資料。

若之後更換了 API 金鑰,Home Assistant 會提示「需要重新驗證」,貼上新金鑰即可。

常見錯誤排解

以下是實際操作時遇到的錯誤與解法。

Invalid key format, please check it's using base64

secrets.yaml 裡的 api_key 不是有效的 32-byte base64 字串。常見原因:

  • 值還是範例文字,沒有換成真正的金鑰
  • 複製時多了空白、換行,或漏掉結尾的 =
  • 中文輸入法打出全形引號或全形空白
  • 改到別的 secrets.yaml;必須是跟主設定檔同一個資料夾的那一份

用前面的 PowerShell 指令重新產生一組,可用 "你的金鑰".Length 確認長度為 44。

DLL load failed:應用程式控制原則已封鎖此檔案

這個錯誤發生在燒錄完成後的 show_logs 階段,韌體其實已經燒進去了。原因是 Windows 11 的「智慧型應用程式控制」(Smart App Control)擋住了 aioesphomeapi 套件中沒有數位簽章的 .pyd 檔。

解法:改裝不含已編譯檔的純 Python 版本:

$env:SKIP_CYTHON="1"
pip install --force-reinstall --no-binary aioesphomeapi aioesphomeapi

如果之後其他套件也出現同樣錯誤,把指令中的套件名稱換成錯誤訊息裡的名稱即可。不建議直接關閉智慧型應用程式控制,因為關閉後除非重灌 Windows,否則無法再開啟。

找不到 COM 埠

  • 換一條可傳輸資料的 USB-C 線
  • 按住 BOOT 鍵再插上 USB,強制進入下載模式
  • 在「裝置管理員 → 連接埠 (COM 和 LPT)」確認是否有新的 USB 序列裝置

編譯時出現路徑或檔案找不到的錯誤

把專案移到 C:\esphome\ 這類短、純英文的路徑,避開雲端硬碟同步資料夾。

結語與指令速查

在 Windows 11 上建好 ESPHome 環境後,編譯速度遠快於 Raspberry Pi 4,之後每次改設定都能幾分鐘內無線更新完成。

用途指令
安裝 ESPHomepip install esphome
升級 ESPHomepip install -U esphome
只檢查設定esphome config 檔名.yaml
只編譯esphome compile 檔名.yaml
編譯 + 燒錄 + 看 logesphome run 檔名.yaml
只燒錄esphome upload 檔名.yaml
只看 logesphome logs 檔名.yaml

附錄:完整 YAML

以下是本文使用的完整設定檔 esp32-s3-bluetooth-proxy.yaml(Waveshare ESP32-S3 2.06 吋 AMOLED)。Wi-Fi、API 金鑰與 OTA 密碼都改用 !secret 讀取,請搭配前面說明的 secrets.yaml 使用。

esphome:
  name: esp32-s3-bluetooth-proxy
  friendly_name: ESP32-S3 bluetooth proxy
  on_boot:
    # I2C 匯流排在 priority 1000 已就緒;900 可確保 PMIC 電源早於螢幕初始化
    priority: 900
    then:
      - lambda: |-
          // ⚠ 數值請對照 Waveshare 官方範例確認;不要動 DCDC1 (0x82)
          id(pmic).write_byte(0x92, 0x0D);  // ALDO1 = 1.8V
          // ALDO2 電壓 (0x93) 未設定 → 使用晶片預設值;若 ALDO2 沒用到可把下方 0x90 改成 0x11
          id(pmic).write_byte(0x96, 0x1C);  // BLDO1 = 3.3V
          id(pmic).write_byte(0x90, 0x13);  // 開啟 ALDO1/ALDO2/BLDO1
          id(pmic).write_byte(0x41, 0x03);  // PWR 鍵按下/放開邊緣中斷使能
          id(pmic).write_byte(0x48, 0xFF);  // 清除中斷狀態
          id(pmic).write_byte(0x49, 0xFF);

          uint8_t r = 0;
          // 開啟電池電壓 ADC(0x30 bit0)
          if (id(pmic).read_byte(0x30, &r)) id(pmic).write_byte(0x30, r | 0x01);
          // 開啟電量計(0x18 bit3)
          if (id(pmic).read_byte(0x18, &r)) id(pmic).write_byte(0x18, r | 0x08);

esp32:
  variant: esp32s3
  flash_size: 16MB
  framework:
    type: esp-idf

psram:
  mode: octal
  speed: 80MHz

logger:

api:
  encryption:
    key: !secret api_key

ota:
  - platform: esphome
    password: !secret ota_password

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "ESP32-S3 Proxy Fallback"

captive_portal:

# ==================== 藍牙代理 ====================
esp32_ble_tracker:
  scan_parameters:
    # Wi-Fi 與 BLE 共用射頻;window 小於 interval 可讓 Wi-Fi 較穩定
    # 若連線穩定且想提高掃描率,可再改回 interval/window: 1100ms
    interval: 320ms
    window: 30ms
    active: true

bluetooth_proxy:
  active: true

# ==================== LCD_EN 供電腳位 ====================
switch:
  - platform: gpio
    pin: GPIO10
    id: lcd_en
    restore_mode: ALWAYS_ON
    internal: true

# ==================== I2C / AXP2101 ====================
i2c:
  - id: bus_a
    sda: GPIO15
    scl: GPIO14
    scan: true

i2c_device:
  - id: pmic
    i2c_id: bus_a
    address: 0x34

# ==================== IP / 電池 ====================
text_sensor:
  - platform: wifi_info
    ip_address:
      name: "IP Address"
      id: ip_addr

  - platform: template
    name: "Battery Status"
    id: bat_status
    update_interval: 10s
    lambda: |-
      uint8_t s0 = 0, s1 = 0;
      if (!id(pmic).read_byte(0x00, &s0) || !(s0 & 0x08)) return {"No Battery"};
      if (!id(pmic).read_byte(0x01, &s1)) return {};
      switch ((s1 >> 5) & 0x03) {
        case 1: return {"Charging"};
        case 2: return {"Discharging"};
        default: return {"Standby"};
      }

sensor:
  - platform: template
    name: "Battery Level"
    id: bat_level
    unit_of_measurement: "%"
    device_class: battery
    accuracy_decimals: 0
    update_interval: 30s
    lambda: |-
      uint8_t s0 = 0, v = 0;
      if (!id(pmic).read_byte(0x00, &s0) || !(s0 & 0x08)) return NAN;
      if (!id(pmic).read_byte(0xA4, &v)) return NAN;
      return (float) v;

  - platform: template
    name: "Battery Voltage"
    id: bat_voltage
    unit_of_measurement: "V"
    device_class: voltage
    accuracy_decimals: 2
    update_interval: 30s
    lambda: |-
      uint8_t s0 = 0, h = 0, l = 0;
      if (!id(pmic).read_byte(0x00, &s0) || !(s0 & 0x08)) return NAN;
      if (!id(pmic).read_byte(0x34, &h) || !id(pmic).read_byte(0x35, &l)) return NAN;
      return (((h & 0x3F) << 8) | l) / 1000.0f;

# ==================== 按鍵 ====================
binary_sensor:
  - platform: gpio
    pin:
      number: GPIO0
      inverted: true
      mode:
        input: true
        pullup: true
    name: "Boot Button"
    filters:
      - delayed_on: 10ms

  - platform: template
    name: "PWR Button"
    id: pwr_button

interval:
  - interval: 150ms
    then:
      - lambda: |-
          uint8_t v = 0;
          if (id(pmic).read_byte(0x49, &v) && (v & 0x02)) {
            ESP_LOGD("axp2101", "PWR pressed, reg 0x49 = 0x%02X", v);
            id(pmic).write_byte(0x49, v);   // 寫 1 清除
            id(pwr_button).publish_state(true);
            id(pwr_release).execute();
          }

script:
  - id: pwr_release
    then:
      - delay: 50ms
      - lambda: id(pwr_button).publish_state(false);

# ==================== QSPI 螢幕 ====================
spi:
  - id: spi_1
    type: quad
    clk_pin: GPIO11
    data_pins: [GPIO4, GPIO5, GPIO6, GPIO7]

font:
  - file: "gfonts://Roboto"
    id: my_font
    size: 24

display:
  - platform: mipi_spi
    model: CO5300
    bus_mode: quad
    spi_id: spi_1
    cs_pin: GPIO12
    reset_pin: GPIO8
    # CO5300 預設為 466x466,2.06 吋面板 410x502 需明確指定 offset / pad
    dimensions:
      width: 410
      height: 502
      offset_width: 22
      offset_height: 0
      pad_width: 0
      pad_height: 0
    update_interval: 5s
    lambda: |-
      it.fill(Color::BLACK);
      it.print(20, 40, id(my_font), Color::WHITE, "ESP32-S3 BLE Proxy");

      // Wi-Fi / IP
      if (wifi::global_wifi_component->is_connected()) {
        it.print(20, 80, id(my_font), Color(0, 255, 0), "Wi-Fi: Connected");
        it.printf(20, 115, id(my_font), Color::WHITE, "IP: %s", id(ip_addr).state.c_str());
      } else {
        it.print(20, 80, id(my_font), Color(255, 255, 0), "Wi-Fi: Connecting...");
        it.print(20, 115, id(my_font), Color(128, 128, 128), "IP: --");
      }

      // 電池
      float pct = id(bat_level).state;
      float vol = id(bat_voltage).state;
      if (isnan(pct)) {
        it.print(20, 165, id(my_font), Color(128, 128, 128), "Battery: --");
      } else {
        Color c = pct > 50 ? Color(0, 255, 0) : (pct > 20 ? Color(255, 200, 0) : Color(255, 0, 0));
        it.printf(20, 165, id(my_font), c, "Battery: %.0f%%  %.2fV", pct, vol);
      }
      it.printf(20, 200, id(my_font), Color::WHITE, "%s", id(bat_status).state.c_str());

留言

這個網誌中的熱門文章

Arduino IDE 1.6.5 + BH1750 + CD74HC4067 多工器

Arduino 模擬 Modbus Slave

鹵素燈泡 軌道燈 改用 LED 燈 完整轉換