Integration by Sub-Device Config Files

Integration by sub-device configuration files simplifies the process of connecting a large scale of sub-devices to gateways. This feature is used with Tuya’s proprietary DP Engine.

Background

An IoT gateway, acting as an intermediary between the devices and the cloud, can translate between different communication protocols. It can enable interconnection between devices over the internet or the LAN. For example, Zigbee or Thread devices in the perception layer need a gateway to communicate with the internet.

However, the configuration of IoT gateways for data exchange between an IoT device and the cloud varies based on the type and model of the IoT device. This requires you to develop a protocol conversion program to translate protocols between the IoT devices and the cloud. You also need to update the IoT gateway over time to bring support for a specific type of IoT end device.

Integration by sub-device configuration files is designed to simplify extending the gateway’s compatibility.

Features

What is DP Engine

Tuya’s proprietary data point (DP) Engine is a tool designed for IoT gateways or controllers. DP Engine can translate the data format of the DP defined by the Tuya IoT Development Platform into that of another IoT protocol.

DP Engine consists of the conversion engine implemented in code and the configuration file in JSON.

DP Engine features

• Parse configuration files

  Gateways that support integration by sub-device configuration files come with the conversion engine. After connecting to a sub-device, the gateway downloads and loads the JSON configuration file into memory.

• Match conversion rules

  Match the data to be converted with the corresponding data in the target protocol according to the conversion rules. Tuya divides the IoT protocol data structure into two parts: header and payload. The conversion rules include:

  • LAN protocol header
  • Cloud protocol header
  • Payload conversion functions

  In upstream communication, the LAN protocol is translated into the cloud protocol. Match the header in the upstream data with the LAN protocol header, and further get the corresponding cloud protocol header. Describe the process of protocol conversion using the Zigbee protocol as an example.

  • The epID, clusterID, and subID in the Zigbee Cluster Library (ZCL) header constitute the matching key value in the format endpointId_clusterId_subId that is called zclKey by Tuya.

  • The gateway composes a zclKey with the received ZCL data and matches it with the zclKey in the nodes in the configuration file. If the match is successful, the matched node will be used for data conversion.

    For example, when the brightness changes, the light reports 1_8_0, which means endpointId = 1, clusterId = 8, and subId = 0. The engine matches the zclKey 1_8_0 with the zclKey in the nodes in the configuration file and then identifies that the header of the corresponding DP data is 3.

  In downstream communication, the cloud protocol is translated into the LAN protocol. Match the header in the downstream data with the cloud protocol header, and further get the corresponding LAN protocol header. Describe the process of protocol conversion using the Zigbee protocol as an example.

  • In the conversion from DP data into ZCL data, dpID is used as the matching key value, which is called dpKey by Tuya.

  • The gateway matches the dpKey of the received DP data with the dpKey in the nodes in the configuration file. If the match is successful, the matched node will be used for data conversion.

    For example, the cloud sends DP data {"3":1000} to the device for the adjustment of light brightness. The engine matches the dpKey of 3 with the dpKey in the nodes in the configuration file and then identifies that the header of the corresponding ZCL data is 1_8_1.

• Convert payload values

  After matching conversion rules, the relationship between the two protocols has been identified by header. In some cases, further value conversion is required.

  For example, the brightness range of the ZCL payload is 0 to 255 while that of the DP payload is 0 to 1,000. After matching the conversion rules, the engine performs a precision conversion by finding the matched node and using its conversion function.

• Update files

  The gateway checks for and downloads the latest sub-device configuration file upon restart or every 12 hours. After you update the sub-device configuration file, you can manually restart the gateway or wait 12 hours to ensure the gateway uses the latest file.

Configuration files

For more information, see Format of Sub-Device Configuration Files.

Zigbee configuration file

For more information, see Zigbee Sub-Device Configuration File.

Matter configuration file

For more information, see Matter Sub-Device Configuration File.

Development guide

Initialization

To enable integration by sub-device configuration files, call the following APIs for initialization.

/**
* @brief    start DP engine.
*
* @param[in] cfg service configuration.
*                 {
*                     "storage_path": "./trans_file",            // DP trans file storage path
*                     "file_max_count": 100,                     // max DP trans file count
*                     "pidTable_max_count": 100,                 // max pid_table element count
*                     "enable_zigbee_trans": 1,                  // 0 or 1 If the value is 0, it is disabled
*                     "enable_matter_trans": 1,                  //If the value is 1, it is enabled
*                 }
*
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*/
 OPERATE_RET dp_engine_init_inf(ty_cJSON *cfg);

Parameter

Example

#include "dp_engine_inf.h"

int main(int argc, char **argv)
{
    // ...
    ty_cJSON *eng_cfg = ty_cJSON_CreateObject();
    if (zb_cfg == NULL) {
        return OPRT_CJSON_GET_ERR;
    }
    ty_cJSON_AddStringToObject(eng_cfg, "storage_path", "./trans_files");
    ty_cJSON_AddNumberToObject(eng_cfg, "file_max_count", 100);
    ty_cJSON_AddNumberToObject(eng_cfg, "pidTable_max_count", 100);
    ty_cJSON_AddNumberToObject(eng_cfg, "enable_zigbee_trans", 1);
    ty_cJSON_AddNumberToObject(eng_cfg, "enable_matter_trans", 0);

    // Initialize the service of integration by sub-device configuration files.
    TUYA_CALL_ERR_RETURN(dp_engine_init_inf(eng_cfg));

    // ...

    return 0;
}