與 Home Assistant 整合
把 Woow EMQX add-on（EMQX 5.8.9）當成 HA 的 MQTT broker：接上 MQTT 整合、讓 discovery 自動探索裝置，也順勢把 Zigbee2MQTT 與 Mosquitto 遷移到 EMQX。
為什麼要學這個
Home Assistant 內鍵的 MQTT 整合是「broker 位址＋帳密」最小設定，但你的 Home Assistant 主機不一定想永遠用 Mosquitto。換成 Woow EMQX 的最大理由是把 MQTT 生命週期接管：Dashboard、ACL、規則、監控——前提是 HA 要「能連到」你的 EMQX。
這章把 EMQX 接成 HA 的 broker、讓 discovery 自動把 MQTT 裝置搬進 HA，也把 Zigbee2MQTT 與舊的 Mosquitto 一起收進同一套整合。
核心概念
HA 的 MQTT 整合（MQTT integration）是 Home Assistant 內建的整合，用來連一個 MQTT broker。Woow EMQX add-on 提供的就是這個 broker：add-on 使用 host_network，直接開放主機上的 1883（MQTT）埠，HA 設定時 Broker 填 homeassistant 或 localhost 即可。
連線時需要一組在 EMQX 的「使用者帳號」：因為 Woow EMQX 預設要求先設定 Authentication（驗證），沒有帳密就無法連。因此順序是：先在 EMQX 的 Access Control → Authentication 建立使用者 → 在 HA 建立 MQTT 整合填入這組帳密。
名詞對照
| 英文 | 中文 | 一句話 |
|---|---|---|
| MQTT Integration | MQTT 整合 | HA 連接 MQTT broker（EMQX）的整合 |
| Discovery | 探索 | HA 自動新增「會說話」的 MQTT 裝置 |
| Birth Message | 通知訊息 | 整合上線時發布的「我在」訊息 |
| Status Topic | 狀態主題 | 表達整合是 online／offline 的主題 |
| Will | 遺囑 | 異常/異常離線時 broker 代送的通知 |
| State Topic | 狀態主題 | 裝置更新狀態的主題 |
動手做
在 EMQX 建立 MQTT 使用者
先到 EMQX Dashboard：Access Control → Authentication，選擇 Password-Based → Built-in Database，建立一個使用者與密碼（用於 HA 連線）。
開啟 Home Assistant 的 MQTT 整合
HA 面板：設定 → 裝置與服務 → 新增整合 → 搜尋 MQTT。若還沒安裝，會提示建立。
填寫 broker 連線資訊
Broker 填
homeassistant（或localhost），連接埠 1883，Username 填剛才建立的帳號，Password 填對應密碼。儲存並確認
儲存後 HA 應顯示連線成功。回到 EMQX Dashboard 的 Clients 頁，你會看到 HA 的這個 MQTT client 已上線。
檢查 discovery
若已在
homeassistant/主題有一組 discovery 訊息，HA 應自動探索出裝置；否則手動新增「新增裝置」即可。
MQTT 整合、discovery 與 birth／will
Discovery 是 HA MQTT 整合的便利點：整合訂閱 discovery 前綴（預設 homeassistant/ 主題），當裝置發布符合格式的 discovery 訊息時，HA 自動建立對應的 entity，不必手動加入。
MQTT 整合也用 Birth Message（通知）與 Will（遺囑）協調自己和 broker 的狀態：
- Birth Message：整合一上線就發布一則「我在」訊息，讓其他訂閱者知道 HA 已連接。
- Will：整合會設定一組 will；若 HA 與 broker 異常斷線，broker 代 HA 送出一則「離線」通知。
- Status：這些訊息會落在 HA 的狀態主題（例如
homeassistant/status），別人（與 EMQX 規則）可據此判斷 HA 是在線或離線。
實務上「列出 HA 是否在線」常靠這個狀態主題。若要讓 EMQX 派一個規則處理 HA 離線通知，規則的 FROM 指向該事件源即可。
Zigbee2MQTT 與 Mosquitto 遷移
Zigbee2MQTT（Z2M）是把 Zigbee 裝置橋接成 MQTT 的常用整合。Woow EMQX add-on 是 host_network，Z2M 要連的 broker 位址通常是 homeassistant 或這台 add-on 的 slug（例如 a0d7b954-emqx），連接埠 1883，帳密用你在 EMQX 建立的帳號。
從 Mosquitto 遷移需先注意：Mosquitto 與 EMQX 無法同時運行（都會占用 1883）。做法概要：
- 停用你原本的 Mosquitto add-on，空出 1883。
- 將原 device／整合的 broker 指向 EMQX（
homeassistant、1883、EMQX 帳號）。 - 在 EMQX 建立同樣的 MQTT 使用者，並把保留訊息（retained）與 ACL 的設定也同步到 EMQX 端。
- 啟動 EMQX，確認 HA、Z2M 與外部裝置都連上。
Mosquitto 沒有圖形化介面、用戶端清單、規則引擎、WebSocket 內建；EMQX（Dashboard）這些都能提供，這些正是 EMQX 相對於 Mosquitto 的額外價值。
故障排除
- HA MQTT 整合無法連線：確認 EMQX 已啟動、Address 是
homeassistant或主機位址正確、連接埠 1883、並已在 EMQX 建立帳號（來源驗證）。 - discovery 沒有帶出裝置：檢查 discovery 前綴（homeassistant/）與
birth/will是否正常、裝置有無發布 discovery 訊息、HA 有沒有 Upgrade。 - 與 Mosquitto 同時運行失敗：兩個 broker 搶同一 1883。先停掉 Mosquitto（或把 EMQX 的 listener 改到別埠），再啟動另一邊。
- Z2M 無法連 EMQX：Z2M 的 broker host 要能用（
homeassistant或 add-on slug），也確認 z2m 用的是你在 EMQX 建的帳號，而非 Mosquitto 舊帳號。
常見問題
HA 一定要先有 MQTT broker 嗎
不。把 broker 改成 EMQX 後，HA 的 MQTT 整合只需指到 EMQX（homeassistant、1883、帳號密碼）。EMQX 就是新的 broker。
現在用 Mosquitto，遷移到 EMQX 很費時嗎
主要是「停 Mosquitto → EMQX 占 1883 → 把整合與 Z2M 指到 EMQX → 同步使用者與 ACL」。長期使用的 ACL／規則較繁瑣，可先小型遷移一種裝置。
discovery 前綴或狀態主題在哪設定
在 HA MQTT 進階設定中調整 discovery prefix 與 broker 狀態（birth/will）參數。預設 discovery 前綴是 homeassistant/，birth 與 will 主題可自行命名。
EMQX 與 Mosquitto 能並存嗎
不能同時用 1883（兩者都預設占 1883）。Woow EMQX 官方文件明列「無法與 Mosquitto 同時運行」；要換就換，或把其中一邊的 listener 換埠。