You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: ADVANCED_OPTIONS.md
+19-22Lines changed: 19 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,33 +2,30 @@
2
2
3
3
**During the beta version, the options are unstable, may get changed during updates.**
4
4
5
-
The main function of `deviceOverrides` is to convert "non-standard schema" to "standard schema", making device compatible with this plugin.
5
+
The main function of `deviceOverrides` is to convert "non-standard schema" to "standard schema", making the device compatible with this plugin.
6
6
7
-
Before config, you may need to:
8
-
- Have basic programming skills of JavaScript (Only used in `onGet`/`onSet`handler).
9
-
- Understand the meaning of device schema (aka Data Type): [Tuya IoT Development Platform > Cloud Development > Standard Instruction Set > Data Type](https://developer.tuya.com/en/docs/iot/datatypedescription?id=K9i5ql2jo7j1k)
10
-
- Find your device product's "Standard Instruction Set" and "Standard Status Set" documentation under [Tuya IoT Development Platform > Cloud Development > Standard Instruction Set](https://developer.tuya.com/en/docs/iot/datatypedescription?id=K9i5ql6waswzq)
11
-
-Get your device's detail information from `/path/to/persist/TuyaDeviceList.xxx.json` (Full path can be found from logs).
12
-
-Find the "wrong schema", then convert to the "correct schema" from product documentation.
7
+
Before configuring, you may need to:
8
+
- Have basic programming skills in JavaScript (Only used in `onGet`/`onSet`handlers).
9
+
- Understand the concept of device schema (also known as Data Type): [Tuya IoT Development Platform > Cloud Development > Standard Instruction Set > Data Type](https://developer.tuya.com/en/docs/iot/datatypedescription?id=K9i5ql2jo7j1k)
10
+
- Find the "Standard Instruction Set" and "Standard Status Set" documentation for your device product under [Tuya IoT Development Platform > Cloud Development > Standard Instruction Set](https://developer.tuya.com/en/docs/iot/datatypedescription?id=K9i5ql6waswzq)
11
+
-Obtain detailed information about your device from `/path/to/persist/TuyaDeviceList.xxx.json` (the full path can be found from logs).
12
+
-Identify the "incorrect schema" and convert it to the "correct schema" according to the product documentation.
13
13
14
14
15
15
### Configuration
16
16
17
-
-`options.deviceOverrides` - **optional**: An array of device overriding config objects.
18
-
-`options.deviceOverrides[].id` - **required**: Device ID, Product ID, Scene ID, or `global`.
19
-
<!--
20
-
- `options.deviceOverrides[].accessoryCategory` - **optional**: Accessory Category ID. Overriding this property can change accessory's icon. See: [Homebridge Plugin Documentation > Categories](https://developers.homebridge.io/#/categories)
21
-
-->
22
-
-`options.deviceOverrides[].category` - **optional**: Device category code. See [SUPPORTED_DEVICES.md](./SUPPORTED_DEVICES.md). Also you can use `hidden` to hide device, product, or scene. **⚠️Overriding this property may leads to unexpected behaviors and exceptions. Please remove accessory cache after change this.**
23
-
24
-
-`options.deviceOverrides[].schema` - **optional**: An array of schema overriding config objects, used for describing datapoint(DP). When your device have non-standard DP, you need to transform them manually with config.
-`options.deviceOverrides[].schema[].newCode` - **optional**: New DP code.
27
-
-`options.deviceOverrides[].schema[].type` - **optional**: New DP type. One of the `Boolean`, `Integer`, `Enum`, `String`, `Json`, `Raw`.
28
-
-`options.deviceOverrides[].schema[].property` - **optional**: New DP property object. For `Integer` type, the object should contains `min`, `max`, `scale`, `step`; For `Enum` type, the object should contains `range`. For detail information, please see `TuyaDeviceSchemaProperty` in [TuyaDevice.ts](./src/device/TuyaDevice.ts).
29
-
-`options.deviceOverrides[].schema[].onGet` - **optional**: An one-line JavaScript code convert old value to new value. The function is called with two arguments: `device`, `value`.
30
-
-`options.deviceOverrides[].schema[].onSet` - **optional**: An one-line JavaScript code convert new value to old value. The function is called with two arguments: `device`, `value`. return `undefined` means skip send this command.
31
-
-`options.deviceOverrides[].schema[].hidden` - **optional**: Whether to hide the schema. Defaults to `false`.
17
+
`options.deviceOverrides` is an **optional** array of device overriding config objects, which is used for converting "non-standard schema" to "standard schema", making the device compatible with this plugin. The structure of each element in the array is described as follows:
18
+
19
+
-`id` - **required**: Device ID, Product ID, Scene ID, or `global`.
20
+
-`category` - **optional**: Device category code. See [SUPPORTED_DEVICES.md](./SUPPORTED_DEVICES.md). Also you can use `hidden` to hide the device, product, or scene. **⚠️Overriding this property may lead to unexpected behaviors and exceptions, so please remove the accessory cache after making changes.**
21
+
-`schema` - **optional**: An array of schema overriding config objects, used for describing datapoint (DP). When your device has non-standard DP, you need to transform them manually with configuration. Each element in the schema array is described as follows:
22
+
-`code` - **required**: DP code.
23
+
-`newCode` - **optional**: New DP code.
24
+
-`type` - **optional**: New DP type. One of `Boolean`, `Integer`, `Enum`, `String`, `Json`, or `Raw`.
25
+
-`property` - **optional**: New DP property object. For `Integer` type, the object should contain `min`, `max`, `scale`, and `step`. For `Enum` type, the object should contain `range`. For more information, see `TuyaDeviceSchemaProperty` in [TuyaDevice.ts](./src/device/TuyaDevice.ts).
26
+
-`onGet` - **optional**: A one-line JavaScript code to convert the old value to the new value. The function is called with two arguments: `device` and `value`.
27
+
-`onSet` - **optional**: A one-line JavaScript code to convert the new value to the old value. The function is called with two arguments: `device` and `value`. Returning `undefined` means to skip sending the command.
28
+
-`hidden` - **optional**: Whether to hide the schema. Defaults to `false`.
Fork version of official Tuya Homebridge plugin. Brings a bunch of bug fix and new device support.
11
+
Fork version of the official Tuya Homebridge plugin, with a focus on fixing bugs and adding new device support.
12
12
13
13
14
14
## Features
15
15
16
-
- Optimized code, improved code readability and maintainability.
17
-
-Improved stability.
18
-
-Less duplicate code.
19
-
-Less API errors.
20
-
-Less development costs for new accessory categroies.
21
-
- Tuya Scene supported (Tap-to-Run).
22
-
-Device overriding config supported. "Non-standard DP" have possibility to be supported now.
23
-
-More than 40+ device categories supported, including most of the lights, switches, sensors, cameras ...
16
+
- Optimized and improved code for better readability and maintainability.
17
+
-Enhanced stability.
18
+
-Reduced duplicate code.
19
+
-Fewer API errors.
20
+
-Lower development costs for new accessory categories.
21
+
-Supports Tuya Scenes (Tap-to-Run).
22
+
-Includes the ability to override device configurations, which enables support for "non-standard" DPs.
23
+
-Supports over 40+ device categories, including most lights, switches, sensors, cameras, etc.
24
24
25
25
26
26
## Supported Tuya Devices
@@ -32,59 +32,60 @@ See [CHANGELOG.md](./CHANGELOG.md)
32
32
33
33
34
34
## Installation
35
-
Before use, please uninstall `homebridge-tuya-platform` first. They can't run together. (But the config is compatible, no need to delete.)
35
+
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.
36
36
37
37
#### For Homebridge Web UI Users
38
-
Go to plugin page, search `@0x5e/homebridge-tuya-platform` and install.
38
+
Go to plugin page, search for `@0x5e/homebridge-tuya-platform` and install it.
39
39
40
40
41
41
#### For Homebridge Command Line Users
42
42
43
+
Run the following command in the terminal:
43
44
```
44
45
npm install @0x5e/homebridge-tuya-platform
45
46
```
46
47
47
48
48
49
## Configuration
49
50
50
-
There's two type of project: `Custom` and `Smart Home`.
51
-
The differenct between them is:
52
-
-`Custom`Project pull devices from project's asset.
53
-
-`Smart Home`Project pull devices from Tuya App user's home.
51
+
There are two types of projects: `Custom` and `Smart Home`.
52
+
The difference between them is:
53
+
-The `Custom`project pulls devices from the project's assets.
54
+
-The `Smart Home`project pulls devices from the user's home in the Tuya app.
54
55
55
-
If you are personal user and don't know which to choose, please use `Smart Home`.
56
+
If you are a personal user and are unsure which one to choose, please use the `Smart Home` project.
56
57
57
-
Before configuration, please goto [Tuya IoT Platform](https://iot.tuya.com)
58
-
- Create a cloud develop project, select the data center where your app account located. See [Mappings Between OEM App Accounts and Data Centers](https://developer.tuya.com/en/docs/iot/oem-app-data-center-distributed?id=Kafi0ku9l07qb) (If you don't know where it is, just select all.)
59
-
- Go to `Project Page` > `Devices Panel` > `Link Tuya App Account`, link your app account.
60
-
- Go to `Project Page` > `Service API` > `Go to Authorize`, subscribe the following APIs (it's free for trial):
58
+
Before you can configure, you must go to the [Tuya IoT Platform](https://iot.tuya.com):
59
+
- Create a cloud development project, and select the data center where your app account is located. See [Mappings Between OEM App Accounts and Data Centers](https://developer.tuya.com/en/docs/iot/oem-app-data-center-distributed?id=Kafi0ku9l07qb) (If you don't know where it is, just select all.)
60
+
- Go to the `Project Page` > `Devices Panel` > `Link Tuya App Account`, and link your app account.
61
+
- Go to the `Project Page` > `Service API` > `Go to Authorize`, and subscribe to the following APIs (it is free for trial):
61
62
- Authorization Token Management
62
63
- Device Status Notification
63
64
- IoT Core
64
-
- IoT Video Live Stream (for Camera)
65
-
- Industry Project Client Service (for "Custom" project)
66
-
- Smart Home Scene Linkage (for Scene)
67
-
-**⚠️Extend the API trial period every 6 months here (first-time subscription only give 1 month): [Tuya IoT Platform > Cloud > Cloud Services > IoT Core](https://iot.tuya.com/cloud/products/detail?abilityId=1442730014117204014&id=p1668587814138nv4h3n&abilityAuth=0&tab=1)**
65
+
- IoT Video Live Stream (for cameras)
66
+
- Industry Project Client Service (for the `Custom` project)
67
+
- Smart Home Scene Linkage (for scenes)
68
+
-**⚠️Remember to extend the API trial period every 6 months here [Tuya IoT Platform > Cloud > Cloud Services > IoT Core](https://iot.tuya.com/cloud/products/detail?abilityId=1442730014117204014&id=p1668587814138nv4h3n&abilityAuth=0&tab=1) (the first-time subscription only gives you 1 month).**
68
69
69
70
#### For "Custom" Project
70
71
71
72
-`platform` - **required** : Must be 'TuyaPlatform'
72
73
-`options.projectType` - **required** : Must be '1'
-`options.endpoint` - **required** : The endpoint URL taken from the[API Reference > Endpoints](https://developer.tuya.com/en/docs/iot/api-request?id=Ka4a8uuo1j4t4#title-1-Endpoints) table.
75
+
-`options.accessId` - **required** : The Access ID obtained from [Tuya IoT Platform > Cloud Develop](https://iot.tuya.com/cloud)
76
+
-`options.accessKey` - **required** : The Access Secret obtained from [Tuya IoT Platform > Cloud Develop](https://iot.tuya.com/cloud)
76
77
77
78
#### For "Smart Home" Project
78
79
79
80
-`platform` - **required** : Must be 'TuyaPlatform'
80
81
-`options.projectType` - **required** : Must be '2'
81
-
-`options.accessId` - **required** : Access ID from [Tuya IoT Platform > Cloud Develop](https://iot.tuya.com/cloud)
-`options.password` - **required** : App password. MD5 salted password is also available for better config security.
86
-
-`options.appSchema` - **required** : App schema. 'tuyaSmart' for Tuya Smart App, 'smartlife' for Smart Life App.
87
-
-`options.homeWhitelist` - **optional**: An array of integer home ID values to whitelist. If present, only includes devices matching this Home ID value. Home ID can be found in the homebridge log.
82
+
-`options.accessId` - **required** : The Access ID obtained from [Tuya IoT Platform > Cloud Develop](https://iot.tuya.com/cloud)
83
+
-`options.accessKey` - **required** : The Access Secret obtained from [Tuya IoT Platform > Cloud Develop](https://iot.tuya.com/cloud)
84
+
-`options.countryCode` - **required** : The country code.
85
+
-`options.username` - **required** : The app username.
86
+
-`options.password` - **required** : The app password. MD5 salted password is also available for increased security.
87
+
-`options.appSchema` - **required** : The app schema: 'tuyaSmart' for the Tuya Smart App, or 'smartlife' for the Smart Life App.
88
+
-`options.homeWhitelist` - **optional**: An array of integer values for the home IDs you want to whitelist. If provided, only devices with matching Home IDs will be included. You can find the Home ID in the homebridge log.
88
89
89
90
90
91
#### Advanced options
@@ -93,34 +94,33 @@ See [ADVANCED_OPTIONS.md](./ADVANCED_OPTIONS.md)
93
94
94
95
## Limitations
95
96
-**⚠️Don't forget to extend the API trial period every 6 months. Maybe you can set up a reminder in calendar.**
96
-
-The app account can't be used in multiple Homebridge/HomeAssistant instance at the same time! Please consider using different app accounts instead.
97
-
- The plugin requires the internet access to Tuya Cloud, and the lan protocol is not supported. See [#90](https://github.com/0x5e/homebridge-tuya-platform/issues/90)
97
+
-Using the same app account for multiple Homebridge/HomeAssistant instances is not supported. Please use separate app accounts for each instance.
98
+
- The plugin requires an internet connection to the Tuya Cloud and does not support the LAN protocol. See [#90](https://github.com/0x5e/homebridge-tuya-platform/issues/90) for more information.
98
99
99
100
## FAQ
100
101
101
102
#### What is "Standard DP" and "Non-standard DP"?
102
103
103
-
If your device is working properly, you don't need to know this.
104
+
<!--If your device is working properly, you don't need to know this.-->
104
105
105
-
"Standard DP" means the device's DP Code is matching the code in documentation at:[Tuya IoT Development Platform Documentation > Cloud Development > Standard Instruction Set](https://developer.tuya.com/en/docs/iot/standarddescription?id=K9i5ql6waswzq).
106
+
"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](https://developer.tuya.com/en/docs/iot/standarddescription?id=K9i5ql6waswzq).
106
107
107
-
For example, a Lightbulb must have `switch_led` for power on/off, and optional code
108
-
`bright_value`/`bright_value_v2` for brightness, `temp_value`/`temp_value_v2` for color temperature, `work_mode` for change working mode. These code can be found from above documentation.
108
+
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.
109
109
110
-
If your Lightbulb can adjust brightness in Tuya App, but can't do with the plugin, then mostly it has an "Non-standard DP".
110
+
If your light bulb can be adjusted in the Tuya app but not with the plugin, it most likely has "Non-standard DP."
111
111
112
112
113
113
#### Can "Non-standard DP" be supportd by this plugin?
114
114
115
-
Yes. The device should be in the support list, then you need do these steps before it's working.
116
-
1. Change device's control mode on Tuya Platform.
115
+
Yes. The device must be listed in the support list and the following steps must be completed before it will work:
116
+
1. Change the device's control mode on the Tuya Platform:
117
117
- Go to "[Tuya Platform Cloud Development](https://iot.tuya.com/cloud/) > Your Project > Devices > All Devices > View Devices by Product".
118
-
- Find your device-related product, click the "pencil" icon (Change Control Instruction Mode).
118
+
- Find the product related to your device, click the "pencil" icon (Change Control Instruction Mode).
2. Override device schema, see [ADVANCED_OPTIONS.md](./ADVANCED_OPTIONS.md).
123
+
2. Override the device schema, see [ADVANCED_OPTIONS.md](./ADVANCED_OPTIONS.md).
124
124
125
125
126
126
#### Local support
@@ -131,17 +131,16 @@ Although the plugin didn't implemented tuya local protocol now, it still remains
131
131
132
132
## Troubleshooting
133
133
134
-
If your device is not supported, please complete the following steps to collecting the data.
134
+
If your device is not supported, please follow these steps to collect information.
135
135
136
136
#### 1. Get Device Information
137
137
138
-
After successful launching Homebridge, the device info list will be saved inside Homebridge's persist path.
139
-
You can get the file path from homebridge log:
138
+
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:
140
139
```
141
140
[2022/11/3 18:37:43] [TuyaPlatform] Device list saved at /path/to/TuyaDeviceList.{uid}.json
142
141
```
143
142
144
-
**⚠️Please remove the sensitive data such as `ip`, `lon`, `lat`, `local_key`, `uid` before submit the file.**
143
+
**⚠️Please make sure to remove sensitive information such as `ip`, `lon`, `lat`, `local_key`, and `uid` before submitting the file.**
145
144
146
145
147
146
#### 2. Enable Homebridge Debug Mode
@@ -152,11 +151,11 @@ For Homebridge Web UI users:
152
151
- Restart Homebridge.
153
152
154
153
For Homebridge Command Line Users:
155
-
- Start Homebridge with `-D` flag: `homebridge -D`
154
+
- Start Homebridge with the `-D` flag: `homebridge -D`
156
155
157
-
#### 3. Collecting Logs
156
+
#### 3. Collect Logs
158
157
159
-
With debug mode on, you can now receive mqtt logs. Operate your devicephysically, or via Tuya App, then you will get mqtt logs like this:
158
+
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:
0 commit comments