Awaken your home.
前言
Home Assistant是一个隐私优先的智慧家庭系统，支持本地化部署，甚至允许在没有断网的情况下使用。
我是Home Assistant的铁杆粉，用它构建了一些好玩的东西，正打算基于它创建一些更有想象力的项目。
近期基本读完了Home Assistant所有的文档，喜欢它的架构设计。在架构上，codelab-adapter和它有许多相似之处。
Home Assistant的核心源码此前也大体上读了一遍，代码写得非常漂亮，堪称Python Asyncio的典范案例。
Home Assistant近期发布了0.94版本, 为1.0版本做好了准备，预计今年发布1.0版本。
考虑到项目已经基本上稳定下来，API不会再有大的变动。于是我近期准备重新审视一遍Home Assistant，在源码和架构层面对其做一些解读和梳理。
本文焦点
将硬件接入Home Assistant有许多种方式。正如大多数物联网项目一样，接入一款硬件是很容易的。MQTT这类的基础协议提供了充分的自由度。
但我们要知道此类系统往往会随着业务而发展，不断生长，如果没有精心设计的架构，很容易被后期的复杂度压垮。在操作系统的发展史上，太多这样的先烈了。
Home Assistant已经展示出其架构的高度灵活性(至今已经接入了1400+设备)，也许有望成为物联网领域的linux。
往系统中硬编码接入一款硬件总是容易的，但随着系统的生长，这种生态十分容易溃败。所以本文关注Home Assistant社区是如何考虑设备接入这件事的，如何应对组件增长带来的复杂度升高。
我们将分析Home Assistant接入Yeelight彩光灯泡的细节，以此为例，对系统做深入了解。
本文将通过实验来跟踪通信的细节。
Yeelight彩光灯泡搭载了wifi芯片。为了将其接入WiFi，你需要使用官方APP来为它配网。
由于我们准备用Home Assistant控制它，所以需要在APP中做些设置，使其接受来自局域网的控制指令。
实验
实验环境
- MacOS 10.13.5
- Python 3.7.2
- homeassistant==0.94.2
运行 homeassistant
我在虚拟环境里安装homeassistant，为了不与系统中的homeassistant冲突，我选择在当前的虚拟python环境下运行homeassistant: python -m homeassistant
配置目录
第一次运行，会创建配置目录
Config directory: /Users/wuwenjie/.homeassistant
目录内容为:
1
2
3
|
➜ ~ ls /Users/wuwenjie/.homeassistant
automations.yaml customize.yaml groups.yaml home-assistant_v2.db secrets.yaml
configuration.yaml deps home-assistant.log scripts.yaml tts
|
从命名可以看出configuration.yaml是配置文件。
值得一提的是，如果你采用hass.io安装homeassistant，那么你永远不需要在命令行里进入配置目录，可以直接在网页上编辑，这对非技术用户很友好。
由于防火墙的存在，在国内安装hass.io非常痛苦，由于防火墙的存在，技术/科研人员的日常大多时候都是痛苦的。
fuck the GFW.
其他依赖
运行python -m homeassistant的时候，还将安装其他依赖，一些值得留意的依赖包括netdisco==2.6.0.
将灯泡信息添加到configuration.yaml
重启时，发现安装了yeelight==0.5.0。
在Yeelight APP找到Yeelight彩光灯泡的IP地址，将其配置到configuration.yaml
1
2
3
4
|
yeelight:
devices:
192.168.31.30:
name: test light
|
重启home-assistant服务，即可看到灯泡已经出现在用户面板里。控制开关和调节色温一切正常。
开始分析
在接下来的分析里，我们关注
- 彩灯设备的发现和加载
- 控制指令如何生效(通信细节)
意外发现
Yeelight是home-assistant支持的components之一，home-assistant目前支持1400+设备。
技术层面，components的代码见components。在探索如何接入新的components时，意外发现Integration Services已经完美解决了我们前头提到的home-assistant如何接入新设备的问题。
但我们仍然准备继续分析，深入到代码层面的细节。
分析工具
我使用sourcegraph的chrome插件来阅读和跟踪源码，这个工具让我们在代码森林中穿梭变得自如。
程序入口
从setup.py中可以看到程序的入口点: hass = homeassistant.__main__:main
其中ensure_config_file值得关注，这个函数的指责是确保配置文件的正常。如果不存在配置文件则帮助我们创建所需的配置文件(默认),后文提及的configuration.yaml就是由它创建的，如果你对初始化的配置文件感兴趣，从它入手可能是个好主意。更多细节:
此外，try_to_restart的机制怪有趣的，home-assistant是生产级的代码，很多细节考虑得非常周到，很有借鉴价值。
彩灯设备的发现和加载
我们进入到前头提到的分析目标之一:彩灯设备的发现和加载
在components/yeelight/init.py中发现了Integration Services文档描述的内容:def setup(hass, config), 由此可知官方默认支持的components，与用户临时接入的组件，都遵循同一套接入机制。系统的同构性有利于健壮性和灵活性。
还记得我们在configuration.yaml做的设置吗？
1
2
3
4
|
yeelight:
devices:
192.168.31.30:
name: test light
|
这个设置是如何被源码使用的呢？在def setup(hass, config)中看得很清楚:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
|
def setup(hass, config):
"""Set up the Yeelight bulbs."""
conf = config.get(DOMAIN, {})
yeelight_data = hass.data[DATA_YEELIGHT] = {}
def device_discovered(service, info):
_LOGGER.debug("Adding autodetected %s", info['hostname'])
device_type = info['device_type']
name = "yeelight_%s_%s" % (device_type,
info['properties']['mac'])
ipaddr = info[CONF_HOST]
device_config = DEVICE_SCHEMA({
CONF_NAME: name,
CONF_MODEL: device_type
})
_setup_device(hass, config, ipaddr, device_config)
discovery.listen(hass, SERVICE_YEELIGHT, device_discovered)
def update(event):
for device in list(yeelight_data.values()):
device.update()
track_time_interval(
hass, update, conf.get(CONF_SCAN_INTERVAL, SCAN_INTERVAL)
)
if DOMAIN in config:
for ipaddr, device_config in conf[CONF_DEVICES].items():
_LOGGER.debug("Adding configured %s", device_config[CONF_NAME])
_setup_device(hass, config, ipaddr, device_config)
return True
|
彩灯设备的发现和加载机制，这段代码已经很清晰展示了。
def setup(hass, config)中的细节(如track_time_interval)值得深入学习，留待之后有空进一步追踪。
控制指令如何生效(通信细节)
为了理解控制指令如何生效，我们可以跟踪用户操作过程中发生的交互。
从控制台可以看出开关等过程中并不发生http(ajax)交互，于是可以断定是使用websocket交互。
通过观察过程中发生的交互，我们可以使用其他客户端来模拟。下边使用Pharo来替代网页，与Yeelight进行交互。
1
2
3
4
5
6
7
8
9
10
|
webSocket := ZnWebSocket to: <URI>.
[ webSocket
sendMessage: '{"type":"auth","access_token":"<access_token>"}'.] value.
[ (webSocket
readMessage) logCr ] schedule.
[ webSocket
sendMessage: '{"type":"call_service","domain":"light","service":"turn_on","service_data":{"entity_id":"light.test_light"},"id":27}'.] value.
|
让我们进一步跟踪websocket消息是如何生效的。
追踪代码可以发现websocket_api竟是作为components在homeassistant中运行！homeassistant的同构性太惊人了，我非常喜欢这种高度一致的设计。
我们前头发送了开灯命令:
1
2
3
4
5
6
7
|
{
"type": "call_service",
"domain": "light",
"service": "turn_on",
"service_data": { "entity_id": "light.test_light" },
"id": 27
}
|
handle这份命令的代码为:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
|
@decorators.async_response
@decorators.websocket_command({
vol.Required('type'): 'call_service',
vol.Required('domain'): str,
vol.Required('service'): str,
vol.Optional('service_data'): dict
})
async def handle_call_service(hass, connection, msg):
"""Handle call service command.
Async friendly.
"""
blocking = True
if (msg['domain'] == HASS_DOMAIN and
msg['service'] in ['restart', 'stop']):
blocking = False
try:
await hass.services.async_call(
msg['domain'], msg['service'], msg.get('service_data'), blocking,
connection.context(msg))
connection.send_message(messages.result_message(msg['id']))
except ServiceNotFound as err:
if err.domain == msg['domain'] and err.service == msg['service']:
connection.send_message(messages.error_message(
msg['id'], const.ERR_NOT_FOUND, 'Service not found.'))
else:
connection.send_message(messages.error_message(
msg['id'], const.ERR_HOME_ASSISTANT_ERROR, str(err)))
except HomeAssistantError as err:
connection.logger.exception(err)
connection.send_message(messages.error_message(
msg['id'], const.ERR_HOME_ASSISTANT_ERROR, str(err)))
except Exception as err: # pylint: disable=broad-except
connection.logger.exception(err)
connection.send_message(messages.error_message(
msg['id'], const.ERR_UNKNOWN_ERROR, str(err)))
|
至此我们弄清楚了本文感兴趣的所有问题。
todo
参考
