Hello fellow developers and contributors,
Iâm excited to announce that a new test version of the Tuya Zigbee app has been published on the Homey App Store. This update focuses primarily on refactoring the codebase to make the app more maintainable and scalable, especially when it comes to handling Tuya-specific Zigbee devices.
In this post, Iâll explain the recent changes, how they streamline development, and how you can leverage these updates to improve or contribute to the app. While this release doesnât promise huge improvements for end users immediately, itâs laying the foundation for better stability, faster integration of new devices, and a more efficient development process.
Overview of Changes
- Helper Files: Introduced
TuyaHelpers.js
and TuyaDataPoints.js
to centralize utility functions and datapoint (DP) definitions, making it easier to manage device interactions and add new devices.
- Tuya-Specific Clusters and Devices: Detailed the usage of
TuyaSpecificCluster.js
and TuyaSpecificClusterDevice.js
, which simplify the integration and communication with Tuya Zigbee devices.
New Helper Files
TuyaHelpers.js
:
- A set of utility functions like
getDataValue
, marshalSchedule
, and parseSchedule
, designed to simplify working with Tuya Datapoints (DPs).
- Example: To handle a DP value, instead of manually parsing its structure, you can simply call
getDataValue(dpValue)
. This streamlines how we interpret DPs in different devices.
TuyaDataPoints.js
:
- Centralizes all the known datapoints for Tuya devices (e.g., thermostats, lights, switches), making it easier to add new devices or modify existing ones without duplicating code.
- This allows for a more consistent and scalable approach to DP management.
Tuya-Specific Cluster and Device Classes
In addition to these helper files, the Tuya-specific Zigbee protocol requires some specialized handling. To that end, the app uses custom clusters and device classes.
- TuyaSpecificCluster.js
- This defines the Tuya-specific Zigbee cluster (ID: 61184), which handles commands like
datapoint
, reporting
, and response
for Tuya devices. These commands facilitate communication between Zigbee devices using the Tuya protocol.
- Usage: In your device drivers, you register this cluster by adding
Cluster.addCluster(TuyaSpecificCluster)
. Once registered, it listens for events like reporting
, response
, or datapoint
changes and triggers the appropriate actions.
- Example: If you need to handle a device reporting a change in one of its datapoints, you can listen to the
reporting
event and update the deviceâs state in Homey accordingly.
- TuyaSpecificClusterDevice.js
- This extends the Homey
ZigBeeDevice
class to add methods for writing data to Tuya datapoints. It abstracts writing booleans, integers, strings, enums, and raw data to the device.
- Key functions include:
writeBool(dp, value)
: Sends a boolean value to a specific datapoint.
writeData32(dp, value)
: Sends a 32-bit integer to a datapoint.
writeString(dp, value)
: Sends a string to a datapoint.
writeEnum(dp, value)
: Sends an enum value to a datapoint.
writeRaw(dp, data)
: Sends raw data to a datapoint.
- This class manages the transaction IDs required by Tuyaâs protocol, automatically incrementing with each new command, so you donât need to worry about manually managing transaction states.
- TuyaZigBeeLightDevice.js
- This is a base class for handling Tuya Zigbee light devices with capabilities like
onoff
, dim
, light_hue
, light_saturation
, light_temperature
, and light_mode
.
- It handles different lighting modes (e.g., color, temperature) and includes methods to manage dimming, changing colors, or adjusting color temperature.
- The class utilizes a debounced approach to handle multiple capability changes at once (e.g., changing brightness and color simultaneously).
- A noteworthy feature is its ability to fall back to default values when specific attributes like
hue
or saturation
arenât provided, ensuring the device always operates smoothly even if some settings are missing.
Usage for Developers
If youâre contributing to this project or adding new devices to your own forks, hereâs how you can use these files:
- Adding Support for New Devices:
- When adding a new device that follows the Tuya protocol, instead of writing all the DP parsing logic yourself, you can simply extend the
TuyaSpecificClusterDevice
class and utilize methods like writeBool()
or writeData32()
to communicate with the device.
- For lights, extend
TuyaZigBeeLightDevice
to inherit all the base functionality and then register any additional capabilities specific to your device.
- Using
TuyaSpecificCluster
in Your Driver:
- In your driver file, you can easily register the Tuya-specific cluster by adding the following lines:
const TuyaSpecificCluster = require('../../lib/TuyaSpecificCluster');
Cluster.addCluster(TuyaSpecificCluster);
- This allows your driver to receive and handle Tuya-specific commands, such as datapoint reporting.
- Centralized DP Management:
- Rather than hardcoding each DP value across multiple files, you can import the
TuyaDataPoints.js
file to access standardized datapoints for various devices, ensuring your code remains clean and DRY (Donât Repeat Yourself).
Whatâs Next:
The introduction of these changes is primarily aimed at developers and those contributing to the Tuya Zigbee app. While users may notice small improvements in certain areas, the bigger impact will come as more devices are integrated and the codebase becomes easier to maintain and extend.
Iâm also planning to refactor more drivers to make use of this centralized logic, and if youâre working on new device integrations, feel free to join in, use the helper files, and share your feedback. This is a collaborative effort, and any improvements you make to the helper files or clusters will benefit the entire Homey community.
Letâs continue making this app stronger and more scalable!
A big thank you to all the contributors so far. Your input has been invaluable, and I look forward to seeing more of your contributions and ideas!
// Johan