ESPHome 的 substitutions 與 packages：別再複製貼上

charles

做到第三個裝置的時候，你會發現每個 YAML 有八成是一樣的。

改一個東西要改八個檔案 —— 這時候就該用 packages 了。



問題長什麼樣

假設你有五個溫濕度感測器，每個的 YAML：

1. esphome:
2.   name: bedroom-sensor
3. esp32:
4.   board: esp32dev
5.   framework: {type: esp-idf}
6. logger:
7. api:
8.   encryption: {key: "xxx"}
9. ota:
10.   - platform: esphome
11.     password: "xxx"
12. wifi:
13.   ssid: !secret wifi_ssid
14.   password: !secret wifi_password
15.   ap: {ssid: "Fallback"}
16. captive_portal:
17. i2c: {sda: GPIO21, scl: GPIO22}
18. sensor:
19.   - platform: aht10
20.     ...

複製代碼

五個檔案，只有 name 和感測器名稱不一樣。

想加一個「Wi-Fi 訊號」感測器到全部？改五次。

第一層：substitutions（變數）

1. substitutions:
2.   device_name: bedroom-sensor
3.   friendly_name: 臥室感測器
4.   update_time: 30s
6. esphome:
7.   name: ${device_name}
8.   friendly_name: ${friendly_name}
10. sensor:
11.   - platform: aht10
12.     variant: AHT20
13.     temperature:
14.       name: "溫度"
15.     humidity:
16.       name: "濕度"
17.     update_interval: ${update_time}

複製代碼

${變數名} 會被代換掉。

這樣至少改一個地方就能改全部的回報間隔。

但還是五個檔案。



第二層：packages（真正的解法）

概念：把共用的部分抽出來變成一個檔案，每個裝置引用它。

檔案結構

在 ESPHome 的檔案清單裡建立：

1. /config/esphome/
2. ├── secrets.yaml
3. ├── common/
4. │   ├── base.yaml           ← 所有裝置都要的
5. │   ├── wifi.yaml           ← Wi-Fi 設定
6. │   └── sensor-aht20.yaml   ← 溫濕度感測器
7. ├── bedroom-sensor.yaml
8. ├── study-sensor.yaml
9. ├── living-sensor.yaml
10. └── ...

複製代碼

common/base.yaml

1. esphome:
2.   name: ${device_name}
3.   friendly_name: ${friendly_name}
5. esp32:
6.   board: ${board}
7.   framework:
8.     type: esp-idf
10. logger:
11.   level: INFO
13. api:
14.   encryption:
15.     key: !secret api_key
17. ota:
18.   - platform: esphome
19.     password: !secret ota_password
21. # 所有裝置都要有的診斷資訊
22. sensor:
23.   - platform: wifi_signal
24.     name: "Wi-Fi 訊號"
25.     update_interval: 300s
26.     entity_category: diagnostic
28.   - platform: uptime
29.     name: "運行時間"
30.     update_interval: 300s
31.     entity_category: diagnostic
33. text_sensor:
34.   - platform: version
35.     name: "ESPHome 版本"
36.     entity_category: diagnostic
38.   - platform: wifi_info
39.     ip_address:
40.       name: "IP 位址"
41.       entity_category: diagnostic
43. button:
44.   - platform: restart
45.     name: "重新開機"
46.     entity_category: config

複製代碼

common/wifi.yaml

1. wifi:
2.   ssid: !secret wifi_ssid
3.   password: !secret wifi_password
5.   # 訊號弱的時候自動重連
6.   reboot_timeout: 15min
8.   ap:
9.     ssid: "${device_name} Fallback"
10.     password: !secret ap_password
12. captive_portal:

複製代碼

common/sensor-aht20.yaml

1. i2c:
2.   sda: ${i2c_sda}
3.   scl: ${i2c_scl}
4.   scan: true
6. sensor:
7.   - platform: aht10
8.     variant: AHT20
9.     temperature:
10.       name: "溫度"
11.       filters:
12.         - median:
13.             window_size: 5
14.             send_every: 5
15.         - delta: 0.2        # 變化超過 0.2 度才回報
16.     humidity:
17.       name: "濕度"
18.       filters:
19.         - median:
20.             window_size: 5
21.             send_every: 5
22.         - delta: 1.0
23.     update_interval: ${update_time}

複製代碼

然後每個裝置的檔案變成

1. # bedroom-sensor.yaml
2. substitutions:
3.   device_name: bedroom-sensor
4.   friendly_name: 臥室
5.   board: esp32dev
6.   i2c_sda: GPIO21
7.   i2c_scl: GPIO22
8.   update_time: 30s
10. packages:
11.   base: !include common/base.yaml
12.   wifi: !include common/wifi.yaml
13.   sensor: !include common/sensor-aht20.yaml

複製代碼

十行。而且加新裝置只要複製這十行改三個字。



這樣做的四個好處

一、改一次，全部生效

想讓所有裝置都加一個「重新開機」按鈕？
改 base.yaml 一個地方，然後重新編譯所有裝置。

二、新裝置十秒搞定

複製一個現有的、改 device_name 和 friendly_name，完成。

三、可以混搭

1. packages:
2.   base: !include common/base.yaml
3.   wifi: !include common/wifi.yaml
4.   temp: !include common/sensor-aht20.yaml
5.   motion: !include common/sensor-pir.yaml     # 這台多一個人體感應
6.   relay: !include common/relay.yaml           # 這台還有繼電器

複製代碼

像積木一樣組合。

四、版本管理容易

整個 esphome 資料夾進 Git，
改了什麼一目了然。

覆寫（override）：某一台要不一樣怎麼辦

packages 引入的設定，可以在裝置檔案裡覆寫。

1. substitutions:
2.   device_name: garage-sensor
3.   update_time: 120s        # 這台車庫的，兩分鐘回報一次就好
5. packages:
6.   base: !include common/base.yaml
7.   wifi: !include common/wifi.yaml
8.   sensor: !include common/sensor-aht20.yaml
10. # 這台額外加的東西
11. binary_sensor:
12.   - platform: gpio
13.     pin: GPIO13
14.     name: "車庫門"
15.     device_class: garage_door

複製代碼

清單類型（sensor、binary_sensor）會合併，
純值（substitutions）會被覆蓋。

進階：遠端 packages

packages 可以指向網路上的檔案：

1. packages:
2.   common:
3.     url: https://github.com/你的帳號/esphome-config
4.     files: [common/base.yaml]
5.     ref: main
6.     refresh: 1d

複製代碼

適合：你有很多台裝置，而且想集中管理。

但一般家庭用本地檔案就夠了，
而且不依賴網路比較可靠。

一個實際的資料夾結構範例

我自己的：

1. /config/esphome/
2. ├── secrets.yaml
3. ├── common/
4. │   ├── base.yaml
5. │   ├── wifi.yaml
6. │   ├── wifi-iot-vlan.yaml       ← IoT 網段用的（不同 SSID）
7. │   ├── sensor-aht20.yaml
8. │   ├── sensor-scd40.yaml        ← CO2
9. │   ├── sensor-pms5003.yaml      ← PM2.5
10. │   ├── sensor-pir.yaml
11. │   ├── sensor-ld2410.yaml       ← 毫米波
12. │   ├── relay-1ch.yaml
13. │   ├── ir-transceiver.yaml      ← 紅外線
14. │   └── display-eink.yaml
15. ├── bedroom-sensor.yaml
16. ├── study-air.yaml
17. ├── living-presence.yaml
18. ├── bt-proxy-1.yaml
19. └── info-panel.yaml

複製代碼

十一個 common 檔案、五台裝置。

新增第六台的時候，大概三分鐘就好了。

三個小提醒

一、substitutions 的值一定要是字串

1. substitutions:
2.   update_time: 30s        # 對
3.   pin_number: "13"        # 數字也要加引號比較保險

複製代碼

二、packages 裡不能再用 !secret（某些版本）

這個看版本。如果遇到問題，把 secret 改成 substitution 傳進去。

三、改了 common 檔案，所有裝置都要重新編譯

ESPHome 不會自動幫你編譯全部。

要一台一台按 INSTALL，或者用命令列：

1. esphome run bedroom-sensor.yaml study-air.yaml living-presence.yaml

複製代碼

---

下一篇：感測器濾波器完全指南 ——
讓數值不要一直跳，而且省下大量的資料庫空間。