search

milo526 / homebridge-tuya-web

Hoobs and Homebridge plugin for Tuya devices using Home Assistant Tuya Web Api
MIT License
217 stars 93 forks source link
homebridge homebridge-plugin hoobs tuya

readme

Tuya Web

verified-by-homebridge certified-by-hoobs

npm npm npm GitHub release License: MIT

Homebridge Discord GitHub issues GitHub pull requests

Overview

Hoobs and Homebridge plugin for Tuya devices using a cloud Tuya Web Api.

This plugin is based on the Home Assistant Tuya integration that implements a special Tuya Home Assistant API.

See Home Assistant Tuya integration and Tuyaha python library.

Features

This plugin implements the following features:

Installation

npm i -g @milo526/homebridge-tuya-web

Support

Please notice that there is no official support for this plugin.
If you have a question, please start a discussion.
If you would like to report a bug, please open an issue.

You can also get community help in the Homebridge Discord Server or on the Homebridge Reddit.

Homebridge Discord Homebridge Reddit

Configuration

:check: The preferred and always up-to-date way to configure this plugin is through the config UI.
For details check their documentation.

{
  "platform": "TuyaWebPlatform",
  "name": "TuyaWebPlatform",
  "options": {
    "username": "xxxx@gmail.com",
    "password": "xxxxxxxxxx",
    "countryCode": "xx",
    "platform": "tuya"
  }
}

The options has these properties:

:warning: Sign-in with Apple, Google, Facebook or any other provider is not supported and, due to limitations, will probably never be supported :warning:
Please make sure your account is created using a plain old username and password combination.

All option outlines below are optional, they are useful to provide finer control on the working of the plugin.

Overruling Device Types

It is possible to override values from the default. As of now, only overruling device types is possible. See example configuration below.

{
  "platform": "TuyaWebPlatform",
  "name": "TuyaWebPlatform",
  "options": {},
  "defaults": [
    {
      "id": "<device name or id>",
      "device_type": "<desired device type>"
    }
  ]
}

The defaults has these properties:

Note: After overriding the device type, it might appear duplicated in both HomeBridge (Accessories Tab) and the Home App. To solve this issue, go to the Homebridge settings (top right corner) and remove the device using the Remove Single Cached Accessory option.

Configure Devices

Some devices allow for extra configuration.
The easiest option is to do this through Homebridge Config UI X.
In the plugin settings, go to "Device Settings" and click on "Add Device Settings".
Add the device ID (or name) and select the device type.
If the given device type allows overwriting settings, the options will appear below.

Thermostat/Climate

These devices can have a minimum- and maximum temperature, as well as a temperature factor.

The minimum and maximum values must be entered as degrees Celsius with half degree increments; i.e. -16, 5, 23, 32.5.
This will influence the minimum and maximum temperature that you will be able to set the thermostat at in HomeKit.

The temperature factor can be used to influence the shown temperature. If HomeKit is showing an extremely high temperature, please try setting this value to 0.1. This will change the shown value from i.e. 220 to 220 * 0.1 = 22. The value entered here must be a positive decimal value i.e. 0.1, 1, 2.5.

If desired, you can overwrite these devices to the temperature sensor. This will only report the current temperature and not allow you to change the temperature.

Hiding devices

There are some valid reasons why you might not want to expose certain devices to HomeKit. You might for example have another plugin active which also exposes certain Tuya devices, adding these devices to this list will prevent them from showing up multiple times.

{
  "platform": "TuyaWebPlatform",
  "name": "TuyaWebPlatform",
  "options": {},
  "hiddenAccessories": ["<device name or id>"]
}

Whitelisting scenes

To prevent an overload of scenes clogging up your HomeKit devices, scenes are by default not exposed to HomeKit. When you wish to add Tuya scenes to homekit, you will need to add them to the whitelist.

Add all scenes to HomeKit

You can add all your tuya scenes to HomeKit by setting the scenes key to true.

{
  "platform": "TuyaWebPlatform",
  "name": "TuyaWebPlatform",
  "options": {},
  "scenes": true
}

Add specific scenes to HomeKit

To add specific scenes to HomeKit, you can set the scenes key to true and set scenesWhitelist to an array in which you define either the names or IDs of the scenes that you'd wish to expose.

{
  "platform": "TuyaWebPlatform",
  "name": "TuyaWebPlatform",
  "options": {},
  "scenes": true,
  "scenesWhitelist": ["Scene-id", "Scene-name"]
}

Add no scenes to HomeKit

To explicitly disable scene support, set the scenes key to false.

Supported Device Types

There is currently support for the following device types within this plugin:

How to check whether the API this library uses can control your device?

Determining platform for branded devices

The Tuya cloud supports different branded platforms. If your devices came with a branded app, then it is likely that your username and password are not recognized by the Tuya platform. If the app that came with your devices is not for one of the supported platforms (tuya, _smartlife or _jinvoosmart) your best bet is to check which of the apps for the supported platforms recognizes your devices. Unregister your device from the branded app (so that they are "factory clean" again) and then try re-registering them in the app for one of the supported platforms.

The device checking script above can help you to debug this.

Additional Resources

If you need more assistance regarding Plugin installation, please have a look at the following external resources: