{"id":13494639,"url":"https://github.com/make-all/tuya-local","last_synced_at":"2026-03-07T02:28:02.816Z","repository":{"id":37097206,"uuid":"256928684","full_name":"make-all/tuya-local","owner":"make-all","description":"Local support for Tuya devices in Home Assistant","archived":false,"fork":false,"pushed_at":"2025-05-11T02:32:15.000Z","size":11552,"stargazers_count":1828,"open_issues_count":110,"forks_count":680,"subscribers_count":28,"default_branch":"main","last_synced_at":"2025-05-11T03:28:29.222Z","etag":null,"topics":["climate","dehumidifiers","fans","heaters","home-assistant","humidifiers","lights","pool-heaters","switches","tuya"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/make-all.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-04-19T06:16:57.000Z","updated_at":"2025-05-11T02:32:19.000Z","dependencies_parsed_at":"2024-02-15T13:47:02.527Z","dependency_job_id":"f27d1f7b-f794-40c1-a5bc-93c848304b4a","html_url":"https://github.com/make-all/tuya-local","commit_stats":{"total_commits":3721,"total_committers":322,"mean_commits":"11.555900621118013","dds":"0.34909970438054283","last_synced_commit":"b89611bb2da32fa56f1ef1e2fa930f03f4834c96"},"previous_names":[],"tags_count":192,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/make-all%2Ftuya-local","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/make-all%2Ftuya-local/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/make-all%2Ftuya-local/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/make-all%2Ftuya-local/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/make-all","download_url":"https://codeload.github.com/make-all/tuya-local/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254043996,"owners_count":22005054,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["climate","dehumidifiers","fans","heaters","home-assistant","humidifiers","lights","pool-heaters","switches","tuya"],"created_at":"2024-07-31T19:01:26.779Z","updated_at":"2026-03-07T02:28:02.743Z","avatar_url":"https://github.com/make-all.png","language":"Python","funding_links":["https://www.buymeacoffee.com/jasonrumney"],"categories":["Python"],"sub_categories":[],"readme":"# Home Assistant Tuya Local component\r\n\r\nPlease report any [issues](https://github.com/make-all/tuya-local/issues) and feel free to raise [pull requests](https://github.com/make-all/tuya-local/pulls).\r\n[Many others](https://github.com/make-all/tuya-local/blob/main/ACKNOWLEDGEMENTS.md) have contributed their help already.\r\n\r\n[![BuyMeCoffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/jasonrumney)\r\n\r\nThis is a Home Assistant integration to support devices running Tuya\r\nfirmware without going via the Tuya cloud.  Devices are supported\r\nover WiFi, limited support for devices connected via hubs is available.\r\n\r\nNote that many Tuya devices seem to support only one local connection.\r\nIf you have connection issues when using this integration, ensure that\r\nother integrations offering local Tuya connections are not configured\r\nto use the same device, mobile applications on devices on the local\r\nnetwork are closed, and no other software is trying to connect locally\r\nto your Tuya devices.\r\n\r\nUsing this integration does not stop your devices from sending status\r\nto the Tuya cloud, so this should not be seen as a security measure,\r\nrather it improves speed and reliability by using local connections,\r\nand may unlock some features of your device, or even unlock whole\r\ndevices, that are not supported by the Tuya cloud API.\r\n\r\nA similar but unrelated integration is\r\n[rospogrigio/localtuya](https://github.com/rospogrigio/localtuya/), if\r\nyour device is not supported by this integration, you may find it\r\neasier to set up using that as an alternative.\r\n\r\n\r\n---\r\n\r\n## Device support\r\n\r\nNote that devices sometimes get firmware upgrades, or incompatible\r\nversions are sold under the same model name, so it is possible that\r\nthe device will not work despite being listed.\r\n\r\nBattery powered devices such as door and window sensors, smoke alarms\r\netc which do not use a hub will be impossible to support locally, due\r\nto the power management that they need to do to get acceptable battery\r\nlife.\r\n\r\nHubs are currently supported, but with limitations.  Each connection\r\nto a sub device uses a separate network connection, but like other\r\nTuya devices, hubs are usually limited in the number of connections\r\nthey can handle, with typical limits being 1 or 3, depending on the specific\r\nTuya module they are using.  This severely limits the number of sub devices\r\nthat can be connected through this integration.\r\n\r\nSub devices should be added using the `device_id`, `address` and `local_key`\r\nof the hub they are attached to, and the `node_id` of the sub-device. If there\r\nis no `node_id` listed, try using the `uuid` instead.\r\n\r\nTuya Zigbee devices are usually standard zigbee devices, so as an\r\nalternative to this integration with a Tuya hub, you can use a\r\nsupported Zigbee USB stick or Wifi hub with\r\n[ZHA](https://www.home-assistant.io/integrations/zha/#compatible-hardware)\r\nor [Zigbee2MQTT](https://www.zigbee2mqtt.io/guide/adapters/).\r\n\r\nTuya Bluetooth devices can be supported directly by the\r\n[tuya_ble](https://github.com/PlusPlus-ua/ha_tuya_ble/) integration.\r\n\r\nTuya IR hubs that expose general IR remotes as sub devices usually\r\nexpose them as one way devices (send only).  Due to the way this\r\nintegration does device detection based on the dps returned by the\r\ndevice, it is not currently able to detect such devices at all.  Some\r\nspecialised IR hubs for air conditioner remote controls do work, as\r\nthey try to emulate a fully smart air conditioner using internal memory\r\nof what settings are currently set, and internal temperature and humidity\r\nsensors.\r\n\r\nSome Tuya hubs now support Matter over WiFi, and this can be used as an\r\nalternative to this integration for connecting the hub and sub-devices\r\nto Home Assistant. Other limitations will apply to this, so you might want\r\nto try both, and only use this integration for devices that are not working\r\nproperly over Matter.\r\n\r\nA list of currently supported devices can be found in the [DEVICES.md](https://github.com/make-all/tuya-local/blob/main/DEVICES.md) file.\r\n\r\nDocumentation on building a device configuration file is in [/custom_components/tuya_local/devices/README.md](https://github.com/make-all/tuya-local/blob/main/custom_components/tuya_local/devices/README.md)\r\n\r\nIf your device is not listed, you can find the information required to add a configuration for it in the following locations:\r\n\r\n1. When attempting to add the device, if it is not supported, you will either get a message saying the device cannot be recognised at all, or you will be offered a list of devices that are partial matches. You can cancel the process at this point, and look in the Home Assistant log - there should be a message there containing the current data points (dps) returned by the device.\r\n2. If you have signed up for [iot.tuya.com](https://iot.tuya.com/) to get your local key, you should also have access to the API Explorer under \"Cloud\". Under \"Device Control\" there is a function called \"Query Things Data Model\", which returns the dp_id in addition to range information that is needed for integer and enum data types.\r\n\r\nIf you file an issue to request support for a new device, please include the following information:\r\n\r\n1. Identification of the device, such as model and brand name.\r\n2. As much information on the datapoints you can gather using the above methods.\r\n3. If manuals or webpages are available online, links to those help understand how to interpret the technical info above - even if they are not in English automatic translations can help, or information in them may help to identify identical devices sold under other brands in other countries that do have English or more detailed information available.\r\n\r\nIf you submit a pull request, please understand that the config file naming and details of the configuration may get modified before release - for example if your name was too generic, I may rename it to a more specific name, or conversely if the device appears to be generic and sold under many brands, I may change the brand specific name to something more general.  So it may be necessary to remove and re-add your device once it has been integrated into a release.\r\n\r\n---\r\n\r\n## Installation\r\n\r\n[![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg?style=for-the-badge)](https://github.com/hacs/integration)\r\n\r\nInstallation is easiest via the [Home Assistant Community Store\r\n(HACS)](https://hacs.xyz/), which is the best place to get third-party\r\nintegrations for Home Assistant. Once you have HACS set up, simply click the button below (requires My Homeassistant configured) or\r\nfollow the [instructions for adding a custom\r\nrepository](https://hacs.xyz/docs/faq/custom_repositories) and then\r\nthe integration will be available to install like any other.\r\n\r\n[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=make-all\u0026repository=tuya-local\u0026category=integration)\r\n\r\n## Configuration\r\n\r\nAfter installing, you can easily configure your devices using the Integrations configuration UI.  Go to Settings / Devices \u0026 Services and press the Add Integration button, or click the shortcut button below (requires My Homeassistant configured).\r\n\r\n[![Add Integration to your Home Assistant\r\ninstance.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=tuya_local)\r\n\r\n### Choose your configuration path\r\n\r\nThere are two options for configuring a device:\r\n- You can login to Tuya cloud with the Smart Life app and retrieve a list of devices and the necessary local connection data.\r\n- You can provide all the necessary information manually [as per the instructions below](#finding-your-device-id-and-local-key).\r\n\r\nThe first choice essentially automates all the manual steps of the second and without needing to create a Tuya IOT developer account. This is especially important now that Tuya has started time limiting access to a key data access capability in the IOT developer portal to only a month with the ability to refresh the trial of that only every 6 months.\r\n\r\nThe cloud assisted choice will guide you through authenticating, choosing a device to add from the list of devices associated with your Smart Life account, locate the device on your local subnet and then drop you into [Stage One](#stage-one) with fully populated data necessary to move forward to [Stage Two](#stage-two).\r\n\r\nThen Smart Life authentication token expires after a small number of hours and so is not saved by the integration. But, as long as you don't restart Home Assistant, this allows you to add multiple devices one after another only needing to authenticate once for the first one.\r\n\r\n### Stage One\r\n\r\nThe first stage of configuration is to provide the information needed to connect to the device.\r\n\r\nYou will need to provide your device's IP address or hostname, device\r\nID and local key; the last two can be found using [the instructions\r\nbelow](#finding-your-device-id-and-local-key).\r\n\r\n#### host\r\n\r\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;_(string) (Required)_ IP or hostname of the device.\r\n\r\n#### device_id\r\n\r\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;_(string) (Required)_ Device ID retrieved\r\n[as per the instructions below](#finding-your-device-id-and-local-key).\r\n\r\n#### local_key\r\n\r\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;_(string) (Required)_ Local key retrieved\r\n[as per the instructions below](#finding-your-device-id-and-local-key).\r\n\r\n\r\n#### protocol_version\r\n\r\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;_(string or float) (Required)_ Valid options are \"auto\", 3.1, 3.2, 3.3, 3.4, 3.5, 3.22.  If you aren't sure, choose \"auto\", but some 3.2, 3.22 and maybe 3.4 devices may be misdetected as 3.3 (or vice-versa), so if your device does not seem to respond to commands reliably, try selecting between those protocol versions. Protocol 3.22 is a special case, that enables tinytuya's \"device22\" detection with protocol 3.3. Previously we let tinytuya auto-detect this, but it was found to sometimes misdetect genuine 3.3 devices as device22 which stops them receiving updates, so an explicit version was added to enable the device22 detection.\r\n\r\nAt the end of this step, an attempt is made to connect to the device and see if\r\nit returns any data. For tuya protocol version 3.1 devices, the local key is\r\nonly used for sending commands to the device, so if your local key is\r\nincorrect the setup will appear to work, and you will not see any problems\r\nuntil you try to control your device.  For more recent Tuya protocol versions,\r\nthe local key is used to decrypt received data as well, so an incorrect key\r\nwill be detected at this step and cause an immediate failure.  Note that each\r\ntime you pair the device, the local key changes, so if you obtained the\r\nlocal key using the instructions below, then re-paired with your\r\nmanufacturer's app, then the key will have changed already.\r\n\r\n\r\n### Stage Two\r\n\r\nThe second stage of configuration is to select which device you are connecting.\r\nThe list of devices offered will be limited to devices which appear to be\r\nat least a partial match to the data returned by the device.\r\n\r\n#### type\r\n\r\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;_(string) (Optional)_ The type of Tuya device.\r\nSelect from the available options.\r\n\r\nIf you pick the wrong type, you will need to delete the device and set\r\nit up again. This is because different types of devices create different\r\nentities, so changing the device type without deleting everything is\r\nnot easy.\r\n\r\n### Stage Three\r\n\r\nThe final stage is to choose a name for the device in Home Assistant.\r\n\r\nIf you have multiple devices of the same type, you may want to change\r\nthe name to make it easier to distinguish them.\r\n\r\n#### name\r\n\r\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;_(string) (Required)_ Any unique name for the\r\ndevice.  This will be used as the base for the entity names in Home\r\nAssistant.  Although Home Assistant allows you to change the name\r\nlater, it will only change the name used in the UI, not the name of\r\nthe entities.\r\n\r\n## Offline operation issues\r\n\r\nMany Tuya devices will stop responding if unable to connect to the\r\nTuya servers for an extended period.  Reportedly, some devices act\r\nbetter offline if DNS as well as TCP connections is blocked.\r\n\r\n## General issues\r\n\r\nMany Tuya devices do not handle multiple commands sent in quick\r\nsuccession.  Some will reboot, possibly changing state in the process,\r\nothers will go offline for 30s to a few minutes if you overload them.\r\nThere is some rate limiting to try to avoid this, but it is not\r\nsufficient for many devices, and may not work across entities where\r\nyou are sending commands to multiple entities on the same device.  The\r\nrate limiting also combines commands, which not all devices can\r\nhandle. If you are sending commands from an automation, it is best to\r\nadd delays between commands - if your automation is for multiple\r\ndevices, it might be enough to send commands to other devices first\r\nbefore coming back to send a second command to the first one, or you\r\nmay still need a delay after that.  The exact timing depends on the\r\ndevice, so you may need to experiment to find the minimum delay that\r\ngives reliable results.\r\n\r\nSome devices can handle multiple commands in a single message, so for\r\nentity platforms that support it (eg climate `set_temperature` can\r\ninclude presets, lights pretty much everything is set through\r\n`turn_on`) multiple settings are sent at once.  But some devices do\r\nnot like this and require all commands to set only a single dp at a\r\ntime, so you may need to experiment with your automations to see\r\nwhether a single command or multiple commands (with delays, see above)\r\nwork best with your devices.\r\n\r\nWhen adding devices, some devices that are detected as protocol version\r\n3.3 at first require version 3.2 to work correctly. Either they cannot be\r\ndetected, or work as read-only if the pprotocol is set to 3.3.\r\n\r\n## Finding your device ID and local key\r\n\r\n### Tuya IoT developer portal\r\n\r\nThe easiest way to find your local key is with the Tuya Developer portal.\r\nIf you have previously configured the built in Tuya cloud integration, or\r\nlocaltuya, you probably already have a developer account with the Tuya app\r\nlinked.  Note that you need to use Tuya's own branded \"Tuya Smart\" or\r\n\"SmartLife\" apps to access devices through the developer portal.  For most\r\ndevices, your device will work identically with those apps as it does with\r\nyour manufacturer's branded app, but there are a few devices where that is\r\nnot the case and you will need to decide whether you are willing to potentially\r\nlose access to some functionality (such as mapping for some vacuum cleaners).\r\n\r\nIf you log on to your Developer Portal account, under Cloud you should\r\nbe able to get a list of your devices, which contains the \"Device ID\".\r\nIf you don't see them, check your server is set correctly at the top\r\nof the page.  Make a note of the Device IDs for all your devices, then\r\nselect Cloud on the side bar again and go to the API Explorer.\r\n\r\nUnder \"Devices Management\", select the \"Query Device Details in Bulk\"\r\nfunction, and enter your Device IDs, separated by commas.\r\nIn the results you should see your local_key.\r\n\r\nThe IP address you should be able to get from your router.  Using a\r\ncommand line Tuya client like tuyaapi/cli or\r\n[tinytuya](https://github.com/jasonacox/tinytuya) you may also be able\r\nto scan your network for Tuya devices to find the IP address and also automate\r\nthe above process of connecting to the portal and getting the local key.\r\n\r\n### Finding device ids and local keys with tinytuya\r\n\r\nYou can use this component's underlying library [tinytuya](https://github.com/jasonacox/tinytuya) to scan for devices in your network and find the required information about them. In particular, you need to use this procedure to obtain the `node_id` value required to connect to hub-dependent devices.\r\n\r\nBefore running tinytuya's wizard you need to gather your API credentials so head to [Tuya's Developer Portal](https://iot.tuya.com) -\u003e Cloud -\u003e Development -\u003e Open project and make a note of:\r\n\r\n- Access ID/Client ID\r\n- Access Secret/Client Secret\r\n\r\nNext, go to the \"Devices\" tab and note your device id (any of them will work). Also note your region (eg. \"Central Europe Data Center\") in the combobox at the top right of the page.\r\n\r\nThen, open a terminal in your HA machine and run:\r\n\r\n```sh\r\npython -m tinytuya wizard\r\n```\r\n\r\nAnswer the following:\r\n\r\n- Enter API Key from tuya.com: your \"Access ID/Client ID\"\r\n- Enter API Secret from tuya.com: your \"Access Secret/Client Secret\"\r\n- Enter any Device ID currently registered in Tuya App (used to pull full list) or 'scan' to scan for one: your device id\r\n- Enter Your Region: your datacenter's region\r\n- Download DP Name mappings? (Y/n): Y\r\n- Poll local devices? (Y/n): Y\r\n\r\nIf your device supports local connections and is in the same network as your HA instance this should find it and report its IP address.\r\n\r\nIn the `devices.json` file you will everything you need to add your device:\r\n\r\n- \"id\": the device id\r\n- \"key\": the local key\r\n- \"node_id\": the sub-device id. You need this for hub-dependent devices\r\n- \"mapping\": in the unfortunate case your device is not [yet supported](DEVICES.md), this key contains a description of all the datapoints reported by the device, type and expected values. You are more than welcome to create a new device specification following [the guidelines](custom_components/tuya_local/devices/README.md) and submitting a PR.\r\n\r\n## Connecting to devices via hubs\r\n\r\nIf your device connects via a hub (eg. battery powered water timers) you have to provide the following info when adding a new device:\r\n\r\n- Device id (uuid): this is the **hub's** device id\r\n- IP address or hostname: the **hub's** IP address or hostname\r\n- Local key: the **hub's** local key\r\n- Sub device id: the **actual device you want to control's** `node_id`. Note this `node_id` differs from the device id, you can find it with tinytuya as described below.\r\n\r\n## Next steps\r\n\r\n1. This component is mostly unit-tested thanks to the upstream project, but there are a few more to complete. Feel free to use existing specs as inspiration and the Sonar Cloud analysis to see where the gaps are.\r\n2. Once unit tests are complete, the next task is to complete the Home Assistant quality checklist before considering submission to the HA team for inclusion in standard installations.\r\n3. Discovery seems possible with the new tinytuya library, though the steps to get a local key will most likely remain manual.  Discovery also returns a productKey, which might help make the device detection more reliable where different devices use the same dps mapping but different names for the presets for example.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmake-all%2Ftuya-local","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmake-all%2Ftuya-local","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmake-all%2Ftuya-local/lists"}