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 updates

Browse Source
This commit is contained in:
tsightler
2020-10-17 14:13:35 -04:00
parent 535b6edecf
commit 66541558dd
2 changed files with 28 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@@ -3,11 +3,9 @@ This project provides an MQTT gateway for locally controlling IOT devices manufa
Using this script requires obtaining 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).
Acquiring device keys is outside the scope of this project. Please see the instructions at the TuyAPI project (on which this script is based) available at the TuyAPI project site:
To acquire keys for your device please see the instructions at the TuyAPI project (on which this script is based) available at the [TuyAPI GitHub site](https://github.com/codetheweb/tuyapi/blob/master/docs/SETUP.md).
https://github.com/codetheweb/tuyapi/blob/master/docs/SETUP.md.
Issues opened regarding acquiring keys will likely be closed without comment. Please verify that your device can be queried and controlled via tuya-cli before opening an issue. If your device can't be controlled by tuya-cli then it cannot be used with this project.
**Acquiring device keys is outside the scope of this project!** Issues opened regarding acquiring keys will likely be closed without comment. Please verify that your device can be queried and controlled via tuya-cli before opening any issue. If your device can't be controlled by tuya-cli then it cannot be used with this project.
**!!!!!!!!!! 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 for all users of previous versions. Almost everything about the project is different, including configuration method, topic names, etc. Upgrading users should carefully read the instructions below and assume they are starting over from scratch.
@@ -34,8 +32,9 @@ Tuya-mqtt has two different configuration files. The first is config.json, a si
### Seting up config.json:
```
cp config.json.sample config.json
// Edit config.json with your MQTT broker settings and save
```
**Edit config.json with your MQTT broker settings and save**
```
nano config.json
```
@@ -62,8 +61,9 @@ While the above syntax is enough to create a working tuya-mqtt install with gene
### Starting tuya-mqtt
```
node tuya-mqtt.js
// To enable debugging output (required when opening an issue)
```
**Enable debugging output (required when opening an issue)**
```
DEBUG=tuya-mqtt:* tuya-mqtt.js
```
@@ -83,7 +83,7 @@ tuya/86435357d8b123456789/
```
All additional state/command topics are then built below this level. You can view the status of the device using the status topic, which reports "online" or "offline" based on whether tuya-mqtt currently has an active connection to the device or not.
```
tuya/kitche_table/state <-- oneline/offline
tuya/kitche_table/state --> online/offline
```
You can also trigger the device to send an immediate update of all known device DPS topics by sending the message "get-states" to the command topic (this topic exist even if there is no correspoinding state topic):
```
@@ -114,9 +114,9 @@ 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/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/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 !!!**\

32
docs/DEVICES.md
View File

@@ -33,9 +33,9 @@ Simple devices that support only on/off.
| state | Power state | on/off |
| command | Set power state | on/off, 0/1, true/false |
Configuration override options:
Manual configuration options:
| Option | Description | Default |
| --- | --- | |
| --- | --- | --- |
| dpsPower | DPS key for power state | 1 |
### SimpleDimmer
@@ -47,29 +47,31 @@ Simple device with on/off and brightness functions (dimmer switches or lights)
| brightness_state | Brightness in % | 1-100 |
| brightness_command | set brightness in % | 1-100 |
Configuration override options:
Manual configuration 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 |
| Condition | Mode |
| --- | --- |
| 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 |
| Changes white brightness | white |
| Changes to color temperature (for device with color temp support) | white |
| Saturation < 10 % | white |
| Saturation >= 10 % | color |
| All other changes | 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.
This means changing the hue of the light will only switch to color mode if saturation is also >= 10%. Some lights automatically attempt to switch to color mode when any HSB value is updated however, if the saturation setting remains < 10%, tuya-mqtt will force the light back to white mode in this case. This can cause a very quick flicker when chaning hue or color brightness while the saturation remains below the 10% threshold. I expect this not to be a common issue and implemented this in an attempt to make all tuya lights behave in a consistent way.
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.
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 topic 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 may still be represented with a color icon in the platforms 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.
Tuya bulbs store their HSB color value in a single DPS key using a custom format. Some bulbs use a 14 character format, referred to as HSBHEX, which represents the saturation and brightness values from 0-255 as 2 character hex, while the others use a 12 character format, referred to as HSB, which still uses hex values, but stores saturation and brightness values from 0-1000 as 4 character hex. The code attempts to autodetect the format used by the bulb and perform the proper conversion in all cases, but this can be overridden for cases where the dection method fails.
| Topic | Description | Values |
| --- | --- | --- |
| state | Power state | on/off |
@@ -87,9 +89,9 @@ Not all devices support color temperature and the script attempts to detect this
| 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:
Manual configuration options:
| 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) |
@@ -101,7 +103,7 @@ The RGBTWLight function attempts to detect all required options automatically, t
| 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:
To use the manual configuration options simply add them to device.conf file after defining the device type like the following example:
```
[
{