把涂鸦设备搬回局域网：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建议先给设备绑定静态 IP（DHCP 保留）后手动填写。虽然集成允许把 IP 填成Auto让它自己发现设备，但这种方式在以下情况会失败：装了 localtuya、手机上 App 连着部分设备、或者网络不是单一简单子网；而且即便能成功，每次重连都要先扫一遍网络，恢复速度也慢。手动填固定 IP 是更稳的做法。两个容易忽略的细节重新配对会换 key：local 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_key，protocol_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），仅供参考
把涂鸦设备搬回局域网：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建议先给设备绑定静态 IP（DHCP 保留）后手动填写。虽然集成允许把 IP 填成Auto让它自己发现设备，但这种方式在以下情况会失败：装了 localtuya、手机上 App 连着部分设备、或者网络不是单一简单子网；而且即便能成功，每次重连都要先扫一遍网络，恢复速度也慢。手动填固定 IP 是更稳的做法。两个容易忽略的细节重新配对会换 key：local 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_key，protocol_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），仅供参考