add mkdocs files

xZetsubou · Nov 11, 2023 · 1ec1af9 · 1ec1af9
1 parent e493ee4
commit 1ec1af9
Show file tree

Hide file tree

Showing 27 changed files with 628 additions and 0 deletions.
diff --git a/docs/auto_configure.md b/docs/auto_configure.md
@@ -0,0 +1,88 @@
+# Auto configure devices
+Localtuya can disocver you device entities if cloud is enable because the feature at the moment rely on `DP code` and [Devices Category](https://developer.tuya.com/en/docs/iot/standarddescription?id=K9i5ql6waswzq#title-6-List%20of%20category%20code).
+
+By known the `category` we use that to get all the possible entities from stored data.<br> Data stored in `/localtuya/core/tuya_devices` (1)
+{.annotate}
+
+1. Files named with entity type <br> <br> ![](/images/dev/tuya_devices_dir.png)
+
+??? info "DPCodes data"
+    All known `Codes` are stored in `base.py` in `DPCode Class`. <br>
+    If class doesn't contains your `DPCode` Add it, `DPCode class sorted in alphabetically`.
+
+
+!!! tip annotate "How to get the `Codes and DP`"
+    You can download your devices data from HA using `Download diagnostics`
+
+    1. Download device diagnostics `localtuya` from device page. (1) `file -> device_cloud_info`
+    2. Download entry diagnostics `note: contains all devices data` (2) `file -> cloud_devices`
+
+    Inside downloaded `txt file`, in `cloud_data object` look for your `device -> dps_data`
+
+1. ![](/images/dev/device_diagnostics.png)
+2. ![](/images/dev/entry_diagnostics.png)
+
+__Now that we know the device `category` and `Codes` we can start add the entities.__
+
+In `/localtuya/core/tuya_devices` open the file named with `entity type` you want to add.<br>
+All files contain `constant dict` contains all known `categories` (1).<br>
+Look for the `category` modify if it existed then add the missing `entity`.
+{.annotate}
+
+1. e.g `COVERS or SWITCHES`
+
+Using `LocalTuyaEntity class` we pass entity parameters and `DP Fields names` DP Keys has to be supported by `localtuya` (1)
+{.annotate}
+
+1. All entities has `id` key. but some has mode dp fields <br> For example: `cover platforms` has config keys for `current_position_dp` and  `set_position_dp`<br> 
+
+
+# Examples 
+
+
+
+??? example "Add `code: switch_4` into `SWITCHES` `kg` category"
+    ```python 
+    "kg": (
+        LocalTuyaEntity(
+            id=DPCode.SWITCH_4, # REQUIRED: id config look for code `switch_4`
+            name="Switch 4", # name the entity: `Switch 4`
+            icon="mdi:icon_name",  # icon of the entity
+            entity_category=EntityCategory.CONFIG, # show entity in this category
+        ),
+    ),
+    ```
+
+??? example "Add `switch` into `SWITCHES` `cl` category: with condition"
+    ```python 
+    "cl": (
+        LocalTuyaEntity(
+            id=DPCode.CONTROL_BACK,
+            name="Reverse",
+            icon="mdi:swap-horizontal",
+            entity_category=EntityCategory.CONFIG,
+            condition_contains_any=["true", "false"],
+        ),
+    ),
+    ```
+
+
+
+??? example "Add `cover` into `COVERS` `cl` category"
+    ```python 
+    "cl": (
+        LocalTuyaEntity(
+            id=DPCode.CONTROL,
+            name="Curtain",
+            custom_configs=localtuya_cover("open_close_stop", "position"), # localtuya config
+            current_state=DPCode.SITUATION_SET,
+            current_position_dp=(DPCode.PERCENT_CONTROL, DPCode.PERCENT_STATE),#(1)!
+            set_position_dp=DPCode.PERCENT_CONTROL,
+        ),
+    ),
+    ```
+
+    1. current_position_dp will search two possible codes and will take the first `DP` found.
+
+
+
diff --git a/docs/cloud_api.md b/docs/cloud_api.md
@@ -0,0 +1,111 @@
+# Cloud API Setup
+
+The Tuya integration integrates all Powered by Tuya devices you have added to the Tuya Smart and Tuya Smart Life apps.
+
+!!! note
+    `LocalTuya` uses cloud only to get your devices data to make configure devices much easier.
+
+## Configuration of the Tuya IoT Platform
+
+### Prerequisites
+
+- Your devices need first to be added in the [Tuya Smart or Smart Life app](https://developer.tuya.com/docs/iot/tuya-smart-app-smart-life-app-advantages?id=K989rqa49rluq#title-1-Download).
+- You will also need to create an account in the [Tuya IoT Platform](https://iot.tuya.com/).
+This is a separate account from the one you made for the app. You cannot log in with your app's credentials.
+
+### Create a project
+
+1. Log in to the [Tuya IoT Platform](https://iot.tuya.com/).
+2. In the left navigation bar, click `Cloud` > `Development`. 
+3. On the page that appears, click `Create Cloud Project`.
+4. In the `Create Cloud Project` dialog box, configure `Project Name`, `Description`, `Industry`, and `Data Center`. For the `Development Method` field, select `Smart Home` from the dropdown list. For the `Data Center` field, select the zone you are located in. Refer to the country/data center mapping list [here](https://github.com/tuya/tuya-home-assistant/blob/main/docs/regions_dataCenters.md) to choose the right data center for the country you are in.
+
+    ![](https://www.home-assistant.io/images/integrations/tuya/image_001.png)
+
+5. Click `Create` to continue with the project configuration.
+6. In Configuration Wizard, make sure you add `Industry Basic Service`, `Smart Home Basic Service` and `Device Status Notification` APIs. The list of API should look like this:
+  ![](https://www.home-assistant.io/images/integrations/tuya/image_002new.png)
+7. Click `Authorize`.
+
+### Link devices by app account
+
+1. Navigate to the `Devices` tab.
+2. Click `Link Tuya App Account` > `Add App Account`.
+  ![](https://www.home-assistant.io/images/integrations/tuya/image_003.png)
+3. Scan the QR code that appears using the `Tuya Smart` app or `Smart Life` app using the 'Me' section of the app.
+
+    ![](https://www.home-assistant.io/images/integrations/tuya/image_004.png)
+
+4. Click `Confirm` in the app.
+5. To confirm that everything worked, navigate to the `All Devices` tab. Here you should be able to find the devices from the app.
+6. If zero devices are imported, try changing the DataCenter and check the account used is the "Home Owner".
+   You can change DataCenter by clicking the Cloud icon on the left menu, then clicking the Edit link in the Operation column for your newly created project. You can change DataCenter in the popup window.
+
+![](https://www.home-assistant.io/images/integrations/tuya/image_005.png)
+
+### Get authorization data
+
+Click the created project to enter the `Project Overview` page and get the `Authorization Key`. You will need these for setting up the integration. in the next step.
+
+![](/images/tuya_iot_overview.png)
+
+  `Data center region`: 
+    Choose the country you picked when signing up.
+
+  `Client ID`:
+    Go to your cloud project on [Tuya IoT Platform](https://iot.tuya.com/). on the **Project Overview** tab.
+
+  `Client Secret`:
+    Go to your cloud project on [Tuya IoT Platform](https://iot.tuya.com/). on the **Project Overview** tab.
+
+### Get USER ID
+  Navigate to the `Devices` tab -> Click Link `Tuya App Account` Copy `UID` <- is `User ID`.
+
+  ![](https://user-images.githubusercontent.com/46300268/246021288-25d56177-2cc1-45dd-adb0-458b6c5a25f3.png)
+
+## Error codes and troubleshooting
+
+
+
+??? info "1004: sign invalid"
+    Incorrect Access ID or Access Secret. Please refer to the **Configuration** part above.
+
+??? info "1106: permission deny"
+    - 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/docs/iot/Platform_Configuration_smarthome?id=Kamcgamwoevrx#title-3-Link%20devices%20by%20app%20account).
+
+    - Incorrect username or password: Enter the correct account and password of the Tuya Smart or Smart Life app in the **Account** and **Password** fields (social login, which the Tuya Smart app allows, may not work, and thus should be avoided for use with the Home Assistant integration). 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/).
+
+    - Incorrect country. You must select the region of your account of the Tuya Smart app or Smart Life app.    
+
+??? info "1100: param is empty"
+    Empty parameter of username or app. Please fill the parameters refer to the **Configuration** part above.
+
+??? info "2406: skill id invalid"
+    - Make sure you use the **Tuya Smart** or **SmartLife** app account to log in. Also, choose the right data center endpoint related to your country region. For more details, please check [Country Regions and Data Center](https://github.com/tuya/tuya-home-assistant/blob/main/docs/regions_dataCenters.md). 
+
+    - Your cloud project on the [Tuya IoT Development Platform](https://iot.tuya.com) should be created after May 25, 2021. Otherwise, you need to create a new project. 
+
+    - This error can often be resolved by unlinking the app from the project (`Devices` tab > `Link Tuya App Account` > `Unlink`) and [relinking it again](#link-devices-by-app-account).
+
+??? info "28841105: No permissions. This project is not authorized to call this API"
+    Some APIs are not authorized, please [Subscribe](https://developer.tuya.com/docs/iot/applying-for-api-group-permissions?id=Ka6vf012u6q76#title-2-Subscribe%20to%20APIs) then [Authorize](https://developer.tuya.com/docs/iot/applying-for-api-group-permissions?id=Ka6vf012u6q76#title-3-Grant%20a%20project%20access%20to%20API%20calls). The following APIs must be subscribed for this tutorial:
+
+        - Device Status Notification
+
+        - Industry Basic Service
+
+        - Smart Home Basic Service
+        
+        - Authorization
+
+        - IoT Core
+
+        - Smart Home Scene Linkage
+
+        - IoT Data Analytics
+
+??? info "28841002: No permissions. Your subscription to cloud development plan has expired"
+    Your subscription to Tuya cloud development **IoT Core Service** resources has expired, please [extend it](https://iot.tuya.com/cloud/products/detail?abilityId=1442730014117204014) in `Cloud` > `Cloud Services` > `IoT Core` > `My Subscriptions` tab > `Subscribed Resources` > `IoT Core` > `Extend Trial Period`. 
+
+## REF Document
+[HomeAssistant Tuya](https://www.home-assistant.io/integrations/tuya/#28841105-no-permissions-this-project-is-not-authorized-to-call-this-api){target="_blank"}
diff --git a/docs/ha_events.md b/docs/ha_events.md
@@ -0,0 +1,77 @@
+# Events
+Localtuya have fires an [events](https://www.home-assistant.io/docs/configuration/events/){target="_blank"} on `homeassisstant` 
+that can be used on automation or check your device `DPS`<Br>
+
+With this you can automate `scene remote` (1) devices to trigger action on `homeassistant`
+{.annotate}
+
+1. e.g. `single click`, `double click` or `hold`.
+
+| Event       | Data                                  
+| ----------- | ------------------------------------ 
+| `localtuya_device_triggered`      | `#!json {"data": {"device_id", "states"} }`                   
+| `localtuya_device_dp_triggered`   | `#!json {"data": {"device_id", "dp", "value"} }`              
+| `localtuya_states_update`         | `#!json {"data": {"device_id", "old_states", "new_states"} }` 
+
+Exaples 
+=== "localtuya_device_triggered"
+
+    ```yaml
+
+    trigger:
+      - platform: event
+        event_type: localtuya_device_triggered
+    condition: []
+    action:
+      - service: persistent_notification.create
+        data:
+          message: "{{ trigger.event.data }}"
+
+    ```
+
+=== "localtuya_device_dp_triggered"
+
+    ```yaml title=""
+
+    trigger:
+      - platform: event
+        event_type: localtuya_device_dp_triggered
+    condition: []
+    action:
+      - service: persistent_notification.create
+        data:
+          message: "{{ trigger.event.data }}"
+
+    ```
+    ???+ example "Automation for scene remote trigger if 1st button single clicked"
+        ```yaml title=""
+        
+        trigger:
+          - platform: event
+            event_type: localtuya_device_dp_triggered
+            event_data:
+              device_id: bfa2f86e3068440a449dhd
+              dp: "1" # quotes are important for dp
+              value: single_click 
+        condition: []
+        action:
+          - service: persistent_notification.create
+            data:
+              message: "{{ trigger.event.data }}"
+
+        ```
+
+=== "localtuya_states_update"
+
+    ```yaml title=""
+
+    trigger:
+      - platform: event
+        event_type: localtuya_states_update
+    condition: []
+    action:
+      - service: persistent_notification.create
+        data:
+          message: "{{ trigger.event.data }}"
+
+    ```
diff --git a/docs/images/Thumbs.db b/docs/images/Thumbs.db
diff --git a/docs/images/configure.png b/docs/images/configure.png
diff --git a/docs/images/delete_device.png b/docs/images/delete_device.png
diff --git a/docs/images/dev/Thumbs.db b/docs/images/dev/Thumbs.db
diff --git a/docs/images/dev/device_diagnostics.png b/docs/images/dev/device_diagnostics.png
diff --git a/docs/images/dev/entry_diagnostics.png b/docs/images/dev/entry_diagnostics.png
diff --git a/docs/images/dev/tuya_devices_dir.png b/docs/images/dev/tuya_devices_dir.png
diff --git a/docs/images/dp_list_explain.png b/docs/images/dp_list_explain.png
diff --git a/docs/images/dps_list_ex.png b/docs/images/dps_list_ex.png
diff --git a/docs/images/init.png b/docs/images/init.png
diff --git a/docs/images/opt_add_devices.png b/docs/images/opt_add_devices.png
diff --git a/docs/images/opt_configure_device.png b/docs/images/opt_configure_device.png
diff --git a/docs/images/opt_configure_entity.png b/docs/images/opt_configure_entity.png
diff --git a/docs/images/opt_configure_more.png b/docs/images/opt_configure_more.png
diff --git a/docs/images/opt_configure_switch_ex.png b/docs/images/opt_configure_switch_ex.png
diff --git a/docs/images/opt_reconfigure_device.png b/docs/images/opt_reconfigure_device.png
diff --git a/docs/images/opt_reconfigure_device_entity_check.png b/docs/images/opt_reconfigure_device_entity_check.png
diff --git a/docs/images/options.png b/docs/images/options.png
diff --git a/docs/images/templates.png b/docs/images/templates.png
diff --git a/docs/images/tuya_iot_overview.png b/docs/images/tuya_iot_overview.png
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,43 @@
+# Overview
+LocalTuya is [HomeAssistant](https://www.home-assistant.io/) integration allows you to control your Tuya-based smart devices directly within your local network. 
+
+!!! info "LocalTuya is a HUB"
+    `LocalTuya` is a hub means after setup your entry whether using `cloud` or `no cloud`, You will manage your devices from entry configuration UI
+    by clicking on `configure` (1)
+    { .annotate }
+
+    1. ![](/images/configure.png)
+
+!!! info "Cloud API"
+    LocalTuya uses cloud only to get devices data and fill the required fields for you.
+
+    It provides many features to make device set-up easier.
+
+    `LocalTuya` Can be you used without cloud.
+
+[:simple-homeassistantcommunitystore: Add repository to HACS](https://my.home-assistant.io/redirect/hacs_repository/?category=integration&repository=hass-localtuya&owner=xZetsubou){ target=_blank .md-button }
+
+
+## Features
+- Cloud Api 
+- Supported protocols - `3.1`, `3.2`, `3.3`, `3.4` and `3.5`
+- Auto configure devices - `Requires cloud api set-up`
+- Auto fill devices config fields - `Requires cloud api set-up`
+- Disocvery - `Discover Tuya devices on you network` 
+
+
+
+## Supported platforms
+- Binary Sensor
+- Button
+- Climate
+- Cover
+- Fan
+- Humidifier
+- Light
+- Number
+- Selector
+- Sensor
+- Siren
+- Switch
+- Vacuum