API Description

This topic excerpts the essential APIs, data types, and macros included in the Tuya Bridge SDK. For more information, see doc in the SDK directory.

#define MATTER_MANU_NAME_MAX_LEN      32
#define MATTER_MODEL_ID_MAX_LEN       32
#define MATTER_MAX_ENDPOINT_NUM       20
#define MATTER_ZIGBEE_EUI_STR_LEN     16
#define MATTER_MAX_CLUSTER_ID_NUM     10
#define MATTER_MAX_ATTRIBUTE_ID_NUM   10
/**@brief
 * Protocol types of device capability packages.
 */
typedef enum {
    BRIDGE_NO_USE  = 0, /**< no use tuya's device link capability */
    BRIDGE_ZIGBEE  = 1, /**< use tuya's Zigbee device link capability */
    BRIDGE_BLE     = 2, /**< use tuya's device link capability */
    BRIDGE_WIFI    = 4, /**< use tuya's device link capability */
}SolutionCapabilityType_e;
typedef SolutionCapabilityType_e SOLUTION_PROTO_TYPE_E;
/**
 * @brief Message Types
 */
typedef enum
{
    StatusResponse        = 0x01,
    ReadRequest           = 0x02,
    SubscribeRequest      = 0x03,
    SubscribeResponse     = 0x04,
    ReportData            = 0x05,
    WriteRequest          = 0x06,
    WriteResponse         = 0x07,
    InvokeCommandRequest  = 0x08,
    InvokeCommandResponse = 0x09,
    TimedRequest          = 0x0a,
}SOLUTION_MSG_TYPE_S;
/**
 * @brief general data structure for matter tlv package element
 */
typedef struct __TYPE_VAL_LIST{
    SLIST_HEAD node;
    uint8_t index;//matter TLV tag
    uint64_t len;
    uint8_t data[0];
}TYPE_LENGTH_VAL_S;
typedef struct {
    SLIST_HEAD list;
    uint8_t count;
}TYPE_LENGTH_VAL_MGR_S;
/**
 * @brief Action of device thing model.
 */
typedef struct {
    uint16_t endpoint;
    uint32_t clusterId;
    union{
        uint32_t attributeId;
        uint32_t eventId;
        uint32_t commandId;
    }actionId;
    uint8_t attrType;
    uint16_t attrLen;
    void* payload;//When the commandId takes effect, the payload type is TYPE_LENGTH_VAL_MGR_S.
}SOLUTION_ACTION_S;
/**
 * @brief Matter package's struct
 */
typedef struct {
    CHAR_T eui64_str[17];
    SOLUTION_MSG_TYPE_S messageType;
    uint8_t actionCount;
    SOLUTION_ACTION_S *action;
}SOLUTION_MATTER_MSG_S;
union DefaultAttributeValue
{
    const uint8_t * ptrToDefaultValue;
    uint16_t defaultValue;
};
typedef struct
{
    union DefaultAttributeValue defaultValue;
    union DefaultAttributeValue minValue;
    union DefaultAttributeValue maxValue;
} AttributeMinMaxValue;
typedef struct _attributeMetaElement {
    uint32_t id;
    uint8_t defalutValueLength;
    char* defalutValueJsonString;
}SOLUTION_MATTER_ATTRIBUTE_ELEMENT_S;
typedef struct _ParamsElement {
    uint8_t tag;
    uint8_t length;
}ParamsFormat_t;
typedef struct _clusterCommand {
    uint16_t commandId;
    uint8_t paramsCnt;
    ParamsFormat_t *params;
}SOLUTION_MATTER_CLUSTER_COMMAND_S;
typedef SOLUTION_MATTER_CLUSTER_COMMAND_S ClusterCommand_t;
/**
 * @brief Device data reception processing callback function.
 */
typedef OPERATE_RET (*MATTER_TO_PROTO_RECEIVE_CALLBACK_FN)(IN SOLUTION_MATTER_MSG_S*msg);
typedef struct {
    USHORT_T cluster_id;
    UCHAR_T attribute_cnt;
    uint32_t feature_map;
    uint8_t mask;//CLUSTER_MASK_CLIENT|CLUSTER_MASK_SERVER;
    uint8_t numAcceptedCommand;
    uint8_t numGeneratedCommand;
    SOLUTION_MATTER_CLUSTER_COMMAND_S* pAcceptedCommandList;//end of chip::kInvalidCommandId
    SOLUTION_MATTER_CLUSTER_COMMAND_S* pGeneratedCommandList;
    SOLUTION_MATTER_ATTRIBUTE_ELEMENT_S* attributes;//end of chip::InvalidAttributeId
} SOLUTION_MATTER_CLUSTER_S;
/**
 * @brief Endpoint of device thing model.
 */
 typedef struct {
    UCHAR_T ep_id;
    USHORT_T mtrEp;
    USHORT_T mtrDevtype;
    UCHAR_T cluster_cnt;
    SOLUTION_MATTER_CLUSTER_S *clusters;
}SOLUTION_MATTER_EP_S;
/**
 * @brief device thing model.
 */
typedef struct {
    CHAR_T eui64_str[17];
    SOLUTION_PROTO_TYPE_E proto;
    UCHAR_T ep_cnt;
    SOLUTION_MATTER_EP_S* eps;
    uint16_t composedEndpoint;
    const char* basic_str;
    const char* softwareVersion;
    const char* hardwareVersion;
    const char* vendorName;
    const uint32_t vendorId;
    const char* productName;
    const uint32_t productId;
}SOLUTION_BRIDGE_DEVICE_S;
typedef struct _DEV_Z3_MATTER_DESC_IF{
    CHAR_T eui64_str[MATTER_ZIGBEE_EUI_STR_LEN+1];
    UCHAR_T ep_cnt;
    SOLUTION_PROTO_TYPE_E proto;
    SOLUTION_MATTER_EP_S eps[MATTER_MAX_ENDPOINT_NUM];
    CHAR_T *basic_str;
    uint16_t composedEndpoint;
    MATTER_TO_PROTO_RECEIVE_CALLBACK_FN protoRecvCallback;
}SOLUTION_MATTER_DESC_S;
typedef SOLUTION_MATTER_DESC_S SOLUTION_BRIDGE_INFO_S;
typedef OPERATE_RET (*TRIGGER_SOLUTION_DESC_CALLBACK_FN)(IN CONST SOLUTION_BRIDGE_INFO_S*info);
typedef OPERATE_RET (*DP_ENGINE_STATUS_CALLBACK_FN)(void);
/**
 * @brief Function prototype of the downlink data interface of the device.
 */
typedef struct {
    SOLUTION_PROTO_TYPE_E proto_type;                       /**< Protocol type of registered device. */
    MATTER_TO_PROTO_RECEIVE_CALLBACK_FN proto_recv_callback;/**< Corresponding data reception processing callback function. */
    TRIGGER_SOLUTION_DESC_CALLBACK_FN get_desc_callback;
    DP_ENGINE_STATUS_CALLBACK_FN dp_engine_is_ok;
}SOLUTION_BRIDGE_PROTO_HANDLER_S;


/**@brief
* Notify you after the successful download of the gateway OTA file.
*/
typedef OPERATE_RET (*BRIDGE_MATTER_OTA_FILE_CALLBACK_FN)(IN const char*filePath);
/**@brief
* Gateway OTA progress notification.
*/
typedef void (*OTA_PROCESS_NOTIFY_CALLBACK_FN)(IN CONST CHAR_T* devid, IN CONST UINT_T percent, IN CONST CHAR_T newVersionString[]);
/**@brief matter commissioning state*/
typedef enum {
    MATTER_COMMISSION_OK = 0,                   /**< commissioning ok */
    MATTER_COMMISSION_FAIL_MEMORY,              /**< commissioning 1 */
    MATTER_COMMISSION_FAIL_PASE_AUTH,           /**< commissioning 2 */
    MATTER_COMMISSION_FAIL_BLE_SCAN,            /**< commissioning 3 */
    MATTER_COMMISSION_FAIL_CASE_TIMEOUT,        /**< commissioning 4 */
    MATTER_COMMISSION_FAIL_BLE_UNCONNECTED,     /**< commissioning 5 */
    MATTER_COMMISSION_FAIL_MULTI_FABRIC,        /**< commissioning 6 */
    MATTER_COMMISSION_FAIL_OTHERS = 1000,       /**< commissioning 1000 */
}COMMISSIONING_STA_E;
/**@brief OTA progress report.*/
typedef void (*COMMISSION_STATUS_NOTIFY_CALLBACK_FN)(COMMISSIONING_STA_E eStatus);


/**@brief ble_data_process_callback. */
typedef struct {
    void* ble_data_process_callback;/**< The callback to you when the BLE sub-device's uplink data cannot be parsed. */
}DEVELOPER_PRIVATE_BLE_HANDLER_S;
/**@brief wifi_data_process_callback. */
typedef struct {
    void* wifi_data_process_callback;/**< Callback to you when the upstream data from the WiFi sub-device cannot be parsed. */
}DEVELOPER_PRIVATE_WIFI_HANDLER_S;
/**@brief developer callback that SDK needs. */
typedef struct {
    BRIDGE_MATTER_OTA_FILE_CALLBACK_FN  ota_file_notify_cb;/**< Notification callback for successful download of OTA file by gateway. */
    OTA_PROCESS_NOTIFY_CALLBACK_FN ota_process_notify_cb;/**< Gateway OTA progress notification callback. */
    COMMISSION_STATUS_NOTIFY_CALLBACK_FN commissioning_status_cb;/**< Commissioning result notification */
    //SOLUTION_MATTER_MSG_S
    MATTER_TO_PROTO_RECEIVE_CALLBACK_FN matter_data_private_process_cb;/**< When the downlink Matter data Zigbee capability package cannot be parsed, the original Matter data is output to the developer for self-parsing. */
    //DEVELOPER_PRIVATE_ZIGBEE_HANDLER_S*zigbee_private_handler;/**< Callback to you when the upstream data from the sub-device cannot be parsed. */
    DEVELOPER_PRIVATE_BLE_HANDLER_S *ble_private_handler;/**< Callback to you when the upstream data from the sub-device cannot be parsed. */
    DEVELOPER_PRIVATE_WIFI_HANDLER_S *wifi_private_handler;/**< Callback to you when the upstream data from the sub-device cannot be parsed. */
}DEVELOPER_CALLBACKS_S;
/**@brief developer config information. */
typedef struct {
    CHAR_T ota_storage_name[128];   /**< ota file full path. */
}DEVELOPER_INFO_S;



/**
 * @brief This API is used to notify the bridge module of device information when a new device joins
 *        successfully
 *
 * @param[in] protoCallback The processing function for the downstream data of a newly added device,
 *                          which will be called when there is data about this device coming down from Matter
 * @param[in] devInfo The thing model and attribute information of newly added network devices are used to create a virtual twin device in Matter.
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET matter_bridge_api_shadow_annouce_new_device(IN MATTER_TO_PROTO_RECEIVE_CALLBACK_FN protoCallback, IN SOLUTION_BRIDGE_DEVICE_S *devInfo);
OPERATE_RET matter_bridge_api_shadow_recover_device(IN MATTER_TO_PROTO_RECEIVE_CALLBACK_FN protoCallback, IN SOLUTION_BRIDGE_DEVICE_S *devInfo);
/**
 * @brief Notify the Bridge module that the device has been deleted.
 *
 * @param[in] devid The unique identifier of the deleted device.
 *
 * @return void
 */
void matter_bridge_api_shadow_delete_device(const char* devid);
/**
 * @brief Notify the online/offline status of the Bridge module device.
 *
 * @param[in] dev_id The unique identifier of the device.
 * @param[in] online_stat the online/offline status of the device.
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
void matter_bridge_api_shadow_onoffline_notify(IN CONST CHAR_T *dev_id, IN CONST BOOL_T online_stat);
/**
 * @brief The message data reported by the device to the Bridge module.
 *
 * @param[in] msg The message data reported by the device.
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET matter_bridge_api_message_up_report(IN SOLUTION_MATTER_MSG_S*msg);
/**
 * @brief Register the downstream data reception processing function for a certain type of protocol device to the Bridge module.
 *        Not recommended for use, it is recommended to use matter_bridge_api_shadow_annouce_new_device for new device register
 *
 * @param[in] protocol_type
 *                          
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET matter_bridge_api_register_protocol_mgr_callback(IN SOLUTION_BRIDGE_PROTO_HANDLER_S *protocol_type);
/**
 * @brief Clear all device shadows, calling this function requires restarting the program.
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET matter_bridge_api_shadow_clear_all(void);
int GetZigbeeCommandPayloadTagLength(uint32_t clusterId,uint16_t commandId,uint8_t tag);




/**
  * @brief: specify the developer info and register the developer handler callback for Matter bridge
  *
  * @param[in] capability: Enable the ability module for devices that want to bridge.
  * @param[in] info: Developer's configuration parameters.
  * @param[in] callbacks: Required callback function
  * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
  */
OPERATE_RET tuya_matter_bridge_correlation_register(SolutionCapabilityType_e capability, IN DEVELOPER_INFO_S *info, IN DEVELOPER_CALLBACKS_S *callbacks);