2018年5月14日星期一

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

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>/lights
http://<bridge_ip>/api/<username>/groups
http://<bridge_ip>/api/<username>/schedules
http://<bridge_ip>/api/<username>/scenes
http://<bridge_ip>/api/<username>/sensors
http://<bridge_ip>/api/<username>/rules
http://<bridge_ip>/api/<username>/resourcelinks
http://<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 订阅我的博客。