Added new Tuya v2 Integration (home-assistant#19525)

source/_integrations/tuya.markdown

@@ -2,7 +2,6 @@
 title: Tuya
 description: Instructions on how to setup the Tuya hub within Home Assistant.
 ha_category:
-  - Hub
   - Climate
   - Cover
   - Fan
@@ -14,7 +13,7 @@ ha_release: 0.74
 ha_config_flow: true
 ha_domain: tuya
 ha_codeowners:
-  - '@ollo69'
+  - '@zlinoliver'
 ha_platforms:
   - climate
   - cover
@@ -25,79 +24,108 @@ ha_platforms:
 ha_dhcp: true
 ---
 
-The `tuya` integration is the main integration to integrate [Tuya Smart](https://www.tuya.com) related platforms, except the Zigbee and Bluetooth(BLE) hub. This includes devices linked with the Tuya, Smart Life, and Jinvoo Smart apps. You will need your account information (username, password and account country code) from one of these apps to discover and control devices which related to your account.
+The Tuya integration allows integrating all Powered by Tuya devices you have added to the Tuya Smart and Tuya Smart Life apps. This integration is officially maintained by Tuya.
 
-**Important**: Not all Tuya devices are supported by the `tuya API` used by this integration. For more details refer to [TuyaHA Library](https://github.com/PaulAnnekov/tuyaha).
+{% include integrations/config_flow.md %}
 
-There is currently support for the following device types within Home Assistant:
+## Supported platforms
+- **Climate**: Air conditioner, heater, thermostat.
+- **Cover**: Curtain, curtain switch.
+- **Fan**: Fan, air purifier, humidifier, dehumidifier.
+- **Light**: Light, light strip, ambient light, light string, humidifier's light, Ceiling light.
+- **Scene**: Smart scene.
+- **Switch**: Switch, socket, power strip, smart kettle, breaker, pet water feeder, air purifier, diffuser.
 
-- **Climate** - The platform supports the air conditioner and heater.
-- **Cover** - The platform supports curtains.
-- **Fan** - The platform supports most kinds of Tuya fans.
-- **Light** - The platform supports most kinds of Tuya light.
-- **Scene** - The device state in frontend panel will not change immediately after you activate a scene.
-- **Switch** - The platform supports switch and socket.
+## Quick installation and startup
 
-{% include integrations/config_flow.md %}
+### Configure on the Tuya IoT Platform
+
+#### Prerequisites
+
+You have created an account for [Tuya Smart or Smart Life app](https://developer.tuya.com/en/docs/iot/tuya-smart-app-smart-life-app-advantages?id=K989rqa49rluq#title-1-Download).
+
+#### Create a project
+
+**1.** Log in to the [Tuya IoT Platform](https://iot.tuya.com/).
+
+**2.** In the left navigation bar, click **Cloud** > **Projects**.
+
+**3.** On the page that appears, click **Create**.
+
+**4.** In the **Create Project** dialog box, configure **Project Name**, **Description**, **Industry**, and **Availability Zone**. In the **Development Method** field, select **Smart Home PaaS** from the dropdown list. Select all available zones.
+
+![](/images/integrations/tuya/image_001.png)
+
+**5.** Click **Create** to continue project configuration.
 
-During configuration, be careful to select the [country code](https://www.countrycode.org/) and the platform corresponding to those used by you in the app. Once configuration flow is completed, the devices configured in your app will be automatically discovered. Additionally, if your username or e-mail address isn't accepted, please try using your phone number (minus the country code) as your username.
+**6.** In **Configuration Wizard**, select **Device status notification** API.
+   > **Note:** **Smart Home PaaS** API has been selected as default.
+   
+![](/images/integrations/tuya/image_002.png)
 
-## Integration Options
+**7.** Click **Authorize**.
 
-It is possible to change various behaviors through the integration options, some common for integration and others specific to each `light` and `climate` devices. These can be changed at **Tuya** -> **Options** on the Integrations page.
+#### Get authorization key
 
-### Common Options
+Click the created project to enter the **Project Overview** page and get the **Authorization Key** used to make API calls.
 
-- **Discovery device polling interval** (default=605): define the interval between 2 consecutive calls to the `API discovery method`, which is used to get the status for all registered devices with a single call. If you set interval value too low, Tuya API will return errors, so it is suggested to use the default value until
-you know that it is possible to use lower values.
+![](/images/integrations/tuya/image_003.png)
 
-- **Query device polling interval** (default=120): this option is available only if you have devices that can use the `API query method`. 
-It defines the interval between 2 consecutive calls to the `API query method`, that is used to get the status for a specific device. 
-This method is always used when it is available only one device that can use it. If you set interval value too low, Tuya API will return errors 
-so it is suggested to use the default value until you know that is possible to use lower values.
+#### Link devices by app account
 
-- **Device that will use the query method**: this option is available only if you have devices that can use the `API query method`. 
-Because it is not possible to make multiple calls to the `API query method`. If you have more than one device that can use it you can choose which one will use. This will give a better status refresh for this specific device.
+Link devices by your app account and copy the **Device ID** in the **Device List** to the clipboard for specifying `device_id` later.
 
-- **Device to configure (multi-select list)**: this option is available only if you have a `light` or `climate` device. Selecting a device to 
-configure to options page related to the device will be opened. You can also select more than one devices to configure them simultaneously, 
-but all selected devices must be of the same type.
+**1.** Navigate to the **Devices** tab.
 
-### Light Options
+**2.** Click **Link Tuya App Account** > **Add App Account**.
+![](/images/integrations/tuya/image_004.png)
 
-- **Force color support**: when checked force `color support` for devices that do not report this feature.
+**3.** Scan the QR code that appears using the **Tuya Smart** app or **Smart Life** app.
+![](/images/integrations/tuya/image_005.png)
 
-- **Brightness range**: change the `brightness range` used for the device. Possible options are:
-    - range 1-255 (default)
-    - range 10-1000
+**4.** Click **Confirm** on your **Tuya Smart** or **Smart Life** app.
 
-- **Min color temperature**: set minimum `color temperature` expressed in `kelvin` accepted by the light.
+**5.** Navigate to the **Device List** tab. You can find the devices that have been added through your **Tuya Smart** or **Smart Life** account.   
+![](/images/integrations/tuya/image_006.png)
 
-- **Max color temperature**: set maximum `color temperature` expressed in `kelvin` accepted by the light.
+### Install the Tuya Home Assistant integration
 
-- **Max color temperature reported**: set the maximum `color temperature` value reported by the light.
+#### Install the Tuya integration
 
-### Climate Options
+In **Configuration** > **Integrations** > **ADD INTEGRATION**, search for the keyword **Tuya** and select it for installation.
+![](/images/integrations/tuya/image_007.png)
 
-- **Temperature unit**: change the `temperature unit` used internally by the devices.
+#### Enter your Tuya credential
 
-- **Temperature values divider**: `all temperatures` reported by device will be divided by this value.
+In the Tuya Integration window, select **Smart Home PaaS** and click **SUBMIT**.
 
-- **Current Temperature value divider**: `current temperature` reported by device will be divided by this value.
+![](/images/integrations/tuya/image_008.png)
 
-- **Use divided Temperature value for set command**: when checked the `set_temperature` command use the temperature value calculated using Temperature Divider option.
+See the following table and enter your Tuya credential.
 
-- **Target Temperature step**: allow to override the default target temperature step from a list of available options.
-
-- **Min target temperature**: set the minimum allowed `target temperature` for the entity.
+| Field | Description |
+| ------- | -------- |
+| Access ID and Access Secret| Go to your cloud project on [Tuya IoT Platform](https://iot.tuya.com/). Find the **Access ID** and **Access Secret** on the **Project Overview** tab.|
+| Mobile App | Must select the one you used to link devices on the Tuya IoT Platform. |
+| Country Code | The country you select on logging in to Tuya Smart or Smart Life app.|
+| Account | Tuya Smart or Smart Life app account. |
+| Password | The password of your app account. |
 
-- **Max target temperature**: set the maximum allowed `target temperature` for the entity.
+<p class='note'>The app mentioned in the table must be the one you used to link devices on the Tuya IoT Platform.</p>
 
-## Service
+## Error codes and troubleshooting
 
-These services are available for the `tuya` component:
+|Error Code|Error Message|Troubleshooting|
+|:----|:--------|:------------------------------|
+|1004| sign invalid| Incorrect Access ID or Access Secret. Please refer to [Tuya credential table](https://github.com/tuya/tuya-home-assistant/wiki/Install-Tuya-v2?_source=d10de34623e3daca5b02e3c31528a0c4#3-enter-your-tuya-credential).
+|1106|permission deny|<ul><li> App account not linked with cloud project: On the [Tuya IoT Platform](https://iot.tuya.com/cloud/), you have linked devices by using Tuya Smart or Smart Life app in your cloud project. For more information, see [Link devices by app account](https://developer.tuya.com/en/docs/iot/Platform_Configuration_smarthome?id=Kamcgamwoevrx&_source=7a356dd493196a01bb9021b7680a2a45#title-3-Link%20devices%20by%20app%20account).</li><li> Incorrect username or password: Enter the correct account and password of the Tuya Smart or Smart Life app in the **Account** and **Password** fields. Note that the app account depends on which app (Tuya Smart or Smart Life) you used to link devices on the [Tuya IoT Platform](https://iot.tuya.com/cloud/).</li><li>Incorrect availability zone: See [Availability Zone](https://github.com/tuya/tuya-home-assistant/wiki/Tuya-IoT-Platform-Configuration-Guide-Using-Smart-Home-PaaS#region--available-zone-correspondence) and select the correct availability zone.</li><li>Incorrect countycode: Fill the [code](https://countrycode.org/) of the country you select on logging in to Tuya Smart or Smart Life app.</li></ul>|
+|1100|param is empty| Empty parameter of username or app. Fill the parameters refer to [Tuya credential table](https://github.com/tuya/tuya-home-assistant/wiki/Install-Tuya-v2?_source=d10de34623e3daca5b02e3c31528a0c4#3-enter-your-tuya-credential).
+|2017|schema does not exist| Incorrect app selected. Select the app you used to link devices in the cloud project.|
+| 2406 | skill id invalid | Make sure that your cloud project on the [Tuya IoT Platform](https://iot.tuya.com/cloud/) should be created after May 25, 2021. Otherwise, you need to create a new project or migrate data to a new project. For more information, see [Operation on the Tuya IoT Platform](https://developer.tuya.com/en/docs/iot/migrate-from-an-older-version?id=Kamee9wtbd00b#title-3-Operation%20on%20the%20Tuya%20IoT%20Platform).|
+| 28841105 |No permissions. This project is not authorized to call this API| Some APIs are not authorized, please  [Subscribe](https://developer.tuya.com/en/docs/iot/applying-for-api-group-permissions?id=Ka6vf012u6q76#title-2-Subscribe%20to%20cloud%20products) then [Authorize](https://developer.tuya.com/en/docs/iot/applying-for-api-group-permissions?id=Ka6vf012u6q76#title-3-Authorize%20projects%20to%20call%20the%20cloud%20product). The following APIs must be subscribed for this tutorial: <ul><li>Authorization</li><li>Smart Home Devices Management</li><li>Smart Home Family Management</li><li>Smart Home Scene Linkage</li><li>Smart Home Data Service</li><li>Device status notification</li></ul>|
 
-- force_update
-- pull_devices
+## Related Documents
 
-Devices state data and new devices will refresh automatically. If you want to refresh all devices information or get new devices related to your account manually, you can call the `force_update` or `pull_devices` service.
+- [Supported Device Category](https://github.com/tuya/tuya-home-assistant/wiki/Supported-Device-Category?_source=f5f782752be3c4a9157ec47514d6091b)
+- [How to Develop a New Driver](https://github.com/tuya/tuya-home-assistant/wiki/How-to-Develop-a-New-Driver?_source=dbf3bf17966af48325e4328b2535eefe)
+- [FAQs](https://github.com/tuya/tuya-home-assistant/wiki/FAQs)