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
Tuya devices use a custom `manuSpecificTuya` cluster, the instructions below will help you understand it better and provide some tools to ease discovery of their functions
1
+
# Support new TuYa devices
2
+
TuYa devices use a custom `manuSpecificTuya` cluster, the instructions below will help you understand it better and provide some tools to ease discovery of their functions
`seq` is the transaction number of the payload. `dpValues` is an array of "Data Points" (type: `TuyaDataPointValue`). Such a data point value consists of:
61
+
`seq` is the transaction number of the payload. `dpValues` is an array of "Data Points" (type: `TuYaDataPointValue`). Such a datapoint value consists of:
67
62
68
63
```js
69
64
dp:DataType.uint8;
70
65
datatype:DataType.uint8;
71
66
data: Buffer;
72
67
```
73
68
74
-
-`dp` is so called "Data Point ID" which is at the core of Tuya devices. From the point of view of a device the DPIDs are the functions that the device provides.
69
+
-`dp` is so called "Data Point ID" which is at the core of TuYa devices. From the point of view of a device the DPIDs are the functions that the device provides.
75
70
-`datatype` is the type of data contained in the `data` field, see `dataTypes` in `node_modules/zigbee-herdsman-converters/lib/tuya.js`
76
71
77
-
Some data points are 'report only' (they report changes that happen within the device) others are 'issue and report' (they can report by themselves, but also respond with a report when set). The list of currently known data points can be found in `dataPoints` in [node_modules/zigbee-herdsman-converters/lib/tuya.js](https://github.com/Koenkk/zigbee-herdsman-converters/blob/master/lib/tuya.js). Data point IDs may be device dependent, they are not unified across all Tuya devices.
78
-
79
-
For example on Saswell thermostat data point number `103` is heating setpoint, it has `value` (i.e. integer) type and is 'issue and report', we will use that information later in examples.
72
+
Some datapoints are 'report only' (they report changes that happen within the device) others are 'issue and report' (they can report by themselves, but also respond with a report when set). Data points are not unified across all TuYa devices so they can differ per device.
80
73
81
-
If you have a Tuya gateway, you can find what the function is of data point number by following [this how-to guide](./03_find_tuya_data_points.md)
74
+
### 4. Mapping the datapoints
75
+
Now we have to map the datapoints in `tuyaDatapoints`. Start Zigbee2MQTT with [debug logging](../../guide/usage/debug.md) enabled and trigger some actions on the device. You will now see logging like:
82
76
83
-
### 4. Deciphering the data points
84
-
By adding the two debug converters mentioned earlier, we have the tools to decipher Tuya data points.
85
-
86
-
#### fz.tuya_data_point_dump
87
-
This converter will log a message for each data point value received in a Tuya specific message from the device. For the "heating setpoint" example with data point number `103`, this could look like:
88
-
89
-
```
90
-
zigbee-herdsman-converters:tuya_data_point_dump: Received DP #103 from 0x123456789abcdef with raw data '{"dp":103,"datatype":2,"data":[0,0,0,215]}': type='commandDataResponse', datatype='value', value='215', known DP# usage: ["maxTemp","moesSboostHeatingCountdownTimeSet","neoDuration","hyExternalTemp","trsIlluminanceLux","msVacancyDelay","hochActivePower"]
91
77
```
92
-
93
-
The log message contains the data point number, the raw and the decoded data, and the list of symbolic names which are already known for this data point number (from the `dataPoints` definition in `node_modules/zigbee-herdsman-converters/lib/tuya.js`).
94
-
95
-
In addition to the log entry, the converter will append a line to the file `data/tuya.dump.txt` (which can be used for test scripts). For each data point value received format of line is:
Zigbee2MQTT:debug 2022-11-30 18:29:19: Datapoint '106' with value '77' not defined for '_TZE200_d0yu2xgi'
99
79
```
100
80
101
-
A `commandDataReport` (corresponding to the `dataReport` type) and `commandDataResponse` (corresponding to `dataResponse`) message may contain multiple data point values. `dpv_number` is the index of the data point value in the payload (0 being the first).
81
+
Next we have to find out what this datapoint means (`106` in this example), there are different ways to do this:
82
+
-[Find TuYa datapoint using the TuYa gateway](./03_find_tuya_data_points.md) (easiest but requires TuYa gateway)
83
+
- Check if an already supported TuYa device has this datapoint mapped ([search](https://github.com/Koenkk/zigbee-herdsman-converters/search?q=tuyaDatapoints))
84
+
- Guess based on the value
102
85
103
-
The example python script [read_tuya_dump.py](https://github.com/Koenkk/zigbee-herdsman-converters/blob/master/scripts/read_tuya_dump.py) is able to parse this file. It's pre-filled with Saswell data points, but should be easy to modify it to work with your device if needed. On a linux computer/Raspberry Pi you can do `tail -f -n +0 data/tuya.dump.txt | read_tuya_dump.py` to get real time view of what your device is sending.
86
+
For this device we know that datapoint `106` is the humidity, we can now update the `exposes` and `tuyaDatapoints` section of the external converter:
104
87
105
-
#### tz.tuya_data_point_test
106
-
This converter will allow you to send arbitrary data point to Tuya device, you only need to publish a message in the format `datatype,dp,data` to `zigbee2mqtt/{device_friendly_name}/set/tuya_data_point_test` MQTT topic
107
-
108
-
### 5. Adding your first data point
109
-
Let's assume we want to add the heating setpoint of the Saswell thermostat first.
110
-
111
-
As the log message for the data point did not contain a suitable existing definition, first add the `saswellHeatingSetpoint` data point to `dataPoints` in `node_modules/zigbee-herdsman-converters/lib/tuya.js` with value `103`.
112
-
113
-
Then add to `node_modules/zigbee-herdsman-converters/converters/fromZigbee.js`:
constdp=dpValue.dp; // First we get the data point ID
122
-
constvalue=tuya.getDataValue(dpValue); // This function will take care of converting the data to proper JS type
123
-
switch (dp) {
124
-
casetuya.dataPoints.saswellHeatingSetpoint: // DPID that we added to common
125
-
result.current_heating_setpoint= (value /10).toFixed(1); // value is already converted to a number in JS, and we deduced that it needs to be divided by 10
126
-
break;
127
-
default:
128
-
meta.logger.warn(`zigbee-herdsman-converters:SaswellThermostat: NOT RECOGNIZED DP #${
129
-
dp} with data ${JSON.stringify(dpValue)}`); // This will cause zigbee2mqtt to print similar data to what is dumped in tuya.dump.txt
130
-
}
131
-
}
132
-
return result;
133
-
},
134
-
},
135
-
```
136
-
137
-
Then add to `node_modules/zigbee-herdsman-converters/converters/toZigbee.js`
138
88
```js
139
-
saswell_thermostat_current_heating_setpoint: {
140
-
key: ['current_heating_setpoint'],
141
-
convertSet:async (entity, key, value, meta) => {
142
-
consttemp=Math.round(value *10);
143
-
awaittuya.sendDataPointValue(entity, tuya.dataPoints.saswellHeatingSetpoint, temp); // tuya.sendDataPoint* functions take care of converting the data to proper format
144
-
},
145
-
},
146
-
```
147
-
148
-
The `tuya.sendDataPoint*` functions send a single data point value. In case you
149
-
want to send multiple data points at once, you can use the `tuya.sendDataPoints`
//Here you should put all functionality that your device exposes
90
+
e.humidity(), //<- added the humdity expose
195
91
],
196
-
};
197
-
198
-
module.exports= definition;
92
+
meta: {
93
+
tuyaDatapoints: [
94
+
[8, 'humidity', tuya.valueConverter.raw], // <- mapped the datapoint
95
+
],
96
+
},
199
97
```
200
98
201
-
Repeat for all data points.
99
+
The values in the mapped datapoint are as follows:
100
+
1. The datapoint (`8` in this example)
101
+
2. The key under which this value should be published in the state (`humidity` in this example)
102
+
3. The value converter, this converts the received value before publishing it (`tuya.valueConverter.raw` in this example). There are more value converters available, examples:
103
+
- If the value needs to be divided by 10 you can use `tuya.valueConverter.divideBy10`
104
+
- If the value needs to be mapped to a string you can use `tuya.valueConverterBasic.lookup({'single': 0, 'double': 1, 'hold': 2})`
105
+
- For more examples search for `tuyaDatapoints` in [`tuya.js`](https://github.com/Koenkk/zigbee-herdsman-converters/blob/master/devices/tuya.js).
106
+
107
+
Repeat this for all datapoints.
202
108
203
109
### 6. BONUS: Contacting the manufacturer
204
-
When contacting a manufacturer of Tuya compatible device DO NOT ask for Zigbee protocol of the device, they usually have no idea how the Tuya radio that they bought communicates over Zigbee. Instead ask for the UART protocol for their device, this should give you a better cooperation. You can also ask them about DPIDs and data formats for their functions.
110
+
When contacting a manufacturer of TuYa compatible device DO NOT ask for Zigbee protocol of the device, they usually have no idea how the TuYa radio that they bought communicates over Zigbee. Instead ask for the UART protocol for their device, this should give you a better cooperation. You can also ask them about DPIDs and data formats for their functions.
205
111
206
112
### 7. BONUS 2: Further reading
207
-
You can read more about how the device communicates with Tuya Zigbee radio module [here](https://developer.tuya.com/en/docs/iot/device-development/access-mode-mcu/zigbee-general-solution/tuya-zigbee-module-uart-communication-protocol/tuya-zigbee-module-uart-communication-protocol?id=K9ear5khsqoty)
113
+
You can read more about how the device communicates with TuYa Zigbee radio module [here](https://developer.tuya.com/en/docs/iot/device-development/access-mode-mcu/zigbee-general-solution/tuya-zigbee-module-uart-communication-protocol/tuya-zigbee-module-uart-communication-protocol?id=K9ear5khsqoty)
0 commit comments