mirrors
/
Tasmota
mirror of https://github.com/arendst/Tasmota.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated TuyaMCU (markdown)

blakadder 2019-10-27 22:10:46 +01:00
parent a79d9e4e00
commit 7ef8ab79f9
1 changed files with 177 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

180
TuyaMCU.md

@ -1,56 +1,90 @@
TuyaMCU module is used with Tuya devices (dimmers, curtain motors, humidifiers, etc) employing a secondary MCU to facilitate communication between Tasmota and that MCU.
Module **TuyaMCU (54)** is configured for devices with a Tuya Wi-Fi module and a secondary MCU.
In those devices the Wi-Fi module takes care of Wi-Fi and software features while the MCU controls the hardware based on commands from the module or built-in controls (buttons, switches, remotes and similar) and reports its status back to the Wi-Fi module. TuyaMCU maps all the different functions to Tasmota components and issues serial commands to the MCU and interprets status messages sent over serial from the MCU.
Originally, in those devices, the Wi-Fi module takes care of network and software features. Meanwhile, the MCU controls the hardware based on commands received from the Wi-Fi module or built-in controls (buttons, switches, remotes and similar) and reports the status back to the Wi-Fi module.
# TuyaMCU command
The TuyaMCU module introduces a new command [`TuyaMCU`](commands#tuyamcu) which maps the FunctionIDs to DpIds.
> Used only if your device is defined as module `TuyaMCU (54)` (formerly: `Tuya Dimmer (54)`) .
The MCU communicates with the Wi-Fi module through the serial port. Protocols are classified into basic and functional protocols.
## DpId
All the components (relays, dimmers, switches, lights, sensors, etc) controlled by the MCU are identified by a DpId.
Whenever a command is sent to the MCU, this DpId dictates which component needs to be changed and same is used when the status is received from MCU.
## Basic protocols
They are common protocols integrated in Tasmota's TuyaMCU module. They stay the same for each product and are mandatory for Tuya module to work correctly.
There is no way the Wi-Fi module firmware knows the function of each DpId, so, just like [configuring GPIOs](Configuration-Procedure-for-New-Devices) for your device, you need to map DpId's with their functions.
## Functional protocols
Functional protocols are used for delivering and reporting data of functions. These protocols differ between devices and manufacturers and might require configuration in Tasmota using [`TuyaMCU`](#tuyamcu) command or with [`TuyaSend<x>`](#tuyasend) command.
## FunctionID
FunctionID defines which type of [component](components) is located at which DpId.
### Anatomy of functional protocols
TuyaMCU module supports the following:
|Name|Description|
|---|---|
|Frame Header Version|Fixed value of 0x55aa |
|Command Word | `0x06` - send commands<br>`0x07` - report status|
|Data Length | defines expected length of data
|dpID|numbered ID of a function (DP = Data Point or Define Product)|
|Data Type|[see Data Type table below](#data-type-table)|
|Function Length|length of command|
|Function Command|formatted according to Data Type|
|Verification Method| checksum = remainder of the byte sum starting from Frame Header to 256|
Component| FunctionId
-|-
Switch1 to Switch4 | 1 to 4
Relay1 to Relay8 | 11 to 18
Dimmer | 21
Power (in deci Watt) | 31
Current (in milli Amps) | 32
Voltage (in deci Volt) | 33
Relay Inverted1 to Relay Inverted8 | 41 to 48
<a id="data-type-table"></a>
#### Data Type
|Hex|Tasmota Command|Decription|Max length|
|---|---|---|---|
|0x01|TuyaSend1|boolean data `0/1`|1 byte|
|0x02|TuyaSend2|value data. If a value contains less than 4 bytes, 0 is supplemented before|4 bytes|
|0x00|TuyaSend3|string data|unknown|
|0x04|TuyaSend4|enum data `0/1/2/3/4/5`|1 byte|
|0x05|###|fault data, report only|8 bytes|
> Array of various Tuya devices is vast and this component is under active development which means the function list may expand in the future. Currently it might not be possible to implement all functions of your device (for example: RGB color selection or multiple DpId states).<br>For multiple DpId states functionality can be regained using rules and captured serial commands from the original firmware.
Let's dissect and explain the MCU protocol using serial command `55aa0006000501010001010e`:
## Command Usage
The TuyaMCU command value consists of two comma separated parameters: FunctionID and DpId.
| Frame Header Version | Command Word | Data Length | dpID | Data Type | Function Length | Function Command | Verification Method |
|----------------------|--------------|-------------|------|-----------|-----------------|------------------|---------------------|
| 55aa00 | 06 | 0005 | 01 | 01 | 0001 | 01 | 0e |
This is the command which powers on the device sending Function Command = `1` to dpID 1 (Switch):
- Frame Header Version = `0x55aa00` which is a fixed value and always the same
- Command Word = `0x06` because we're sending a command
- Data Type = `0x01` since the command sent is a 1 byte boolean
- Function Length = `0x001` instruct 1 character only for function command length
- Function Command = `0x01` in hex which equals `1` in int
- Verification Method = `0e` is calculated
### Protocol flow
On device boot, TuyaMCU executes the required basic protocols and reads the functional protocol data received, which are used to update status of components mapped in TuyaMCU (Relays, dimmer, power monitoring data).
After receiving a command from Tasmota (Command Word `0x06`), the MCU performs corresponding logical control. When the dpID status is changed, the MCU reports the data (Command Word `0x07`) to TuyaMCU component.
TuyaMCU module facilitates communication between Tasmota and the MCU with:
- `TuyaMCU` command maps device functions to Tasmota components
- `TuyaSend<x>` command calculates and sends complex serial commands using only two parameters
- "TuyaReceived" response interprets status messages and publishes a JSON payload to an MQTT topic
# TuyaMCU
Command [`TuyaMCU`](commands#tuyamcu) is used to map Tasmota components to Tuya device dpId's.
> Used only if your device is defined as module `TuyaMCU (54)`.
Command value consists of two comma separated parameters: fnId and dpId.
```
TuyaMCU <fnId>,<dpId>
```
where `<fnId>` is FunctionID and `<dpId>` is the DpId to map the function to.
- `TuyaMCU 11,1` maps Relay1 (FunctionID 11) to DpId 1.
where `<fnId>` is a Tasmota component and `<dpId>` is the dpId to map the function to.
> `TuyaMCU 11,1` maps Relay1 (fnId 11) to dpId 1.
If any existing entry with same `fnId` or `dpId` is already present, it will be updated to the new value.
Entry is removed when `fnId` or `dpId` is `0`.
When no parameters are provided `TuyaMCU` prints the current mapped values.
## Identification of FunctionIDs and DpIds
As mentioned, the hardware is controlled by an MCU. The Wi-Fi module sends commands to MCU over serial to control the hardware. Each hardware component has a DpId which can have different functions on each model. See [this list](tuya-protocols) for *possible* combinations.
### dpId
All the device functions controlled by the MCU are identified by a dpId.
Whenever a command is sent to the MCU, this dpId determines which component needs to be controlled and the applies when the status is received from MCU.
We need to identify these DpIds:
**There is no way to autodetect dpId's and their functions.**
Use this procedure to determine which dpId's are available:
1. Go to `Configure` -> `Console` option in Tasmota web interface.
2. Use command `weblog 4` to enable verbose logging in web interface.
3. Observe the log. After every 9-10 seconds you should see log messages such as:
3. Observe the log. After every 9-10 seconds you should see log messages similar to:
```
TYA: Heartbeat
TYA: RX Packet: "55aa0107000501010001000f"
@ -78,7 +112,89 @@ We need to identify these DpIds:
TYA: RX Packet: "55aa0107000868020004000009870d"
TYA: FnId=0 is set for dpId=104
```
4. Observe all lines printed as `TYA: FnId=0 is set for dpId=XXX` and note all dpId values.
4. The function ids are printed as `TYA: FnId=0 is set for dpId=XXX` We will use these `XXX` ids in the guide ahead
Now that you have a list of usable dpId's you need to determine what their functions are:
1. Consulting our [list of commonly used](https://github.com/arendst/Sonoff-Tasmota/wiki/TuyaMCU-Configurations#dpid-functions-in-different-devices) dpId's and existing device configurations
2. Observing Tasmota logs while activating features of the device (with a remote or on device controls) and correlating log messages
3. Extrapolating possible function of the dpId based on Data Type and Function Command, then testing using `TuyaSend<x>`
### fnId
Identifier used in `TuyaMCU` command to map a dpId to a Tasmota component.
Component| FunctionId|Note
-|-|-
Switch1 to Switch4 | 1 to 4 | Map only to dpId with on / off function
Relay1 to Relay8 | 11 to 18 | Map only to dpId with on / off function
Dimmer | 21 | only on dpId with dimming function
Power (in deci Watt) | 31 |
Current (in milli Amps) | 32 |
Voltage (in deci Volt) | 33 |
Relay Inverted1 to Relay Inverted8 | 41 to 48 | Map only to dpId with on / off function
> This component is under active development which means the function list may expand in the future.
Since the majority of devices have a power on/off functions on dpId 1 its mapped to fnId 11 (Relay1) by default.
***Mapping a relay or switch to a dpId that is not Data Type 0x01 (simple on/off) might result in unwanted power toggling (f.e. dpId sends value of 4 which toggles the relay to Power 4 aka blink mode***
More on [TuyaMCU configuration of specific devices](tuyamcu-configurations)
# TuyaSend
**Requires latest development version, not supported in 6.7.1**
Command `TuyaSend` is used to send commands to dpId's. It is required for dpId's that shouldn't be mapped to a fnId.
With this command it is possible to control every function of the dpId that is controllable, providing you know its data type and data length. With them provided, the rest of the protocol command is calculated.
Command's value consists of two comma separated parameters: dpId and data.
`TuyaSend<x> dpId,data`
There are 4 different commands, one for each [data type](#data-type-table).
- `TuyaSend1` -> Sends boolean (Type 1) data (`0/1`) to dpId (Max data length 1 byte)
> `TuyaSend1 1,0` sends vaue `0` to dpId=1 switching the device off
- `TuyaSend2` -> Sends integer or 4 byte (Type 2) data to dpId (Max data length 4 bytes)
> `TuyaSend2 14,100` sends value `100` to dpId=14 setting timer to 100 minutes
- `TuyaSend3` -> Sends string (Type 3) data to dpId ( Max data length not-known)
> `TuyaSend3 108,ff0000646464ff` sends a 14 char hex string to dpId=108 (Type 3) containing RGBHSV values to control a light
- `TuyaSend4` -> Sends enum (Type 4) data (`0/1/2/3/4/5`) to dpId (Max data length 1 bytes)
> `TuyaSend4 103,2` sends value `2` to dpId=103 to set fan speed to high
# TuyaReceived
**Requires latest development version, not supported in 6.7.1**
Every status message from the MCU gets a JSON response named `TuyaReceived` which contains the MCU protocol status message inside key/value pairs which are hidden from the user by default.
To publish them to an MQTT Topic of `tele/%topic%/RESULT` you need to enable `SetOption66 1`.
### Example
After issuing serial command `55aa0006000501010001010e` (Device power (dpId=1) is mapped to Relay1 (fnId=11)) we get the following console output (with `weblog 4`):
```
19:54:18 TYA: Send "55aa0006000501010001010e"
19:54:18 MQT: stat/GD-30W/STATE = {"Time":"2019-10-25T19:54:18","Uptime":"0T01:45:51","UptimeSec":6351,"Heap":27,"SleepMode":"Dynamic","Sleep":0,"LoadAvg":999,"MqttCount":1,"POWER1":"ON","POWER2":"OFF","POWER3":"ON","POWER4":"OFF","POWER5":"ON","Dimmer":100,"Fade":"OFF","Speed":1,"LedTable":"OFF","Wifi":{"AP":1,"SSId":"HTPC","BSSId":"50:64:2B:5B:41:59","Channel":10,"RSSI":24,"LinkCount":1,"Downtime":"0T00:00:08"}}
19:54:18 MQT: stat/GD-30W/RESULT = {"POWER1":"ON"}
19:54:18 MQT: stat/GD-30W/POWER1 = ON
19:54:18 MQT: stat/GD-30W/RESULT = {"TuyaReceived":{"Data":"55AA0007000501010001010F","ChkSum":"0x0F","Cmnd":7,"CmndDataLen":5,"CmndData":"0101000101","DpId":1,"DpIdType":1,"DpIdLen":1,"DpIdData":"01"}}
19:54:18 TYA: fnId=11 is set for dpId=1
19:54:18 TYA: RX Relay-1 --> MCU State: On Current State:On
```
Above `TYA: fnId=11 is set for dpId=1` you can see the JSON response for that dpId. This JSON string displays the response MCU gave to our command.
"Data" field contains the complete response and the rest of the key/value pairs show the protocol broken into parts. "DpId", "DpIdData" and "DpIdType" are the ones we're most interested in since we can used them for `TuyaSend`.
> You can use command `SerialSend5 55aa0001000000` at any time to request statuses of all dpId's from the MCU.
### Use in rules
This data can also be used as a trigger for rules using `TuyaReceivedData#Data=hex_string`
```
Rule1 on TuyaReceived#Data=55AA000700056E040001007E do publish2 stat/tuya_light/effect rgb_cycle
```
will publish a status message to a custom topic when `55AA000700056E040001007E` appears in "Data" field of the response.
#### Useful tidbits
## [TuyaMCU Configurations](TuyaMCU-Configurations)