Tuya LocalHome Assistant 涂鸦设备本地控制完整指南【免费下载链接】tuya-localLocal support for Tuya devices in Home Assistant项目地址: https://gitcode.com/GitHub_Trending/tu/tuya-local本文介绍 tuya-local一个运行在 Home Assistant 的集成通过局域网直连涂鸦设备不经过 Tuya 云端中转控制指令。读完你能完成集成安装、备齐设备连接信息并在 Home Assistant 中添加、命名你的第一台涂鸦设备。本地直连与云端中转的差别对比项传统云端方案tuya-local 本地方案指令延迟指令经公网往返云端服务器受外网波动影响局域网直连设备毫秒级响应数据链路状态与指令都经过 Tuya 云端控制指令只在 Home Assistant 与设备之间收发断网可用性断网或云服务中断时无法控制局域网内设备仍可继续控制费用依赖云服务状态部分功能可能受限免费使用无订阅本地链路控制指令直达设备不绕公网。免费运行不产生云服务或订阅费用。一点提醒集成只改变控制路径设备仍会向 Tuya 云端上报状态它不等同于数据隔离。接入前先备好四样信息需要的信息获取途径备注device_id设备 ID集成内的云辅助登录或 Tuya 开发者平台设备列表每台设备一个local_key本地密钥同上手动获取见 DEVICE_DETAILS.md每次用 App 重新配对该设备后密钥会变需重新获取设备 IP 地址路由器局域网设备列表或 tinytuya 扫描建议绑定静态 IP协议版本配置流程中选 auto 自动检测可选手动指定 3.1 至 3.5、3.22如果不想逐项手动查询可以在 Home Assistant 主机上用 tinytuya 的向导扫描局域网pip install tinytuya python -m tinytuya wizard按提示填入开发者平台的 Access ID、Access Secret 和任意一台已注册设备的 ID。向导会把扫描结果写入 devices.json其中 id、key、node_id、mapping 四项分别对应上表的设备 ID、本地密钥、子设备 ID 和数据点描述。首台设备接入的完整五步1. 操作安装 HACS 后在 HACS 的自定义仓库中添加仓库地址 https://gitcode.com/GitHub_Trending/tu/tuya-local 然后搜索并安装Tuya Local集成。结果集成出现在设置 → 设备与服务的集成列表中。易错点该版本要求 Home Assistant 不低于 2026.8.0、HACS 不低于 2.0.0。2. 操作进入设置 → 设备与服务 → 添加集成搜索 Tuya Local。选择用 Tuya 或 SmartLife App 账号云辅助登录或选择手动填写。结果云辅助路径会列出你账号下的设备清单并自动回填 ID 与密钥手动路径需要你输入 host、device_id、local_key。易错点多数涂鸦设备只允许一个本地连接开始前先关闭局域网内 Tuya App 的本地连接及其他本地 Tuya 集成。3. 操作第一阶段填入 host设备 IP、device_id、local_key协议版本选 auto确认提交。结果集成尝试连接并读取设备返回的数据点列表密钥错误会在此处直接报错。易错点协议 3.1 的设备在连接阶段不校验密钥密钥填错也能连接成功要等你下发指令时才发现失败。4. 操作第二阶段从过滤后的设备类型列表中选择与你设备匹配的类型。结果Home Assistant 按该类型生成对应的控制实体。易错点选错类型只能删除设备后重新配置不同类型生成的实体不同无法就地切换。5. 操作第三阶段给设备起一个唯一名称完成配置。结果设备及其一组实体出现在 Home Assistant 中名称作为实体名前缀。易错点同类型多台设备时名称里加上房间或位置例如客厅_电暖器避免后期混淆。进阶技巧静态 IP、指令节奏与批量添加固定 IP 绑定在路由器 DHCP 设置中为每台设备保留固定 IP配置时直接填该 IP。原因是配置里填 Auto 时集成每次重连都要扫描网络寻找设备速度慢且在多 VLAN 或已安装 localtuya 的网络中会直接失败。自动化指令间隔 0.5-2 秒涂鸦设备处理不了快速连发的指令过载时部分设备会重启部分会离线 30 秒到几分钟。在自动化中给同一设备的连续指令加入延迟从 1 秒起步再按设备实际表现微调。一次登录批量添加云辅助登录的 Tuya 认证令牌有效期为几小时Home Assistant 不重启的前提下连续添加多台设备只需认证一次。故障自查表现象可能原因处理方法配置时连不上设备或设备频繁掉线其他软件占用了唯一本地连接设备与 Home Assistant 不在同一网段动态 IP 已变更关闭 Tuya App 本地连接和其他本地 Tuya 集成绑定静态 IP 并核对同网段连接成功但下发指令无反应或提示密钥错误重新配对该设备后 local_key 已更换密钥复制不完整重新获取最新 local_key3.1 设备密钥错误只在发指令时暴露指令无响应就优先重取密钥数据错乱或设备只读、命令不生效协议版本自动检测误判3.2、3.22 与 3.3 之间常见在协议版本中手动依次尝试 3.2、3.22、3.4电池供电传感器始终无法接入门磁、烟感等设备为省电不维持本地长连接本地方式不支持改用对应协议方案或接受该设备走云端设备支持范围当前支持 1000 余种设备类型按功能归纳如下完整清单见 DEVICES.md类别示例加热与气候电壁炉、油汀、毛巾架、地暖空调与热泵Airton 空调、Carrier-Midea 分体机、泳池热泵空气处理除湿机、加湿器、空气净化器照明与开关智能灯泡、LED 灯带、智能插座与排插能源管理带功率监测的插座、断路器、充电桩安防与门禁智能锁、摄像头、门铃、警报器覆盖物与清洁窗帘/卷帘、扫地机器人、割草机器人宠物用品自动喂食器、猫砂盆、宠物饮水机注意设备固件升级或同型号不同批次可能导致个别在售设备不兼容列表中找不到型号时可按仓库指引提交新设备配置。一页速查表项目内容安装方式HACS 自定义仓库安装 Tuya Local扫描命令python -m tinytuya wizard扫描结果文件devices.jsonid / key / node_id / mapping配置入口设置 → 设备与服务 → 添加集成 → Tuya Localhost 参数设备 IP 或 Auto推荐填静态 IPprotocol_versionauto、3.1、3.2、3.3、3.4、3.5、3.22网关子设备用网关的 device_id、IP、local_key 加子设备 node_id验证方式实体出现且状态与实际一致可开关设备状态随实际变化同步先检查已添加设备的实体状态是否与实物一致再按同样流程把其余设备逐一接入。遇到日志中能看到 dps 数据但列表无匹配类型的设备可参考 custom_components/tuya_local/devices/README.md 编写设备配置文件并反馈给项目。【免费下载链接】tuya-localLocal support for Tuya devices in Home Assistant项目地址: https://gitcode.com/GitHub_Trending/tu/tuya-local创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
