====== DIN-RY CFLink Protocol ======

The following documentation is for the DIN-RYx-N devices CFLink protocol messages. This protocol can be used regardless of connection method to the DIN-RYx device either via USB, RS232 or RS485.

===== Control Port Configuration =====

This command is used to configure the communication properties for each control port on the unit.
<sxh cflink; light: true>
> [F2]<ID>[F3]CCFXSPC[F4]<PORT>:<MODE>:<BAUD>:<DATABITS>:<PARITY>:<STOP>:<FLOW CONTROL>[F5][F5]
</sxh>

* **<PORT>** would be designated as:
       * P01 = RS232 IN
       * P02 = RS485 IN
       * P03 = RS485 OUT
       * P04 = RS232 OUT
       * PZZ = All Ports

* **<MODE>** would be designated as:
       * BUS (Bus Mode) - Messages are to be treated as control protocol commands and forwarded along the bus as per the Message Handling documentation. Available <BAUD> rates would be 115200 (default) and 38400.

<sxh cflink; light: true>
> [F2][20][F3]CCFXSPC[F4]P04:BUS:115200:8:N:1:0[F5][F5]
</sxh>

       * EXT (External Mode) - Messages sent to/from a third party device, allowing control of other RS232 or RS485 devices via rules and macros. Available <BAUD> rates would be:
         * 100
         * 600
         * 1200
         * 2400
         * 4800
         * 9600 (Default for EXT mode)
         * 14400
         * 19200
         * 38400
         * 57600
         * 115200
         * 128000
         * 256000

      * CFL (CFLink Mode) - Messages sent to/from the CFLink Bus, allowing control of other CFLink devices via rules and macros. 115200 is the default <BAUD> rate. Note that CFLink mode connection is only available for RS485-In port.

<sxh cflink; light: true>
> [F2][20][F3]CCFXSPC[F4]P02:CFL:115200:8:N:1:0[F5][F5]
</sxh>

=== Query Port Configuration ===
This command is used to query and get the current port settings for each control port on the unit.

<sxh cflink; light: true>
> [F2]<ID>[F3]QCFXSPC[F4]<PORT>[F5][F5]    \\ Query status of individual ports
> [F2]<ID>[F3]QCFXSPC[F4][F5][F5]          \\ Query status of all ports
</sxh>

=== Sending Command to Control External Devices ===

This command is used to send data to control the external device depending on the port used.

<sxh cflink; light: true>
> [F2]<ID>[F3]TCFXSPW[F4]<PORT>:<DATA>[F5][F5]    
</sxh>

===== Relay Commands =====

==== On / Off / Toggle ====

The ''TRLYSET'' (Send) command is used to send a command to the relay channels.

=== Data ===

<sxh cflink; light: true>
> [F2]<ID>[F3]TRLYSET[F4]<PORT>:<STATE>[F5][F5]
</sxh>

  * **<PORT>** = The relay channel (port) to be controlled. Relay channels would be from ''P01-P08'' for the 8-channel and ''P01-P05'' for the 5-channel.
  * **<STATE>** = The command to set the status of relay. ''0'' would set the relay to open, ''1'' would set the relay to close, ''T'' would set the relay to toggle. 

=== Reply ===

<sxh cflink; light: true>
< [F2]<ID>[F3]RRLYCHA[F4]<PORT>:<STATE>[F5][F5] // The reply comes from only the port where the change event happens
< [F2]<ID>[F3]RRLYSTA[F4]<PORT>:<STATE>[F5][F5] // The reply comes from all the ports 
</sxh>

To minimize the data traffic on the communication bus, the ''RRLYCHA'' will only reflect the affected ports only. It will also be sent as unsolicited messages when buttons on the display panel are set. The ''RRLYSTA'' reply will have all port status, separated by pipes.

===== Dry Contacts =====

==== Status Read ====

=== Send ===

<sxh cflink; light: true>
> [F2]<ID>[F3]QCFXSTA[F4]<PORT>[F5][F5] // query single port
> [F2]<ID>[F3]QCFXSTA[F4][F5][F5]       // query all ports
</sxh>

=== Reply ===

<sxh cflink; light: true>
> [F2]<ID>[F3]RCFXSTA[F4]<PORT>:<STATE>[F5][F5]  // reply with 
> [F2]<ID>[F3]RCFXCHA[F4]<PORT>:<STATE>[F5][F5]  // auto reporting
</sxh>

When <PORT> is specified, reply will have status of only specified port. If <PORT> is omitted, reply will have all port states. ''RCFXCHA'' will be sent as unsolicited message when port changed.

==== Mode Configuration ====

=== Send ===
<sxh cflink; light: true>
> [F2]<ID>[F3]CCFXDCP[F4]<Port>:<Mode>:<Double Tap Time>:<Hold Time>[F5][F5]
> [F2]<ID>[F3]CCFXDCP[F4]<Port>:<Mode>:<Timeout Time>:<Trigger State>[F5][F5]
</sxh>

=== Reply ===
<sxh cflink; light: true>
> [F2]<ID>[F3]RCFXDCP[F4]<Port>:<Mode>:<Double Tap Time>:<Hold Time>[F5][F5]
</sxh>

  * **<PORT>** = The relay channel (port) to be controlled. Relay channels would be from ''P01-P08'' for the 8-channel and ''P01-P05'' for the 5-channel.
  * **<MODE>** = ''N'' for **Normal** (default), ''A'' for **Advanced**, ''T'' for **Timer**. 
  * **<Double Tap Time>** = Time in 100ths of a second for a double tap to occur within. Valid range (1-65535) (0.1s - 6553.5s).
  * **<Hold Time>** = Time in 100ths of a second for a long press and hold to occur. Valid range (1-65535) (0.1s - 6553.5s). 
  * **<Timeout Time>** = Time in 100ths of a second for a port to stop reporting commands. Valid range (1-65535) (0.1s - 6553.5s).
  * **<Trigger State>** = When to trigger timer to start and restart. 1 = on close, 0 = on open. Default is “1 On Close” if this param is missing.

In **Normal** mode, dry contacts work as currently - report state on change, on press and on release. <Double Tap Time> and <Hold Time> can be omitted from command when setting normal mode.

<sxh cflink; light: true>
> [F2]<ID>[F3]RCFXCHA[F4]<PORT>:<STATE>[F5][F5] // <STATE> = 1 for press or 0 for release.
</sxh>

In **Timer** mode, dry contacts report on change as normal to start, but do not report any CHA or STA again until the timer goes out. Still report if manually requested via ''QCFXSTA'' regardless of timer.

Each time the port “trigger state” is reached, the timer will restart. Only once it times out (the time elapses with no state changes) will it begin to start sending state changes again.

When the timer times out, it will also send a special reply''RCFXTUP'' for indicating the time is up with the port number as the data. For example:
<sxh cflink; light: true>
> [F2]<ID>[F3]RCFXTUP[F4]<PORT>[F5][F5] // <PORT> = P01 or P02, etc.
</sxh>

An example on Timer:

A command is sent with Port 1 defined as timer mode with timer as 300s, trigger on close.
<sxh cflink; light: true>
> [F2]<ID>[F3]CCFXDCP[F4]P01:T:3000:1[F5][F5] 
</sxh>

-> Port 1 closes: (timer = 0s)
<sxh cflink; light: true>
> [F2]<ID>[F3]RCFXCHA[F4]P01:1[F5][F5] 
</sxh>

-> 10 secs later, Port 1 closes: (time = 10s)
<no report, timer restarts>

-> 290 secs later from last event, Port 1 closes: (time = 300s) 
<no report, timer restarts>

-> 300 secs later from last event, and Port 1 is now open: (time = 600s)
<sxh cflink; light: true>
> [F2]<ID>[F3]RCFXCHA[F4]P01:0[F5][F5] // reports state
> [F2]<ID>[F3]RCFXTUP[F4]P01[F5][F5] // timeout 
</sxh>

Another example:

^ Time from 0 ^ Event ^ Bus Traffic ^ Timer ^
|Before 0s| | |inactive|
|0s|Motion trigger on port 1|\xF2<ID>\xF3RCFXCHA\xF4P01:1\xF5\xF5|started (300s)|
|10s|Motion trigger on port 1(port closes)|<no report>|re-started(300s)|
|15s|Port 1 opens|<no report>|No effect|
|20s|Motion trigger on port 1(port closes)|<no report>|re-started (300s)|
|25s|Port 1 opens|<no report>|No effect|
|320s|No event|\xF2<ID>\xF3RCFXCHA\xF4P01:0\xF5\xF5|Timer completed|
|~320s|No event|\xF2<ID>\xF3RCFXTUP\xF4P01\xF5\xF5|Timer completed|
|350s|Motion trigger on port 1 (port closes)|\xF2<ID>\xF3RCFXCHA\xF4P01:1\xF5\xF5|started (300s)|
|650s|No event|\xF2<ID>\xF3RCFXSTA\xF4P01:1\xF5\xF5| |
|~650s|No event|\xF2<ID>\xF3RCFXTUP\xF4P01\xF5\xF5|Timer completed|
|660s|Port 1 opens|<no report>|No effect|
|670s|Motion trigger on port 1 (port closes)|\xF2<ID>\xF3RCFXCHA\xF4P01:1\xF5\xF5|Timer “restarts” (300s)|

In **Advanced** mode, dry contacts will have no reports on press or release. Instead, it reports physical "gestures" - single tap (press), double tap (press) or held on change (press and hold) based on timing configuration:
<sxh cflink; light: true>
> [F2]<ID>[F3]RCFXCHA[F4]<PORT>:<STATE>[F5][F5] // <STATE> = S for Single Tap, D for Double Tap OR H for Hold
</sxh>

For example, let's configure a dry contact as **Advanced** mode P01:A:15:30 where Double Tap time = 1.5 seconds, Hold time = 3.0 seconds

A Single Tap is reported if the 1x press and 1x release is detected within the double tap time (1.5 seconds). A single tap will not be reported til after the double tap time has lapsed.

A Double Tap is reported if the 2x presses and 2x releases are detected within the double tap time (1.5 seconds).

A Hold is then reported if 1x press with no release is detected within the hold time (3 seconds). 

Start is defined by the detection of the first press. End is defined when a report is made. All timings are PER PORT.

Therefore a report of an event should be either a S, D OR H.  A “single” event CANNOT report multiple types of presses.

Valid time values are 000:100 where 100 = 10 seconds

<sxh cflink; light: true>
> [F2]<ID>[F3]CCFXDCP[F4]<PORT_CONFIG>[F5][F5] \\ Send
> [F2]<ID>[F3]RCFXDCP[F4]<PORT_CONFIG>[F5][F5] \\ Reply
</sxh>

For Example:
<sxh cflink; light: true>
> [F2]<ID>[F3]CCFXDCP[F4]P01:A:15:300|P02:N|P03:N[F5][F5] \\ Send
> [F2]<ID>[F3]RCFXDCP[F4]P01:A:15:300|P02:N|P03:N[F5][F5] \\ Reply
</sxh>

===== AC Load Status Read =====
<sxh cflink; light: true>
> [F2]<ID>[F3]QCFXACS[F4]<PORT>:<STATE>[F5][F5] \\ Query AC Load Status
> [F2]<ID>[F3]RCFXACS[F4]<PORT>:<STATE>[F5][F5] \\ Reply
</sxh>

===== Conditional commands based on variable states =====
<sxh cflink; light: true>
> [F2]<ID>[F3]TCFXCON[F4]<CONDITION>[F6]<ACTION>[F5][F5]  \\ Send
> [F2]<ID>[F3]RCFXCON[F4]<BOOLEAN>[F5][F5]                \\ Reply
</sxh>

Example of command syntax to send:
<sxh cflink; light: true>
> [F2]<ID>[F3]TCFXCON[F4]<VARIABLE><OPERATOR><VALUE>[F6]<TARGET_ID>:<COMMAND>:<DATA>[F5][F5]  \\ Syntax
> [F2]<ID>[F3]TCFXCON[F4]01==1[F6]00:TRLYSET:M2|P02:1[F5][F5] 
> [F2]<ID>[F3]RCFXCON[F4]TRUE[F5][F5]                                                          \\ Reply                                 
</sxh>

  * \xF6 splits the condition and the action. It is a single hex byte. The first \xF6 byte in the data should be considered the split location, so that the actual action can contain any byte including \xF6.
  * <DATA> can contain anything, except \xF5\xF5, including additional colons.
  * <VARIABLE> the data represents the variable type and variable character to get the value of, AA-ZZ. This allows you to compare a variable value in the condition.
  * Built in variables for this device are:
       * 00 = Any AC state is on = 1, else all off then = 0.
       * 01 = AC Status 1 (1 = on or 0 = off)
       * 02 = AC Status 2 (1 = on or 0 = off)
       * ....
       * 08 = AC Status 8 (1 = on or 0 = off)
  * <OPERATOR> can be one of the following symbol sequences (always 2 bytes)
       * ==    EQUAL TO
       * !=    NOT EQUAL TO
       * >>    GREATER THAN
       * >=    GREATER THAN OR EQUAL TO
       * <<    LESS THAN
       * <=    LESS THAN OR EQUAL TO
  * <VALUE> must be a digit, 0-65535. This is used (with the <OPERATOR>) to compare the state of the <VARIABLE>.
  * <TARGET_ID> should be the CFLink ID of the unit receiving the command, in plain ascii (range 2 - EF). Single character will work (2-9) or two characters (02-EF). 00 = local device (ie. target the same device the condition is running on).
  * For each reply, a boolean ''TRUE'' or ''FALSE'' will be returned on each condition evaluation, as the reply data payload. ''RCFXCON'' ''TRUE'' for example.

===== Conditional ON and OFF based on AC Status read =====
<sxh cflink; light: true>
> [F2]<ID>[F3]TRLYCON[F4]<CONDITION>|<ACTION>[F5][F5]  \\ Send
> [F2]<ID>[F3]RRLYCON[F4]<BOOLEAN>[F5][F5]             \\ Reply                                 
</sxh>


  * <IF AC STATE> = S01:1 (AC state 1 is on)
  * <IF AC STATE> = S01:0 (AC state 1 is off)

  * <SET PORT STATE> = P01:1 (port 1 L1/NO)
  * <SET PORT STATE> = P01:2 (port 1 L2/NC)
  * <SET PORT STATE> = P01:0 (port 1 L2/NC)
  * <SET PORT STATE> = P01:T (port 1 toggle)

<sxh cflink; light: true>
> [F2]<ID>[F3]TRLYCON[F4]S01:1|P01:1[F5][F5]  \\ If AC State 1 is ON, then Set Port 1 to L1

> [F2]<ID>[F3]TRLYCON[F4]S01:0|P01:2[F5][F5]  \\ If AC State 1 is OFF, then set relay port 1 to L2
> [F2]<ID>[F3]TRLYCON[F4]S01:0|P01:T[F5][F5]  \\ If AC State 1 is OFF, then toggle relay port 1, effectively turning ON circuit 1 when status reads OFF.
> [F2]<ID>[F3]TRLYCON[F4]S01:1|P02:T[F5][F5]  \\ If AC State 1 is ON, then toggle relay port 2.
> [F2]<ID>[F3]TRLYCON[F4]SZZ:1|PZZ:1[F5][F5]  \\ All ports.If AC State 1 is ON, then Set Port 1 to L1, If AC State 2 is ON, then Set Port 2 to L1, etc. until If AC State 8 is ON, then Set Port 8 to L1.
</sxh>

===== User Variable =====

You can use user variables to store strings or values that can be retrieved anytime for use later. 

The ''CVARSET'' (Send) command is used to assign a value to the defined user variable.

=== Data ===

<sxh cflink; light: true>
> [F2]<ID>[F3]CVARSET[F4]<VARIABLE_NAME>:<VALUE>[F5][F5]
</sxh>

  * **<VARIABLE_NAME>** = The name of the user variable.
  * **<VALUE>** = The value to be assigned to the variable.

=== Reply ===

<sxh cflink; light: true>
< [F2]<ID>[F3]RVARSET[F4]<VARIABLE_NAME>:<VALUE>[F5][F5] 
</sxh>

There are two variable query commands available -  ''QVARLST'' command is used to query all available variables and its respective values. ''QVARGET'' command is used to query a specific variable value.

=== Data ===

<sxh cflink; light: true>
> [F2]<ID>[F3]QVARLST[F4][F5][F5] \\ Query value for all variables
> [F2]<ID>[F3]QVARGET[F4]<VARIABLE_NAME>[F5][F5] \\ Query value for specific variable
</sxh>

  * **<VARIABLE_NAME>** = The name of the user variable.
  * **<VALUE>** = The value to be assigned to the variable.

=== Reply ===

<sxh cflink; light: true>
< [F2]<ID>[F3]RVARGET[F4]<VARIABLE_NAME>:<VALUE>[F5][F5] 
</sxh>