mbillow/localthings

项目介绍

LocalThings 是一个 Home Assistant 自定义集成，用来控制原本通过 SmartThings App 连接的三星家电。它不经过三星云端，而是直接在家居局域网内与洗衣机、烘干机、冰箱、空调、烤箱、灶台、洗碗机、扫地机器人等受支持设备通信。具体能获得哪些实体取决于设备上报的内容，通常包括电源、模式或程序选择、启动/暂停/停止、温度与设定值、剩余时间、门锁与童锁状态、能耗、滤网状态和告警。

支持推送的设备会即时上报变化，其余设备每 30 秒轮询一次。添加设备时大多只需输入 IP 地址，集成会读取设备类型和型号并生成对应控制项。约 2022 年及之后的大多数三星家电可用，部分更早的洗衣机、空调和嵌入式烤箱也能通过旧的 TCP 8888 接口接入。

集成基于 OCF 设备模型和 CoAP over DTLS，协议层由 smartthings-local 库实现。设备支持通过声明式的映射表把上报资源转换为 Home Assistant 实体。

安装与添加设备

1. 在 HACS 中进入 Integrations，搜索 LocalThings 并选择 Download。该集成已在 HACS 默认列表中，无需添加自定义仓库；也可以使用 HACS 仓库快捷入口。
2. 重启 Home Assistant。
3. 进入 Settings > Devices & Services > Add Integration > LocalThings。
4. 输入家电的 IP 地址。LocalThings 会连接设备、读取类型和型号，并添加一个对应的 Home Assistant 设备。

不使用 HACS 时，将 custom_components/localthings/ 复制到 Home Assistant 配置目录的 custom_components/ 下。添加第一台设备时，集成会访问一次三星服务器以读取公共标识，不需要账号或登录；后续设备复用该标识，只需 IP 地址。

使用约束与已知行为

• 家电必须继续保留在 SmartThings 中。若从 App 中移除，设备下次连接三星服务器时会重置网络设置，并从 Wi-Fi 掉线。
• 部分设备拒绝自动证书，需要预共享密钥，而 LocalThings 无法替你获取；参见证书获取说明和跟踪用的 issue #435。旧的 TCP 8888 设备则需要设备令牌，具体步骤因型号而异。
• 一台家电同一时间只接受一个本地连接，其他客户端占用连接会造成干扰。短暂断连属正常现象，重连期间实体保留最后一次的值。
• 不上报 MAC 地址的设备在 IP 变化后需要在条目上选择 Reconfigure 重新填写；删除后重新添加会丢失实体、历史记录和自动化。
• 启动烤箱、灶台或微波炉时，模式、温度和烹饪时间必须一起下发；每台设备会报告哪些模式允许远程启动。使用 DA_WM_TP2_20_COMMON 主板的洗衣机和烘干机在无法连接 SmartThings 时，能耗累计可能停止增长。
• 诊断下载在保存前会脱敏，是上报不支持设备的推荐方式；项目使用 MIT 许可证。

HotRepo 点评

在 2026-11-07 的 GitHub 全语言日榜中，LocalThings 最高排到第 12 名，当天新增 184 Star，同一份快照记录为 926 Star、102 Fork。对一个 Home Assistant 自定义组件来说，这种涨幅并不常见，更像是填补了具体的本地控制空白，而不是被大量开发者广泛采用。README 对协议细节、各型号限制和诊断流程写得很具体，比一般集成目录更容易判断是否适用；但支持范围仍取决于设备上报内容，准备使用前应先核对支持设备表和已知行为，再确认目标型号能否正常工作。