在Ubuntu上从零开始编译并运行Home Assistant源码并集成HACS与小米开源的Ha Xiaomi Home

目录

  • [1. 前言&&叠甲](#1. 前言&&叠甲)
  • [2. 使用的环境](#2. 使用的环境)
  • [3. 相关链接](#3. 相关链接)
  • [4. 前期步骤](#4. 前期步骤)
    • [4.1 安装路径提前说明](#4.1 安装路径提前说明)
    • [4.2 Ubuntu 相关依赖安装](#4.2 Ubuntu 相关依赖安装)
    • [4.3 Python源码编译安装](#4.3 Python源码编译安装)
      • [4.3.1 编译安装](#4.3.1 编译安装)
      • [4.3.2 换源](#4.3.2 换源)
      • [4.3.3 环境变量](#4.3.3 环境变量)
  • [5. 构建Home Assistant源码](#5. 构建Home Assistant源码)
    • [5.1 clone源码](#5.1 clone源码)
    • [5.2 创建虚拟Python环境](#5.2 创建虚拟Python环境)
    • [5.3 安装项目依赖](#5.3 安装项目依赖)
    • [5.4 安装项目](#5.4 安装项目)
    • [5.5 运行项目](#5.5 运行项目)
    • [5.6 查看配置文件夹](#5.6 查看配置文件夹)
    • [5.7 补充相关](#5.7 补充相关)
  • [6. 访问Home Assistant](#6. 访问Home Assistant)
    • [6.1 首次运行创建用户](#6.1 首次运行创建用户)
    • [6.2 选择家的位置](#6.2 选择家的位置)
    • [6.3 进入首页](#6.3 进入首页)
  • [7. 安装HACS](#7. 安装HACS)
    • [7.1 下载HACS包](#7.1 下载HACS包)
    • [7.2 将hacs放置对应位置](#7.2 将hacs放置对应位置)
    • [7.3 添加HACS](#7.3 添加HACS)
    • [7.4 HACS绑定GitHub](#7.4 HACS绑定GitHub)
  • [8. 安装小米的Ha Xiaomi Home](#8. 安装小米的Ha Xiaomi Home)
    • [8.1 三种安装方式](#8.1 三种安装方式)
      • [8.1.1 源码构建形式](#8.1.1 源码构建形式)
      • [8.1.2 单独文件形式](#8.1.2 单独文件形式)
      • [8.1.3 使用HACS安装Ha Xiaomi Home](#8.1.3 使用HACS安装Ha Xiaomi Home)
    • [8.2 重启后添加Ha Xiaomi Home到Home Assistant](#8.2 重启后添加Ha Xiaomi Home到Home Assistant)
      • [8.2.1 账号授权认证和地址回调](#8.2.1 账号授权认证和地址回调)
  • [9. 总结](#9. 总结)

1. 前言&&叠甲

本文章为全文皆慢慢敲的文字,本人非专业人士,难免存在遗漏和错误,请指出即可。若有更好方案,欢迎提出。

为什么会写这篇文章?因为搜索了一段时候,发现很少有介绍从零开始编译Home Assistant源码的教程和视频,大多是使用docker或者使用Nas,定制化/可修改程度不高?

同时由于官方的方案仅剩下为数不多的几个,主要是基于HA OS(也就是做成了镜像系统),或者是Container。一个是镜像封装了,不方便自定义和使用系统,另一个是不太利于没有Docker环境。本篇想在裸机系统上部署,并且随时能切换Git版本从而随时升级,故写此篇。

2. 使用的环境

操作系统版本:Ubuntu-Desktop 24.04.2 LTS。

Home Assistant版本:2025.7.1,但是是GitHub的最新dev构建。但是由于是源码部署,所以可以随时升级。

Python版本:3.13.5,源码构建。否则可能会影响Ubuntu内置的3.12。2025.7版本的Home Assistant需要Python3.13。

3. 相关链接

本篇编写时候的相关安装包/软件的链接如下,可以参考换成最新的

https://releases.ubuntu.com/24.04/ubuntu-24.04.2-desktop-amd64.iso

https://www.python.org/ftp/python/3.13.5/Python-3.13.5.tgz

相关GitHub仓库链接如下

https://github.com/home-assistant/core

https://github.com/hacs/integration

https://github.com/XiaoMi/ha_xiaomi_home

4. 前期步骤

4.1 安装路径提前说明

为方便使用,本篇安装都位于~/HomeAssistant-All/目录下,包括Python、Home Assistant。

4.2 Ubuntu 相关依赖安装

bash 复制代码
# 更新
sudo apt update

# 安装Home Assistant需要的依赖,和其他一些常用的工具。但不包括Nginx、Python等
sudo apt install -y autoconf automake avahi-daemon bluez build-essential ca-certificates curl ffmpeg gdebi git gnupg gnupg2 htop libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libbz2-dev libcap2-bin libffi-dev libgdbm-compat-dev libgdbm-dev libglib2.0-dev libjpeg-dev liblzma-dev libncursesw5-dev libnss3-dev libopenjp2-7-dev libpython3-dev libreadline-dev libsqlite3-dev libssl-dev libswscale-dev libtiff5-dev libtool libturbojpeg0-dev libudev-dev libxml2-dev libxmlsec1-dev libxslt1-dev libyaml-dev lrzsz lsb-release lsof neofetch net-tools openssh-server p7zip-full rar rsync software-properties-common tk-dev tmux tree unrar unzip uuid-dev vim wget xz-utils zip zlib1g-dev

以上依赖安装较为缓慢。由于下载的Ubuntu镜像默认使用的是清华的安装源,所以在网络上还是没有问题的。若不是,请自行换源。出现如下表明安装完成。

4.3 Python源码编译安装

4.3.1 编译安装

为了防止干扰Ubuntu自带的Python版本,此处Python仅在安装文件夹中进行。若本机已经有Python3.13的环境,直接跳过至构建Home Assistant源码即可。

将下载的Python源码包Python-3.13.5.tgz解压到~/HomeAssistant-All/,进入该目录cd Python-3.13.5/

然后开始编译Python。

bash 复制代码
# 位于 ~/HomeAssistant-All/Python-3.13.5/
sudo ./configure --enable-optimizations
sudo make -j$(nproc)
sudo make altinstall

由于Python源码编译较慢,若机器配置较低可能需要数分钟至十数分钟。安装完成后为如下。

安装完毕后,可以执行

bash 复制代码
~/HomeAssistant-All/Python-3.13.5/python

看到如下则表明Python安装成功,可以使用Ctrl+D退出。

4.3.2 换源

bash 复制代码
mkdir -p ~/.pip
vim ~/.pip/pip.conf

在里面输入如下,即使用清华源。

bash 复制代码
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
timeout = 10
trusted-host = pypi.tuna.tsinghua.edu.cn

4.3.3 环境变量

此处环境变量不与系统的冲突,做到输入命令python313方可运行。

bash 复制代码
vim ~/.bashrc
bash 复制代码
# 然后划到最后,输入
export PATH="$HOME/HomeAssistant-All/Python-3.13.5/bin:$PATH"
alias python313='python3.13'
alias pip313='pip3.13'
bash 复制代码
# 生效环境变量
source ~/.bashrc

新开终端,输入python313即可正常使用Python3.13.5。

5. 构建Home Assistant源码

5.1 clone源码

将源码clone到本地~/HomeAssistant-All/home-assistant-core/文件夹

bash 复制代码
git clone https://github.com/home-assistant/core.git home-assistant-core

进入该文件夹,cd home-assistant-core

默认的clone下来的,可能是dev分支,dev分支push比较活跃,不清楚有没有bug。可以使用如下命令查看和切换成稳定的master分支,或者是其他分支。

bash 复制代码
# 查看当前分支
git branch

# 本地没有master分支,从远程拉取
git checkout -b master origin/master

# 若本地有master分支,则切换到本地的master分支
git checkout master

# 更新分支代码
git pull

5.2 创建虚拟Python环境

直接覆盖原本Python安装的环境,可能会带来依赖冲突。所以创建一个虚拟的Python环境,所有依赖都安装到这个环境中,不会出现依赖问题。若因为某些原因环境出问题了,只需要删除虚拟环境再建即可。

此处使用Python虚拟环境,名为venv313

bash 复制代码
# 创建虚拟环境
python313 -m venv venv313
# 激活环境
source venv313/bin/activate
bash 复制代码
# 更新相关软件包
pip install --upgrade pip setuptools wheel

5.3 安装项目依赖

bash 复制代码
pip install -r requirements_all.txt

为什么使用requirements_all而不是requirements_test,是因为all能安装所有依赖。test只有部分依赖,若运行中代码走到没有安装的依赖,则会默认安装,走的是pip的默认源,可能因为网络问题无法下载,导致运行报错。

安装all的项目依赖会耗时较长时间,可能为十数分钟。安装完成后如下显示

5.4 安装项目

bash 复制代码
pip install -e .

5.5 运行项目

直接运行命令

bash 复制代码
hass

即可启动项目。默认第一次运行,会在如图的~/.homeassistant/文件夹下创建配置文件。出现下图即说明已经成功在运行了。

使用http://ip:8123可直接访问。

5.6 查看配置文件夹

bash 复制代码
cd ~/.homeassistant/

运行如上命令,即可进入Home Assistant的配置文件夹。可以修改端口号等信息,此处不再赘述。

5.7 补充相关

本篇全篇运行于基于VMware的Ubuntu中。若也有相同的,建议对VMware配置做网络上的桥接,方便手机连接。

6. 访问Home Assistant

浏览器访问http://ip:8123即可访问。

6.1 首次运行创建用户

点击创建我的智能家居,输入用户名和密码即可创建。

输入相关信息后,点击创建账户,我这边没有任何反应,然后去看运行日志,发现有报错。

bash 复制代码
KeyError: 'component.onboarding.area.living_room'

不知道是版本问题,还是什么问题。但是不影响使用。用户已经创建,此处需要重启应用。即使用Ctrl + C停止运行,再使用hass运行,再刷新网页即可。

6.2 选择家的位置

登录后,出现要选择家的位置。可以在输入框中输入中文的城市名称。

这个地图有时候需要特殊网络才能搜索。但是不影响选择。可以缩放地图后,拖动地图定位的标点,来选择到自己所在的城市。

6.3 进入首页

无脑下一步后,即可进入首页,如图

那么,至此为止,初级的Home Assistant部署运行完成。

下面将介绍如何添加HACS、如何添加小米的Ha Xiaomi Home(两者可独立安装,也可以Ha Xiaomi Home通过HACS安装)。

7. 安装HACS

HACS官方的GitHub链接:https://github.com/hacs/integration/releases

此处使用官方构建的HACS的release安装到Home Assistant中。

7.1 下载HACS包

打开https://github.com/hacs/integration/releases,下载最新版的hacs.zip文件。

7.2 将hacs放置对应位置

进入到Home Assistant的配置文件夹~/.homeassistant/

bash 复制代码
cd ~/.homeassistant/

在该文件夹位置新建一个名为custom_components的文件夹。

进入该custom_components的文件夹,将hacs.zip文件解压到这个文件夹中,保留最外层的文件夹,如图。

7.3 添加HACS

完成后,重启Home Assistant应用,进入路径设置-设备与服务

点击右下角添加集成按钮,搜索hacs,可以看到一个右侧有橙色方块的栏目(代表"自定义集成"),选择后点击提交

7.4 HACS绑定GitHub

提交完成后,需要点击转圈的下方的链接,进行GitHub的授权。同时下方小字有8个字符的配对码,需要复制粘贴至GitHub进行授权方可使用。

然后点击Authorize hacs即可完成,如图结果出现即可关闭该页面。

完成后如图所示界面,可以看到侧边有HACS的入口了。

点击HACS,可以看到有较多可下载的扩展组件。

如果出现如图的报错,could_not_register则请排查,Home Assistant主机是否无法访问GitHub。

至此,HACS集成进Home Assistant已完成。

8. 安装小米的Ha Xiaomi Home

小米在2024年底开源了自家的Home Assistant的组件,GitHub链接:https://github.com/XiaoMi/ha_xiaomi_home。至此可以很方便地将米家生态接入到Home Assistant

8.1 三种安装方式

Ha Xiaomi Home官方介绍了3种接入方式,分别是源码、HACS、单独文件形式。此篇都将介绍。

这三种方法都是将Ha Xiaomi Home的代码文件复制到指定位置(~/.homeassistant/custom_components/)后,重启Home Assistant应用,从而可以在添加集成的地方搜索并添加小米的Home Assistant集成,并设置账号信息。

所以三种方法均写至复制完成,提示重启为止。重启之后的操作将在后面一小节的添加Ha Xiaomi Home到Home Assistant中有写。

8.1.1 源码构建形式

源码形式的话,可以将源码clone至本地任何位置,但请

不要同时

  1. 将源码clone至~/.homeassistant/custom_components/
  2. 将clone的文件夹命名为xiaomi_home
  • 否则在构建的时候,将会出现覆盖性问题。可以适当修改文件名。

此处将源码clone至~/.homeassistant/xiaomi_home_git/,使用如下命令即可。

bash 复制代码
cd ~/.homeassistant/
clone https://github.com/XiaoMi/ha_xiaomi_home.git xiaomi_home_git

clone完毕后,进入目录

bash 复制代码
cd xiaomi_home_git/

运行构建命令,将构建产物复制到~/.homeassistant/custom_components/

bash 复制代码
# 给install.sh运行权限。当然也可以自行设置更小的权限。
chmod +x install.sh
# 将构建产物复制到~/.homeassistant/custom_components/。其中,custom_components路径不要手动添加,因为在install.sh脚本中已经自带该路径,若添加了则会变成~/.homeassistant/custom_components/custom_components/xiaomi_home/从而无法识别。
./install.sh ~/.homeassistant/

运行后出现如下提示,即成功:Xiaomi Home installation is completed. Please restart Home Assistant.。根据提示重启Home Assistant即可。

一至三的方法(选其一)添加完毕后,都需要重启Home Assistant。重启后,需要将Ha Xiaomi Home集成到Home Assistant并添加账号。

后续更新Ha Xiaomi Home的方式,在Ha Xiaomi Home的Git目录运行命令即可。

bash 复制代码
# 更新至最新的代码
git pull
# 构建并复制最新产物
./install.sh ~/.homeassistant/
# 完成后重启Home Assistant

8.1.2 单独文件形式

打开https://github.com/XiaoMi/ha_xiaomi_home/releases链接,下载最新的xiaomi_home.zip的压缩包。

进入到Home Assistant的配置文件夹~/.homeassistant/,在该文件夹位置新建一个名为custom_components的文件夹(如果已有,或者在上面HACS中有操作,则不必新建)。

进入该custom_components的文件夹,将hacs.zip文件解压到这个文件夹中,保留最外层的文件夹,如图。将压缩包解压到该文件。

至此,Ha Xiaomi Home已经添加到Home Assistant。现在需要重启Home Assistant方可使用。下面介绍如何使用HACS来添加。

一至三的方法(选其一)添加完毕后,都需要重启Home Assistant。重启后,需要将Ha Xiaomi Home集成到Home Assistant并添加账号。

8.1.3 使用HACS安装Ha Xiaomi Home

点击HACS栏目,搜索栏中输入Ha Xiaomi Home,看到stars数较多的即是官方的集成。

点击进入后,点击右下角的download,将会自动下载到本地。但是该方法如果在网络不佳的时候将会无法下载。此时建议使用上一种方式。

安装完成后,点击HACS选项卡,可以看到Xiaomi Home在列表中,并且是Pending restart,这时候重启Home Assistant即可。

一至三的方法(选其一)添加完毕后,都需要重启Home Assistant。重启后,需要将Ha Xiaomi Home集成到Home Assistant并添加账号。

8.2 重启后添加Ha Xiaomi Home到Home Assistant

不论是直接文件复制形式,还是HACS添加,完成后需要集成进Home Assistant。重启Home Assistant应用,进入路径设置-设备与服务

点击右下角添加集成按钮,使用英文搜索xiaomi,可以看到其中一个右侧有橙色方块的栏目(代表"自定义集成"),选择该有橙色的栏目后点击,按照说明一步步即可。


8.2.1 账号授权认证和地址回调

一步步进行后,在拉起小米账号登录前,有一个步骤,这里需要点击蓝字的请点击此处进行登录才能拉起小米的账号授权。

确认授权后,将会跳转到一个新的页面,网址的格式为:http://homeassistant.local:8123/api/webhook/1261686089886280620?code=xxxxxxxxxxxxxxxx

显然,这个网页是无法访问的。可以看到访问的域名是homeassistant.local,这个域名是不存在的,ping该域名也没有ip的解析。这个域名猜测是在做HAOS或者container的时候,写入到系统的hosts指向的本地地址。

有两种解决办法,最简单的就是,手动将访问的域名前缀homeassistant.local:8123修改为目前访问的ip:8123,然后回车访问即可。或者可以在本机的hosts文件中,手动配置指向Home Assistant的ip的条目。

这里使用直接修改ip访问。回车访问后,这个页面稍等几秒即变成空白页,或者被关闭。然后手动打开刚刚的授权页面,稍等几秒即可看到已经成功授权了。然后只要勾选要导入的设备即可。

需要等待一段时间添加完毕后即可使用。添加完成后,可以在概览处看到原本在米家中的设备。

9. 总结

至此,在Ubuntu上从零开始编译并运行Home Assistant源码并集成HACS与小米开源的Ha Xiaomi Home的讲述完毕。

本篇为了不使用官方的镜像,不使用Container,直接裸Ubuntu系统部署并运行Home Assistant,为的是能够有更好的安装空间。现在太多教程在教如何使用各家Nas来安装Home Assistant,对于没有Nas的人比较不友好。使用Docker来安装的则对没有容器化部署的不友好。故写本篇。

相关推荐
Deng94520131428 分钟前
基于Python的旅游数据可视化应用
python·numpy·pandas·旅游·数据可视化技术
2401_8786247930 分钟前
pytorch 自动微分
人工智能·pytorch·python·机器学习
胖达不服输33 分钟前
「日拱一码」021 机器学习——特征工程
人工智能·python·机器学习·特征工程
screenCui2 小时前
macOS运行python程序遇libiomp5.dylib库冲突错误解决方案
开发语言·python·macos
小眼睛羊羊2 小时前
pyinstaller打包paddleocr
python
java1234_小锋2 小时前
基于Python的旅游推荐协同过滤算法系统(去哪儿网数据分析及可视化(Django+echarts))
python·数据分析·旅游
蓝婷儿2 小时前
Python 机器学习核心入门与实战进阶 Day 4 - 支持向量机(SVM)原理与分类实战
python·机器学习·支持向量机
%d%d22 小时前
python 在运行时没有加载修改后的版本
java·服务器·python
amazinging3 小时前
北京-4年功能测试2年空窗-报培训班学测开-第四十七天
python·学习·selenium
Freak嵌入式3 小时前
一文速通 Python 并行计算:13 Python 异步编程-基本概念与事件循环和回调机制
开发语言·python·嵌入式·协程·硬件·异步编程