涂鸦Zigbee SDK开发系列教程——6.SDK API函数接口介绍

Posted 2022-12-04 三明治开发社区

本章节主要介绍 TuyaOS SDK API 相关的函数接口，内容如下：

zigbee 网络相关函数

Endpoint 注册函数：

OPERATE_RET tal_zg_endpoint_register(TAL_ENDPOINT_T *ep_desc, UINT8_T sums);

此函数是 ZigBee Endpoint 注册函数，用户把需要的 Endpoint、Cluster、Attribute 通过此函数注册到协议栈内部。TuyaOS ZigBee 开发框架为了开发者更好地专注业务开发，屏蔽了用户无需关心的 Cluster，例如 server端 Basic cluster、client 端 OTA cluster 和 time cluster，都已经默认注册在了 Endpoint1 上，用户在开发的时候无需再次注册，此函数用户必须手动配置。

注意：此函数注册完成前禁止调用任何 ZigBee 相关API。

注册一个开关设备例子如下：

TAL_ENDPOINT_T dev_endpoint_desc[] = 
    1, ZHA_PROFILE_ID, ZG_DEVICE_ID_ON_OFF_LIGHT, SERVER_CLUSTER_NUM, (TAL_CLUSTER_T *)&app_server_cluster_list[0], 0, NULL,
;

//register zigbee endpoint
  tal_zg_endpoint_register(dev_endpoint_desc, GET_ARRAY_LEN(dev_endpoint_desc));

节点配置函数：

OPERATE_RET tal_zg_node_config(TAL_ZG_NODE_CFG_T *config);

此函数是用来配置 ZigBee 节点的相关行为，例如节点类型、发射功率、扫描间隔以及 sleep end device rejoin 的相关行为，此函数用户必须手动配置。

以一个路由设备为例说明如何配置节点参数：

/**
 * @brief zigbee node init
 * 
 * @return VOID_T 
 */
STATIC VOID_T __app_router_node_init(VOID_T)

    TAL_ZG_NODE_CFG_T node_config = 
        .node_type = ZG_ROUTER,        //节点类型为路由设备
        .tx_power = 11,                //发射功率为11
        .scan_interval = 0,            //加入网络时扫描时间间隔为0
        .scan_duration = ZG_SCAN_DURATION_3,  //RF接收器在一个频道上打开的时间为153.6s
    ;
    tal_zg_node_config(&node_config);

加网扫描配置函数：

OPERATE_RET tal_zg_join_config(TAL_ZG_JOIN_CFG_T *config);

此函数是用来配置 ZigBee 入网参数，例如是否需要上电自动配网、被网关删除是否自动配网、配网扫描超时时间等，此函数用户必须手动配置。

以配置设备入网参数为上电需自动配网，被网关移除需自动配网，配网扫描超时时间为20s为例举例：

//zigbee joining network configuration
  TAL_ZG_JOIN_CFG_T join_config = 
      .auto_join_power_on_flag = TRUE,     //上电自组网
      .auto_join_remote_leave_flag = TRUE, //被网关移除后自组网
      .join_timeout = 20000,               //配网扫描超时时间为20s
  ;
  
  tal_zg_join_config(&join_config);

配网扫描函数：

BOOL_T tal_zg_join_start(UINT_T timeout_ms);

此函数是用来开启 ZigBee 入网扫描的，调用后会先进行本地离网，然后对设置的超时时间内进行配网扫描，配网成功或者配网失败后会调用网关状态改变的回调函数，通知用户网络状态变化。如果没有配置关闭网关自恢复功能，在入网超时后会尝试进行网络自恢复，如果成功回到之前的网络，则会自动重启。

#define ZIGBEE_JOIN_MAX_TIMEOUT 30 * 1000

/**
 * @note join start delay timer hander, join now
 * @param[in]  none
 * @param[out] none
 * @return none
 */
STATIC VOID_T __app_network_join_start_delay_cb(TIMER_ID timer_id, VOID_T *arg)

    tal_zg_join_start(ZIGBEE_JOIN_MAX_TIMEOUT);

离网函数：

VOID_T tal_zg_leave_start(TAL_ZG_JOIN_CFG_T *config);

此函数是在网设备用来进行离网使用的，离网成功后会调用网关状态改变的回调函数，通知用户网络状态变化。如果没有配置关闭网关自恢复功能，断电重启后且没有设置上电自动配网的情况下，会尝试进行网络自恢复，如果成功回到之前的网络，则会自动重启。

网络状态改变回调函数：

VOID_T tal_zg_nwk_status_changed_callback(TAL_ZG_NWK_STATUS_E status);

此函数用于在 ZigBee 网络状态发送改变后通知用户，用户可以根据不同的网络状态进行相关操作，对于网络状态解释如下：

状态	调用时机	作用
TAL_ZG_NWK_POWER_ON_LEAVE	设备上电后没有加入任何网络	指示上电后的网络状态
TAL_ZG_NWK_POWER_ON_ONLINE	设备上电后处于在网状态	指示上电后的网络状态
TAL_ZG_NWK_JOIN_START	在调用配网时扫描后用于通知用户配网扫描开启	指示开启配网扫描状态
TAL_ZG_NWK_JOIN_TIMEOUT	在开启配网的指定时间内没有成功入网	指示配网超时
TAL_ZG_NWK_JOIN_OK	在配网开启后成功加入ZigBee网络	指示开启配网后成功入网状态
TAL_ZG_NWK_LOST	低功耗设备由于某种原因与父节点失联	指示设备与它的父节点丢失的状态
TAL_ZG_NWK_REJOIN_OK	低功耗设备在丢失父节点后重新回到网络	指示重回网络后的状态
TAL_ZG_NWK_LOCAL_LEAVE	设备本地调用离网函数	指示设备离网是本地调用离网函数
TAL_ZG_NWK_REMOTE_LEAVE	设备接收到网关的离网请求，或者3.0 key交互失败，本地主动离网	指示离网是由于网关请求或者是key交互失败
TAL_ZG_NWK_MF_TEST_LEAVE	设备在进行网关产测后，本产测网关请求离网	指示产测结束导致的离网

设备上电计数及配网流程说明：

• 设备每次上电都会读取一次 flash 中存储的 cnt （上电次数），并将该值+1，若下一次上电的时间间隔超过5秒，则会通过一个计数器清0事件，将该 cnt 清零后再次上电时等同于首次上电；
• 配网时，网络指示灯快闪，提示用户设备已进入配网状态；
• 设备配网成功后，网络指示灯常亮，并上报当前的设备属性如开关等；
• 当配网时间超过最大配网时间时，配网失败，此时灯常亮并结束配网；
• 设备在网，通过 app 远端移除后，会再次配网，灯快闪，提示设备进入配网状态；

函数使用举例如下：

/**
 * @brief zigbee network network change callback(user can rewrite this API)
 * 
 * @param[in]   status: network status
 * @return VOID_T
 */
VOID_T tal_zg_nwk_status_changed_callback(TAL_ZG_NWK_STATUS_E status)

    switch (status)
    
    case TAL_ZG_NWK_POWER_ON_LEAVE:
    
        TAL_PR_DEBUG("power_on_leave---");
        break;
    
    case TAL_ZG_NWK_POWER_ON_ONLINE:
    
        TAL_PR_DEBUG("power_on_online---");
        break;
    
    case TAL_ZG_NWK_JOIN_START:
    
        TAL_PR_DEBUG("nwk_join_start---");
        break;
    
    case TAL_ZG_NWK_JOIN_OK:
    
        TAL_PR_DEBUG("nwk_join_ok---");
        break;
    
    case TAL_ZG_NWK_REJOIN_OK:
    
        TAL_PR_DEBUG("nwk_rejoin_ok---");
        break;
    
    case TAL_ZG_NWK_JOIN_TIMEOUT:
    
        TAL_PR_DEBUG("nwk_join_timeout---");
        break;
    
    case TAL_ZG_NWK_LOST:
    
        TAL_PR_DEBUG("nwk_lost---");
        break;
    
    case TAL_ZG_NWK_REMOTE_LEAVE:
    
        TAL_PR_DEBUG("nwk_remote_leave---");
        break;
    
    case TAL_ZG_NWK_LOCAL_LEAVE:
    
        TAL_PR_DEBUG("nwk_local_leave---");
        break;
    
    case TAL_ZG_NWK_MF_TEST_LEAVE:
    
        TAL_PR_DEBUG("nwk_mf_test_leave---");
        break;
    
    default:
    
        break;
    
    

恢复出厂设置回调函数：

VOID_T tal_zg_reset_factory_default_callback(TAL_RESET_TYPE_T type);

此函数是在收到网关请求回复出厂设置时用来通知用户进行数据清除的，用户可以根据类型来进行不同业务的实现。

zigbee 网络数据收发接口

写属性前置回调函数：

TAL_WRITE_RET_E tal_zg_pre_write_attribute_callback(UINT8_T ep_id,
                                                    UINT16_T cluster_id,
                                                    TAL_ATTR_REC_T *attr_rec);

此函数是在收到远程设备写属性命令后，但是在真正写本地属性前进行调用的，用户可以检查传入参数，并通过返回值来决定 SDK 内部是否需要将属性写入到本地。

写属性后置回调函数：

TAL_WRITE_RET_E tal_zg_post_write_attribute_callback(UINT8_T ep_id, 
                                                    UINT16_T cluster_id,
                                                    TAL_ATTR_REC_T *attr_rec);

此函数是在收到远程设备写属性命令后，但是在本地真正写完属性后进行调用的。

general cmd 命令接收回调函数：

TAL_MSG_RET_E tal_zcl_general_msg_recv_callback(TAL_ZCL_MSG_T *msg);

此函数是在接收到 ZCL Frame Type 和 command acts across the entire profile 类型的数据时会将数据透传给用户，目前用户无特殊需求，不需要处理此函数所给的数据。

/**
 * @brief general message receive callback
 *
 * @param msg
 * @return TAL_MSG_RET_E
 *
 */
TAL_MSG_RET_E tal_zcl_general_msg_recv_callback(TAL_ZCL_MSG_T *msg)

    //TAL_PR_DEBUG("app gen msg cb: cluster 0x%02x, cmd %d", msg->cluster, msg->command);

    return ZCL_MSG_RET_SUCCESS;

specific cmd 命令接收回调函数：

TAL_MSG_RET_E tal_zcl_specific_msg_recv_callback(TAL_ZCL_MSG_T *msg);

此函数是在接收到 ZCL Frame Type 和 command is specific to a cluster 类型的数据时会将数据通过此函数透传给用户，用户需要根据结构体指针自行解析和处理 ZigBee 业务数据。

以开关设备接收数据并处理为例：

/**
 * @brief specific message receive callback
 *
 * @param msg
 * @return TAL_MSG_RET_E
 */
TAL_MSG_RET_E tal_zcl_specific_msg_recv_callback(TAL_ZCL_MSG_T *msg)

    TAL_PR_DEBUG("app spec msg cb: cluster 0x%02x, cmd 0x%02x", msg->cluster, msg->command);

    ZIGBEE_CMD_T app_cmd_type = ZIGBEE_CMD_SINGLE;
    if (msg->mode == ZG_UNICAST_MODE)
    
        app_cmd_type = ZIGBEE_CMD_SINGLE;
        TAL_PR_DEBUG("receive single message");
    
    else
    
        app_cmd_type = ZIGBEE_CMD_GROUP;
        TAL_PR_DEBUG("receive group message");
    

    switch (msg->cluster)
    
    case CLUSTER_ON_OFF_CLUSTER_ID:
    
        //handle on/off cluster command
        app_onoff_cluster_handler(msg->command, msg->payload, msg->length, app_cmd_type);
    
    break;
    case CLUSTER_LEVEL_CONTROL_CLUSTER_ID:
    
        //handle level control cluster command
        app_level_cluster_handler(msg->command, msg->payload, msg->length, app_cmd_type);
    
    break;

    case CLUSTER_PRIVATE_TUYA_CLUSTER_ID:
    
        break;
    
    default:
        break;
    

    return ZCL_MSG_RET_SUCCESS;

场景保存回调函数：

VOID_T tal_zg_scene_save_callback(UINT8_T ep_id, UINT8_T scene_id, UINT16_T group_id, TAL_SCENE_DATA_T *data);

此函数是在接收到远程设备给当前设备 Add scene 或者要求设备 Store scene 时进行回调通知，用户根据场景数据类型，决定是否需要存储当前设备的状态，如果是 TAL_SCENE_DATA_TYPE_YOURSELF 则用户需要把当前设备的状态进行保存便于在 recall 时进行状态还原，如果是 TAL_SCENE_DATA_TYPE_EXT_SERVER 则用户不需要存储场景数据， SDK 内部会把接收到的场景数据进行自动存储。

场景 recall 回调函数：

VOID_T tal_zg_scene_recall_callback(UINT8_T ep_id, UINT8_T scene_id, UINT16_T group_id, UINT_T time100ms, TAL_SCENE_DATA_T *data);

此函数是在接收到远程设备 recall scene 时给到用户的回调通知函数，用户可以在此函数中获取到之前存储的场景数据，并利用此数据进行设备状态的还原。

数据发送函数：

VOID_T tal_zg_send_data(TAL_ZG_SEND_DATA_T *pdata, TAL_SEND_RESULT_CB callback, UINT_T timeout);

此函数用于发送 ZigBee 数据，底层会把业务数据进行缓存，然后按照顺序进行按需发送，用户可以通过设置回调状态来确认数据是否发送成功，同时还可以设置远程设备回访应答的最大超时时间，建议此时间是 200ms 的整数倍。其中callback参数用于注册发送回调，用户可以在此回调接口中获取发送状态信息。

以上报开关设备当前状态为例：

/**
 * @brief 
 * 
 * @param Qos 
 * @param delay_ms 
 * @param onoff 
 * @return VOID_T 
 */
VOID_T app_onoff_report_value(TAL_SEND_QOS_E Qos, USHORT_T delay_ms, UINT8_T onoff)

    TAL_ZG_SEND_DATA_T send_data;

    tal_system_memset(&send_data, 0, sizeof(TAL_ZG_SEND_DATA_T));

    send_data.delay_time = delay_ms;
    send_data.random_time = 0;
    send_data.zcl_id = ZCL_ID_ONOFF;
    send_data.qos = Qos;
    send_data.direction = ZG_ZCL_DATA_SERVER_TO_CLIENT;
    send_data.frame_type = ZG_ZCL_FRAME_TYPE_GLOBAL;
    send_data.command_id = CMD_REPORT_ATTRIBUTES_COMMAND_ID;

    // unicast to gateway
    send_data.addr.mode = SEND_MODE_DEV;
    send_data.addr.type.dev.dst_addr = TUYA_GATEWAY_ADDRESS;
    send_data.addr.type.dev.dst_ep = 0x01;
    send_data.addr.type.dev.src_ep = TUYA_PRIMARY_ENDPOINT;
    send_data.addr.type.dev.cluster_id = CLUSTER_ON_OFF_CLUSTER_ID;

    send_data.data.zg.attr_sum = 1;
    send_data.data.zg.attr[0].attr_id = ATTR_ON_OFF_ATTRIBUTE_ID;
    send_data.data.zg.attr[0].type = ATTR_BOOLEAN_ATTRIBUTE_TYPE;
    send_data.data.zg.attr[0].size = 1;
    send_data.data.zg.attr[0].value[0] = onoff;
    tal_zg_send_data(&send_data, NULL, 2000);
    TAL_PR_DEBUG("Report onoff qos:%d VALUE %d", Qos, onoff);

数据发送队列清除函数：

VOID_T tal_zg_clear_send_data(TAL_ZG_CLEAR_TYPE_E type, VOID_T *args);

此函数是清除缓存在 SDK 底层的业务数据，避免因为缓存导致发送了不正确的数据。

zigbee 属性读写

写属性函数：

OPERATE_RET tal_zg_write_attribute(UINT8_T endpoint,
                                UINT16_T cluster,
                                UINT16_T attr_id,
                                VOID_T* data,
                                ZG_ATTR_TYPE_E type);

此函数用于写入 ZigBee 对应的属性值，写入的属性必须是要注册过的，否则写入会失败，如果在注册时标注属性的掩码值为 ATTR_MASK_TOKEN_FAST，则会将在写属性时同时将属性值存入NV flash 中。

以更新开关设备数据为例：

    //update on/off attribute
    tal_zg_write_attribute(1,
                           CLUSTER_ON_OFF_CLUSTER_ID,
                           ATTR_ON_OFF_ATTRIBUTE_ID,
                           &onoff,
                           ATTR_BOOLEAN_ATTRIBUTE_TYPE);

读属性函数：

OPERATE_RET tal_zg_read_attribute(UINT8_T endpoint,
                                UINT16_T cluster,
                                UINT16_T attr_id,
                                VOID_T *data,
                                UINT8_T length);

此函数用于读取 ZigBee 对应的属性值，读取的属性必须是要注册过的，否则读取会失败。

    tal_zg_read_attribute(TUYA_PRIMARY_ENDPOINT,
                          CLUSTER_BASIC_CLUSTER_ID,
                          ATTR_APPLICATION_VERSION_ATTRIBUTE_ID,
                          (VOID_T *)&version,
                          sizeof(version));

ZigBee 产测

禁止信标产测函数：

VOID_T tal_mf_test_disable_beacon_test(VOID_T);

此函数用于禁止 beacon 产测模式。

产测串口配置函数：

VOID_T tal_mf_test_get_uart_cfg(UINT_T *out_uart_id, TAL_UART_CFG_S *out_cfg);

此函数用于配置产测时使用的串口，但是 uart id 只能返回 MF_TEST_UART_ID ，如果不调用此函数则使用默认产测接口进行串口产测。

预产测回调函数：

VOID_T tal_mf_test_pre_start_callback(VOID_T *args);

此函数仅用户 double dongle 产测模式，在接收到进入预产测模式的广播后会调用此函数，用户可以用一些行为指示进入预产测模式，方便产测人员观察。

产测退出回调函数：

VOID_T tal_mf_test_end_callback(UINT8_T *data);

此函数仅用户 double dongle 产测模式，产测结束后会调用此函数，并将产测结果通知用户，*data = 1 产测流程成功结束。

Beacon 产测进入回调函数：

VOID_T tal_beacon_mf_test_callback(VOID_T);

此函数仅用于 beacon 产测模式，在接收到 beacon 广播的进入 beacon 产测的数据帧时，会通过此函数通知用户，用户可以根据自己的需要进行相应的操作，来表明这个设备的功能是完整的。

VOID_T tal_beacon_mf_test_callback(VOID_T)

    TAL_PR_DEBUG("enter beacon test\\n");
    tal_sw_timer_create(app_light_ctrl_mf_blink_cb, NULL, &etimer_mf_blink);
    tal_sw_timer_start(etimer_mf_blink, 250, TAL_TIMER_ONCE);

产测数据处理回调函数：

TUYA_MF_TEST_RET_T tal_mf_test_handle_callback(TUYA_MF_TEST_CMD_T cmd,
                                                UINT8_T*arg, 
                                                UINT16_T arg_len);

此函数用于接收产测数据帧，在串口产测、网关产测、double dongle 产测模式下接收到的产测数据都将通过这个接口通知用户，用户解析数据帧后进行相应的产测行为。

产测结果通知函数：

VOID_T tal_mf_test_result_notify(TUYA_MF_TEST_RET_T result);

此函数用于回复产测结果为 true 或者 false 的产测项。

按键产测结果通知函数：

VOID_T tal_mf_test_button_test_notify(UINT_T key_id);

此函数用于回复按键产测结果，key_id 是产测按键 id 。

电平式传感产测结果通知函数：

VOID_T tal_mf_test_bool_sensor_notify(UINT8_T sensor_type, UINT8_T index, BOOL_T result);

此函数用于回复高低电平传感器产测结果。