Jci Hitachi Platform：把日立冷氣放進 Apple「家庭」App

家裡的燈、插座和感應器都已經在 Apple「家庭」App 裡，日立冷氣卻還得打開 AirCloud Home App 才能控制——如果你也是這樣，Jci Hitachi Platform 就是為這件事寫的。它是我維護的 Homebridge 外掛，用你的 AirCloud Home 帳號登入日立的雲端，把每台冷氣放進「家庭」App，可以用 Siri、場景和自動化控制，也支援凍結洗淨、快速運轉、濕度與空氣品質。

它怎麼連到冷氣

日立的 Wi-Fi 冷氣是透過 AirCloud Home 雲端控制的，所以這個外掛的做法和 App 一樣：在 Homebridge 上用你的帳號登入雲端，再把帳號裡的冷氣轉成 HomeKit 配件。你在「家庭」App 裡的每個操作，都會經由 Homebridge 和雲端送到冷氣。

「家庭」App 透過 Homebridge 與雲端控制冷氣。

反方向的同步也是即時的。雲端會透過 MQTT 把狀態變化推送到 Homebridge，所以用遙控器或 AirCloud Home App 調整之後，幾秒內就會反映在「家庭」App；外掛另外每 60 秒輪詢一次，作為推送之外的備援。

雲端偶爾會維護，網路也可能中斷。這時外掛會持續重試，間隔逐步拉長但有上限，等服務恢復就自己連回來，不需要重新啟動 Homebridge。

在「家庭」App 裡會看到什麼

每台冷氣在「家庭」App 裡是一個配件，外掛能控制的功能都收在裡面：冷氣本身的開關、模式、溫度與風速，三個感應器，以及用主帳號登入時才有的三個開關。

示意圖：一台冷氣包含的控制項與感應器。

模式、溫度與風速

模式：「家庭」App 可以設定自動、冷氣和暖氣。除濕與送風仍可用遙控器或 AirCloud Home App 切換，外掛會以最接近的 HomeKit 狀態顯示。
溫度：可調範圍取自機器本身的回報（常見是 16–32 °C），每次 1 度，所以「家庭」App 只會提供這台冷氣實際支援的溫度。
風速：對應到風速滑桿的七段，依序是自動、靜音、弱、中、強、急速、超急速。
目前是在製冷、製熱還是閒置，是比較室內溫度與目前模式的設定溫度推算出來的。

濕度與空氣品質

冷氣本身會回報室內的相對濕度和 PM2.5 讀數，外掛把它們做成濕度感應器與空氣品質感應器。空氣品質的等級由 PM2.5 數值換算，原始的 PM2.5 濃度也會一起提供。

Siri、場景與自動化

冷氣進了「家庭」App 之後，就和其他配件一樣：可以請 Siri 開冷氣、把它加進場景，或設定自動化，在到家前先讓臥室涼下來。

凍結洗淨，不用再記著

有凍結洗淨功能的日立冷氣，會讓熱交換器結霜再融化，把灰塵沖掉，並在該洗淨時提醒你。外掛把這個提醒做成「凍結洗淨通知」感應器：機器提示需要洗淨時它就會觸發，「家庭」App 便能通知你。HomeKit 沒有「需要清潔」這類專用的感應器類型，所以它在「家庭」App 裡是以漏水感應器的形式出現。

另外還有兩個開關：「凍結洗淨」可以手動開始洗淨，也會顯示洗淨是否正在進行；「快速運轉」則用來切換快速運轉。

自動凍結洗淨

1.5 版加入的「自動凍結洗淨」更進一步，連提醒都不必理會。打開某台冷氣的這個開關後，外掛會留意它什麼時候被關掉——不論是用「家庭」App、遙控器還是 AirCloud Home App——五分鐘後再檢查一次，條件都符合就自動開始洗淨。

自動凍結洗淨：關機五分鐘後，條件都成立才洗淨。

五分鐘內把冷氣再打開，或把「自動凍結洗淨」關掉，這次洗淨就會取消。每台冷氣有自己的開關，哪幾台要自動洗淨由你決定；開關狀態會各自保存，Homebridge 重新啟動後依然保留，不過重新啟動當下正在等待的那次洗淨不會接續執行。

外掛設定「進階」裡的 autoCleanWhenPowerOff 選項，決定這些開關第一次出現時是否開啟；之後就一律以「家庭」App 裡的開關為準。

主帳號限定：「快速運轉」、「凍結洗淨」和「自動凍結洗淨」這三個開關，只有 Homebridge 用冷氣的主帳號（擁有者）登入時才會建立。用分享帳號登入時不會出現，autoCleanWhenPowerOff 也不會生效，啟動時記錄裡會留下一則警告。

支援哪些裝置

在 AirCloud Home App 註冊的日立冷氣，單機與一對多都支援。帳號裡支援的冷氣會自動出現，不需要一台一台設定。
同一個帳號下的除濕機與空氣清淨機會出現在裝置清單，但還不會加入 HomeKit。
不支援 AirCloud Go：那是日立另一個 App，使用不同的雲端服務，只註冊在那裡的冷氣不會出現在這個外掛。

冷氣要先在 AirCloud Home App 裡註冊、能正常使用，外掛才看得到它。從帳號移除的裝置，會在 Homebridge 重新啟動後從「家庭」App 消失。

用主帳號還是分享帳號

我建議另外建立一個帳號給 Homebridge，再從主帳號把冷氣分享過去。過去同一個帳號在多個裝置上登入，常會有其中一邊被登出的情況，分開帳號比較穩定。代價是前面提到的三個開關只有主帳號才有：需要快速運轉和凍結洗淨的話，就讓外掛用主帳號登入；用不到的話，分享帳號是比較穩的選擇。

安裝與設定

需要 Homebridge 1.6 以上（支援 2.x），以及 Node.js 18、20、22 或 24。外掛已通過 Homebridge 官方驗證（Verified by Homebridge），在 Homebridge UI 裡就能完成安裝：

安裝外掛：在 Homebridge UI 開啟外掛頁面，搜尋 Jci Hitachi Platform 並安裝。
登入帳號：開啟外掛設定，輸入 AirCloud Home 的 Email 和密碼。裝置清單會列出帳號裡的每台冷氣；不想加入 HomeKit 的，勾選「略過」後按「儲存」。設定頁會記住登入權杖，之後再打開裝置清單不必重新登入。
重新啟動 Homebridge：冷氣會出現在「家庭」App，就在你原本使用的橋接器上。

不用 Homebridge UI 的話，也可以用 npm 手動安裝：

npm install -g homebridge-jci-hitachi-platform

習慣直接編輯 config.json 的話，設定長這樣：

{
  "platforms": [
    {
      "platform": "JciHitachi Platform",
      "name": "JciHitachi Platform",
      "email": "mail@example.com",
      "password": "********",
      "ignoredDevices": [],
      "autoCleanWhenPowerOff": false,
      "debugMode": false
    }
  ]
}

platform 保持原樣，name 會顯示在 Homebridge 記錄裡，email 和 password 是 AirCloud Home 的帳號密碼。ignoredDevices 是不想加入 HomeKit 的裝置 ThingName，用設定頁的裝置清單勾選最方便，改完記得重新啟動 Homebridge。完整的設定說明在 GitHub 的 README（英文）。

遇到問題時

在設定的「進階」裡開啟「除錯模式」，重新啟動外掛後，記錄裡會有更多資訊。若還是無法解決，歡迎到 GitHub 開 issue，並附上除錯資訊。
帳號密碼正確卻無法登入時，先用日立的 App 登入一次，確認已經同意最新的使用條款。
雲端維護期間，記錄裡會出現連線失敗的訊息；外掛會自動重試，服務恢復後自己連回來，不必重新啟動。
如果它影響到整個 Homebridge 的反應速度或穩定性，可以讓它在獨立的子橋接器（child bridge）裡執行。

這個外掛以 Apache-2.0 授權釋出。它的動機來自 qqaatw 的 LibJciHitachi，在釐清 API 的請求與回應格式時也幫了很大的忙，在此致謝。歡迎回報問題、檢視程式碼變更，或直接送 pull request。