本地联动

概述

基本概念

• 一键执行 和 自动化：都是 联动，两者的区别是：

  • 一键执行不包含条件，但包含动作。
  • 自动化包含条件和动作，当条件满足时，会触发动作。

• 本地联动：是联动的一种，其条件和动作包含的设备 (如果有的话) 均在同一网关下，本地联动的执行不依赖云端，当网关无法连接云端(比如无外网)时，本地联动仍旧可以执行。

• 云端联动：是由云端执行的联动，联动的执行依赖云端。

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

• 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。