Tuya Local：Home 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_key；3.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.json（id / key / node_id / mapping） |
| 配置入口 | 设置 → 设备与服务 → 添加集成 → Tuya Local |
| host 参数 | 设备 IP 或 Auto，推荐填静态 IP |
| protocol_version | auto、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），仅供参考
