homebridge hue
v0.14.7
版权所有 © 2016-2024 埃里克·巴乌。版权所有。
此 Homebridge 插件向由 Signify 连接到 Hue 桥的 Apple HomeKit Hue 兼容设备（灯、插头、传感器、开关等）公开。
请注意，Hue 最初是由飞利浦开发的，之后他们将照明部门拆分为 Signify。 Signify 仍在使用 Philips Hue 品牌名称。
请参阅 Wiki，了解 Homebridge Hue 功能和支持的设备的列表，包括以下功能的比较：
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 启动问题，请运行单独的 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 -CD 2>&1 | tee homebridge.log
$ 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。
