Local Linkage

Overview

Concepts

• Tap-to-run and automation: Both are a type of linkage, but differ in the following ways.

  • Tap-to-run does not contain conditions, but actions.
  • Automation contains both conditions and actions. When a condition is met, an action is taken.

• Local linkage: It is a type of automation, in which the devices (if any) involved in the condition and action are connected to the same gateway. Local linkage is not dependent on the cloud. It can be run even if the gateway cannot connect to the cloud, for example, due to no internet access.

• Cloud linkage: The cloud runs the linkage. Linkage execution depends on the connection to the cloud.

• LAN linkage: The gateway runs the linkage. It differs from local linkage in that the devices involved in the condition and action for LAN linkage are connected to different gateways that belong to the same home and are in the same LAN.

• Zigbee scene: It is created with Zigbee scene devices. A Zigbee scene is triggered by Zigbee scene devices, without a gateway and cloud involved. Devices run in a Zigbee scene must be Zigbee-enabled.

  The automation triggers can be level triggering or edge triggering. The former means to trigger automation as long as the condition is met. The latter means to trigger automation only once when the condition is met.

How it works

• After a linkage is created, if the cloud determines that the gateway can take over the linkage, it sends the rule to the gateway. Then, the gateway takes care of everything about the linkage locally. This is local linkage. If the cloud determines the gateway cannot take over the linkage, it does not send the rule to the gateway. The cloud takes care of everything about the linkage. This is cloud linkage.

  

• To run local linkage, the following requirements must be met:

  • The devices involved in the condition and action are sub-devices to the same gateway or the gateway itself.
  • The condition is tap-to-run, a schedule, or a change in device status.
  • The action is a device operation, a delay, or tap-to-run.

Development guide

How to use

The SDK automatically performs initialization and processes rules internally. You call the following APIs as needed.

Data structure

Type definition

typedef BYTE_T LINKAGE_RULE_TYPE_T;

#define LINKAGE_RULE_LOCAL       0
#define LINKAGE_RULE_LAN         1

typedef struct{
    CHAR_T rule_id[RULE_ID_LEN + 1];
    CHAR_T name[128];   
    BOOL_T isHaveCond;  /**< 0: Tap-to-Run. 1: Automation. */
    BOOL_T isEnable;    /**< 0: Disable. 1: Enable. */
} RULE_INFO;

typedef struct{
    UINT_T rule_num;
    LINKAGE_RULE_TYPE_T rule_type;
    RULE_INFO **rule_info;
} ALL_RULE_INFO;

API description

Execute a tap-to-run task

/**
 * @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);

Get the name and ID of a linkage rule

/**
 *  @brief Get linkage rules of the gateway
 *  
 *  @note You should invoke scene_linkage_all_rule_info_free to release resources
 *  
 *  @example
 *      // get local linkage rules
 *      OPERATE_RET exe_ret = scene_linkage_load_all_rule_info_from_disk(LINKAGE_RULE_LOCAL, &all_rule_info);
 *      if (exe_ret == OPRT_OK) {
 *          INT_T i = 0;
 *          for (i = 0; i < all_rule_info.rule_num; ++i) {
 *              CONST RULE_INFO *rule_info = all_rule_info.rule_info[i];
 *              // TODO
 *          }
 *          scene_linkage_all_rule_info_free(&all_rule_info);
 *      }
 *
 */
OPERATE_RET scene_linkage_load_all_rule_info_from_disk(LINKAGE_RULE_TYPE_T rule_type,  ALL_RULE_INFO *all_rule_info);

/**
 * @brief Release resource for linkage rules
 *
 * @param all_rule_info pointer of rule info
 */
VOID scene_linkage_all_rule_info_free(ALL_RULE_INFO *all_rule_info);

Register notifications of changes in linkage rules

typedef VOID (*SCENE_LINKAGE_NAME_ID_UPADATE_CB)(VOID);

/**
 * @brief Enable linkage rule changed event
 */
VOID scene_linkage_oneclick_get_name_enable_set(VOID);

/**
 * @brief Register linkage rule changed event
 *
 * @note You should invoke scene_linkage_oneclick_get_name_enable_set before SDK initialization to enable this event
 *
 * @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);

Things to note

• Reliability: Local linkage > LAN linkage > cloud linkage Local linkage is recommended to ensure reliable performance.
• Try to use less logic for easy understanding. For example:
  • Not recommended: A links to B, and B links to C.
  • Recommended: A links to B and C.