霍姆布里奇色調

Philips Hue 的 Homebridge 插件

介紹

此 Homebridge 外掛程式向由 Signify 連接到 Hue 橋的 Apple HomeKit Hue 相容設備（燈、插頭、感測器、開關等）公開。

請注意，Hue 最初是由飛利浦開發的，之後他們將照明部門拆分為 Signify。 Signify 仍在使用 Philips Hue 品牌名稱。

請參閱 Wiki，以了解 Homebridge Hue 功能和支援的設備的列表，包括以下功能的比較：

gen-2（方形）Hue 橋的原生 HomeKit 功能；的
gen-2（方形）Hue 橋的原生 Matter 功能，連接到 HomeKit；的
Homebridge Hue 與 Hue 橋結合；和的
Homebridge deCONZ 與 deCONZ 閘道結合。

Homebridge Hue 會自動發現 Hue 橋。它支援一次安裝多個網橋。它支援 v2（方形）和 v1（圓形）Hue 橋。它與 v2 Hue 橋接器的本機 HomeKit 功能結合使用。

請參閱 Wiki 以了解 Homebridge Hue 的詳細說明。

先決條件

您需要一個飛利浦 Hue 橋來將 Homebridge Hue 連接到與 Hue 相容的燈、開關和感應器。我建議使用最新的 Hue 橋固件，帶有 API v1.61.0（v2 橋）或 v1.16.0（v1 橋）或更高版本。

您需要一台伺服器來運行 Homebridge。它可以是運行 Node.js 的任何東西：來自 Raspberry Pi、NAS 系統或運行 Linux、macOS 或 Windows 的始終在線的 PC。有關詳細信息，請參閱 Homebridge Wiki。我建議使用有線乙太網路連接運行 Homebridge、Hue 橋的伺服器和充當家庭集線器的 AppleTV。

要與 HomeKit 交互，您需要 iPhone、Apple Watch、iPad、iPod Touch 或 Apple TV（第 4 代或更高版本）上的 Siri 或 HomeKit App。我建議使用最新發布的 iOS、watchOS 和 tvOS 版本。
請注意，Siri 甚至 Apple 的 Home 應用程式仍然僅提供有限的 HomeKit 支援。要使用 Homebridge Hue 的完整功能，您可能需要查看其他一些 HomeKit 應用程序，例如 Eve 應用程式（免費）或 Matthias Hochgatterer 的 Home+ 應用程式（付費）。

由於 HomeKit 使用多播 DNS（又稱 Bonjour）來發現 Homebridge，因此執行 Homebridge 的伺服器必須與執行 HomeKit 的 iDevice 位於同一子網路中。對於遠端存取和 HomeKit 自動化（包括對無線開關的支援），您需要將 Apple TV（第四代或更高版本）或 HomePod 設定為家庭集線器。

命令列實用程式

Homebridge Hue 包含ph命令列實用程序，用於從命令列與 Hue API 進行互動。有關此實用程式的介紹，請參閱 Wiki 上的教學。

發出ph -h或ph --help以提供其功能和命令列參數的簡要概述。

安裝

要安裝 Homebridge Hue：

依照 Homebridge Wiki 上的說明安裝 Node.js 和 Homebridge；
透過 Homebridge Config UI X 或手動安裝 Homebridge Hue 外掛程式：
```
 $ sudo npm -g i homebridge-hue
```
編輯config.json ，新增Homebridge Hue提供的Hue平台，請參考配置；
首次運行 Homebridge Hue，按下（每個）橋上的連結按鈕。請注意日誌輸出中每個網橋的橋接器 ID/API 金鑰對。編輯config.json以包含這些內容，請參閱配置。
請注意，您無法透過 Homebridge Config UI X 中的 Homebridge Hue設定新增這些內容，但可以使用Homebridge Config Editor 。

要更新 Homebridge Hue，只需發出另一個sudo npm -gi homebridge-hue@latest 。請在更新 Homebridge Hue 之前查看發行說明。請注意，對次要版本的變更通常表示您需要檢查/重做 HomeKit 配置。由於 Hue 橋資源暴露方式的映射發生了變化，HomeKit 可能會將它們視為新的配件、服務和/或特性，從而丟失對 HomeKit 房間、場景、操作和觸發器的任何分配。若要還原到先前的版本，請在安裝 Homebridge Hue 時指定版本，如下所示： sudo npm -gi [email protected] 。

配置

在 Homebridge 的config.json中，您需要將 Homebridge Hue 指定為平台外掛程式。此外，您需要指定要向 HomeKit 公開的內容。請參閱 Wiki，以取得 Homebridge Hue 使用的config.json設定的完整參考以及一些範例。

要更細粒度地控制 Homebridge Hue 向 HomeKit 公開哪些資源以及如何在橋上建立資源鏈接，請參閱 Wiki。

故障排除

請查看常見問題。

檢查依賴關係

如果您遇到 Homebridge 啟動問題，請仔細檢查已安裝的 Node.js 和 Homebridge 版本。 Homebridge Hue 是使用最新的 LTS 版本的 Node.js 和最新版本的 Homebridge 進行開發和測試的。其他版本可能會或可能不會工作 - 我只是沒有足夠的頻寬來測試這些。

單獨運行 Homebridge Hue

如果您遇到 Homebridge 啟動問題，請執行單獨的 Homebridge 實例，並在config.json中僅啟用 Homebridge Hue （和 Homebridge Config UI X）。這樣，您就可以確定問題是否與 Homebridge Hue 本身有關，或與您的設定中多個 Homebridge 外掛程式的互動有關。您可以在不同的系統上、以不同的使用者身分或從不同的使用者目錄（由-U標誌指定）啟動這個單獨的 Homebridge 實例。確保在config.json中為每個實例使用不同的 Homebridge name 、 username和（如果在同一系統上執行） port 。

偵錯日誌文件

Homebridge Hue 為它設定的每個 HomeKit 特徵值以及它收到的每個 HomeKit 特徵值變更通知輸出一則訊息訊息。當 Homebridge 使用-D啟動時，Homebridge Hue 會針對向橋接器發出的每個請求、輪詢橋接器時偵測到的每個狀態變更以及從gen-2 Hue 橋接器事件流接收到的每個推播通知輸出一條調試訊息。此外，它還為其偵測到的每個網橋資源發出偵錯訊息。

若要將這些訊息捕獲到日誌檔案中，請執行以下操作：

如果您將 Homebridge 作為服務運行，請停止該服務；
手動運行 Homebridge，透過發出以下命令將輸出捕獲到檔案中：
```
 $ homebridge -CD 2>&1 | tee homebridge.log
```
透過裝置的本機應用程式和/或透過 HomeKit 與您的裝置互動以觸發問題；
點擊中斷（ctrl-C）停止 Homebridge；
如果您將 Homebridge 作為服務運行，請重新啟動服務；
透過發出以下命令來壓縮日誌檔案：
```
 $ gzip homebridge.log
```

調試轉儲文件

為了協助進行故障排除，Homebridge Hue 在啟動時會將其環境（包括其config.json設定和所有網橋的完整狀態）轉儲到壓縮的 json 檔案homebridge-hue.json.gz中。 IP 位址和橋接器 API 金鑰被封鎖。該檔案建立在 Homebridge 使用者目錄中，預設為~/.homebridge 。它可以透過 Homebridge Config UI X 使用者介面從插件標籤上的 Homebridge Hue SETTINGS彈出視窗下載。

尋求協助

如果您有疑問，請在 Discord 上的 Homebridge 社區#hue頻道上發布。

如果遇到問題，請在 GitHub 上提出問題。請將homebridge-hue.json.gz的副本附加到問題中，請參閱偵錯轉儲檔案。請將homebridge.log.gz的副本附加到問題中，請參閱偵錯日誌檔案。請不要複製/貼上大量日誌輸出。

貢獻

有時我會遇到這樣的問題：人們如何支援我在 Homebridge Hue 上的工作。我創建 Homebridge Hue 作為業餘愛好項目，供我自己使用。我在 GitHub 上分享它，以便其他人受益，並回饋開源社區，沒有他們，Homebridge Hue 就不可能實現。

話雖如此，如果沒有對設備的實體訪問，在 Homebridge Hue 中添加對新設備的支援是非常困難的。由於這是一個業餘愛好項目，我無法花錢購買我自己不會使用的設備，只是為了整合它們以造福他人。我很高興收到小額捐贈，以整合新設備的形式，或自己購買這些設備的資金。如果您提供運費，我也很樂意在之後退回設備。請透過電子郵件或透過 Discord 聯絡我以了解運送詳情。

注意事項

Homebridge Hue 是我的一個業餘愛好項目，按原樣提供，沒有任何保證。我已經在家裡成功運行了很多年，但你的里程可能會有所不同。

HomeKit 術語需要一些時間來適應。配件或多或少對應於實體設備，可透過 WiFi 或藍牙從 iOS 設備存取。橋接器（如 Homebridge）是一種配件，可提供對其他橋接附件的存取。一個配件可能提供多種服務。每個服務對應一個虛擬設備（如燈泡、開關、運動感應器…，還有：可編程開關按鈕、配件資訊、電池狀態）。 Siri 與服務交互，而不是與配件交互。一項服務包含一個或多個特徵。特徵就像服務屬性，可以由 HomeKit 應用程式讀取或寫入。您可能想查看 Apple 的 HomeKit Accessory Simulator，它是作為Xcode的附加工具分發的。

在內部，HomeKit 透過 UUID 識別配件。對於 Zigbee 設備（燈、感應器、開關），Homebridge Hue 將此 UUID 基於 Zigbee mac 位址。對於非 Zigbee 資源（群組、調度、CLIP 感測器），UUID 是基於網橋 ID 和資源路徑（例如/sensors/1 ）。透過不使用資源名稱（例如Daylight ），Homebridge Hue 可以處理重複的名稱。此外，在橋接器上的資源名稱變更後，HomeKit 仍會辨識該配件，記住它所屬的 HomeKit 房間、群組、場景、操作和觸發器。但是，當非Zigbee網橋資源被刪除然後重新創建，導致資源路徑不同時，HomeKit會將其視為新配件，您將需要重新配置HomeKit。

展開

附加信息