Integration by Sub-Device Config Files

Last Updated on : 2023-09-06 07:37:52

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

Feature Before integration
by sub-device
configuration files
After integration
by sub-device
configuration files
Note
Easy integration with third-party devices To connect your proprietary sub-devices to the Tuya ecosystem, you need to develop a gateway. To connect your proprietary sub-devices to the Tuya ecosystem, create a custom solution for the target sub-device, generate the respective configuration file, and use a gateway that supports integration by sub-device configuration files. The sub-device configuration files only provide basic protocol conversion, so custom gateway firmware must be built to implement custom features.
Comprehensive support for device ecosystems A lack of consistency between the products. For instance, Gateway A now supports a particular sub-device, but Gateway B does not yet support it. The differences in iteration cycles among multiple gateway products cause this inconsistency. When you publish the configuration file for a new sub-device, a gateway that supports integration by sub-device configuration files and the respective sub-device configuration file can manage that sub-device. Sub-device configuration files support version control and backward compatibility, with less frequent iteration.
Fast iteration To update the sub-device’s firmware, you must first update the gateway program and then deploy an OTA update to the sub-device. Update the configuration file in the cloud and then deploy an OTA update to the sub-device. A gateway program update is required only in certain special conditions.

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.

Integration by Sub-Device Config Files

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

Field Description
storage_path The directory of the configuration file, which should be readable.
file_max_count The maximum number of configuration files. 100 is recommended.
pidTable_max_count The maximum number of PID mapping tables. 100 is recommended.
enable_zigbee_trans Specify whether to enable Zigbee sub-device configuration file. 1: Enable. 0: Disable.
enable_matter_trans Specify whether to enable Matter sub-device configuration file. 1: Enable. 0: Disable.

With integration by sub-device configuration files enabled, a gateway can connect to a paired sub-device that has a configuration file set.

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;
}