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

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

Data structure

Type definition

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;

Callback

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

API description

Tap-to-run

/**
 * @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 exists, the scene is executed. Otherwise, OPRT_NOT_FOUND is returned.
 */
OPERATE_RET scene_linkage_scene_exe_by_name(const CHAR_T *scene_name);

Get the name and ID of tap-to-run

/**
 * @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 tap-to-run 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 must be converted into 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);

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.