CommandFusion Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Rules (Event Triggering) ======

===== 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 any the 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.

===== Rules Protocol =====

Due to the storage requirements on CFLink devices, all rules on a device must be transfered in one process. Single rules cannot be added/edited/removed without sending all other rule information stored on the device at the same time. This means there are only three CFLink messages used to manipulate rules on a device, Write, Read and Delete.

Below is more information on these three commands, but to make life easier, we have also created a [RulesProcessor JavaScript object](http://github.com/CommandFusion/RulesProcessor) that you can use if needed.\\
This script will handle all the byte formatting and rule object creation for you, based on the CF Rules File Format specification.

===== File Format Documentation =====

Full documentation for the rules file format and transmission protocol is available with diagrams and sample data in the following PDF:\\
[[Rules Protocol Document]]

===== Queries =====

==== RLR - Rules Read ====

The `RLR` query is used to read all the rules stored a specific CFLink device.

=== Data ===

The `RLR` query does not have any associated data.

=== Reply ===

All rule information is transmitted in a series of replies, depending on the size of the data (the number of rules defined, number and size of actions, etc).\\
For specific details, on the return format, please see this PDF.

=== Example ===

Here is a basic example (without actual rule data) to show the basic sequence of events when sending rule information to be stored on the device

<sxh cflink; light: true>
// Request the Rules stored on device at CFLink ID [03]
> [F2][03][F3]QCFXRLR[F4]START[F5][F5]
// The Reply if the unit was a LAN Bridge would be as follows
< [F2][03][F3]RLANRLR[F4]<DATA1>[F5][F5]
// We must then acknowledge the data receipt by sending an ACK to the device so that it can continue sending the next reply
> [F2][03][F3]QLANRLR[F4]ACK[F5][F5]
// Second packet of rule data will now be transmitted
< [F2][03][F3]RLANRLR[F4]<DATA2>[F5][F5]
// Acknowledge receipt of the data again
> [F2][03][F3]QLANRLR[F4]ACK[F5][F5]
// Continue this back and forth whilst more rule data packets need to be received
< [F2][03][F3]RLANRLR[F4]<DATA3>[F5][F5]
> [F2][03][F3]QLANRLR[F4]ACK[F5][F5]
< [F2][03][F3]RLANRLR[F4]<DATA4>[F5][F5]
> [F2][03][F3]QLANRLR[F4]ACK[F5][F5]
.
.
.
// Once all rule data has been transmitted by the device, a final END message is transmitted.
< [F2][03][F3]RLANRLR[F4]END[F5][F5]
// We must then acknowledge the END receipt as well.
> [F2][03][F3]QLANRLR[F4]ACK[F5][F5]
</sxh>

All the received rule data can then be appended to create a single byte array, and parsed using the RulesProcessor JavaScript.

===== Configuration Messages =====

==== RLW - Rules Write ====

The `RLW` command is used to write rules to the on-board memory of a CFLink device. All rules must be included in the transmition, as partial rule writing is not possible.

=== Data ===

The `RLW` command requires sending the rule records as the command data, split into packets of 264 bytes, padding with \xFF bytes if the final record does not reach 264 bytes in length.

=== Reply ===

After each record, the device will reply with the acknowledgement reply, and the same for the final END command.

=== Example ===

Here is a basic example (without actual rule data) to show the basic sequence of events when requesting the stored rule information

<sxh cflink; light: true>
// Start by sending the first record of Rule data to be stored on device at CFLink ID [03]
> [F2][03][F3]CCFXRLW[F4]<DATA1>[F5][F5]
// Device will then acknowledge the data receipt by sending an ACK
< [F2][03][F3]RLANRLW[F4]ACK[F5][F5]
// We can continue sending the next record of data
> [F2][03][F3]CCFXRLW[F4]<DATA2>[F5][F5]
// Acknowledge receipt of the data replied again
< [F2][03][F3]RLANRLW[F4]ACK[F5][F5]
// Continue this back and forth whilst more rule record data packets need to be sent
> [F2][03][F3]CCFXRLW[F4]<DATA3>[F5][F5]
< [F2][03][F3]RLANRLW[F4]ACK[F5][F5]
> [F2][03][F3]CCFXRLW[F4]<DATA4>[F5][F5]
< [F2][03][F3]RLANRLW[F4]ACK[F5][F5]
.
.
.
// Once all rule data has been transmitted to the device, a final END message must be transmitted.
> [F2][03][F3]CCFXRLW[F4]END[F5][F5]
// We then receive acknowledgment of the END message as well.
< [F2][03][F3]RLANRLW[F4]ACK[F5][F5]
</sxh>

==== RLD - Rules Delete ====

The `RLD` command is used to delete rules stored in the on-board memory of a CFLink device. All rules will be deleted when this command is sent.

=== Data ===

The `RLD` command does not have any associated data.

=== Reply ===

<sxh cflink; light: true>
// After the delete command is issued, the following message is replied from the device
< [F2]<ID>[F3]RCFXRLD[F4]<NUM_RULES_DELETED>:<NUM_MACROS_DELETED>[F5][F5]
</sxh>

=== Example ===

<sxh cflink; light: true>
// Start by sending the delete command to a LAN Bridge on CFLink ID [03]
> [F2][03][F3]CCFXRLD[F4][F5][F5]
// LAN Bridge will then reply that the rules have been deleted with the stats of deleted items
< [F2][03][F3]RLANRLD[F4]4:3[F5][F5]
// 4 rules deleted
// 3 macros deleted
</sxh>
CommandFusion Wiki

User Tools

Site Tools

Page Tools
