make-all/tuya-local

 请报告任何[问题](https://github.com/make-all/tuya-local/issues)，并随时发起[pull request](https://github.com/make-all/tuya-local/pulls)。 [许多其他贡献者](https://github.com/make-all/tuya-local/blob/main/ACKNOWLEDGEMENTS.md) 已经提供了帮助。 这是一个 Home Assistant 集成，用于支持运行 Tuya 固件的设备，而无需通过 Tuya 云端。支持通过 WiFi 连接的设备，对通过网关连接的设备提供有限的支持。 请注意，许多 Tuya 设备似乎只支持一个本地连接。如果您在使用此集成时遇到连接问题，请确保没有配置其他提供本地 Tuya 连接的集成来使用同一设备，关闭本地网络中设备上的移动应用程序，并且没有其他软件尝试本地连接到您的 Tuya 设备。 使用此集成并不会阻止您的设备向 Tuya 云端发送状态，因此不应将其视为一种安全措施，而是通过使用本地连接来提高速度和可靠性，并可能解锁您的设备的某些功能，甚至解锁 Tuya 云端 API 不支持的完整设备功能。 一个类似但不相关的集成是 [rospogrigio/localtuya](https://github.com/rospogrigio/localtuya/)，如果您的设备不受此集成支持，您可能会发现使用它作为替代方案更容易设置。 ## 设备支持 请注意，设备有时会进行固件升级，或者不兼容的版本会在相同的型号名称下销售，因此，即使设备已被列出，也可能无法正常工作。 不使用网关的电池供电设备（如门窗传感器、烟雾报警器等）无法在本地提供支持，因为它们需要进行的电源管理才能获得可接受的电池寿命。在某些情况下，当可以通过电池或 USB 供电的设备插入 USB 时，这也可能适用。如果您在尝试设置时无法收集到列出了 dps 的警告级别日志，那么它很可能无法与此集成配合使用。 目前支持网关，但存在限制。每个到子设备的连接都使用单独的网络连接，但与其他 Tuya 设备一样，网关通常在它们可以处理的连接数量上受到限制，典型限制为 1 或 3，具体取决于它们使用的特定 Tuya 模块。这严重限制了可以通过此集成的子设备数量。 添加子设备时应使用其连接到的网关的 `device_id`、`address` 和 `local_key`，以及子设备的 `node_id`。如果没有列出 `node_id`，请尝试使用 `uuid`。 Tuya Zigbee 设备通常是标准的 Zigbee 设备，因此作为使用 Tuya 网关的此集成的替代方案，您可以使用受支持的 Zigbee USB 网关或 WiFi 网关配合 [ZHA](https://www.home-assistant.io/integrations/zha/#compatible-hardware) 或 [Zigbee2MQTT](https://www.zigbee2mqtt.io/guide/adapters/)。 一些 Tuya 蓝牙设备可以直接通过 [tuya_ble](https://github.com/PlusPlus-ua/ha_tuya_ble/) 集成来支持。 Tuya IR/RF 遥控器通过 remote 实体平台提供支持。它们可以学习和存储 IR 和 RF 命令，并通过 `remote.learn_command` 和 `remote.send_command` 服务重播它们。 将通用 IR 遥控器作为子设备暴露的 Tuya IR 网关通常将其暴露为单向设备（仅发送）。由于此集成基于设备返回的 dps 进行设备检测，因此目前根本无法检测到此类设备。一些用于空调遥控器的专用 IR 网关确实可以工作，因为它们尝试使用当前设置的内部存储以及内部的温度和湿度传感器来模拟一个完全智能的空调。 一些 Tuya 网关现在支持 Matter over WiFi，这可以作为此集成的替代方案，用于将网关和子设备连接到 Home Assistant。这会有其他限制，因此您可能想两者都试一下，并且仅将此集成用于通过 Matter 无法正常工作的设备。 目前支持的设备列表可以在 [DEVICES.md](https://github.com/make-all/tuya-local/blob/main/DEVICES.md) 文件中找到。 关于构建设备配置文件的文档位于 [/custom_components/tuya_local/devices/README.md](https://github.com/make-all/tuya-local/blob/main/custom_components/tuya_local/devices/README.md) 如果您的设备未被列出，您可以在以下位置找到为其添加配置所需的信息： 1. 在尝试添加设备时，如果它不受支持，您将收到一条消息，指出完全无法识别该设备，或者将为您提供部分匹配的设备列表。您可以在此时取消该过程，并查看 Home Assistant 日志 - 那里应该有一条包含设备返回的当前数据点 的消息。 2. 如果您已注册 [iot.tuya.com](https://iot.tuya.com/)，您应该可以访问“云开发”下的 API Explorer。在“设备控制”下，有一个名为“查询设备数据模型”的功能，除了整数和枚举数据类型所需的范围信息外，它还会返回 dp id。 如果您提交 issue 以请求对新设备的支持，请包含以下信息： 1. 此集成的日志，显示实际从设备接收到的 LOCAL DPS。 2. 设备的标识，例如型号和品牌名称。 3. 尽可能多使用上述方法收集的关于数据点的信息。 4. 如果在线有手册或网页，指向这些内容的链接有助于理解如何解释上述技术信息 - 即使它们不是英文的，自动翻译也能提供帮助，或者其中的信息可能有助于识别在其他国家/地区以其他品牌销售的、但确实有英文或更详细信息的相同设备。 如果您提交 pull request，请理解配置文件的命名和配置细节可能会在发布前被修改 - 例如，如果您的命名过于笼统，我可能会将其重命名为更具体的名称，或者相反，如果该设备看起来是通用的并以许多品牌销售，我可能会将特定品牌的名称更改为更通用的名称。因此，一旦它被集成到发布版本中，可能需要移除并重新添加您的设备。 ## 安装 [](https://github.com/hacs/integration) 通过 [Home Assistant Community Store (HACS)](https://hacs.xyz/) 安装是最简单的，这是获取 Home Assistant 第三方集成的最佳场所。设置好 HACS 后，只需点击下面的按钮（需要配置 My Homeassistant）或按照[添加自定义存储库的说明](https://hacs.xyz/docs/faq/custom_repositories)进行操作，然后该集成就可以像其他任何集成一样进行安装了。 [](https://my.home-assistant.io/redirect/hacs_repository/?owner=make-all&repository=tuya-local&category=integration) ## 配置 安装后，您可以使用集成配置 UI 轻松配置您的设备。转到“设置 / 设备与服务”并点击“添加集成”按钮，或点击下面的快捷按钮（需要配置 My Homeassistant）。 [](https://my.home-assistant.io/redirect/config_flow_start/?domain=tuya_local) ### 选择您的配置路径 配置设备有两种选择： - 您可以使用 Tuya 或 SmartLife 应用登录 Tuya 云端，并检索设备列表和必要的本地连接数据。 - 您可以[按照 DEVICES_DETAILS.md 中的说明](DEVICE_DETAILS.md#finding-your-device-id-and-local-key)手动提供所有必要的信息。 第一种选择实际上自动化了第二种的所有手动步骤，并且不需要创建 Tuya IOT 开发者帐户。这一点尤其重要，因为 Tuya 现在已开始对 IOT 开发者门户中关键数据访问功能的访问进行时间限制，仅限一个月，并且只能每 6 个月刷新一次该试用。 云端辅助的选择将引导您完成身份验证，从与您的 Tuya 帐户关联的设备列表中选择要添加的设备，在您的本地子网中定位该设备，然后您将进入[阶段一](#stage-one)，其中包含继续进入[阶段二](#stage-two)所需填充完整的数据。 Tuya 身份验证 token 会在几个小时后过期，因此集成不会保存它。但是，只要您不重新启动 Home Assistant，这允许您依次添加多个设备，只需对第一个设备进行一次身份验证。 ### 阶段一 配置的第一阶段是提供连接到设备所需的信息。 使用云端辅助配置时，设备 ID 和 local key 将从云端预先填充，如果不被其他集成或复杂的网络设置阻止本地发现，IP 地址也将被填充。否则，有关如何查找信息的说明，请参见 [DEVICE_DETAILS.md](DEVICE_DETAILS.md)。 #### host     _(字符串) (必填)_ 设备的 IP 或主机名。 #### device_id     _(字符串) (必填)_ 检索到的设备 ID #### local_key     _(字符串) (必填)_ 检索到的本地密钥 请注意，每次配对设备时，本地密钥都会更改，因此如果您使用以下说明获取了本地密钥，然后又与制造商的应用重新配对，则密钥已经更改了。 #### protocol_version     _(字符串或浮点数) (必填)_ 有效选项为“auto”、3.1、3.2、3.3、3.4、3.5、3.22。如果不确定，请选择“auto”，但某些 3.2、3.22 以及可能 3.4 的设备可能会被误检测为 3.3（或反之亦然），因此如果您的设备似乎无法可靠地响应命令，请尝试在这些协议版本之间进行选择。协议 3.22 是一种特殊情况，它启用了 tinytuya 的“device22”检测及协议 3.3。以前我们让 tinytuya 自动检测此项，但发现它有时会将真正的 3.3 设备误检测为 device22，从而阻止它们接收更新，因此添加了显式版本来启用 device22 检测。 在此步骤结束时，会尝试连接到设备并查看它是否返回任何数据。对于 Tuya 协议版本 3.1 的设备，本地密钥仅用于向设备发送命令，因此如果您的本地密钥不正确，设置似乎仍会正常工作，并且直到您尝试控制设备时才会看到任何问题。对于较新的 Tuya 协议版本，本地密钥也用于解密接收到的数据，因此在此步骤中将检测到不正确的密钥并导致立即失败。 ### 阶段二 配置的第二阶段是选择您正在连接的设备。 提供的设备列表将限于与设备返回的数据至少部分匹配的设备。 #### type     _(字符串) (可选)_ Tuya 设备的类型。 从可用选项中选择。 显示的列表经过筛选，排除了在 1000 多种受支持设备中明确不匹配的设备。如果您期望的设备配置未显示，可能是您的固件版本不同，因此报告此问题的最佳方法是将其视为一个新设备。 如果您选择了错误的类型，则需要删除该设备并重新设置。这是因为不同类型的设备会创建不同的实体，因此不建议在不删除所有内容的情况下更改设备类型。 ### 阶段三 最后阶段是在 Home Assistant 中为设备选择一个名称。 如果您有多个相同类型的设备，您可能需要更改名称以便更容易区分它们。 #### name     _(字符串) (必填)_ 设备的任意唯一名称。 这将用作 Home Assistant 中实体名称的基础。 ## 离线操作问题 如果长时间无法连接到 Tuya 服务器，许多 Tuya 设备将停止响应。据报道，如果 DNS 以及 TCP 连接被阻止，某些设备在离线时表现会更好。 ## 常规问题 许多 Tuya 设备无法处理快速连续发送的多个命令。有些设备会重启，在此过程中可能会改变状态，如果使它们超载，其他设备会离线 30 秒到几分钟。存在一些速率限制来尽量避免这种情况，但对于某些设备来说是不够的，并且在您向同一设备上的多个实体发送命令时可能无法跨实体工作。速率限制还会合并命令，而并非所有设备都能处理。如果您从自动化发送命令，最好在命令之间添加延迟 - 如果您的自动化针对多个设备，可能足以先向其他设备发送命令，然后再回来向第一个设备发送第二个命令，或者您可能仍需要在此之后添加延迟。确切的时间取决于设备，因此您可能需要进行实验以找到能够提供可靠结果的最小延迟。 大多数设备可以在单个消息中处理多个命令，因此对于支持它的实体平台（例如，climate `set_temperature` 可以包含预设，灯光的几乎所有设置都是通过 `turn_on` 完成的），会一次发送多个设置。但是有些设备不喜欢这样，并要求所有命令一次只设置一个 dp，因此您可能需要使用自动化进行试验，看看单个命令还是多个命令（带有延迟，见上文）最适合您的设备。 添加设备时，一些最初被检测为协议版本 3.3 的设备需要版本 3.2 才能正常工作。它们要么无法被检测到，要么如果协议设置为 3.3 则仅作为只读工作。 ## 通过网关连接设备 如果您的设备通过网关（例如电池供电的定时器）连接，在添加新设备时您必须提供以下信息： - Device ID (uuid)：这是**网关的**设备 ID - IP 地址或主机名：**网关的** IP 地址或主机名 - Local key：**网关的**本地密钥 - Sub device id：**您想要控制的实际设备**的 `node_id`。请注意，此 `node_id` 与设备 ID 不同，您可以按照下文所述使用 tinytuya 找到它。 ## 安全锁 许多锁设计有基本安全控制，以使解锁更加困难。此集成支持来自 Tuya 的标准 BLE 锁型号，该型号在配对阶段使用一对 dps（60：`remote_no_pd_seykey`，61：`remote_no_dp_key`）在应用和锁之间共享密钥。 如果您有权访问 Tuya 开发者门户，则可以在使用应用远程解锁时窃听这些消息中的第二条。如果您捕获了应用发送的值，则可以使用 base64 解码器（例如 https://base64decode.org）对其进行解码。 其格式为 4 个字节的二进制数据，随后是一个 8 位 ASCII 数字代码，随后是 3 个或 4 个以上的字节二进制数据。 来自配对的第一个应用的 8 位数字代码应该可用于解锁。 尽管这在 Tuya 的 BLE 锁文档中有说明，但 Zigbee 和 WiFi 锁通常对数据点使用相同的命名，这可能与该方案兼容。 ## IR/RF 遥控器 Tuya IR 和 RF 遥控器作为 remote 实体公开，并支持通过标准的 Home Assistant remote 服务学习和发送命令。 ### 学习命令 使用 `remote.learn_command` 服务并带上以下参数： - `command`：用于存储命令的名称（例如 `power`） - `device`：受控电器的名称（例如 `TV`） - `command_type`：设置为 `rf` 用于 RF 遥控器，对于 IR 遥控器请忽略或留空 集成会将遥控器置于学习模式，并等待最多 30 秒供您在原始遥控器上按下按钮。学习到的代码会持久存储并在重启后依然存在。 ### 发送命令 使用 `remote.send_command` 服务并带上与学习时使用的相同 `command` 和 `device` 值。您也可以直接发送代码而无需先学习： - **IR 内联代码**：以 `b64:` 为前缀，后跟 base64 编码的 IR 代码 - **RF 内联代码**：以 `rf:` 为前缀，后跟 base64 编码的 RF 代码 ### UI 如果您希望将学习到的命令作为用户界面中的按钮公开，您可能需要查看与 Tuya Local 兼容的 [Remote buttons](https://github.com/kongo09/remote_buttons) 集成。 ## 贡献 除了贡献设备配置外，以下是一些需要更多人手的领域： 1. 单元测试。由于上游项目，此集成大部分已经过单元测试，但还有几项需要完成。单元测试的重点是 python 代码，当前的覆盖率总结在 github 的报告中，但要获取完整的覆盖详细信息，您可以自己运行测试。 2. 一旦单元测试完成，下一个任务是针对 Home Assistant 质量标准进行正确评估。 3. 发现。本地发现目前仅限于在云端辅助配置中查找 IP 地址。在后台执行发现将允许在网络上发现新设备时发出通知，并为手动配置方法在匹配设备配置时提供可使用的 productKey。

标签：ESP32, ESP8266, Home Assistant, IoT设备管理, Tuya固件, Tuya本地控制, WiFi设备, 家庭自动化, 局域网控制, 开源硬件, 智能家居, 智能家居集成, 智能插座, 智能灯泡, 本地API, 本地网络, 物联网, 特权提升, 绕过云端, 自动化部署, 自定义组件, 设备控制, 逆向工具