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 CFLink Protocol (Event Triggering) ======

===== Rules 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.

For more details on how to configure rules, please see our [[hardware:rules|general rules tab entry]] on our wiki.

===== Rules CFLink 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 [[http://github.com/CommandFusion/RulesProcessor|RulesProcessor JavaScript object]] 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:\\
[[https://github.com/downloads/CommandFusion/Downloads/RulesProtocol_v0.8.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
