mhop/tuya-mqtt
1
0
Fork 0
mirror of https://github.com/lehanspb/tuya-mqtt.git synced 2025-12-16 09:44:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

3.0.0 Documentation Update

Browse Source
This commit is contained in:
tsightler
2020-10-16 21:32:27 -04:00
parent ab2d4da5d6
commit 1abcdb02dc
4 changed files with 147 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
README.md
View File

@@ -1,11 +1,13 @@
# tuyAPI-MQTT Client
MQTT interface for Tuya home automation devices sold under various names.
This is a wrapper script for the Project codetheweb/tuyapi. https://github.com/codetheweb/tuyapi
# tuya-mqtt
This project provides an MQTT gateway for locally controlling home automation devices made by Tuya Inc and sold under many different brands. To use this script you will need to obtain the device ID and local keys for each of your devices after they are configured via the Tuya/Smart Life or other Tuya compatible app (there are many). With this information it is possible to communicate locally with Tuya devices using Tuya protocol version 3.1 and 3.3, without using the Tuya Cloud service, however, getting the keys requires signing up for a Tuya IOT developer account or using one of several other alternative methods (such as dumping the memory of a Tuya based app running on Andriod).
This project provides an MQTT gateway for locally controlling home automation devices made by Tuya Inc. To use this script you will need to obtain the device ID and local keys for each of your devices after they are configured via the Tuya/Smart Life or other Tuya compatible app (there are many). With this information it is possible to communicate locally with Tuya devices using protocol 3.1 and 3.3, without using the Tuya Cloud service, however, getting the keys requires signing up for a Tuya IOT developer account or using one of several other alternative methods (such as dumping the memory of a Tuya based app running on Andriod). Acquiring keys is not part of this project, please see the instructions at the TuyAPI project (on which this script is based) available at the TuyAPI project site:
Acquiring keys is not part of this project, please see the instructions at the TuyAPI project (on which this script is based) available at the TuyAPI project site:
https://github.com/codetheweb/tuyapi/blob/master/docs/SETUP.md.
**!!!!!!!!!! Important information regarding the 3.0 release !!!!!!!!!!**
The 3.0.0 release (Oct 17th, 2020) is a major refactor of the tuya-mqtt project and, as such, is a breaking release. Almost everything about the project is different, including configuration, topic names, etc. Upgrading users should carefully read the instructions below and assume they are starting over from scratch.
## Instructions:
Download this project to your system into any directory (example below uses /opt/tuya-mqtt) and install tuyapi from the same folder that the tuya-mqtt.js is in
```
@@ -22,16 +24,37 @@ cd tuya-mqtt
npm install
```
## Configuration
tuya-mqtt uses two different configuration files, config.json is a simple file which contains settings for connection to the MQTT broken, and devices.conf is a JSON5 file which defines the Tuya device that the script should connect to and expose via MQTT. This file uses the same basic format as the "tuya-cli wizard" outputs when used to acquire the device keys, so it can be used as the basis for you configuration.
## Basic Usage
### Create your configuration file:
### Seting up config.json:
```
cp config.json.sample config.json
// edit the configuration file
// Edit config.json with your MQTT broker settings and save
nano config.json
```
## Setup devices.conf:
If you use the "tuya-cli wizard" method to acquire your device keys you can leverage the output of this tool as the start of your devices.conf file. Otherwise, you want to create a file using a formate like this:
```
[
{
name: 'Tuya Device 1',
id: '86435357d8b123456789',
key: '8b2a69c9876543210'
},
{
name: 'Tuya Device 2',
id: 'eb532eea7d12345678abc',
key: '899810012345678'
}
]
Note that, because the format is JSON5, which is a superset of JSON, you can use standard, strict JSON syntax, or the more forgiving JSON5 format, or even mix and match in the same file.
While the above syntax is enough to create a working tuya-mqtt install with generic devices, the full power and simplicity of tuya-mqtt 3.0 is only unlocked by configuring device types to get . Please see the full [DEVICES](docs/DEVICES.md) documenation for details.
### Start command
```
node tuya-mqtt.js
@@ -39,76 +62,31 @@ node tuya-mqtt.js
// For debugging purpose, to use DEBUG : https://www.npmjs.com/package/debug
//on Linux machines at the bash command prompt, to turn ON DEBUG:
DEBUG=* tuya-mqtt.js
//on Linux machines at the bash command prompt, to turn OFF DEBUG:
DEBUG=-* tuya-mqtt.js
DEBUG=tuya-mqtt:* tuya-mqtt.js
// on Windows machines at the cmd.exe command prompt, to turn ON DEBUG:
Set DEBUG=* & node c:/openhab2/userdata/etc/scripts/tuya-mqtt.js
// on Windows machines at the cmd.exe command prompt, to turn OFF DEBUG:
Set DEBUG=-* & node c:/openhab2/userdata/etc/scripts/tuya-mqtt.js
Set DEBUG=tuya-mqtt:* & node c:/openhab2/userdata/etc/scripts/tuya-mqtt.js
```
### MQTT Topic's (send data)
**It's possible to replace the device IP address \<tuyAPI-ip\> with the word "discover" to have the API attempt to automatically discover the device IP address. This allows support for 3.3 protocol devices transparently, without additional configuraiton, but does require the system running this script to be on the same IP subnet as the Tuya device since the discovery protocol relies on UDP broadcast packets from the devices.**
```
tuya/<tuyAPI-id>/<tuyAPI-key>/discover/state
tuya/<tuyAPI-id>/<tuyAPI-key>/discover/command
```
**If discovery will not work for your case you can still use the IP address, but, to use protocol 3.3 you must specify it in the topic explicitly**
```
tuya/ver3.3/<tuyAPI-id>/<tuyAPI-key>/<tuyAPI-ip/state
tuya/ver3.3/<tuyAPI-id>/<tuyAPI-key>/<tuyAPI-ip>/command
```
### Example command topic to set the device state:
```
tuya/<tuyAPI-id>/<tuyAPI-key>/<tuyAPI-ip>/command
```
### Example MQTT message payload for basic commands (default controls DPS[1] value, assumes true/false state control):
```
"ON"
"OFF"
"on"
"off"
"1"
"0"
"toggle"
"TOGGLE"
```
### Example MQTT message payload for advanced commands (set any DPS value):
```
"{ \"dps\": 1, \"set\": true }"
"{ \"dps\": 7, \"set\": true }"
"{ \"multiple\": true, \"data\": { \"1\": true, \"7\": true } }"
"{ \"schema\": true }"
"{ \"multiple\": true, \"data\": { \"1\": true, \"2\": \"scene_4\" } }"
"{ \"multiple\": true, \"data\": { \"1\": true, \"2\": \"scene\", \"6\": \"c479000025ffc3\" } }"
```
### Example command topic for color change of lightbulb
```
tuya/<tuyAPI-id>/<tuyAPI-key>/<tuyAPI-ip>/color
### Tuya DPS values Overview
Tuya devices are monitored and controlled using a simple API where a devices functions are mapped to DPS (data point state) values stored in various numbered keys. For example, a simple on/off switch may have a single key, DPS1, with a setting of true/false representing the on/off state of the device. The device state can be read via this DPS1 key, and, for values that can be changed, sending true/false to DPS 1 will turn the device on/off. A simple dimmer might have the same DPS1 key as true/false for on/off, and a DPS2 key as a value from 0-255 to represent the state of the dimmer value. More complex devices use more DPS keys with various values representing the states and control functions of the device.
Example MQTT message payload:
64,0,100
0,0,89
### MQTT Topic Overview
The top level topics are created using the device name or ID as the primary identifier. If the device name is available, it will be converted to lowercase and spaced replace with underscores('_') characters so, for example, if using the sample devices.conf file from above, the top level topic would be:
```
tuya/tuya_device_1/
```
If the device name was not available, it would instead use the device ID:
```
tuya/86435357d8b123456789/
```
All other topics are then build below this level.
### Example state topics (get device data)
### Get current device state (always DPS[1] value):
tuya/<tuyAPI-id>/<tuyAPI-key>/<tuyAPI-ip>/state
tuya-mqtt directly exposes the Tuya DPS keys and values via MQTT topics and you can control any Tuya device using these topics, however, because it is not always easy to translate the Tuya values into something easy to consume by standard Home Automation systems, tuya-mqtt includes a simple templating engine to map DPS values to "friendly topics", i.e. topics that are easier to consume.
### Get all available device DPS values
Returns JSON.stringify(dps) values, use with care, does not always contain all dps values
```
tuya/<tuyAPI-id>/<tuyAPI-key>/<tuyAPI-ip>/dps
```
By default, all devices are treated as generic Tuya devices and only the raw DPS values are exposed, however, some devices have predefined templates which can be configured in the device.conf file. Also, you can manually define a template mapping using the "GenericDevice" configuraiton. Please read more details in the [DEVICES](docs/DEVICES.md) documentation.
### Get any single DPS data value
```
tuya/<tuyAPI-id>/<tuyAPI-key>/<tuyAPI-ip>/dps/<tuya-dps-id>
```
For more details on DPS and friendly topics, please see the [TOPICS](TOPICS.md) documentation.
## Issues
Not all Tuya protocols are supported. For example, some devices use protocol 3.2 which currently remains unsupported by the TuyAPI project due to lack of enough information to reverse engineer the protcol. If you are unable to control your devices with tuya-mqtt please verify that you can query and control them with tuya-cli first. If tuya-cli works, then this script should also work, if it doesn't then this script will not work either.

2
devices/tuya-device.js
View File

@@ -522,7 +522,7 @@ class TuyaDevice {
return hex + hsb;
}
// Set white/colour mode based on
// Set white/colour mode based on received commands
async setLight(topic, command) {
let targetMode = undefined

0
docs/DEVICES.md Normal file
View File

100
docs/TOPICS.md Normal file
View File

@@ -0,0 +1,100 @@
# tuya-mqtt Topics
tuya-mqtt support two styles of topics for devices. For all devices the DPS topics are always published and commands are accepted, however, friendly topics allow mapping DPS values into friendier topics names with more control over allowed values, and allow simple functions like math transforms, etc. While it's always possible to use the DPS topics directly, friendly topics are the generally recommended approach but require you to create a template for your device if it doesn't match one of the pre-defined templates.
If you create a template for your device, please feel free to share it with the community as adding additional pre-defined devices is desired for future versions of tuya-mqtt.
If you would like to use the raw DPS topics, please jump to the DPS topic section of this document.
## Friendly Topics
Friendly topics are only available when using a pre-defined device template or, when using the generic device, when you have defined a custom template. Friendly topics use a simple templating engine to map raw Tuya DPS key values to easy to consume topic and transform the data where needed. The other advantage to using friendly topics is that not all devices respond to schema requets so it's not always possible for tuya-mqtt to know which DPS topics to acquire state information from during startup. With a template the required DPS topics are configured and tuya-mqtt will always query these individual values during initial connection to the device.
When using pre-device device templates, please see the appropriate section in the [DEVICES](docs/DEVICES.md) documentation. When using a generic device, you can define a template in the devices.conf file. Imagine a simple dimmer with key 1 representing on/off and key 2 represeting brightness. When using just the basic devices.conf file, controlling a device requires using the DPS topics directly, for example:
```
tuya/dimmer_device/DPS/1 <-- true/false for state and control
tuya/dimmer_device/DPS/2 <-- value 1-255, for state and control, accepts invalid values, etc.
```
While this will work, in this case the automation system would need to understand true/false vs on/off, and would need to be manually configured for 1-255 scale instead of, for example, a 1-100% scale (some systems deal with this quite easily, others, not so much). However, using a template you can quickly create an easy to use set of friendly topics with easier to consume values:
```
[
{
name: 'Tuya Device 1',
id: '86435357d8b123456789',
key: '8b2a69c9876543210',
template: {
state: {
key: 1,
type: 'bool'
},
brightness_state: {
key: 2,
type: 'int',
min: 1,
max: 255,
stateMath: '/2.55',
commandMath: '*2.55'
}
}
}
]
```
Now, controlling the device can be done with the following topics:
```
tuya/dimmer_device/state <-- Reports ON/OFF
tuya/dimmer_device/command <-- Accepts 0/1, on/off, or true/false
tuya/dimmer_device/brightness_state <-- Reports 1-100 scale for brightness %
tuya/dimmer_device/brightness_state <-- Accepts 1-100 scale for brightness %
```
More complex mappings are possible. All pre-defined device templates use the same, built-in, templating engine, so further examples can been seen by browsing the source code of the device files. Below are the available options for each value type:
### Boolean values
| type | 'bool' |
| key | DPS key for the value |
### Integer values
| type | 'int' |
| key | DPS key for the value |
| min | Minumum value allowed for the command topic |
| max | Maximum value allowed for the command topic |
| stateMath | Simple math applied to the DPS key value before being published to state topic |
| commandMath | Simple math applied to command value before being set to DPS key |
### Floating point values
| type | 'float' |
| key | DPS key for the value |
| min | Minumum value allowed for the command topic |
| max | Maximum value allowed for the command topic |
| stateMath | Simple math applied to the DPS key value before being published to state topic |
| commandMath | Simple math applied to command value before being set to DPS key |
### String values
| type | 'string' |
| key | DPS key for the value |
### Tuya HSB values (newer style Tuya, 12 character color value)
| type | 'hsb' |
| key | DPS key for the value |
| components | Comma separated list of HSB components that should be included in this topic |
### Tuya HSBHEX values (older style Tuya 14 character color value)
| type | 'hsbhex' |
| key | DPS key for the value |
| components | Comma separated list of HSB components that should be included in this topic |
## DPS Topics
Controlling devices directly via DPS topics requires enough knowledge of the device to know which topics accept what values. There are actually two differnt methods interfacing with DPS values, the JSON DPS topic, and the individual DPS key topics.
### JSON DPS Topics
The JSON DPS topic allows controlling Tuya devices by sending raw, Tuya style JSON messages to the command topic, and by monitoring for Tuya style JSON replies on the state topic. You can get more details on this format by reading the [TuyAPI documentaiton](https://codetheweb.github.io/tuyapi/index.html), but, for example, to turn off a dimmer switch you could issue a MQTT message containing the JSON value {dps: 1, set: false} to the DPS/command topic for the device. If you wanted to turn the dimmer on, and set brightness to 50%, you could issue separate messages {dps: 1, set: true} and then {dps: 2, set: 128}, or, the Tuya JSON protocol also allows setting multiple values in a single set command using the format {'multiple': true, 'data': {'1': true, '2': 128}}. JSON state and commands should use the DPS/state and DPS/command topics respectively. Below is an example of the topics:
```
tuya/dimmer_device/DPS/state
tuya/dimmer_device/DPS/command
```
In addition to the JSON DPS topic, it's also possible to use the DPS key topics. DPS key topics allow you to monitor and send simple bool/number/string values directly to DPS keys without having to use the Tuya JSON format, the conversion to Tuya JSON is handled by tuya-mqtt. Using the example from above, turning on the dimmer and setting brightness to 50% you would simply issue the message "true" to DPS/1/command and the message "128" to DPS/2/command.
```
tuya/dimmer_device/DPS/1/state <-- true/false for on/off state
tuya/dimmer_device/DPS/2/command <-- 1-255 for brightness state
tuya/dimmer_device/DPS/1/state <-- accept true/false for turning device on/off
tuya/dimmer_device/DPS/2/command <-- accepts 1-255 for controlling brightness level
```
**!!! Important Note !!!** When sending commands directly to DPS values there are no controls on what values are sent as tuya-mqtt has no way to know what are valid vs invalid values. Sending values that are out-of-range or of different types can cause unpredicatable behavior of your device, from causing timeouts, to reboots, to hanging the device. While I've never seen a device not recover after a restart, please keep this in mind when sending commands to your device.