[APP][Pro] Tuya Zigbee App

Apps
4887

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

  1. 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.
  2. 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

  1. 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.
  1. 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.

  1. 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.
  1. 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.
  1. 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:

  1. 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.
  1. 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.
  1. 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

15 Likes