Matter Bridge

Certain smart devices run over the underlying protocols that are not supported by Matter. TuyaOS provides the capability to convert these devices to Matter things data models and make them interoperable with Matter devices.

Data structure

Initialization callback

Register callback functions during initialization.

typedef struct {
    BRIDGE_MATTER_OTA_FILE_CALLBACK_FN ota_file_notify_cb;/**< The callback to invoke when the gateway finishes downloading the OTA file. */
    OTA_PROCESS_NOTIFY_CALLBACK_FN ota_process_notify_cb;/**< The callback for the notification of the gateway OTA progress. */
    COMMISSION_STATUS_NOTIFY_CALLBACK_FN commissioning_status_cb;/**< The notification of the commissioning result. */
    MATTER_MANUFACTOR_DATA_QUERY_CB get_manufactory_data_cb;/**< The callback to invoke when the production test data is obtained. */
    MATTER_TO_PROTO_RECEIVE_CALLBACK_FN matter_data_private_process_cb;/**< If the Zigbee capability package fails to parse the downstream Matter data, the raw Matter data is returned to be parsed by yourself. */
    DEVELOPER_PRIVATE_ZIGBEE_HANDLER_S* zigbee_private_handler;/**< The callback to invoke when the upstream data from the sub-device fails to be parsed and is returned to you. */
    DEVELOPER_PRIVATE_BLE_HANDLER_S* ble_private_handler;/**< The callback to invoke when the upstream data from the sub-device fails to be parsed and is returned to you. */
    DEVELOPER_PRIVATE_WIFI_HANDLER_S* wifi_private_handler;/**< The callback to invoke when the upstream data from the sub-device fails to be parsed and is returned to you. */
}DEVELOPER_CALLBACKS_S;

Environment information

Complete the environment information during initialization.

typedef struct {
    CHAR_T ota_storage_name[128];   /**< The full path of the OTA file. */
}DEVELOPER_INFO_S;

Types of integrated device capabilities

typedef enum {
    BRIDGE_NO_USE = 0, /**< Tuya's capability packages are unused. */
    BRIDGE_ZIGBEE = 1, /**< Tuya's Zigbee capability package is used. */
    BRIDGE_BLE     = 2, /**< Tuya's Bluetooth capability package is used. */
    BRIDGE_WIFI    = 4, /**< Tuya's Wi-Fi capability package is used. */
}SolutionCapabilityType_e;

Structure of Matter packet

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 Matter packet elements
*/
typedef struct __TYPE_VAL_LIST{
    uint8_t Id;//Matter TLV tag
    ELEMENT_TYPE_S type;
    void* parameter;
    struct __TYPE_VAL_LIST* next;
}TYPE_VAL_LIST_S;

/**
 * @brief Action of things data 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 commandId takes effect, the payload type is TYPE_VAL_LIST_S.
}SOLUTION_ACTION_S;
/**
 * @brief Matter packet structure
 */
typedef struct {
    CHAR_T eui64_str[17];
    SOLUTION_MSG_TYPE_S messageType;
    uint8_t actionCount;
    SOLUTION_ACTION_S *action;
}SOLUTION_MATTER_MSG_S;

Structure of Matter device meta properties

/**
 * @brief Things data model and properties
 */
typedef struct {
    CHAR_T eui64_str[17];
    SOLUTION_PROTO_TYPE_E proto;
    UCHAR_T ep_cnt;
    SOLUTION_MATTER_EP_S* eps;
    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;

API description

Implement Matter bridge capability

Call the following functions to enable the Matter bridge capability:

• tuya_matter_svc_init: initializes the environment information and callback functions required by the SDK.

• tuya_matter_svc_start: starts the Matter bridge capability module.

  /**
      * @brief: Initialize Matter service.
      *
      * @param[in] cfgl: cfg service configuration.
      * @param[in] capability: Enable the capability module of the device to be bridged.
      * @param[in] info: the configurations provided by you.
      * @param[in] callbacks: the required callback functions.
      * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
      */
  OPERATE_RET tuya_matter_svc_init(ty_cJSON *cfg, SolutionCapabilityType_e capability, IN DEVELOPER_INFO_S *info, IN DEVELOPER_CALLBACKS_S *callbacks);
  
  /**
      * @brief: Start Matter service.
      *
      * @param[in] cfg: the service environment configurations.
      * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
      */
  OPERATE_RET tuya_matter_svc_start(ty_cJSON *cfg);
  

Send notification of new device joining network

Invoke the callback when the device capability package enables a new device to join the network.

/**
 * @brief This API is used to notify bridge module that device information when new device joins.
 *        successfully
 *
 * @param[in] protoCallback The callback to invoke for processing when downstream data for a newly joined device is received.
 * @param[in] devInfo The things data model and properties of the newly joined device. The data is used to create a digital twin 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);

Delete data from Matter bridge module

Call this function to delete device data from the Matter bridge module when the device is removed.

/**
 * @brief Notify the bridge module of the removed device.
 *
 * @param[in] devid The device ID.
 *
 * @return void
 */
void matter_bridge_api_shadow_delete_device(const char* devid);

Send notification of offline device

Call this function when the device capability package detects a device goes offline.

/**
 * @brief Notify the bridge module of the online or offline state of the device.
 *
 * @param[in] dev_id The callback to invoke for processing when downstream data for a newly joined device is received.
 * @param[in] online_stat The things data model and properties of the newly joined device. The data is used to create a digital twin in Matter.
 *
 * @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);

Report device packets

Call this function when the device capability package receives packets reported by a device.

/**
 * @brief Notify the bridge module of the packets reported by the device.
 *
 * @param[in] msg The packets 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);

Example

static OPERATE_RET __zigbee_data_process_callback(IN TuYaApsFrame* frame){
    OPERATE_RET oprt_ret = OPRT_OK;
    (void)frame;
    PR_DEBUG("tuya capability can not process ,so developer must call matter_bridge_api_message_up_report after process by self");
    //matter_bridge_api_message_up_report
    return oprt_ret;
}

static OPERATE_RET __matter_data_process_callback(IN SOLUTION_MATTER_MSG_S*msg){
    OPERATE_RET oprt_ret = OPRT_OK;
    (void)msg;
    PR_DEBUG("tuya capability can not process ,so developer must process by self");
    return oprt_ret;
}

OPERATE_RET user_svc_init(VOID *cb){
    DEVELOPER_INFO_S info = {0};
    strcpy(&info.ota_storage_name, "/tmp/ota.bin");

    DEVELOPER_PRIVATE_ZIGBEE_HANDLER_S zigbee = {
        .zigbee_data_process_callback = __zigbee_data_process_callback,
    };
    DEVELOPER_CALLBACKS_S callbacks = {
        .ota_file_notify_cb = NULL,
        .ota_process_notify_cb = NULL,
        .commissioning_status_cb = NULL,
        .zigbee_private_handler = &zigbee,
        .matter_data_private_process_cb = __matter_data_process_callback,
        .get_manufactory_data_cb = user_prod_test_matter_get,
    };
    // Configure the environment and callbacks required by the SDK.
    tuya_matter_svc_init(NULL,BRIDGE_ZIGBEE, &info, &callbacks);
    // Start the SDK.
    tuya_matter_svc_start(NULL);
    return OPRT_OK;
}