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

3.0.0 Documentation updates

Browse Source
This commit is contained in:
tsightler
2020-10-17 13:32:50 -04:00
parent 1147b9e8c1
commit 45a26f84de
4 changed files with 242 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
README.md
View File

@@ -29,7 +29,7 @@ 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.
Tuya-mqtt has two different configuration files. The first is config.json, a simple file which contains settings for connection to the MQTT broker. The second is devices.conf, a JSON5 formatted file which defines the Tuya devices 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 your tuya-mqtt device configuration.
### Seting up config.json:
```
@@ -83,11 +83,38 @@ tuya/86435357d8b123456789/
```
All state/command topics are then built below this level.
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.
Tuya-mqtt supports two distinct topic types for interfacing with and controlling devices. For all devices, the DPS topics are always published and commands are accepted, however, friendly topics allow mapping DPS values into device specific topic names allowing more control over allowed values, and allowing simple functions like math transforms, min/max limits, 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 a pre-defined template for your device does not currently exist.
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.
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. There is a templates section of the project that you can submit a PR for your templates.
For more details on DPS and friendly topics, please see the [TOPICS](docs/TOPICS.md) documentation.
If you would like to use the raw DPS topics, please jump to the [DPS topics](#dps-topics) section of this document.
## Friendly Topics
As noted above, friendly topics are only available when using a pre-defined device template or, for the generic device, when you have defined a custom template for your device. Friendly topics use the tuyq-mqtt templating engine to map raw Tuya DPS key values to easy to consume topics and transform the data where needed.
Another advantage of friendly topics is that not all devices respond to schema requets (i.e. a request to report all DPS topics the device uses). Because of this, it's not always possible for tuya-mqtt to know which DPS topics to acquire state information from during initial startup. With a defined template the required DPS keys for each friendly topic are configured and tuya-mqtt will always query these DPS key values during initial connection to the device and report their state appropriately.
Also, when using friendly topics, it is always possible to get the current state of all topics by sending a message to the device "command" topic with the mssage "get-states". For more details on using friendly topics, please read the [DEVICES](docs/DEVICES.md) documentation.
## DPS Topics
Controlling devices directly via DPS topics requires enough knowledge of the device to know which topics accept what values. There are two differnt methods interfacing with DPS values, the JSON DPS topic, and the individual DPS key topics.
### DPS JSON topic
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
```
### DPS Key topics
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.
## 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.

4
devices/rgbtw-light.js
View File

@@ -22,8 +22,8 @@ class RGBTWLight extends TuyaDevice {
this.config.dpsWhiteValue = this.config.dpsWhiteValue ? this.config.dpsWhiteValue : this.guess.dpsWhiteValue
this.config.whiteValueScale = this.config.whiteValueScale ? this.config.whiteValueScale : this.guess.whiteValueScale
this.config.dpsColorTemp = this.config.dpsColorTemp ? this.config.dpsColorTemp : this.guess.dpsColorTemp
this.config.minColorTemp = this.config.minColorTemp ? this.config.minColorTemp : 160
this.config.maxColorTemp = this.config.maxColorTemp ? this.config.maxColorTemp : 385
this.config.minColorTemp = this.config.minColorTemp ? this.config.minColorTemp : 154 // ~6500K
this.config.maxColorTemp = this.config.maxColorTemp ? this.config.maxColorTemp : 400 // ~2500K
this.config.colorTempScale = this.config.colorTempScale ? this.config.colorTempScale : this.guess.colorTempScale
this.config.dpsColor = this.config.dpsColor ? this.config.dpsColor : this.guess.dpsColor
this.config.colorType = this.config.colorType ? this.config.colorType : this.guess.colorType

209
docs/DEVICES.md
View File

@@ -0,0 +1,209 @@
# Device in tuya-mqtt
The most powerful feature in tuya-mqtt is the ability to configure devices to use friendly topics. For some devices there exist pre-defined device templates which makes using those devices quite easy, simply add the type information to the devices.conf file and tuya-mqtt automatically creates friendly topics for that device. Friendly topics make it easy to communicate with the device in a standard way and thus integrating into various Home Automation platforms. The topic style generally follows that used by the Home Assistant MQTT integration components and the pre-defined devices even send Home Assistant style MQTT discovery messages during startup to make integration with Home Assistant, or other platforms which understand Home Assistant MQTT discovery, even easier.
If your device does not have a pre-defined device template, you can still create a template using the [generic device template](#generic-device-templates) feature.
## Pre-defined Device Templates
Pre-defined device templates (except for the Generic Device) will always expose friendly topics for the given device in a consistent manner. Currently the following pre-defined device templates are available:
| Device Type | Descrition |
| --- | --- |
| SimpleSwitch | Supports simple on/off devices |
| SimpleDimmer | Supports simple devices with on/on and brightness |
| RGBTWLight | Supports color/white lights with optional color temerature support |
| GenericDevice | Allows defining a custom template for any device |
To use a device template, simply add the "type" option to the devices.conf similar to the following example:
```
[
{
name: 'Tuya Device 1',
id: '86435357d8b123456789',
key: '8b2a69c9876543210',
type: 'RGBTWLight'
}
]
```
Once the device type is defined tuya-mqtt will attempt to create friendly topics for that device type on connection to the device. Each device type defines specific defaults for DPS values which are typical for common Tuya devices and some, like RGBTWLight, have logic to attempt to detect different variation by querying the device. The goal is that, in most cases, simply adding the type is all that is needed, however, in many cases it is also possible to override the manual settings for the device. The device friendly topics and options for each device are documented below.
### SimpleSwitch
Simple devices that support only on/off.
| Topic | Description | Values |
| --- | --- | --- |
| state | Power state | on/off |
| command | Set power state | on/off, 0/1, true/false |
Configuration override options:
| Option | Description | Default |
| --- | --- | |
| dpsPower | DPS key for power state | 1 |
### SimpleDimmer
Simple device with on/off and brightness functions (dimmer switches or lights)
| Topic | Description | Values |
| --- | --- | --- |
| state | Power state | on/off |
| command | Set power state | on/off, 0/1, true/false |
| brightness_state | Brightness in % | 1-100 |
| brightness_command | set brightness in % | 1-100 |
Configuration override options:
| Option | Description | Default |
| --- | --- | |
| dpsPower | DPS key for power state | 1 |
| dpsBrightness | DPS key for brightness state | 2 |
| brightnessScale | Scale for brightness DPS value | 255 |
### RGBTWLight
The RGBTWLight device support Tuya color lights (bulbs and LEDs). Tuya lights operate in either white or color mode. The RGBTWLight device automatically switches between modes on certain conditions as documented below:
| Condition | Mode Switch |
| --- | --- |
| Changes white brightness | Yes: white |
| Changes to color temperature (for device with color temp support) | Yes: white |
| Saturation < 10 % | Yes: white |
| Saturation >= 10 % | Yes: color |
| All other changes | No: remain in current mode |
This means changing the hue of the light will only switch to color mode if saturation is also >= 10%. Some lights automatically switch to color mode when any HSB value is updated, but, if saturation remains < 10%, the code will force the light back to white mode. This sometimes causes a very fast flicker when chaning Hue or color brightness while the saturation is < 10%. I expect this not to be a common issue and implemented this in an attempt to make all bulbs have a consistent behavior.
When the bulb is in white mode, saturation values in the friendly topics are always reported as 0%. This is true even if the mode is toggled manually from color to white mode using the mode_command or the Tuya/SmartLife app. When the light is toggled back to color mode, saturation will be reported at the correct level. This is done primarly as a means to indicate color state to automation platforms that don't have a concept of white/color mode, otherwise a light in white mode my still be represented with a color icon in the platform UI.
Not all devices support color temperature and the script attempts to detect this capability and enables the color temperature topics only when found. Color temperature topics report in Mireds (commonly used by automation tools) and the default range supports roughly 2500K-6500K. This works reasonably well for most available Tuya devices, even if they are not exactly in this range, but, if you know a devices specific color range, the limits can be manually specified to more accurately reflect the exact color temperature.
| Topic | Description | Values |
| --- | --- | --- |
| state | Power state | on/off |
| command | Set power state | on/off, 0/1, true/false |
| white_brightness_state | White mode brightness in % | 1-100 |
| white_brightness_command | Set white mode brightness in % | 1-100 |
| color_brightness_state | Color mode brightness in % | 1-100 |
| color_brightness_command | Set white mode brightness in % | 1-100 |
| hs_state | Hue, saturation % | H,S (Hue 0-360, Saturation 1-100) |
| hs_command | Set hue, saturation % | H,S (Hue 0-360, Saturation 1-100) |
| hsb_state | Hue, saturation %, brightness % | H,S,B (Hue 0-360, Saturation 1-100, Brightness 1-100) |
| hsb_command | Set hue, saturation %, brightness % | H,S,B (Hue 0-360, Saturation 1-100, Brightness 1-100) |
| mode_state | White/Color mode | 'white', 'colour' (some devices also support scenes here) |
| mode_command | Set white/color mode | 'white', 'colour' (some devices also support scenes here) |
| color_temp_state | Color temperature in mireds (only available if device support color temp) | 154-400 (defult range, can be overridden) |
| color_temp_command | Set color temperature in mireds (only available if device support color temp) | 154-400 (defult range, can be overridden) |
The RGBTWLight function attempts to detect all required options automatically, this works for most common devices which use a standard Tuya DPS configurations (typically 1-5 or 20-24), however, it is possible to override the defaults for all used values. Below are the manual options for RGBTWLight:
| Option | Description | Default (common detected values) |
| --- | --- | |
| dpsPower | DPS key for power state | Auto Detect (1,20) |
| dpsMode | DPS key for white/color mode state | Auto Detect (2,21) |
| dpsWhiteValue | DPS key for white mode brightness | Auto Detect (3,22) |
| whiteValueScale | White mode brightness DPS scale | Auto Detect (255, 1000) |
| dpsColorTemp | DPS key for color temperature | Auto Detect (4,23) |
| minColorTemp | Min color temperature in Mireds | 154 (~6500K) |
| maxColorTemp | Max color temperature in Mireds | 400 (~2500K) |
| colorTempScale | Color temperature DPS key scale | Auto Detect (255, 1000) |
| dpsColor | DPS key for HSB color values | Auto Detect (5,24) |
| colorType | Tuya color format for color DPS key | Auto Detect (hsb, hsbhex) |
To use these options simply add them to device.conf file, example:
```
[
{
name: 'Tuya Device 1',
id: '86435357d8b123456789',
key: '8b2a69c9876543210',
type: 'RGBTWLight',
dpsPower: 31,
dpsMode: 32,
dpsWhiteValue: 33,
whiteValueScale: 255,
dpsColorTemp: 34,
minColorTemp: 165,
maxColorTemp: 385,
colorTempScale: 255,
dpsColor: 34,
colorType: 'hsbhex'
}
]
```
## Generic Device Templates
If a pre-defined device tempate does not exist for the device, or does not expose all capabilities of the device, there are still mulitple options available to control the devices. One method is to use the DPS topics directly to control the device using either native Tuya JSON commands or via the DPS key values by using the DPS key topics (see [DPS Topics](TOPICS.md#dps-topics)). The second method is to create a template for your device to map DPS key values to friendly topics. The GenericDevice type allows you to manually create a template for any device using the same templating engine as the pre-defined device templates. Once you've created a tempalte for your device, it can be re-used with other, similar devices and you can submit your template to the tuya-mqtt project for other to use, or even for inclusion at a pre-defined device template in the future.
Creating a device template is relatively straightforward, but first you must know what DPS keys your devices uses. The GenericDevice attempts to query all device DPS states on startup, but some devices to not respond to this command, however, the generic device will ALWAYS report any DPS topics from which it receives upated. The easiest way to determine how your device uses it's DPS topics is to connect to the MQTT broker via a tool like MQTT Explorer or mosquitto_sub, and watch the topics as you manipulate the device with the Tuya/Smartlife app.
Once you have a reasonable idea of how the device uses it's DPS key values, you can create a template. A simple template for a dimmer looks something like this:
```
[
{
name: 'Tuya Device 1',
id: '86435357d8b123456789',
key: '8b2a69c9876543210',
template: {
state: {
key: 1,
type: 'bool'
},
brightness_state: {
key: 2,
type: 'int',
topicMin: 1,
topicMax: 100,
stateMath: '/2.55',
commandMath: '*2.55'
}
}
}
]
```
The template above defines two topics "state" and "brightness_state", and the template engine automatically creates the corresponding command topics, in this case specifically "command" and "brightness_command".
The "state" topic maps to DPS key 1, and uses a bool (true/false) value in the DPS key. Now you will be able to see "on/off" state in the state topic instead of having to read the true/false value from the DPS/1 topic
The the "brightness_state" topic maps to DPS key 2, and this value defines the brightness using an integer in the 1-255 scale. We define the value as an integer (type: 'int') and the stateMath and commandMath values allow transforming the raw DPS value into a more friendly value that will be presented in the topic. In this case the raw DPS value will be divided by 2.55 before being published to the state, and and received commands will be mulitpled by that same value, converting the 1-255 to a simple 1-100 scale. Note that the topicMin and topicMax values set the minimum and maximum values that the state topic will report and that the command topic will accept. These values are "post-math" for state topics, and "pre-math" for command topics.
The following tables define the available template value types and their options:
### Boolean values
| option | value |
| --- | --- |
| type | 'bool' |
| key | DPS key of the value |
### Integer values
| option | value |
| --- | --- |
| type | 'int' |
| key | DPS key of the value |
| topicMin | Minumum value allowed for the command topic |
| topicMax | 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
| option | value |
| --- | --- |
| type | 'float' |
| key | DPS key of the value |
| topicMin | Minumum value allowed for the command topic |
| topicMax | 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
| option | value |
| --- | --- |
| type | 'string' |
| key | DPS key of the value |
### Tuya HSB values (newer style Tuya, 12 character color value)
| option | value |
| --- | --- |
| type | 'hsb' |
| key | DPS key of 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)
| option | value |
| --- | --- |
| type | 'hsbhex' |
| key | DPS key of the value |
| components | Comma separated list of HSB components that should be included in this topic |
Using these value types you can define templates for a wide range of devices. Additional types and options are likely to be included in future versions of tuya-mqtt.

113
docs/TOPICS.md
View File

@@ -1,113 +0,0 @@
# 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
| option | value |
| --- | --- |
| type | 'bool' |
| key | DPS key for the value |
### Integer values
| option | value |
| --- | --- |
| 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
| option | value |
| --- | --- |
| 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
| option | value |
| --- | --- |
| type | 'string' |
| key | DPS key for the value |
### Tuya HSB values (newer style Tuya, 12 character color value)
| option | 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)
| option | 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.
### DPS JSON topic
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
```
### DPS key topics
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.