本地联动

更新时间:2023-09-06 10:40:14下载pdf

概述

基本概念

  • 一键执行自动化:都是 联动,两者的区别是:

    • 一键执行不包含条件,但包含动作。
    • 自动化包含条件和动作,当条件满足时,会触发动作。
  • 本地联动:是联动的一种,其条件和动作包含的设备 (如果有的话) 均在同一网关下,本地联动的执行不依赖云端,当网关无法连接云端(比如无外网)时,本地联动仍旧可以执行。

  • 云端联动:是由云端执行的联动,联动的执行依赖云端。

  • 局域网联动:局域网联动是由网关执行的联动,与本地联动不同的是,联动里的条件和动作所涉及到的设备在不同网关下,并且要求这些网关处于在同一个家庭和同一个局域网中。

  • Zigbee 标准场景:需要通过 Zigbee 场景设备创建。它的不同在于可以不通过网关和云端,由 Zigbee 场景设备直接触发执行。Zigbee 标准场景的动作设备必须都是 Zigbee 设备。

    另外自动化触发条件可分为 连续触发边缘触发,连续触发表示当前条件和设备状态一样就触发 而边缘触发是当条件从不满足变为满足当前条件时才会触发。

工作原理

  • 一个联动创建后,如果云端判定网关可以接管,则下发规则给网关,网关接管成功后,规则就变为本地联动,后续联动的判定和执行都由网关来处理。如果云端判定规则网关不能接管,规则不会下发给网关,后续联动的判定和执行都由云端来处理,这条规则属于云端联动。

    本地联动

  • 一个联动是否是本地联动,需要符合以下几点 :

    • 条件和动作都是单网关下的子设备或者网关自身的 dp
    • 条件是一键执行 或 定时 或 设备状态变化
    • 动作是操作设备 或 延时执行 或 一键执行

开发指导

使用方法

SDK 内部会自动初始化和处理规则,使用者只需根据需求调用如下外部接口即可。

数据结构

类型定义

typedef struct {
	CHAR_T rule_id[RULE_ID_LEN + 1];
	CHAR_T rule_name[0];
} RULE_NAME_ID_INFO;

typedef struct{
	UINT_T rule_num;
	RULE_NAME_ID_INFO **rule_info;
}ALL_RULE_NAME_ID;

typedef struct{
	UINT_T rule_num;
	CHAR_T **rule_id;
}ALL_RULE_ID;

回调函数

// One-click execution rule update callback function
typedef VOID(*SCENE_LINKAGE_NAME_ID_UPADATE_CB)();

API 说明

执行一键执行相关 API

/**
 * @brief Execute the specified one-click execution (scene) by id
 *
 * @param sceneId  The one-click execution (scene) id that needs to be executed
 * @return VOID
 */
VOID scene_linkage_scene_exe(CHAR_T *sceneId);

/**
 * @brief Execute the specified one-click execution (scene) by name
 *
 * @param scene_name  The one-click execution (scene) name that needs to be executed
 * @return OPRT_OK if scene_name exist and execute it, Otherwise return OPRT_NOT_FOUND
 */
OPERATE_RET scene_linkage_scene_exe_by_name(const CHAR_T *scene_name);

获取一键执行名称和 ID

/**
 * @brief Enable the function of obtaining the name and id of one-click execution
 *
 * @return VOID
 */
VOID scene_linkage_oneclick_get_name_enable_set();

/**
 * @brief Whether the one-click execution name and id function is enabled
 *
 * @return  TRUE when turned on, FALSE when turned off
 */
BOOL_T scene_linkage_oneclick_get_name_enable_get();

/**
 * @brief Get the name and id of all one-click execution
 *
 * @return ALL_RULE_NAME_ID*
 * @note
 *      1. Need to call scene_linkage_oneclick_name_id_free() after use up
 *      2. The name of one-click execution cannot exceed 127 bytes, otherwise it cannot be obtained
 *      3. Please make sure you have called scene_linkage_oneclick_get_name_enable_set before calling,
 *         otherwise return NULL
 *      4. All uppercase letters in the name are coerced to lowercase
 * @example
 *       ALL_RULE_NAME_ID *all_rule = scene_linkage_oneclick_name_id_get();
 *       if(all_rule != NULL){
 *           for(int i = 0;i < all_rule->rule_num; ++i){
 *               CHAR_T *id = all_rule->rule_info[i]->rule_id;
 *               CHAR_T *name = all_rule->rule_info[i]->rule_name;
 *               // do something here;
 *           }
 *       }
 *       scene_linkage_oneclick_name_id_free(all_rule);
 *
 */
ALL_RULE_NAME_ID *scene_linkage_oneclick_name_id_get();

/**
 * @brief release ALL_RULE_NAME_ID resources, this function must be called after calling
 *        scene_linkage_oneclick_name_id_get
 *
 * @param all_rule , The resource identifier that needs to be released
 * @return VOID
 */
VOID scene_linkage_oneclick_name_id_free(ALL_RULE_NAME_ID *all_rule);

/**
 * @brief Register the callback function, when there is an update in one-click execution,
 *        the callback function cb will be called
 *
 * @param cb
 * @return VOID
 * @note The cb function cannot be blocked or delayed
 */
VOID scene_linkage_oneclick_name_id_update_cb_set(SCENE_LINKAGE_NAME_ID_UPADATE_CB cb);

注意事项

  • 可靠性:本地联动 > 局域网联动 > 云端联动。所以请尽量配置本地联动。
  • 联动逻辑层级建议尽量少,便于理解。例如:
    • 不推荐:A 联动 B,B 再联动 C。
    • 推荐:A 联动 B 和 C。