【輕鬆工作家】在 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
- 到 python.org 下載 Python 3.12 或 3.13 安裝檔。
- 執行安裝檔時,務必勾選「Add python.exe to PATH」,再按 Install Now。
- 開啟 PowerShell,安裝 ESPHome:
pip install esphome
- 確認安裝成功,會顯示版本號:
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,因為板子上還沒有可以接收無線更新的韌體。
- 用 USB-C 線把開發板接上電腦。
- 在 PowerShell 進入專案資料夾並執行:
cd C:\esphome
esphome run esp32-s3-bluetooth-proxy.yaml
- ESPHome 會先檢查設定、下載工具鏈並編譯。第一次約需 10–20 分鐘。
- 編譯完成後會列出可用的連接埠,輸入對應 COM 埠的編號即開始燒錄。
- 燒錄完成後會自動重開機並顯示 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:
- 裝置上線後,Home Assistant 通常會自動發現,在 設定 → 裝置與服務 出現「已發現」提示。
- 按 設定,輸入
secrets.yaml裡的api_key。 - 完成後,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,之後每次改設定都能幾分鐘內無線更新完成。
| 用途 | 指令 |
|---|---|
| 安裝 ESPHome | pip install esphome |
| 升級 ESPHome | pip install -U esphome |
| 只檢查設定 | esphome config 檔名.yaml |
| 只編譯 | esphome compile 檔名.yaml |
| 編譯 + 燒錄 + 看 log | esphome run 檔名.yaml |
| 只燒錄 | esphome upload 檔名.yaml |
| 只看 log | esphome 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());

留言
張貼留言
請多指教