如何为 LocalThings 添加新家电类型:完整贡献者指南

原创2026-11-12 09:56:091,893 阅读
文章标签:物联网智能家居插件系统

如何为 LocalThings 添加新家电类型:完整贡献者指南

LocalThings 是一个 Home Assistant 自定义集成,让你通过家庭网络直接控制三星家电(洗衣机、冰箱、空调、烤箱等),全程无需云端账号。如果你想让自家还不被识别的三星家电"上岗",本文就是为你准备的完整贡献者指南:从搭建开发环境、下载设备诊断数据,到注册新家电类型并跑通回归测试,全流程 5 步走通。

LocalThings 项目标识:三星家电本地控制集成

为什么贡献这么"轻"?先看架构

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 步:下载诊断文件,拿到设备资源清单

这是整个流程的起点,也是最容易被忽视的一步:

  1. 先把家电添加到 Home Assistant(即使 LocalThings 不认识它的类型也行);
  2. 在该设备的 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() 会按以下优先级把设备路由到你的类型——每一步都只是往表里加一行,不是写新代码:

  1. OCF 设备类型(_OIC_TYPE_TO_KEY):设备自报的类型(如 oic.d.washer),来自 /oic/d,最可靠,优先检查;
  2. 资源特征签名(for_device_by_resources()):针对不报 /information/vs/0 的设备,需要两个独立资源同时命中,防止误匹配;
  3. deviceSubType(_DEVICE_SUBTYPE_TO_KEY):老式 8888 端口设备专用;
  4. 板卡 token(_BOARD_TOKEN_TO_KEY):从 modelNum 中取整词匹配,如 'VSKR': 'vacuum_station'。注意要写具体类型名,别写板卡家族名——DA-AC- 前缀同时覆盖空调、除湿机和空气净化器,写个 AC 会把三者全吞掉;
  5. 消费级型号前缀(_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 步贡献清单

  1. 添加设备并下载诊断文件(起点,也是维护者最快需要的材料);
  2. 优先复用 registry/capabilities/ 里的 Capability;
  3. 新建 registry/by_type/<name>.py;
  4. 在 _REGISTRY_BY_KEY 注册,并配置一条路由表项;
  5. 补夹具 + 黄金文件,跑通四项检查后提交 PR。

你的家电类型被合入后,所有用户都会在下一次更新中免费获得它的支持——这正是 LocalThings 社区驱动的最佳回报。

登录后查看全文
localthings