LocalThings：让 Home Assistant 在局域网控制三星家电
给 Home Assistant 接入三星家电，局域网用 OCF 和 CoAP 控制，不依赖云端。
GitHub mbillow/localthings 更新 2026-11-08 分支 main 星标 1.1K 分叉 112
Python Home Assistant Samsung SmartThings OCF CoAP over DTLS 局域网

🧭 决策指南

为什么现在热： 无法从材料判断

适合，如果你

  • 你使用 Home Assistant，并能为三星家电提供局域网 IP 地址。
    README 的“Add an appliance”：输入 appliance's IP address，LocalThings 会读取型号并添加 Home Assistant device。
  • 你希望首次配置后不再让 LocalThings 访问 Samsung 服务器。
    README 的“Updates are fast”与“ It works without the internet”：setup 后 LocalThings never contacts Samsung's servers；但首次添加家电会例外联系一次。
  • 你的三星家电大约为 2022 年或更新型号。
    README 的“What it supports”：Most Samsung appliances from about 2022 onward work。
  • 你需要洗衣机、烘干机或空调的状态推送和 Home Assistant 控件。
    README 的“Built on open standards”：CoAP Observe 用于 push updates；支持表列出了 washer、dryer 和 air conditioner。

不适合，如果你

  • 你的要求是从未连接 Samsung 服务器，包括第一次添加家电。
    README 的“Add an appliance”明确写明添加第一个 appliance 时会联系 Samsung's servers once。
  • 你的家电拒绝自动证书，且你无法取得 pre-shared key。
    README 的“Add an appliance”：部分 appliance 需要导入 pre-shared key，而 LocalThings can't obtain it for you。
  • 你希望移除家电在 SmartThings 中的注册并继续稳定使用。
    README 的“Known device behavior”：从 SmartThings 移除后，家电下次连接 Samsung 服务器会重置网络设置并掉线。
  • 你依赖持续准确的洗衣机或烘干机能耗累计，但设备无法连接 SmartThings。
    README 的“Known device behavior”：DA_WM_TP2_20_COMMON 设备在无法访问 SmartThings 时能耗总量会停止增加。

前置条件

  • 运行 Home Assistant，并在“Settings > Devices & Services > Add Integration”中添加 LocalThings。
  • 通过 HACS 安装 LocalThings，或将 custom_components/localthings/复制到 Home Assistant 配置目录。
  • 重启 Home Assistant。
  • 为待添加的三星家电提供 IP address。
  • 首次添加第一个家电时需要访问 Samsung 服务器读取 public identifier；后续家电只需 IP address。
  • 家电应保持注册在 SmartThings 中。
  • 拒绝自动证书的家电需要可用的 pre-shared key；旧设备 TCP 8888 需要 device token。

要注意

  • 设备短暂断线时实体保留最后值，频繁重连应检查 Wi-Fi 信号。
    README 的“Known device behavior”：Brief disconnects are normal；若每分钟多次重连，检查 appliance's Wi-Fi signal。
  • 三星家电一次只接受一个连接，其他客户端可能与 LocalThings 冲突。
    README 的“Known device behavior”：an appliance accepts one connection at a time。
  • 开启 Allow writes even when remote control is reported off 可能让命令被家电静默忽略。
    README 的“Per-device settings”：默认拒绝 remote control off 时的命令，因为 appliance would ignore the command without saying so。
  • 某些多设备家电会产生重复或空的 Subdevices，需要在 Device settings 中取消。
    README 的“Per-device settings”：部分 appliance 会报告不存在的 extra slot，显示为 duplicate or empty device。
  • 新家电必须在设置时可达；设备此前成功连接过则 Home Assistant 重启期间可显示 unavailable。
    README 的“Restarting while an appliance is powered off”。

替代方案

  • SmartThings app：当你需要 Samsung 官方云端管理，或家电无法通过 LocalThings 的 OCF、CoAP over DTLS 本地接口接入时，README 明确将 SmartThings app 作为这些家电的既有连接方式。
    README 的“What it supports”与“Known device behavior”

材料未说明

  • README 未说明支持的 Home Assistant 最低版本。
  • README 未给出不同三星型号的完整兼容性清单，只有“about 2022 onward”和设备类型概述。
  • README 未说明 CoAP、DTLS、TCP 8888 所需的具体网络端口放行规则。
  • README 未说明 Dockerfile 的使用方式；安装章节只描述 HACS 和 custom_components/localthings/。
  • README 未说明每类家电可暴露的实体数量及不同型号之间的功能差异。
  • README 未说明自动证书失败的完整型号范围；仅指出部分设备需要 pre-shared key。

💡 深度解析

6
不适合 我准备把三星 WW80T654ALX 洗衣机和 DV80T6220LX 烘干机的能耗累计值接入 Home Assistant；我希望断网后仍能持续累计，LocalThings 是否适合做能源数据源？
适合读者： 把三星洗衣机和烘干机的累计能耗接入 Home Assistant 能源仪表盘、需要长期可信读数的家庭自动化用户

不适合把它当作断网条件下的可靠累计电表，因为 README 明确记录了相关机型在无法访问 SmartThings 时会停止增加能耗总量。

  • README 点名 DA_WM_TP2_20_COMMON 主板，包括 WW80T654ALX 和 DV80T6220LX：家电无法连接 SmartThings 时，energy total 会停止增加，恢复连接后才继续。
  • LocalThings只能显示家电自身记录的资源，不能替设备补算缺失的能耗，因此 Home Assistant 中停留不变的数值不一定代表实际没有耗电。
  • 项目确实支持暴露 energy use 等传感器，但“有实体”与“离线期间仍持续计量”是两个不同结论。
  • 如果你的约束是长期、断网也连续的能源计量，README没有给出保证，LocalThings不应作为唯一数据源。
  • Known device behavior："Some washers and dryers stop counting energy without SmartThings."
  • Known device behavior："WW80T654ALX and DV80T6220LX"
  • Known device behavior："LocalThings can only show what the appliance records"
  • What it supports：典型传感器包括 energy use
材料未说明：README 未说明其他主板或型号在断网时是否继续累计能耗。；README 未说明能耗累计值的单位、重置规则或与独立电表的误差。
适合 我维护 Python 编写的 Home Assistant 自定义集成，手头有 90 多份真实三星家电抓包；我想为一个新型号补充实体，但不想修改 CoAP 或 DTLS 协议代码，LocalThings 是否适合作为贡献基础？
适合读者： 维护 Python Home Assistant 自定义集成、想为新三星家电补充能力映射、手头已有 90 多份真实设备抓包的开源贡献者

适合，因为项目把协议通信与 Home Assistant 实体映射分开，新型号通常可以通过声明式能力表扩展，而不必改动协议层。

  • README 说明 smartthings-local 负责协议层，LocalThings负责配置、实体和生命周期管理；这与“只补能力映射”的目标一致。
  • 每类家电使用表格把设备报告的资源映射为 Home Assistant 实体，项目测试会用来自真实设备的 90 多份抓包校验这些表。
  • README 明确说新型号通常只需要增加 table entry，不需要协议代码，因此你的抓包资料可直接用于确认资源和实体映射。
  • 项目以 MIT License 发布，适合修改和再分发；但尚未识别的能力仍需通过诊断下载确认，不能仅凭型号名称猜测。
  • Built on open standards："The smartthings-local library implements the protocol layer."
  • Built on open standards："Declarative appliance maps"
  • Built on open standards："Tests check the tables against 90+ captures from real appliances"
  • Built on open standards："a new model usually needs a table entry and no protocol code"
  • 项目数据：main_language 为 Python；license 为 MIT License
材料未说明：README 未提供新增能力映射所需的具体文件路径、测试命令和提交格式。；README 未说明 90 多份抓包是否覆盖你的目标设备型号和固件版本。
适合 我已经运行 Home Assistant，家里有 2022 年以后支持 SmartThings 的三星洗衣机和冰箱；我希望控制请求留在家庭局域网内，并在断网时继续使用，LocalThings 是否适合？
适合读者： 已运行 Home Assistant、家中主要是 2022 年以后三星洗衣机和冰箱、希望断网时仍能控制设备的本地化智能家居用户

适合，因为这正是 LocalThings 面向的本地 Home Assistant 场景，但“断网可用”不等于家电完全不需要三星云。

  • README 说明它通过家庭网络连接洗衣机、冰箱等设备，配置后“LocalThings never contacts Samsung’s servers”，控制和状态数据不发送给三星。
  • 大多数约 2022 年及之后的三星家电可用；添加设备通常只需输入 IP，集成会自动读取类型和型号并创建实体。
  • 支持推送的设备会即时更新，其余设备每 30 秒检查一次，因此断网时仍可在局域网内工作，但非推送设备存在延迟。
  • 家电本身仍可能需要连接三星服务器维持 SmartThings 注册；移除注册可能导致设备重置网络设置，不能直接把互联网永久阻断作为无条件前提。
  • README："It works without the internet. After setup, LocalThings never contacts Samsung's servers."
  • README："Most Samsung appliances from about 2022 onward work"
  • README："Appliances that support push send changes as they happen. LocalThings checks the rest every 30 seconds."
  • Known device behavior："Keep appliances registered in SmartThings."
材料未说明：README 未按具体洗衣机或冰箱型号列出推送支持情况。；README 未说明家庭网络中断时每种型号的可写操作是否都能成功。
视情况 我通过 HACS 使用 Home Assistant，目标三星家电拒绝自动 X.509 证书；我可以从外部取得预共享密钥，但不想依赖三星账号登录，LocalThings 是否适合？
适合读者： 使用 Home Assistant HACS、希望接入一台拒绝自动证书的三星 SmartThings 家电、能够管理预共享密钥的高级用户

视情况，LocalThings支持导入预共享密钥且不要求三星账号登录，但这类设备的认证仍不是即插即用。

  • README 的安装方式支持 HACS，集成配置在 Home Assistant UI 中完成；多数设备只需 IP，但拒绝自动证书的设备会进入额外认证流程。
  • 项目使用 CoAP over DTLS 和 X.509 客户端证书建立加密连接；部分家电拒绝自动证书时，设置界面会要求导入预共享密钥。
  • README 明确说 LocalThings 无法替用户取得该密钥，因此你必须先解决凭据来源和安全保存问题。
  • README 还提到可提供公开 AC14K_M CA 证书，但目前没有报告证明拒绝自动证书的设备接受它，所以不能把它当作可靠替代方案。
  • Install："In HACS, go to Integrations, search for LocalThings"
  • Built on open standards："CoAP over DTLS ... with an X.509 client certificate"
  • Add an appliance："Some appliances refuse the automatic certificate"
  • Add an appliance："LocalThings can't obtain" the pre-shared key
材料未说明：README 未说明你的具体型号是否拒绝自动证书。；README 未保证外部取得的预共享密钥格式、权限和有效期一定满足该设备要求。
适合 我有一套多联机空调或双腔烤箱，准备在 Home Assistant 中分别控制各个子设备；如果自动识别产生空的子设备，我还能采用 LocalThings 吗？
适合读者： 在 Home Assistant 中管理多联机空调或双腔烤箱、要求每个真实子设备都准确映射且不出现重复实体的用户

适合，但需要接受自动发现可能产生空子设备，并在 Home Assistant 设备设置中处理它们。

  • README 的支持列表明确包含“Air conditioner, including multi-unit systems”，也包含 Oven，因此目标设备类型在项目范围内。
  • 项目洞察说明多联机空调和双腔烤箱可能被识别出额外的空子设备；这些并不表示协议连接失败，而是设备能力映射与实际结构不完全一致。
  • LocalThings按设备报告的资源创建实体，典型实体包括模式、温度、剩余时间和告警；实际子设备内容取决于设备上报的资源。
  • 如果你要求每个子设备的实体数量严格对应物理结构，README没有保证自动识别始终准确；但项目支持在设备设置中隐藏错误识别出的空子设备，因此仍可使用。
  • What it supports："Air conditioner, including multi-unit systems"
  • What it supports："Oven"
  • 项目洞察：多联机空调、双腔烤箱可能被识别出额外的空子设备
  • 项目洞察：允许用户隐藏错误识别出的空子设备
材料未说明：README 未给出具体多联机品牌型号与子设备识别矩阵。；README 未说明空子设备是否会影响自动化触发或仅影响界面显示。
视情况 我有一台较早的三星洗衣机或空调，它不是 2022 年后的型号，而是使用 TCP 8888 旧接口；我可以提供 device token，LocalThings 是否值得采用？
适合读者： 维护较早三星洗衣机、空调或壁挂炉的 Home Assistant 用户，设备只能通过旧版 TCP 8888 本地接口通信，并愿意处理设备令牌

视情况，项目明确覆盖部分使用 TCP 8888 的旧设备，但不能据此保证你的具体型号完整兼容。

  • README 说部分较早的洗衣机、空调和壁挂炉支持旧本地接口，并会在配置时检测设备使用哪种接口；如果未找到接口，会明确提示。
  • TCP 8888 设备需要额外的 device token，说明仅有 IP 地址并不足以完成配置，凭据获取和维护成本高于新设备。
  • README 同时强调旧型号支持不完整，支持范围取决于固件、型号和实际暴露的资源；即使安装成功，也可能缺少某些控制实体。
  • 因此，若你的型号已被项目识别且能取得 token，采用有现实可行性；若必须保证全部模式、程序和写操作，README 没有给出承诺。
  • What it supports："so do some earlier washers, air conditioners and wall ovens that use an older local interface"
  • What it supports："Setup detects which interface an appliance has, and tells you if it finds none."
  • Add an appliance："Older appliances on TCP 8888 ask for a device token."
  • 项目洞察：兼容性取决于固件、型号和本地接口实现；旧型号支持不完整。
材料未说明：README 未列出完整的 TCP 8888 型号兼容清单。；README 未说明 device token 对每个旧型号的具体获取路径和失效周期。

✨ 核心亮点

  • Home Assistant 局域网控制三星家电
  • 支持 OCF、CoAP Observe 与 DTLS
  • 90+ 真实设备抓包验证家电映射
  • 多数 2022 年后三星家电可用

🔧 工程化

  • 通过 IP 地址发现型号并创建 Home Assistant 实体
  • CoAP Observe 推送状态，其他设备每 30 秒轮询
  • 支持洗衣机、冰箱、空调、烤箱等三星家电
  • 声明式家电映射通常只需新增表项

⚠️ 风险

  • 首次添加家电会联系 Samsung 服务器一次
  • 部分设备拒绝自动证书，需要预共享密钥
  • 旧设备 TCP 8888 需要 device token
  • 设备仅接受一个连接，其他连接会造成断线
  • 部分洗烘设备离线时停止记录能耗

👥 适合谁？

  • 使用 Home Assistant 管理三星家电的家庭网络用户
  • 需要无云控制且能提供家电 IP 地址的用户
  • 愿意处理 OCF、DTLS 证书或 TCP 8888 设备的开发者