mi-home-assistant

mi-home-assistant

1. 簡介

大家好！今天來聊聊一個讓智慧家庭愛好者相當振奮的專案：小米官方 Home Assistant 整合 (ha_xiaomi_home)。此專案由小米官方開發與維護，旨在為 Home Assistant 使用者提供更流暢、更可靠的 Xiaomi IoT 裝置控制體驗。

過去雖然市面上有一些第三方小米裝置整合方案，但或多或少存在問題，例如裝置狀態回應延遲等。如今有了官方支援，我們可以期待更好的效能與更強的安全性。

Home Assistant 是一個開源的家庭自動化平台，以強大的相容性與靈活性著稱，深受 DIY 愛好者喜愛。如今小米這個智慧家庭領域的巨頭也加入了 Home Assistant 生態系，無疑是一件令人期待的事。

主要功能：

  • 官方支援： 由小米官方開發與維護，提供更好的穩定性與相容性。
  • Home Assistant 整合： 允許使用者在 Home Assistant 中控制和管理小米智慧裝置。
  • 增強的使用者體驗： 旨在提供更快的裝置狀態回應，解決第三方整合存在的延遲問題。
  • 廣泛的裝置支援： 支援大多數小米 IoT 裝置，但藍牙、紅外線和虛擬裝置除外。
  • 多帳戶與區域支援： 支援多個小米帳戶，且可將不同區域的裝置加入同一個 Home Assistant 區域。

2. 核心功能

  • 多種安裝方式： 支援多種安裝方式，包括 Git 複製、HACS 和手動安裝。官方推薦使用 Git 複製，因為方便進行版本管理和更新。
    • Git 複製安裝：cd config; git clone https://github.com/XiaoMi/ha_xiaomi_home.git; cd ha_xiaomi_home; ./install.sh /config。
  • OAuth 2.0 登入： 採用 OAuth 2.0 登入方式，不直接在 Home Assistant 中儲存使用者密碼，提高安全性。
  • 雲端控制與本機控制： 主要透過小米雲進行控制。對於支援本機控制的裝置，可透過小米閘道器或區域網路進行控制。
    • 雲端控制：透過小米雲伺服器進行通訊和控制。
    • 本機控制：透過小米中央閘道器或區域網路 (LAN) 直接在本機網路中通訊，但本機控制並非在所有地區都可用。
      • 中央閘道器：僅在中國大陸地區可用。
      • 區域網路控制：適用於所有地區，但僅限 IP 裝置，且為實驗性功能，不推薦使用。
  • 裝置訊息訂閱機制： 使用訊息訂閱機制，當裝置屬性變化或事件發生時，會即時推送訊息到 Home Assistant，減少對雲端的輪詢壓力。
  • MIoT-Spec-V2 映射： 使用小米 IoT 協定 MIoT-Spec-V2 將裝置、服務、屬性、事件和動作映射到 Home Assistant 的實體 (entity) 中，確保裝置功能正常運作。

3. 使用技巧

  • 多帳戶管理： 完成一個小米帳戶的登入和設定後，可透過「新增 HUB」來加入其他小米帳戶。
  • 區域選擇： 匯入小米裝置時，請務必選擇正確的區域，因為不同區域的資料是隔離的。
  • 除錯模式： 啟用動作 (action) 的除錯模式可以手動發送帶參數的動作命令。
  • 實體轉換規則更新： 如果您修改了 specv2entity.py、spec_filter.json 或 multi_lang.json 檔案，您需要在整合的設定頁面中更新實體轉換規則，以使變更生效。
  • 自訂過濾： 使用 spec_filter.json 檔案來過濾不需要轉換到 Home Assistant 的 MIoT-Spec-V2 實例。
  • 本地化： multi_lang.json 檔案用於提供裝置名稱和其他文字元素的本地化翻譯，且優先順序高於雲端翻譯。

4. 應用案例

  • 智慧照明控制： 透過 Home Assistant 控制小米智慧燈泡的亮度、顏色和開關狀態。
  • 智慧安防： 結合小米智慧攝影機和感測器，實現家庭安防自動化，例如當偵測到異常移動時發送警報。
  • 環境監測： 使用小米溫溼度感測器，即時監測室內環境，並根據溫度自動調節空調或暖氣。
  • 自動化場景： 利用 Home Assistant 的自動化功能，設定各種場景，例如「回家模式」、「離家模式」等，實現智慧家庭的自動化控制。

5. 安全顧慮

雖然小米官方整合使用了 OAuth 2.0 登入方式，提高了安全性，但仍然存在一些安全風險：

  • 明文儲存使用者資料： 使用者的裝置資訊、憑證和權杖等敏感資訊會以明文形式儲存在 Home Assistant 的設定檔中。這意味著如果設定檔洩漏，他人可能會存取您的 Xiaomi 裝置。
  • 保護設定檔： 您需要確保 Home Assistant 設定檔妥善保管，防止洩漏。
  • 撤銷授權： 如果懷疑 OAuth 權杖洩漏，可以透過小米 Home App 撤銷登入授權。

因此，務必妥善保管您的 Home Assistant 設定檔，防止洩漏！

6. 常見問題

  • 哪些裝置不支援？
    • 目前不支援藍牙裝置、紅外線裝置和虛擬裝置。
  • 如何新增多個小米帳戶？
    • 在已設定的小米 Home 整合頁面中，點擊「新增 HUB」可以新增其他小米帳戶。
  • 本機控制在所有地區都可用嗎？
    • 本機控制透過中央閘道器僅在中國大陸可用，而區域網路控制適用於所有地區，但僅限 IP 裝置，且不推薦使用。
  • 為什麼官方推薦 Git 複製安裝？
    • Git 複製方便進行版本切換和更新，更易於管理。
  • 如何更新整合？
    • 可以透過 Git 複製切換到指定版本，或使用 HACS 進行更新。
  • 如何使用自訂設定？
    • 可以編輯 spec_filter.json 和 multi_lang.json 檔案來進行過濾和翻譯，並更新實體轉換規則。