{"id":18217275,"url":"https://github.com/pascal-fb-martin/housetuya","last_synced_at":"2026-05-02T06:39:03.089Z","repository":{"id":259384927,"uuid":"877724228","full_name":"pascal-fb-martin/housetuya","owner":"pascal-fb-martin","description":"A web service to control Tuya devices locally","archived":false,"fork":false,"pushed_at":"2024-10-25T00:13:35.000Z","size":52,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-25T01:40:50.762Z","etag":null,"topics":["home-automation","raspberry","raspberry-pi","raspbian","smart-home","smart-switches","smarthome","tuya","tuya-devices","tuya-iot"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pascal-fb-martin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-24T06:16:02.000Z","updated_at":"2024-10-25T00:31:16.000Z","dependencies_parsed_at":"2024-10-25T01:52:55.887Z","dependency_job_id":"09a21d59-d958-462a-b625-b62227f7ecd5","html_url":"https://github.com/pascal-fb-martin/housetuya","commit_stats":null,"previous_names":["pascal-fb-martin/housetuya"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pascal-fb-martin%2Fhousetuya","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pascal-fb-martin%2Fhousetuya/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pascal-fb-martin%2Fhousetuya/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pascal-fb-martin%2Fhousetuya/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pascal-fb-martin","download_url":"https://codeload.github.com/pascal-fb-martin/housetuya/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247737121,"owners_count":20987714,"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":["home-automation","raspberry","raspberry-pi","raspbian","smart-home","smart-switches","smarthome","tuya","tuya-devices","tuya-iot"],"created_at":"2024-11-03T17:04:17.417Z","updated_at":"2026-05-02T06:39:03.084Z","avatar_url":"https://github.com/pascal-fb-martin.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HouseTuya\n\nA House web service to control Tuya devices (lights, plugs, valves..)\n\n## Overview\n\nThis is a web server to give access to Tuya WiFi devices. This server can sense the current status and control the state of each device. The web API is meant to be compatible with the [House control API](https://github.com/pascal-fb-martin/houseportal/blob/master/controlapi.md).\n\nThis service is not really meant to be accessed directly by end-users: these should use [houselights](https://github.com/pascal-fb-martin/houselights) to control Tuya devices.\n\nSo far HouseTuya has been tested with the following US models:\n\n* Feit Electric Smart Bulbs (Costco)\n\nThis service is not dependent on the Tuya cloud.\n\n## Installation\n\n* Install the OpenSSL development package(s).\n* Install [echttp](https://github.com/pascal-fb-martin/echttp).\n* Install [houseportal](https://github.com/pascal-fb-martin/houseportal).\n* Clone this GitHub repository.\n* make\n* sudo make install\n* Edit /etc/house/Tuya.json (see below)\n\nOtherwise installing [houselights](https://github.com/pascal-fb-martin/houselights) is recommended, but not necessarily on the same computer.\n\nThe [housesaga](https://github.com/pascal-fb-martin/housesaga) and [housedepot](https://github.com/pascal-fb-martin/housedepot) projects are also highly recommended, to store logs and configuration files in a more centralized fashion.\n\n## Initial Device Setup\n\nEach device must be setup using the Feit Electric phone app, or the phone app recommended by your specific vendor. The protocol for setting up devices has not been reverse engineered at that time.\n\n## Configuration\nThe preferred method is to configure the devices from the Configure web page.\nThe configuration is stored in file /etc/house/tuya.json. A typical example of configuration is:\n\n```\n{\n    \"tuya\" : {\n        \"devices\" : [\n            {\n                \"name\" : \"light1\",\n                \"id\" : \"xxxxxxxxxx\",\n                \"model\" : \"xxxxxxxxxx\",\n                \"key\" : \"xxxxxxxxxx\",\n                \"host\" : \"192.168.x.y\",\n                \"description\" : \"a Tuya light\"\n            },\n            {\n                \"name\" : \"light2\",\n                \"id\" : \"xxxxxxxxxx\",\n                \"model\" : \"xxxxxxxxxx\",\n                \"key\" : \"xxxxxxxxxx\",\n                \"host\" : \"192.168.x.z\",\n                \"description\" : \"another Tuya light\"\n            }\n        ],\n        \"models\": [\n            {\n                \"name\" : \"vendor model\",\n                \"id\" : \"xxxxxxxxx\",\n                \"control\" : 20, (or some other DP ID value)\n            }\n        ]\n    }\n}\n```\n\nThe \"key\" field represents the device's local key and is required if the device uses the Tuya protocol version 3.3 or above. Other information (i.e. \"host\", protocol version, etc.) is retrieved by listening to the devices present on the network.\n\nThe devices \"model\" and \"host\" fields are saved in the configuration for information only. The application does not use these fields because information is provided by the devices itself during discovery.\n\nThis application automatically detects every Tuya device currently active on the network and add any unknown device to the configuration. Only the \"id\", \"model\" and \"host\" fields will be populated when a new device has been detected: the \"name\", \"key\" and \"description\" fields are to be manually populated by the user.\n\nEvery Tuya device is controlled by changing the value of data points, and monitored by querying the current value of these data points. Each data point is identified by an index number (starting at 1). The meaning of each data point may change from model to model. You cannot even really rely on a type of device (like a light bulb or switch): each vendor may have changed the mapping. The result is an horrible mess better illustrated by the complexity of the Tuya web UI used to query these device details and properties. (On the plus side, this makes Tuya very flexible and adjustable to every possible type of devices.)\n\nA list of some Tuya models is provided by the [localtuya](https://github.com/rospogrigio/localtuya/wiki/Known-working-and-non-working-devices) project. To obtain a description of the data points for other models, one should check the vendor's documentation, or query the device details in the Device Control section of a Tuya IOT projects (this requires setting up a developer account and creating one dummy IOT project, a.k.a. \"Cloud\".)\n\nThe product key can be used to identify what model the device belongs to.\n\nAt this time, this application is only concerned with the data point linked to the on/off command.\n\nA list of known models is included in the configuration. The application comes with a (rather incomplete) initial list, and the user must manually add an entry for each model present on his network.\n\n## Obtaining the Local Key\n\nThe local key is not disclosed by the device, obviously. The only way to obtain this key is to \"extend\" your account (created using the Tuya app) into a free developper account and then create an IOT project (also known as a Cloud project).\n\nOnce this was done, the devices initialized through the Tuya app can be listed, and their details revealed. The Tuya web site changes from time to time, so this is a discovery expedition every time.\n\nA free Tuya developer account expires after a month or so, but it can be renewed when needed.\n\n## Tuya Protocol\n\nThis section describes the subset of the Tuya LAN protocol that is implemented in HouseTuya. This is not a complete description of the Tuya protocol.\n\nInformation about the tuya protocol came thanks to the [tinytuya](https://github.com/jasonacox/tinytuya project) project and its debug output. You can also look at project [tuyapi](https://github.com/codetheweb/tuyapi).\n\nNote that some discrepancies in the protocol used by different device types might be attributed to the firmware version: when identifying a device it is recommended to consider both the type of device and the firmware version.\n\nAll commands and responses contain an encrypted JSON structure. The AES encryption is used in ECB mode.\n\nThe Tuya protocol uses ports 6666 and 6667 (UDP) and 6668 (TCP).\n\nEach JSON payload is prefixed with an envelop that provides a sequence number, a command code and a payload length. UDP packets do not use sequence number (always 0).\n\nThe UDP messages are periodically broadcasted by the device, as an automatic discovery mechanism. Firmware version 3.1 uses port 6666, while firmware version 3.3 or higher uses port 6667. Payloads for version 3.3 and higher are encrypted using AES in ECB mode and a hard coded key.\n\nThe status of each device is represented by a set of _data points_. Each data points is identified by a number. See (the TinyTuya project)[https://github.com/jasonacox/tinytuya] for a list of data points for each type of devices. One important detail is that the mapping of points is different for each type of device, so turning a device on and off may be a different data point. The type of the device must be identified before one can interpret the status. Controls (if supported) are implemented by setting the same data point to the desired state.\n\n### How HouseTuya Uses the Tuya Protocol\n\nThis section describes what subset and variant of the local Tuya protocol is used by the HouseTuya service.\n\n#### Detect device:\n\nThe device message:\n\n```\n{'ip': '192.168.1.xxx', 'gwId': '\u003cID\u003e', 'active': 2, 'ablilty': 0, 'encrypt': True, 'productKey': '\u003cBLTID\u003e', 'version': '3.3'}\n```\n\n(ProductKey seems to be the BlueTooth's device ID.)\n\nThat message is encrypted for versions 3.3 and higher, using a harcoded key.\n\n#### Query device status:\n\nThe request:\n\n```\n{\"gwId\":\"\u003cID\u003e\",\"devId\":\"\u003cID\u003e\",\"uid\":\"\u003cID\u003e\",\"t\":\"\u003cTIME\u003e\"}\n```\n\n(gwId, DevId and uid are the same if the unit houses a single device. The 't' item is the current time.)\n\nThe response from the device (a RGB liht bulb in this example):\n\n```\n{\"dps\":{\"20\":true,\"21\":\"white\",\"22\":1000,\"23\":0,\"24\":\"003702cd034f\",\"25\":\"000e0d0000000000000000c80000\",\"26\":0}}\n```\n\nEach \"numbered item\" (data point) is a specific portion of the device's state: on/off state, color, dimming level, etc.\n\n#### Turn off the light\n\nThe request for an RGB light bulb:\n\n```\n{\"devId\":\"\u003cID\u003e\",\"uid\":\"\u003cID\u003e\",\"t\":\"\u003cTIME\u003e\",\"dps\":{\"20\":false}}\n```\n\n(DevId and uid are the same if the unit houses a single device. The 't' item is the current time.)\n\nThe response:\n\n```\n{\"dps\":{\"20\":false},\"t\":\"\u003cTIME\u003e\"}\n```\n\nThe request for a dimmer switch:\n\n```\n{\"devId\":\"\u003cID\u003e\",\"uid\":\"\u003cID\u003e\",\"t\":\"\u003cTIME\u003e\",\"dps\":{\"1\":false}}\n```\n\nThe response:\n\n```\nTBD\n```\n\n#### Turn on the light\n\nThe request for an RGB light bulb:\n\n```\n{\"devId\":\"\u003cID\u003e\",\"uid\":\"\u003cID\u003e\",\"t\":\"\u003cTIME\u003e\",\"dps\":{\"20\":true}}\n```\n\n(DevId and uid are the same if the unit houses a single device. The 't' item is the current time.)\n\nNote: item t may not need to be quoted (see response).\n\nThe response:\n\n```\n{\"dps\":{\"20\":true},\"t\":\u003cTIME\u003e}\n```\n\nThe request for a dimmer switch:\n\n```\n{\"devId\":\"\u003cID\u003e\",\"uid\":\"\u003cID\u003e\",\"t\":\"\u003cTIME\u003e\",\"dps\":{\"1\":true}}\n```\n\nThe response:\n\n```\nTBD\n```\n\n## Debian Packaging\n\nThe provided Makefile supports building private Debian packages. These are _not_ official packages:\n\n- They do not follow all Debian policies.\n\n- They are not built using Debian standard conventions and tools.\n\n- The packaging is not separate from the upstream sources, and there is\n  no source package.\n\nTo build a Debian package, use the `debian-package` target:\n\n```\nmake debian-package\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpascal-fb-martin%2Fhousetuya","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpascal-fb-martin%2Fhousetuya","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpascal-fb-martin%2Fhousetuya/lists"}