如何为 LocalThings 添加新家电类型:完整贡献者指南
如何为 LocalThings 添加新家电类型:完整贡献者指南
LocalThings 是一个 Home Assistant 自定义集成,让你通过家庭网络直接控制三星家电(洗衣机、冰箱、空调、烤箱等),全程无需云端账号。如果你想让自家还不被识别的三星家电"上岗",本文就是为你准备的完整贡献者指南:从搭建开发环境、下载设备诊断数据,到注册新家电类型并跑通回归测试,全流程 5 步走通。
为什么贡献这么"轻"?先看架构
LocalThings 的核心设计是声明式设备映射:每种家电类型只是一张"资源 → 实体"的映射表,而不是各写各的协议代码。设备上报哪些资源,表里就配置哪些实体,测试会用 90+ 份真实设备抓包数据来校验这些表。因此:
新增一个型号,通常只需要加一条表记录 + 一份测试夹具,几乎不碰协议层代码。
关键模块分工(均在 custom_components/localthings/ 下):
| 模块 | 职责 |
|---|---|
| registry/capabilities/ | 共享的 Capability 定义,如电源、童锁、远程控制、能耗/水耗 |
| registry/by_type/ | 每种家电一个注册表(DeviceRegistry) |
| registry/discovery.py | 把设备实时资源绑定到能力上 |
| tests/fixtures/ | 真实设备抓包夹具与黄金回归文件 |
官方贡献流程完整记载于 CONTRIBUTING.md,建议提交 PR 前通读一遍。
一键搭建本地开发环境
项目用 Docker 提供开箱即用的开发环境:
git clone https://gitcode.com/GitHub_Trending/lo/localthings
cd localthings
docker compose up -d --build
docker compose logs -f
Dockerfile 基于官方 home-assistant/home-assistant:stable 镜像,构建时预装 smartthings-local 协议库;docker-compose.yml 使用 host 网络(DTLS 走 UDP,桥接网络到不了局域网家电),并把 custom_components/localthings/ 只读挂载进 HA 配置目录。
测试环境则用 Python 3.13+:
python3.13 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
requirements-dev.txt 会安装 Home Assistant、pytest、ruff、ty,并以与 manifest.json 一致的方式锁定 smartthings-local 版本,保证测试跑在同一个协议库上。
第 1 步:下载诊断文件,拿到设备资源清单
这是整个流程的起点,也是最容易被忽视的一步:
- 先把家电添加到 Home Assistant(即使 LocalThings 不认识它的类型也行);
- 在该设备的 Download diagnostics(下载诊断)处点击导出。
诊断文件包含该家电上报的每个资源的脱敏副本——账号邮箱、令牌、MAC、序列号等敏感信息已被 registry/redact.py 清除。其中 identity.device_types 字段还记录了 OCF 设备类型,是后续路由决策的重要依据。
第 2 步:优先复用现有 Capability
打开 registry/capabilities/,逐个比对资源:
- 大部分能力是跨家族共享的,集中在 common.py:
/power/vs/0(电源)、/kidslock/vs/0(童锁)、/remotectrl/vs/0(远程控制)、/alarms/vs/0(告警)、/energy/consumption/vs/0(能耗)等; - 每个
Capability由 OCF 资源 href、产出实体和轮询层级(poll_tier)组成,定义见 registry/capability.py; - 只为新类型独有的资源新建能力,能复用就复用,这是代码评审的第一道关卡。
第 3 步:创建 registry/by_type/.py
新建一个注册表文件,模式非常统一——参考 by_type/air_monitor.py:
REGISTRY = DeviceRegistry(
name="air_monitor",
capabilities=_build([
*ignored.IGNORED,
*common.UNIVERSAL,
air_monitor.SENSORS,
air_monitor.BATTERY,
]),
)
两个要点:
capabilities=_build([...])组织固定 href 的能力,按 href 分组;- 资源 href 会变化的(如冰箱每个隔室独立的温度资源),放进
pattern_capabilities,by_type/refrigerator.py 中的fridge.TEMP_SETPOINT是标准范例。
DeviceRegistry 本体(by_type/_base.py)还支持 subscribe_tiers、write_settle_s 等按板卡调优的字段,绝大多数新类型用默认值即可。
第 4 步:注册路由,让设备找到你的注册表
打开 registry/by_type/init.py,把新注册表挂进 _REGISTRY_BY_KEY。随后 resolve() 会按以下优先级把设备路由到你的类型——每一步都只是往表里加一行,不是写新代码:
- OCF 设备类型(
_OIC_TYPE_TO_KEY):设备自报的类型(如oic.d.washer),来自/oic/d,最可靠,优先检查; - 资源特征签名(
for_device_by_resources()):针对不报/information/vs/0的设备,需要两个独立资源同时命中,防止误匹配; - deviceSubType(
_DEVICE_SUBTYPE_TO_KEY):老式 8888 端口设备专用; - 板卡 token(
_BOARD_TOKEN_TO_KEY):从modelNum中取整词匹配,如'VSKR': 'vacuum_station'。注意要写具体类型名,别写板卡家族名——DA-AC-前缀同时覆盖空调、除湿机和空气净化器,写个AC会把三者全吞掉; - 消费级型号前缀(
_CONSUMER_PREFIX_TO_KEY):洗衣机/干衣机共用DA_WM_板卡,靠WW/DV等型号前缀区分。
第 5 步:添加夹具与黄金回归测试
把诊断文件整理成两份测试数据放进 tests/fixtures/:
tests/fixtures/<name>_device.json—— 设备资源快照(形如device0批次结构,可对照 ehs_device.json);tests/fixtures/golden/<name>.json—— 黄金文件,记录期望的实体键集合。
test_golden_regression.py 会用你的注册表重放夹具、压平实体,并与黄金文件逐键比对——多一个、少一个都会失败。这保证了新注册表不会悄悄改变已有家电的行为。测试统一用 conftest 提供的 _load_device(name) 读取夹具,写法见 tests/conftest.py。
提交前:跑全量检查
本地提交前请依次执行(CI 在 Python 3.14 上跑同样四项检查):
.venv/bin/ruff format --check custom_components tests
.venv/bin/ruff check custom_components tests
.venv/bin/ty check custom_components tests
.venv/bin/pytest tests/ -q -n auto
-n auto 借助 pytest-xdist 全核并行;单跑一个文件时建议去掉,省去每个 worker 几秒的 HA 导入开销。测试禁止等待真实时间——打补丁模拟延迟或时钟,参考 tests/localthings/test_sensor_sticky.py。
贡献礼仪:注释与提交规范
这个代码库大量工作在"逆向未文档化的设备 API",因此注释要求格外严格(详见 CONTRIBUTING.md 的 Code comments 一节):
- 只注释"为什么",不注释"是什么";一两句话给出结论加一条可查证的证据(issue 编号或型号名)即可;
- 失败排查日志放 issue 或 docs/investigations/,不要塞进代码注释;
- 提交时 author 与 committer 必须填对变更负责的真实姓名和邮箱,即使代码由 AI 辅助起草,也不得使用机器人身份或添加 AI 的 Co-Authored-By 行。
PR 中同样严禁携带真实设备 UUID、MAC、序列号、IP 或私钥。
小结:5 步贡献清单
- 添加设备并下载诊断文件(起点,也是维护者最快需要的材料);
- 优先复用 registry/capabilities/ 里的
Capability; - 新建
registry/by_type/<name>.py; - 在
_REGISTRY_BY_KEY注册,并配置一条路由表项; - 补夹具 + 黄金文件,跑通四项检查后提交 PR。
你的家电类型被合入后,所有用户都会在下一次更新中免费获得它的支持——这正是 LocalThings 社区驱动的最佳回报。
