home assistant开发环境

一、概述

搭建home assistant core开发环境，开发自己的集成组件，记录基于windows中的vs code ssh远程连接Ubuntu 22进行开发的过程（容器下载依赖需要很长时间所以没有采用容器方式）。

二、开发环境

环境搭建参考官方文档手动环境

1、安装核心依赖项

sudo apt-get update
#因为后续可能用python版本要求，所以这里先不安装python，后续通过pyenv安装
sudo apt-get install  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 libswresample-dev libavfilter-dev ffmpeg libgammu-dev build-essential

2、安装配置pyenv

#1.安装 pyenv 依赖（编译 Python 需要的系统库）
# Ubuntu/Debian
sudo apt update
sudo apt install -y build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

# CentOS/RHEL
sudo yum install -y gcc openssl-devel bzip2-devel libffi-devel \
readline-devel sqlite-devel tk-devel xz-devel zlib-devel

#2.安装 pyenv
curl https://pyenv.run | bash

#3.配置 pyenv
#将以下内容添加到~/.bashrc（bash 用户）或~/.zshrc（zsh 用户）
# 配置 pyenv 国内镜像（清华源）
export PYTHON_BUILD_MIRROR_URL_SKIP_CHECKSUM=1
export PYTHON_BUILD_MIRROR_URL="https://mirrors.tuna.tsinghua.edu.cn/python/"
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

#4.生效配置：
source ~/.bashrc  # 或 source ~/.zshrc

3、安装配置python

# 查看可安装的版本（确认3.13.2存在）
pyenv install --list | grep 3.13.2
# 安装3.13.2（编译过程可能需要5-10分钟）
pyenv install 3.13.2

#设置python版本
# 全局生效（所有终端默认使用3.13.2）
pyenv global 3.13.2
# 或仅当前项目生效（进入项目目录执行）
pyenv local 3.13.2

#验证环境
python --version  # 应输出 Python 3.13.2

4、配置pip

#设置国内源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

#验证
pip config list

5、配置uv

#uv设置国内镜像源
#在用户目录下创建 uv.toml 文件（路径参考）：
#Linux/macOS: ~/.config/uv/uv.toml
#Windows: %APPDATA%\uv\uv.toml
[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
default = true
# 或使用阿里源
# url = "https://mirrors.aliyun.com/pypi/simple/"

6、安装运行HA

#如果没有git,就安装以下
git clone https://github.com/home-assistant/core.git
#进入项目根目录
#授权脚本
chmod 755 script/setup script/bootstrap
#执行脚本
script/setup

#脚本会创建python虚拟环境.venv,每次启动新的终端会话时，都需要激活虚拟环境：
source .venv/bin/activate

#运行 （默认端口 8123）
hass -c config

三、集成开发

1、创建集成

参考官方文档，创建第一个集成。数据获取方式iot-class 文档

#注意激活虚拟环境(shell前置会有环境名称)
python3 -m script.scaffold integration
#脚手架交互配置如下
#1.What is the domain?：集成唯一标识（小写，如 ezviz_camera）

#2.What is the name of your integration?：集成显示名称（如 EZVIZ Camera）。

#3.What is your GitHub handle?：github账号名称。(如 @vectorluo)

#4.What PyPI package and version do you depend on? Leave blank for none 所需的依赖包。

#5.How will your integration gather data? 数据获取方式 （如 local_polling）
#assumed_state：无法获取设备状态，根据上一条命令来推测设备状态
#cloud_polling：云端轮询获取通信信息。
#cloud_push：云端推送消息。
#local_polling：本地轮询获取通信信息。
#local_push：提供与设备的直接通信。
#calculated：该集成本身并不处理通信，而是提供计算结果。

#后续基本直接回车

2、调整集成

集成文件结构，以下是涉及调整的文件及内容

manifest.json:清单文件描述了集成及其依赖项

__init__.py :组件文件

修改_PLATFORMS，集成的设备，如Platform.LIGHT，需要创建对应的集成设备文件，如果没有则设置为空数组

修改 type New_NameConfigEntry = ConfigEntry[MyApi] # noqa: F821 为 type EzvizConfigEntry = ConfigEntry

config_flow.py:流程配置文件

修改class ConfigFlow(ConfigFlow, domain=DOMAIN) 为 class ExampleConfigFlow(ConfigFlow, domain=DOMAIN)，ExampleConfigFlow为自定义的流程配置类名称。PlaceholderHub该类为简单临时的业务逻辑处理类。