go-xiaomihome 项目介绍

项目概述

go-xiaomihome 是小米智能家居 Home Assistant 集成（ha_xiaomi_home）的 Golang 移植版。

将原 Python 版核心 miot 包完整移植为 Go 版本，保持 API 语义与行为严格对齐，目标是提供一个高性能、可独立使用的小米 IoT（MIoT）核心 SDK。

Python 原版：ha_xiaomi_home/custom_components/xiaomi_home/miot/
Go 移植版：go-xiaomihome/miot/

---

核心目标

• 严格对齐：Go 版 miot 包与 Python 版功能严格对齐，行为一致
• 独立可用：移植后的 miot 包可作为独立 SDK 被任何 Go 项目引用
• 高性能：利用 Go 的并发优势，提升设备发现、消息订阅等场景的性能
• 易维护：保留 Python 版的文件/模块结构，对应关系清晰

---

架构概览

go-xiaomihome/
├── go.mod                  # Go 模块定义 (module: xiaomihome)
├── go.sum
├── README.md               # (待完善)
└── miot/                   # 核心 MIoT SDK (与 Python miot/ 严格对齐)
    ├── miot_client.go       # 主客户端 (设备管理和协调核心)
    ├── miot_client_api.go   # 外部 API 接口
    ├── miot_client_device.go # 设备管理方法
    ├── miot_client_prop.go  # 属性刷新管理
    ├── miot_client_sub.go   # 订阅管理 (MQTT/mDNS/LAN)
    ├── miot_cloud.go        # 云服务 HTTP API 客户端 + OAuth
    ├── miot_device.go       # 设备模型 (MIoTDevice)
    ├── miot_error.go        # 错误码定义
    ├── miot_storage.go      # 本地存储 (cert/dict/device data)
    ├── miot_lan.go          # LAN 局域网控制 (UDP 9588)
    ├── miot_mdns.go         # mDNS 服务发现 (MIPS)
    ├── miot_network.go      # 网络状态监控
    ├── mips_client.go       # MIPS MQTT 客户端 (云端+本地)
    ├── spec_parser.go       # MIoT SPEC 解析器 (设备能力描述)
    ├── miot_i18n.go        # 国际化 (i18n/)
    ├── miot_matcher.go      # 订阅匹配器 (Matcher)
    ├── common.go            # 工具函数
    ├── const.go             # 常量定义
    ├── web_pages.go         # OAuth 重定向页面
    ├── examples/            # 使用示例 (9个)
    ├── i18n/               # 多语言 JSON 文件 (12种语言)
    ├── specs/               # SPEC 解析配套文件
    ├── lan/                 # LAN 控制配套文件
    ├── migration/           # 移植文档 (13个模块详细对照)
    └── *_test.go            # 单元测试

---

核心模块说明

1. MIoTClient (miot_client.go)

主客户端，管理所有子模块，是整个 SDK 的入口。

核心职责：

• 设备管理（云端/网关/本地三路合并）
• 定时器管理（Token 刷新、证书刷新、属性刷新）
• 订阅协调（云端 MQTT / 本地 MIPS / LAN）
• 回调通知（persistenceNotify）

对齐 Python：miot_client.py MIoTClient 类

---

2. MIoTHttpClient + MIoTOauthClient (miot_cloud.go)

小米云服务的 HTTP API 客户端，包含 OAuth2 授权流程。

核心功能：

• MIoTHttpClient：封装所有 REST API 调用（设备列表、属性读写、SSEC 加密等）
• MIoTOauthClient：OAuth2 授权码流程（生成授权 URL、轮询 token、刷新 token）
• SSEC 服务端加密（AES-128-CBC）

对齐 Python：miot_cloud.py MIoTHttpClient + MIoTOauthClient

---

3. MIoTDevice (miot_device.go)

设备模型，描述单个小米设备的完整状态。

核心字段：

• 设备元数据（did/model/name/online 等）
• SPEC 实例（MIoTSpecService 树）
• 属性/事件/Action 的读写缓存
• LAN 控制相关（token/io 端口/宏定义）

对齐 Python：miot_device.py MIoTDevice 类

---

4. MIoTSpecParser (spec_parser.go)

解析小米 IoT SPEC 描述文件，构建设备能力模型。

核心功能：

• 从云端或本地加载 SPEC 标准库（14 天缓存）
• 解析 JSON 格式 SPEC，生成 MIoTSpecService / MIoTSpecProperty / MIoTSpecEvent / MIoTSpecAction 树
• 支持多语言（从 i18n/ 加载）

对齐 Python：miot_spec.py MIoTSpecParser

---

5. MIoTLan (miot_lan.go)

局域网控制，通过 UDP 9588 端口与设备直接通信。

核心功能：

• 设备发现（广播 {"dev": "1234"}）
• 属性读取（get_prop）
• 属性写入（set_prop / enable_prop）
• Action 调用（action）
• 事件订阅（通过 MIoTMatcher）

对齐 Python：miot_lan.py MIoTLan

---

6. MipsClient (mips_client.go)

MIPS（小米智能平台服务）的 MQTT 客户端，支持云端和本地两种模式。

核心功能：

• MipsCloudClient：连接小米云端 MQTT Broker
• MipsLocalClient：连接本地网关 MQTT Broker
• 设备状态订阅/发布
• 自动重连

对齐 Python：miot_mips.py MipsCloudClient + MipsLocalClient

---

7. MIoTStorage (miot_storage.go)

本地存储管理，处理证书、设备字典、SPEC 等文件的读写。

存储内容：

• cert/：MQTT 证书（PEM 格式）
• miot_devices/：设备字典（.dict 文件）
• miot_specs/：SPEC 标准库（.dict 文件）
• logs/：日志文件

对齐 Python：miot_storage.py MIoTStorage

---

8. MIoTMdns (miot_mdns.go)

mDNS 服务发现，用于发现本地网络中的 MIPS 网关。

核心功能：

• 监听 _miot_mips._tcp.local. 服务记录
• 解析 SRV/TXT 记录，提取 group_id/IP/port
• 服务状态变化回调

对齐 Python：miot_mdns.py MipsService

---

9. 其他模块

模块	文件	功能
错误码	miot_error.go	定义 MIoTErrorCode 枚举和 MIoTError 结构体
常量	const.go	OAuth URL、平台列表、不支持型号等常量
网络监控	miot_network.go	网卡状态监控、ping 检测
国际化	miot_i18n.go	多语言翻译，加载 i18n/*.json
Matcher	miot_matcher.go	属性/事件订阅的快速匹配器
工具函数	common.go	CalcGroupID、LoadJSONFile、Slugify 等

---

移植进度

根据 MIGRATION_PLAN.md，移植工作分四批完成：

批次	优先级	模块数	状态
第一批	P0 基础架构	7	✅ 完成
第二批	P1 高级功能	3	✅ 完成
第三批	P2 LAN 控制	2	✅ 完成
第四批	P3 附加功能	2	✅ 完成

总计：14/14 全部完成

详细审核结果见各批次 BATCH*_REVIEW.md 和 ROUND*_REVIEW.md。

---

依赖项

// go.mod
require (
    github.com/eclipse/paho.mqtt.golang v1.5.1  // MQTT 客户端
    github.com/hashicorp/mdns v1.0.7              // mDNS 服务发现
    gopkg.in/yaml.v3 v3.0.1                      // YAML 解析
)

---

使用示例

miot/examples/ 下提供了 9 个独立可运行示例：

示例	路径	功能
完整客户端	examples/full_client/	演示完整 MIoTClient 使用流程
云端设备	examples/cloud_devices/	从云端获取设备列表
OAuth 授权	examples/cloud_oauth/	OAuth2 授权码流程
LAN 控制	examples/lan_control/	局域网设备控制
mDNS 发现	examples/mdns_discovery/	发现本地 MIPS 网关
MIPS 订阅	examples/mips_subscribe/	订阅设备状态变化
网络监控	examples/network_monitor/	网络状态监控
SPEC 解析	examples/spec_parser/	解析设备 SPEC
存储管理	examples/storage_manage/	证书/设备管理

---

文件对照表

Python 文件	Go 文件	状态
miot_error.py	miot_error.go	✅
const.py	const.go	✅
common.py	common.go	✅
miot_storage.py	miot_storage.go	✅
miot_cloud.py	miot_cloud.go	✅
miot_client.py	miot_client.go + api/device/prop/sub.go	✅
miot_device.py	miot_device.go	✅
miot_spec.py	spec_parser.go	✅
miot_mips.py	mips_client.go	✅
miot_network.py	miot_network.go	✅
miot_mdns.py	miot_mdns.go	✅
miot_lan.py	miot_lan.go	✅
miot_i18n.py	miot_i18n.go	✅
web_pages.py	web_pages.go	✅

---

开发文档

移植过程中的详细文档均保存在 miot/migration/ 目录：

• 01-miot-client.md ~ 13-miot-mdns.md：各模块第一轮移植详细设计
• R2-01-*.md ~ R2-14-*.md：第二轮方法级对齐审核记录
• MIGRATION_PLAN.md：总索引和进度跟踪
• ROUND2_PLAN.md / ROUND3_PLAN.md：后续优化轮次计划

---

许可证

与 Python 原版一致，遵循 Xiaomi proprietary license（非商业用途 Home Assistant 使用授权）。

---

最后更新：2026-06-28