Home Assistant 开发指南

前言

Home Assistant（以下 HA） 是一款智能家居管理系统的开源库。

如果想要使用 HA 一般有两种方式：

• 在虚拟机安装 Hassio - HA 提供的内置相关功能的磁盘映像（可以参考：https://bbs.hassbian.com/thread-8119-1-1.html），这种方法的优点在于非常简单，很快就可以开启一个 HA 的服务器，然后就可以在浏览器访问了，而且 HA 也提供了大量供用户自定义的选项。
• 另外一种就是下载 HA Core 源码，自己组装相关组件（如：Frontend），这种的方式则是为了实现更完全的自定义，如：修改左侧导航栏的标题。

官方文档：

• 环境配置
• frontend 配置

运行

环境：Debian + VSCode

备注：建议在 Linux 下运行，Windows 请按照官方文档安装配置 WSL（Windows Subsystem for Linux）

core+frontend

core 也即 ha 的核，是核心部分，frontend 是 core 可以装载的一个零件。在组装任何零件之前，首先需要把 core 跑起来。

1. 下载源码

• clone 源码到本地 core & frontend

• 安装 VSCode for Linux 与 Docker

• 安装 nvm（nodejs 版本管理工具）

2. 安装依赖

• 运行以下指令安装 Python 及相关组件：

sudo apt-get install python3-pip python3-dev python3-venv autoconf libssl-dev libxml2-dev libxslt1-dev libjpeg-dev libffi-dev libudev-dev zlib1g-dev pkg-config libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libavresample-dev libavfilter-dev ffmpeg

• 提前在 VSCode 中，安装 Docker，Remote - Container 插件。
• 使用 VSCode 打开 core 文件夹，VSCode 自动弹窗，点击确认“在 Container 中打开”。
  

如果提示用户不在 docker 的用户组内，可参考将当前用户添加到 docker 用户组，如果还是不行，重启一下电脑即可。

3. 组装 frontend

组装 frontend 其实就是在已经打开的 core 中配置 frontend 源码的路径，告诉 core 可以在哪里找到零件。

• 在之前打开的 core 的容器中找到 .devcontainer/devcontainer.json，添加一个配置项，装载 frontend。

  "mounts": [
    "source=XXX/frontend,target=/workspaces/frontend,type=bind,consistency=cached"
  ],

其中 XXX/frontend 需要替换成您的 frontend 文件夹的路径（必须使用绝对路径，且需要注意 docker 无法自动识别 ~，要用完整的路径）；
后面的 target 就是我们装载后 frontend 所在的路径（/workspaces/frontend）。

• 找到 config/configuration.yaml，告诉 core 零件的位置（使用上一步中 target 的路径即可）。

# Configure a default setup of Home Assistant (frontend, api, etc)
default_config:

frontend:
  # Example absolute path: /home/paulus/dev/hass/frontend
  development_repo: /workspaces/frontend/

注意！！！frontend 缩进与 default_config 对齐，否则无法装载 frontend，且不会报错！！！！

4. 配置 nodejs

• 在 frontend 文件夹下打开终端。
• 安装 nodejs：运行 nvm install 安装合适版本的 nodejs。（frontend 还是使用的 nodejs，所以需要安装使用 nodejs）
• 启用 nodejs：运行 nvm use
• 安装 yarn (脚本需要用，而且 yarn 与 npm 绑定，使用 nvm 安装了新的 nodejs 后，需要重新安装 yarn)：运行npm install -g yarn
• 安装 bootstrap 依赖：运行 sh script/bootstrap

5. 运行

• 直接在 VSCode 容器内打开 core 文件夹下的终端（注意不能直接在系统终端运行，会出现找不到虚拟环境的问题）
• (first time) 创建虚拟环境，一键配置项目：sh script/setup
• 激活虚拟环境：source venv/bin/activate
• 开启 HA：hass -c config
• 在浏览器中打开本地服务器页面。
  

frontend develop

下载 frontend 源码后，可以看到代码结构与 Vue 如出一辙。直接大刀阔斧地改就好了。

开发指南

开发的时候如果希望自己的修改能够实时显示在浏览器中，就需要运行一个动态编译的 frontend 包。
具体步骤如下：

• 使用 VSCode 在 frontend 文件夹下，打开 container（与 core 一致）

  需要注意的是，由于frontend 的容器与 core 存在冲突，打开 frontend 容器时需要先关闭 core 的容器，否则会报错。

• 在 VSCode 中使用 Ctrl+Shift+P 打开指令面板，Tasks: Run Task -> Develop Frontend 即可开启动态编译。
  
  等待 10 mins 左右（期间出现的一些告警信息可以不用理会）提示打包成功，此后将自动检测代码的改变。

• 回到 core，仍然是开启容器，执行 hass -c config，运行 HA，然后按照官方文档的方法，关闭浏览器的缓存等，即可享受代码变更的实时显示。

1. Disable cache by ticking the box in Network > Disable cache
   
2. Enable Bypass for network in Application > Service Workers > Bypass for network
   

• 通过源码的修改，可以实现例如：修改导航栏标题。
  
• 最终打包 frontend 需要使用 gulp build-app --max_old_space_size=4096 其中 4096 为限制使用的内存大小，单位为 MB。

直接使用 sh script/build_frontend 会出现栈溢出的错误。
注意 gulp 内置在 container，需要开启容器后才能使用。

HA 连接小米网关

本项目使用的是小米 Aquara 网关 M1S。
具体步骤如下：

• 下载米家 APP，注册登录后，添加设备，搜索 Aquara M1S 之类的，点击搜索结果，进入连接网关的流程

  这个地方需要注意，米家直接搜索不一定能够找到我们的网关，这时就需要搜索相应的型号，然后再让米家去找设备。

• 然后回到 HA，在主界面依次找到：配置 -> 集成 -> 添加集成
  
  注意选择上图标记出来的集成，实测 Aqara 集成无法正常使用。
• 在后续的窗口中，登录米家云服务，即可连接自己的网关。
  
  使用登录米家 APP 的帐号和密码登录即可。
• 保持网关与相应设备在同一个局域网下，网关将自动发现这些设备，并同步给 HA。
  

结语

在一些问题上花费了太多时间，结果只是很小的问题把人卡住了。之后有问题还是应该去相关论坛多多请教。

如果也有孤军奋战的小伙伴，有什么问题可以在评论区留言，或许本人可以提供些许帮助。

---

TroubleShooting 持续更新中。