search

0x5e / homebridge-tuya-platform

Make homebridge-tuya-platform great again.
MIT License
223 stars 67 forks source link
homebridge homekit tuya

readme

@0x5e/homebridge-tuya-platform

npm npm mit-license verified-by-homebridge Build and Lint join-discord

Fork version of the official Tuya Homebridge plugin, with a focus on fixing bugs and adding new device support.

⚠️Update on 2024.1.14: Thanks for the attention on this project. There's more and more "problem device", which has wrong definition by manufacture (reversed 0%-100% state, wrong range, wrong unit, ...). Support them one by one really cost a lot. I'm not going to support them in the future, please try solve them by yourself. PRs are still welcome, and bugs will be focused. Thanks again :)

Features

Supported Tuya Devices

See SUPPORTED_DEVICES.md

Changelogs

See CHANGELOG.md

Installation

Before using this plugin, please make sure to uninstall homebridge-tuya-platform first as these two plugins cannot run simultaneously. However, the configuration files are compatible, so there's no need to delete them.

For Homebridge Web UI Users

Go to plugin page, search for @0x5e/homebridge-tuya-platform and install it.

For Homebridge Command Line Users

Run the following command in the terminal:

npm install @0x5e/homebridge-tuya-platform

Configuration

There are two types of projects: Custom and Smart Home. The difference between them is:

If you are a personal user and are unsure which one to choose, please use the Smart Home project.

Before you can configure, you must go to the Tuya IoT Platform:

For "Custom" Project

For "Smart Home" Project

Advanced options

See ADVANCED_OPTIONS.md

Limitations

FAQ

About Login issue

For most users, you can easily find your app account's data center through the documentation and login without any issues. However, for some users, they may encounter error codes such as 1106 or 2406. If you encounter such errors, it's possible that there are differences between your data center and the documentation.

To determine the data center, follow these steps:

  1. Open the app and navigate to "Me > Settings > Network Diagnosis".
  2. Start the diagnosis and select "Upload Log > Copy the Log to Clipboard".
  3. Paste the log anywhere and find the line beginning with "Region code:".
  4. Look for the following codes: "AY" for China, "AZ" for the West US, "EU" for Central Europe, and "IN" for India.

Then manually specify endpoint in the plugin config.

What is "Standard DP" and "Non-standard DP"?

"Standard DP" refers to device properties or functionalities that are specified in the Tuya IoT Development Platform documentation at Tuya IoT Development Platform Documentation > Cloud Development > Standard Instruction Set.

For example, a light bulb should have a standard DP code of switch_led for power on/off, and optional codes bright_value/bright_value_v2 for brightness, temp_value/temp_value_v2 for color temperature, and work_mode for changing the working mode. These codes can be found in the above documentation.

If your light bulb can be adjusted in the Tuya app but not with the plugin, it most likely has "Non-standard DP."

Can "Non-standard DP" be supportd by this plugin?

Yes. The device must be listed in the support list and the following steps must be completed before it will work:

  1. Change the device's control mode on the Tuya Platform:
    • Go to "Tuya Platform Cloud Development > Your Project > Devices > All Devices > View Devices by Product".
    • Find the product related to your device, click the "pencil" icon (Change Control Instruction Mode).
    • image
    • In the "Table of Instructions", you can see the cloud mapping and determine which DP codes are missing and need to be manually mapped later.
    • image
    • Select "DP Instruction" and save.
  2. Override the device schema, see ADVANCED_OPTIONS.md.

Local support

See #90.

Although the plugin didn't implemented tuya local protocol now, it still remains possibility in the future.

Troubleshooting

If your device is not supported, please follow these steps to collect information.

1. Get Device Information

After Homebridge has been successfully launched, the device information list will be saved in Homebridge's persist path. You can find the file path in the Homebridge log:

[2022/11/3 18:37:43] [TuyaPlatform] Device list saved at /path/to/TuyaDeviceList.{uid}.json

⚠️Please make sure to remove sensitive information such as ip, lon, lat, local_key, and uid before submitting the file.

2. Enable Debug Mode

Add debug option in the plugin config, then restart Homebridge.

3. Collect Logs

With debug mode enabled, you can now receive MQTT logs. Operate your device, either physically or through the Tuya App, to receive MQTT logs like this:

[2022/12/8 12:51:59] [TuyaPlatform] [TuyaOpenMQ] onMessage:
topic = cloud/token/in/xxx
protocol = 4
message = {
  "dataId": "xxx",
  "devId": "xxx",
  "productKey": "xxx",
  "status": [
    {
      "1": "double_click",
      "code": "switch1_value",
      "t": "1670475119766",
      "value": "double_click"
    }
  ]
}

If you are unable to receive any MQTT logs while controlling the device, it likely means that your device has "Non-standard DP".

By submitting the device information JSON and MQTT logs, you can help us support new device categories.

Contributing

Please see https://github.com/homebridge/homebridge-plugin-template#setup-development-environment for setup development environment.

PRs and issues are welcome.

Thank you for spend time using the project. If it helps you, don't hesitate to give it a star 🌟:-)