飞利浦 Hue 智能照明系统开发(Part 1 - API 入门)

Cat Chen 2018-05-14 15:21

Hue Bridge

我家里有超过 10 个的飞利浦 Hue 智能灯泡,我通常使用 Amazon Echo 和 iOS HomeKit 控制它们,例如说睡觉时对着 Echo 喊「Alexa, turn off bedroom.」,或者在 iPhone 上通过 Control Center 迅速开关一盏灯。在我买了一个 Raspberry Pi架设加密 DNS后,我就开始思考是否能在 Raspberry Pi 上跑一个程序控制 Hue 做更复杂的事情。在此之前,我先要自己搞明白 Hue 的 API 是如何工作的以及能做什么,于是我开始阅读Hue API 文档

Hue API 是很典型的 REST API,我们可以通过 bridge 上面的 HTTP 服务器调用 Hue API 操作这个 bridge 连接的所有灯泡。Hue API 可以操作的对象包括灯泡、房间、传感器、规则等等,不过在我们能够调用这些 API 之前,首先我们必须找到 bridge 的 IP,然后才能连上它的 HTTP 服务器。

寻找 Hue Bridge

大多数人家里的网络都是用 DHCP 动态分配 IP,因此我们不知道 Hue bridge 的 IP 是什么,就算知道了将来还可能变。我们要如何连接 bridge 呢?最简单的方法是发一个请求到这个地址:

https://www.meethue.com/api/nupnp

这是飞利浦自己的服务器,不是我们家里 bridge 的服务器。它会根据我们的公网 IP 来查询我们家是否有 bridge 通过同一个公网 IP 连接着飞利浦的服务器,如果有的话它就会返回这个(或这些)bridge 的信息,包括内网 IP。例如说:

[  {    "id": "001788fffe000999",    "internalipaddress": "10.0.0.9"  }]

这个 JSON 里面只有一个 bridge,这也是最常见的状况。(很少人会需要在家里装超过一个 bridge。)这一个 bridge 的 IP 是10.0.0.9,也就是internalipaddress属性的值。那id属性的值是什么呢?这是这个 bridge 的序列号,如果这个 bridge 的 IP 将来发生了变化,我们可以通过这个序列号来确认这是同一个 bridge。

在找到 bridge 的 IP 后,我们就可以连接上去了。我这里提到的只是最容易上手的 bridge 寻找办法,更复杂的方法可以看官方的Hue Bridge Discovery Guide

Hue Bridge 本地授权

能够连接到 bridge 的 IP 并不意味着能够操作 bridge,否则 bridge 就没有任何安全性可言了。任何新的客户端连接 bridge 之前,都需要有人去手动按一下 bridge 上面的物理按钮,然后新的客户端才能获取到授权。

首先,我们要按下 bridge 上的物理按钮,然后发送一个POST请求到这个地址:

http://<bridge_ip>/api

这个POST请求需要带上一个简单的 JSON:

{  "devicetype": "<app_name>#<device_name>"}

这个 JSON 只有一个叫做devicetype的属性,用来命名这个新增的客户端,格式为应用名称加上#再加上设备名称。(一个应用可以安装在多台设备上,这样的命名格式要求可以帮助区分。)官方文档说这个字符串长度不能超过 40 个字符,其中应用名称不超过 19 个字符,设备名称不超过 20 个字符。实际上当前的 API 版本(1.24.0)只检查字符串长度是否超过 40,不检查应用名称和设备名称是否超过允许长度。

这个请求成功的话,返回的 JSON 会是这样子的:

[  {    "success": {      "username": "83b7780291a6ceffbe0bd049104df"    }  }]

我们获取到了一个叫做username的东西,这实际上是个密钥一样的东西,因为只要掌握了它就能操作 bridge。我们需要把这个密钥保存下来,然后我们就可以进行其他任意操作了。

测试请求

拿到username后,我们当然要测试一下能不能用。Hue API 传输username这个密钥的方式很有趣,我们需要把它放在 URL 里面,例如这样子:

http://<bridge_ip>/api/<username>/config

发一个GET请求到这个地址,我们就能获得这个 bridge 的所有配置信息。成功获取信息意味着username是有效的密钥,之后我们就能用它来获取其他信息了。以下是一些可以尝试GET请求获取的地址:

http://<bridge_ip>/api/<username>/lightshttp://<bridge_ip>/api/<username>/groupshttp://<bridge_ip>/api/<username>/scheduleshttp://<bridge_ip>/api/<username>/sceneshttp://<bridge_ip>/api/<username>/sensorshttp://<bridge_ip>/api/<username>/ruleshttp://<bridge_ip>/api/<username>/resourcelinkshttp://<bridge_ip>/api/<username>/capabilities

总结

拥有上述知识后,我们就可以进一步探索 Hue API 了。为了方便方便我自己,我写了一个叫做Hue Explorer的开源项目用于连接我自己的 bridge 并查看上面的信息,如果你想要看源代码的话你可以到GitHub上查看。我暂时只做了一部分的 JSON 可视化,例如说灯可以可视化为这样子:

Hue Explorer v.0.2.0

如果你想要用第三方工具发送 REST 请求,可以试一下免费的Postman。如果你懒得下载,可以直接访问http://<bridge_ip>/debug/clip.html,这是一个每一个 bridge 都自带的调试工具,可以用来手工编写 REST 请求。

在下一篇文章里,我会开始讲述每一个具体的 Hue API 能做什么,不想错过的话欢迎通过邮件RSS/Atom订阅我的博客。

[返回] [原文链接]