涂鸦Zigbee SDK开发系列教程——6.SDK API函数接口介绍
时间:2022-11-12 06:30:00
本章主要介绍 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, //RF153.6s }; tal_zg_node_config(&node_config); }
加网扫描配置函数:
OPERATE_RET tal_zg_join_config(TAL_ZG_JOIN_CFG_T *config);
该函数用于配置 ZigBee 本函数用户必须手动配置入网参数,如是否需要上电自动配网、是否被网关删除、配网扫描超时等。
配置设备入网参数为上电需要自动配网,被网关移除需要自动配网。s为例举例:
//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);
此函数用于回复高低电平传感器产测结果。