Matter 桥接

TuyaOS 支持将 Matter 协议不支持的底层协议类型的设备，转换虚拟成 Matter 协议的物模型与协议，进而使它们可以与 Matter 设备交互无缝交互的能力。

数据结构

初始化回调

开发者在初始化时，注册进来的回调函数。

typedef struct {
    BRIDGE_MATTER_OTA_FILE_CALLBACK_FN ota_file_notify_cb;/**< 网关下载 OTA 文件成功的通知回调 */
    OTA_PROCESS_NOTIFY_CALLBACK_FN ota_process_notify_cb;/**< 网关 OTA 进度通知回调 */
    COMMISSION_STATUS_NOTIFY_CALLBACK_FN commissioning_status_cb;/**< commissioning 结果通知 */
    MATTER_MANUFACTOR_DATA_QUERY_CB get_manufactory_data_cb;/**< 产测数据获取回调 */
    MATTER_TO_PROTO_RECEIVE_CALLBACK_FN matter_data_private_process_cb;/**< 下行 Matter 数据 Zigbee 能力包无法解析时吐出原始 Matter 数据给开发者吐 Matter 的数据给开发者自行解析 */
    DEVELOPER_PRIVATE_ZIGBEE_HANDLER_S*zigbee_private_handler;/**< 子设备上行数据无法解析时吐给开发者时的回调 */
    DEVELOPER_PRIVATE_BLE_HANDLER_S *ble_private_handler;/**< 子设备上行数据无法解析时吐给开发者时的回调 */
    DEVELOPER_PRIVATE_WIFI_HANDLER_S *wifi_private_handler;/**< 子设备上行数据无法解析时吐给开发者时的回调 */
}DEVELOPER_CALLBACKS_S;

环境信息

开发者在初始化时，需要完善环境信息。

typedef struct {
    CHAR_T ota_storage_name[128];   /**< ota file full path. */
}DEVELOPER_INFO_S;

设备能力接入类型

typedef enum {
    BRIDGE_NO_USE = 0, /**< 不使用涂鸦的能力包 */
    BRIDGE_ZIGBEE = 1, /**< 使用涂鸦的 Zigbee 能力包 */
    BRIDGE_BLE     = 2, /**< 使用涂鸦的蓝牙能力包 */
    BRIDGE_WIFI    = 4, /**< 使用涂鸦的 Wi-Fi 能力包 */
}SolutionCapabilityType_e;

Matter 报文结构体

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 报文元素
*/
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
*/
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;//当 commandId 生效时，payload 类型为 TYPE_VAL_LIST_S
}SOLUTION_ACTION_S;
/**
 * @brief Matter 报文结构体
 */
typedef struct {
    CHAR_T eui64_str[17];
    SOLUTION_MSG_TYPE_S messageType;
    uint8_t actionCount;
    SOLUTION_ACTION_S *action;
}SOLUTION_MATTER_MSG_S;

Matter 设备元属性结构体

/**
 * @brief 设备物模型和属性
 */
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;

接口描述

Matter 桥接能力

两个 Matter 桥接能力的接口的功能如下：

• tuya_matter_svc_init：负责初始化 SDK 依赖的环境信息和必要的回调函数。

• tuya_matter_svc_start：负责启动 Matter 桥接能力模组的启动。

  /**
      * @brief: initialize Matter service..
      *
      * @param[in] cfgl: cfg service configuration.
      * @param[in] capability: 使能想要 bridge 的设备能力模组
      * @param[in] info: 开发者的配置参数
      * @param[in] callbacks: 必要的回调函数
      * @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: 服务环境配置项.
      * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
      */
  OPERATE_RET tuya_matter_svc_start(ty_cJSON *cfg);
  

新设备入网通知

新设备入网通知接口，当设备能力包成功接入一个设备时调用。

/**
 * @brief This API is used to notify bridge modulue that device information when new device join
 *        successfully
 *
 * @param[in] protoCallback 新入网设备的下行数据的处理函数，当有从 Matter 下来的关于此设备的数据时会调用此回调函数
 * @param[in] devInfo 新入网设备的物模型和属性信息，用于在 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);

删除 Matter 桥接模组中的数据

设备删除时调用此接口会删除设备在 Matter 桥接模组中的数据。

/**
 * @brief 通知 Bridge 模组设备被删除
 *
 * @param[in] devid 被删除设备的唯一标识
 *
 * @return void
 */
void matter_bridge_api_shadow_delete_device(const char* devid);

设备离线判定

当设备能力包判定设备离线时调用此接口。

/**
 * @brief 通知 Bridge 模组设备的在离线状态
 *
 * @param[in] dev_id 新入网设备的下行数据的处理函数，当有从 Matter 下来的关于此设备的数据时会调用此回调函数
 * @param[in] online_stat 新入网设备的物模型和属性信息，用于在 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);

上报设备报文

当设备能力包收到设备上报时调用此接口。

/**
 * @brief 向 Bridge 模组上报设备报上来的报文数据
 *
 * @param[in] msg 设备报上来的报文数据
 *
 * @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);

使用示例

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,
    };
    //配置 SDK 需要的环境与回调接口
    tuya_matter_svc_init(NULL,BRIDGE_ZIGBEE, &info, &callbacks);
    //启动 SDK 运行
    tuya_matter_svc_start(NULL);
    return OPRT_OK;
}