====== Rules (Event Triggered Macros) ======

===== Overview =====

Rules allow each device on the CFLink network to perform actions based on string matching of outgoing data on the CFLink bus.\\
For example, you can create a rule that when a specific dry contact on a SW16 is closed, a custom macro is triggered.

Rules are stored on the device that sends the commands. So if you want to perform a rule when a SW16 dry contact closes, you store the rule on the SW16.\\
If you wanted to perform a rule when data arrived on a TCP socket in the LAN Bridge, you would store the rule on the LAN Bridge.\\
If you wanted to perform a rule when the resistance input of a MOD-IO8 changed, you would store the rule in the unit housing the module (DIN-MOD4 for example).

===== Rule Properties =====

A rule is defined with a name, search string and a macro to trigger.

  * **Name** = A name given to the rule for your records. The name has no effect on anything, it's just a way to remember what a rule was created for.
  * **Search String** = A search pattern to match an outgoing CFLink message (as well as incoming TCP/UDP packets for LAN Bridge rules). When this search pattern matches a message, the rule is triggered.\\ Search strings can contain wildcard match characters as follows:
    * ''*'' (asterisk) means match any character zero or more times, until the next defined character in the search string is found, or until the end of the message.
    * ''.'' (period) means match any character a single time.
  * **Macro Name** = The name of a macro to perform when the rule is triggered (when the search string matches any outgoing data)

===== Macro Properties =====

A Macro is defined with a name and a series of actions and delays.

  * **Name** = The name of the macro. This is used by Rule definitions to call the macro to be performed.
  * **List Of Commands & Delays** = One or more actions with a delay
    * **Command Data** = The command data to send as part of the macro.
    * **Delay** = The delay before the command data for this action is sent. This delay is sequential, meaning its the delay from the action above it, NOT a delay from the start of the macro. The delay occurs BEFORE the command is sent. Use a delay of 0 (zero) to instantly send the command data.

====== System Commander Rules Tab ======
The rules tab within [[software:system-commander|System Commander]] allows you to create and add macros and rules to be run on your device. This tab is identical across all CommandFusion hardware that supports our Rules Engine.

{{:hardware:lan-bridge:lan-bridge-configuration:lan_bridge_rules_tab.png?nolink|}}

A detailed explanation of how to program macros and rules can be found in our [[software:system-commander:quick-start-guide:quick-start-page-3|System Commander Quick Start Guide here.]]

===== 1 - Rules =====
A rule watches for a specific event, then runs a macro when that event occurs.

===== 2 - Macro/Action =====
A macro must always be created first, as a rule will trigger a macro. A macro is a pre-defined set of actions to be run when triggered by a rule.

===== 3 - Buttons =====
==== Backup to File ====
This button allows you to backup your rules and macros to a local file. This can be file can be kept as a backup, or used to load the rules and macros onto a different device.

==== Restore to File ====
This button allows you to choose a locally stored backup file to load macros/rules onto the current device.

==== Clear Device Rules ====
Erases all rules all rules and macros from the current device.

==== Load From Device ====
Loads the rules and macros currently stored on the device and shows them in System Commander.

==== Save to Device ====
Saves all changes made to the device.

====== CFLink Protocol ======
For details on the CFLink protocol used to create and delete rules, please see the [[hardware:cflink:rules|Rules Protocol wiki entry]].