★ FEATURED ARTICLE 把涂鸦设备搬回局域网Tuya-Local 本地控制与 Home Assistant 配置指南【免费下载链接】tuya-localLocal support for Tuya devices in Home Assistant项目地址: https://gitcode.com/GitHub_Trending/tu/tuya-localTuya-Local 是 Home Assistant 的一个第三方集成让 WiFi 版涂鸦Tuya设备不再绕道 Tuya 云直接通过局域网与设备通信本文梳理它的工作方式、凭据获取、完整配置流程以及配好之后常见的故障怎么定位。场景引入控制请求为什么总要先出家门用原厂 App 或 Tuya 云端集成时你点一下关灯请求要先发到 Tuya 的服务器再由服务器转发给设备链路长、有延迟家里宽带一断面板上的实体全部失联。Tuya-Local 的做法是把这条链路砍短它在你的局域网里直接和涂鸦设备建立连接、加解密通信命令和状态都不经过云。需要说明的是设备自己通常仍会向云上报状态所以它主要解决的是速度与可靠性而不是一个严格的安全隔离手段顺带的好处是本地接口有时能暴露云端 API 不开放的功能。它是怎么做到的数据点映射与协议协商理解下面两个概念后面排查问题就快了。数据点dps涂鸦设备把开关、模式、温度、目标湿度等功能都编号成一个个数据点如 dp1 是开关、dp2 是模式本地协议收发的就是这些数字。Tuya-Local 靠 devices/ 目录下的 YAML 文件把某个型号设备的 dps 翻译成 Home Assistant 的实体switch、climate、humidifier 等。协议版本设备与主机之间的通信有 3.1、3.2、3.3、3.4、3.5、3.22 等版本集成默认用auto探测。较新版本会用 local key 解密收到的数据3.1 则只在发送命令时用到它——这个差异直接决定了密钥填错时的症状见排坑一节。设备型号不同同一个 dp 含义也可能不同所以配置流程里有一步选择设备类型集成会把你设备实际上报的数据点和内置的 1000 份设备配置做比对只列出至少部分匹配的型号供你挑选。另有一个硬件层面的限制要先知道多数涂鸦设备只允许一条本地连接。如果你在配 Tuya-Local 的同时手机上的 Tuya/SmartLife App 或其他本地集成也连着同一台设备就会出现互相挤占、时好时坏的情况。动手前准备拿齐设备 ID、local key 和固定 IP配一台设备需要四个值缺了任何一个都走不到下一步参数是什么拿不到的后果host设备的 IP 或主机名连不上设备device_id设备的唯一标识无法建立会话local_key本地通信加密密钥新协议版本下连接测试直接失败3.1 设备则到控制时才暴露protocol_version协议版本一般填auto选错版本可能导致无响应或只读三条路径拿到凭据云辅助配置推荐在集成的配置页里直接用 Tuya 或 SmartLife App 的账号登录集成会自动拉出你的设备列表、填好device_id和local_key并尝试在局域网里定位 IP。好处是不需要注册 Tuya IoT 开发者账号登录令牌几小时后过期且不保存但在不重启 Home Assistant 的前提下可以连续添加多台设备只登录一次。Tuya IoT 开发者门户登录后在 Cloud 的设备列表里找到 Device ID再用 API Explorer 的Query Device Details in Bulk批量查询设备详情功能查出local_key。注意 Tuya 现在对这一能力做限时开通试用期只能每 6 个月续一次建议趁早把 key 记下来。tinytuya 命令行扫描在 Home Assistant 主机上运行python -m tinytuya wizard按提示填入开发者门户的 API Key、Secret 和数据区域后它会扫描局域网里的涂鸦设备把id、key、node_id网关子设备用以及数据点描述写进devices.json。在路由器里固定设备 IP建议先给设备绑定静态 IPDHCP 保留后手动填写。虽然集成允许把 IP 填成Auto让它自己发现设备但这种方式在以下情况会失败装了 localtuya、手机上 App 连着部分设备、或者网络不是单一简单子网而且即便能成功每次重连都要先扫一遍网络恢复速度也慢。手动填固定 IP 是更稳的做法。两个容易忽略的细节重新配对会换 keylocal key 在每次配对应设备时会变化。如果你拿到 key 之后又用厂商 App 重新绑定了设备旧 key 就作废了。哪些设备不适合本地门窗传感器、烟雾报警器这类纯电池供电的设备基本无法本地支持掉电管理限制通过网关连接的子设备支持有限每个子设备占用一条连接而网关通常只允许 1~3 条。子设备要用网关的device_id、IP、local_key加上子设备自己的node_id来添加。配置走一遍凭据、设备类型与命名三阶段用 HACS 装上集成第三方集成建议通过 HACS 安装。给 HACS 添加自定义仓库时仓库地址使用https://gitcode.com/GitHub_Trending/tu/tuya-local装完重启添加集成列表里就会出现 Tuya Local。三阶段配置页逐项填入口在设置 → 设备与服务 → 添加集成选 Tuya Local第一阶段连接信息填host、device_id、local_keyprotocol_version不确定就选auto。提交时集成会立刻尝试连接设备并读取数据。做对了长什么样这一步直接通过进入下一屏如果是较新协议版本而 key 填错会在这里就报错属于错得很明显。第二阶段选择设备类型从按数据点过滤后的型号列表里选你的设备。做对了长什么样选完后设备生成的实体开关、气候、传感器等和你实际设备的功能对得上——灯能调光、风扇有档位、湿度计数值正常。第三阶段命名给设备起一个名字它会成为所有实体名的前缀。多台同类型设备时名字务必区分开。选错类型怎么办不同设备类型会生成不同的实体集成不建议在保留实体的情况下改类型——如果选错了把该设备删掉、从头再走一遍三阶段即可。如果你预期中的型号没出现在列表里通常是固件版本不同导致数据点不匹配可以先看 Home Assistant 日志里集成打出的实际 dps再按 devices/README.md 的说明反馈为新设备支持请求。配好之后能玩什么两个具体的自动化场景场景一夜间自动调除湿目标命令之间留延迟涂鸦设备普遍不耐受快速连发多条命令轻则离线 30 秒到几分钟重则重启。集成内置了速率限制并会把部分命令合并成一条消息但跨实体发送时覆盖不到。所以写自动化时建议在同一台设备的两条命令之间加延迟0.5~2 秒之间按设备实测调整。多数设备支持一条消息带多个设置例如 climate 的set_temperature可以顺带把 preset 一起下发也有少数设备只认一条消息只改一个 dp这类设备只能走多命令 延迟的路线。场景二红外发射器当万能遥控器Tuya 的 IR/RF 发射器会被暴露为remote实体支持学习命令。用remote.learn_command服务把发射器放进学习模式对着按原遥控器即可存入一条命令如TV 的 power学习结果持久保存、重启不丢。之后既可以用remote.send_command回发也可以把学到的 IR 码通过 tuya-local 的send_learned_ir_command服务转发给其他infrared发射器等于用一台涂鸦 IR 盒子带动家里所有红外家电。调优与排坑按现象定位原因现象可能原因处理办法配完能连上但命令没有响应协议版本被探测错3.2 / 3.22 / 3.4 和 3.3 互相误判较常见在配置里手动指定协议版本再试3.22 是开启 device22 检测的特殊选项3.1 设备配置成功一控制就失败3.1 的 local key 只在发送时校验配错 key 不会在安装阶段暴露重新核对 key 后重配设备偶尔离线几十秒、甚至重启短时间内连发多条命令超过设备承受力自动化中在命令间加延迟多设备自动化可先操作别的设备再回来补发第二条断网一段时间后设备彻底不理你部分设备长时间连不上 Tuya 服务器后会停止响应有反馈称同时屏蔽 DNS 和 TCP 到 Tuya 的连接时表现更好可按此思路在路由器上做限制时好时坏、实体频繁掉线手机上 App 或其他本地集成占用了设备唯一的本地连接关掉相关 App、移除同设备上的其他本地集成保证同一时刻只有一个本地客户端列表里找不到自己的型号固件升级或同型号不同固件导致数据点变化查看日志中的实际 dps按新设备流程反馈注意设备 OTA 升级后原有配置也可能失效延伸与资源文档、配置目录与社区入口项目主文档与安装说明README.md支持的 1000 设备清单按加热器、空调、净化器等分类DEVICES.md手动查找 device ID / local key / IP 的完整指引DEVICE_DETAILS.md全部设备配置 YAML每份文件就是一个型号的 dps → 实体映射custom_components/tuya_local/devices/如何为新设备编写配置文件devices/README.md集成各实体平台的测试用例可当作某类设备应该生成哪些实体的参照tests/社区支持走项目代码托管页的 issue 区即可提报新设备时附上集成日志里的 LOCAL DPS、设备型号与品牌、以及能找到的数据点说明被采纳的速度会快很多。【免费下载链接】tuya-localLocal support for Tuya devices in Home Assistant项目地址: https://gitcode.com/GitHub_Trending/tu/tuya-local创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
