Xiaomi Home Integration for Home Assistant开发者指南：贡献代码与改进建议

你是否在为Xiaomi Home设备接入Home Assistant时遇到兼容性问题？是否希望为开源社区贡献力量但不知从何入手？本文将系统讲解贡献代码的完整流程、核心模块开发规范、测试策略及最佳实践，帮助你高效参与项目改进。读完本文，你将能够：- 搭建标准化的开发环境- 遵循项目架构规范开发新功能- 提交符合要求的Pull Request- 参与设备支持与协议优化## 开发环境搭建...

陶羚耘Ruby

823人浏览 · 2025-09-08 18:58:37

陶羚耘Ruby · 2025-09-08 18:58:37 发布

Xiaomi Home Integration for Home Assistant开发者指南：贡献代码与改进建议

【免费下载链接】ha_xiaomi_home Xiaomi Home Integration for Home Assistant 项目地址: https://gitcode.com/gh_mirrors/ha/ha_xiaomi_home

你是否在为Xiaomi Home设备接入Home Assistant时遇到兼容性问题？是否希望为开源社区贡献力量但不知从何入手？本文将系统讲解贡献代码的完整流程、核心模块开发规范、测试策略及最佳实践，帮助你高效参与项目改进。读完本文，你将能够：

搭建标准化的开发环境
遵循项目架构规范开发新功能
提交符合要求的Pull Request
参与设备支持与协议优化

开发环境搭建

基础环境配置

开发Xiaomi Home集成需要以下环境依赖，建议使用Python虚拟环境隔离项目依赖：

# 克隆代码仓库
git clone https://gitcode.com/gh_mirrors/ha/ha_xiaomi_home.git
cd ha_xiaomi_home

# 创建并激活虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt
pip install pylint pytest  # 代码检查与测试工具

项目要求Python版本≥3.9，Home Assistant核心版本≥2024.4.4（从hacs.json获取的最低支持版本）。开发前需确保本地Home Assistant实例已安装并运行，以便测试集成功能。

开发工具链

推荐使用以下工具提高开发效率：

代码编辑器：VS Code（安装Python、Pylance、Home Assistant扩展）
代码检查：pylint（使用项目根目录的.pylintrc配置）
调试工具：Home Assistant集成调试器、miot_client.py测试脚本
文档生成：markdownlint（确保文档格式规范）

VS Code配置示例（.vscode/settings.json）：

{
  "python.linting.pylintEnabled": true,
  "python.linting.pylintArgs": ["--rcfile", ".pylintrc"],
  "python.formatting.provider": "black",
  "editor.formatOnSave": true
}

项目架构解析

核心模块结构

Xiaomi Home集成采用模块化架构设计，主要包含以下组件：

mermaid

各模块功能说明：

custom_components/xiaomi_home：集成核心目录，包含设备类型实现
- miot/：MIoT协议处理核心，包含局域网通信(miot_lan.py)、云服务(miot_cloud.py)等
- binary_sensor.py/light.py/switch.py：各设备类型的Home Assistant实体实现
test/：单元测试目录，包含协议解析、设备通信等测试用例
doc/：文档目录，包含中文说明与示例图片

数据流架构

设备数据通过以下流程在系统中流转：

mermaid

关键数据处理流程：

设备通过MIoT协议（局域网或云端）发送状态更新
miot_client.py接收并解析协议数据
MIoTDevice类维护设备状态
各实体类（如Light、Switch）将状态同步至Home Assistant

代码贡献流程

分支管理策略

项目采用Git Flow工作流，分支命名规范如下：

分支类型	命名格式	说明
主分支	main	稳定版本，仅通过PR合并
开发分支	dev	开发版本，包含最新功能
功能分支	feature/[issue-id]-[brief]	新功能开发，如feature/123-light-dimming
修复分支	fix/[issue-id]-[brief]	问题修复，如fix/456-connection-timeout
发布分支	release/vX.Y.Z	版本发布准备

创建功能分支示例：

git checkout dev
git pull origin dev
git checkout -b feature/789-add-humidifier

代码开发规范

命名规范

严格遵循项目命名约定，确保代码一致性：

# 正确示例：小米设备命名规范
def handle_miot_device(miot_device: MIoTDevice) -> None:
    """处理MIoT设备通信"""
    miot_device.async_set_prop(2, 1, True)  # 正确使用miot作为变量前缀

# 错误示例：命名不规范
def xm_dev_ctrl(device):  # 使用缩写而非完整单词
    device.set(2,1,True)  # 缺少类型注解和文档字符串

核心命名规则：

Xiaomi相关：类名用"Xiaomi"，变量用"xiaomi"或"mi"
MIoT协议：类名用"MIoT"，变量用"miot"
Home Assistant：变量用"hass"或"hass_xxx"
中文与英文之间需有空格（如"处理 MIoT 消息"而非"处理MIoT消息"）

代码风格

项目遵循Google Python风格指南，关键要求：

使用4个空格缩进，不使用Tab
每行代码不超过88个字符
函数和类定义之间空两行
导入顺序：标准库 → 第三方库 → 项目内部导入

使用pylint检查代码风格：

pylint custom_components/xiaomi_home/miot/miot_client.py

提交规范

提交信息需遵循以下格式：

<type>: <subject>

<body>

<footer>

类型(type)说明：

feat: 新功能
fix: 错误修复
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
perf: 性能优化
test: 测试相关
chore: 构建/依赖管理

示例提交：

feat: 添加加湿器设备支持

- 实现MIoT加湿器协议解析
- 添加Humidifier实体类
- 支持湿度调节和模式切换

Closes #123

核心模块开发指南

设备实体开发

为新设备类型创建实体时，需继承相应的Home Assistant实体类并实现MIoT属性映射。以加湿器为例：

# custom_components/xiaomi_home/humidifier.py
from homeassistant.components.humidifier import (
    HumidifierEntity,
    HumidifierEntityFeature,
)
from .miot_device import MIoTDevice, MIoTEntityData

class XiaomiHumidifier(MIoTBaseEntity, HumidifierEntity):
    def __init__(self, miot_device: MIoTDevice, entity_data: MIoTEntityData):
        super().__init__(miot_device, entity_data)
        self._attr_supported_features = (
            HumidifierEntityFeature.MODES | HumidifierEntityFeature.TARGET_HUMIDITY
        )
        self._attr_available_modes = ["auto", "silent", "high"]

    @property
    def target_humidity(self) -> int:
        """返回目标湿度"""
        return self.get_prop_value(self._entity_data.get_property("target_humidity"))

    async def async_set_humidity(self, humidity: int) -> None:
        """设置目标湿度"""
        await self.set_property_async(
            self._entity_data.get_property("target_humidity"), humidity
        )

    @property
    def mode(self) -> str:
        """返回当前模式"""
        mode_value = self.get_prop_value(self._entity_data.get_property("mode"))
        return self._attr_available_modes[mode_value]

关键开发步骤：

确定设备的MIoT服务ID(SIID)和属性ID(PIID)，可参考MIoT规范文档
创建实体类继承MIoTBaseEntity和对应设备类型的Home Assistant实体类
实现属性getter方法（如target_humidity）和操作方法（如async_set_humidity）
在__init__.py中注册实体

MIoT协议扩展

如需支持新的MIoT设备协议特性，需扩展协议解析模块：

# custom_components/xiaomi_home/miot/miot_spec.py
class MIoTSpecProperty:
    def __init__(self, spec: dict, service: 'MIoTSpecService'):
        self.siid = spec.get('siid')
        self.piid = spec.get('piid')
        self.type = spec.get('format')
        # 添加新的属性解析逻辑
        self.support_color = spec.get('value-range', {}).get('color', False)
        
    def parse_value(self, raw_value: Any) -> Any:
        """解析原始值为Home Assistant可识别的格式"""
        if self.type == 'bool':
            return bool(raw_value)
        # 添加颜色属性解析
        if self.support_color:
            return self._parse_color(raw_value)
        return raw_value
        
    def _parse_color(self, value: int) -> tuple[int, int, int]:
        """将整数颜色值解析为RGB元组"""
        r = (value >> 16) & 0xFF
        g = (value >> 8) & 0xFF
        b = value & 0xFF
        return (r, g, b)

协议扩展注意事项：

所有协议解析需兼容miot_spec.py中的缓存机制
新增设备类型需更新specs/目录下的设备规格定义
涉及多语言支持时，需更新miot/i18n/目录下的翻译文件

测试策略

单元测试开发

为确保代码质量，所有新功能必须包含单元测试。测试文件应放在test/目录，命名格式为test_[module].py。

设备属性测试示例：

# test/test_miot_device.py
import pytest
from custom_components.xiaomi_home.miot.miot_device import MIoTDevice

@pytest.fixture
def mock_miot_device():
    """创建模拟MIoT设备"""
    device = MIoTDevice(
        miot_client=None,
        device_info={'did': 'test_device', 'model': 'zhimi.humidifier.v1'},
        spec_instance=mock_spec_instance
    )
    return device

@pytest.mark.asyncio
async def test_humidity_property(mock_miot_device):
    """测试湿度属性获取与设置"""
    # 模拟属性获取
    mock_miot_device.set_prop_value(2, 1, 45)  # SIID=2, PIID=1 (湿度)
    assert mock_miot_device.get_prop_value(2, 1) == 45
    
    # 测试属性设置
    result = await mock_miot_device.async_set_prop(2, 1, 50)
    assert result is True

集成测试

集成测试验证整个系统流程，需在真实Home Assistant环境中运行：

将开发目录链接到Home Assistant配置：

ln -s /path/to/ha_xiaomi_home/custom_components/xiaomi_home \
  ~/.homeassistant/custom_components/xiaomi_home

配置日志以调试：

# configuration.yaml
logger:
  default: critical
  logs:
    custom_components.xiaomi_home: debug

重启Home Assistant并监控日志：

tail -f ~/.homeassistant/home-assistant.log | grep xiaomi_home

Pull Request提交

PR准备清单

提交PR前确保完成以下检查：

代码遵循项目风格指南（通过pylint检查）
添加/更新相关测试用例
更新文档（如README.md或doc/CONTRIBUTING_zh.md）
所有测试通过
提交信息符合规范
仅包含相关更改（无多余文件或格式化修改）

PR模板填写

PR描述需包含以下内容：

问题描述：解决的issue或实现的功能
实现方案：核心思路和实现方式
测试步骤：如何验证功能正确性
截图/日志：必要的测试证据

示例PR描述：

## 功能描述
实现小米空气净化器的PM2.5数值显示

## 实现细节
- 添加PM2.5传感器实体（sensor.py）
- 解析MIoT协议中SIID=3, PIID=6的属性
- 添加数值单位转换（从0.1μg/m³到μg/m³）

## 测试步骤
1. 配置小米空气净化器
2. 观察Home Assistant中PM2.5传感器数值
3. 验证数值变化范围（0-500）

## 相关文档
更新了README.md中的支持设备列表

代码审查响应

PR提交后，项目维护者将进行代码审查。请：

及时响应审查意见
保持沟通友好
按要求修改代码
不要在一个PR中解决多个不相关问题

高级贡献方向

设备支持扩展

为新设备添加支持的流程：

获取设备MIoT规格：

使用MIoT设备数据库查询设备型号
或通过miot_spec.py获取设备规格：

from custom_components.xiaomi_home.miot.miot_spec import MIoTSpecParser
parser = MIoTSpecParser()
spec = parser.parse("urn:miot-spec-v2:device:airpurifier:0000A007:zhimi-v3:1")

创建设备实体类：参考现有设备（如humidifier.py）实现对应实体
添加翻译支持：更新translations/目录下的对应语言文件
提交设备支持PR，包含设备型号、规格和测试结果

性能优化

性能优化可关注以下方向：

协议解析缓存：优化miot_spec.py中的规格缓存机制
批量属性获取：改进miot_client.py中的属性获取逻辑，减少网络请求
连接池管理：优化miot_lan.py中的TCP连接复用

优化效果评估指标：

设备状态更新延迟（目标<500ms）
网络请求数量（目标：每设备每分钟<10次）
内存占用（目标：每设备<5MB）

常见问题解决

设备连接问题

设备通信失败的排查步骤：

检查网络环境：

# 测试局域网连接
from custom_components.xiaomi_home.miot.miot_lan import MIoTLan
lan = MIoTLan()
await lan.init_async()
devices = await lan.get_dev_list_async()
print(f"发现设备: {devices}")

验证设备令牌(token)：
- 通过小米家庭安全令牌提取工具获取设备token
- 检查token是否正确存储在配置中
查看协议调试日志：
- 启用miot协议调试日志
- 检查设备通信包内容

兼容性问题

处理不同设备固件版本差异：

# 处理设备固件兼容性
def get_target_temperature_prop(device_model: str, firmware_version: str) -> tuple[int, int]:
    """根据设备型号和固件版本返回温度属性ID"""
    if device_model == "zhimi.aircondition.v1":
        if firmware_version >= "2.0.0":
            return (3, 5)  # 新版固件属性
        else:
            return (2, 4)  # 旧版固件属性
    return (2, 1)  # 默认属性