====== Relay Ports CFLink Protocol ======
The following documentation describes the CFLink protocol for controlling relay ports on any device with relays.\\
This includes relay modules, cards and standalone devices such as the CF Mini

===== Queries =====
==== STA - Query Status ====
The ''STA'' (Status) query returns the status of all relays in a single module/device.

=== Data ===

<sxh cflink; light: true>
// Modular devices
> [F2]<ID>[F3]QRLYSTA[F4]<MODULE>[F5][F5]
// Standalone devices
> [F2]<ID>[F3]QRLYSTA[F4][F5][F5]

</sxh>

  * **<MODULE>** = The module number to request the status of. 2 chars, uppercase 'M' followed by the module number.
  *   eg. ''M1'' = Module 1, ''M4'' = Module 4.

=== Reply ===
<sxh cflink; light: true>

// Modular devices
< [F2]<ID>[F3]RRLYSTA[F4]<MODULE>|<RELAYDATA>[F5][F5]
// Standalone devices
< [F2]<ID>[F3]RRLYSTA[F4]<RELAYDATA>[F5][F5]
</sxh>

  * **<RELAYDATA>** = For each relay port in the module/device, the port status is returned in ''P##:<STATE>'' format. Multiple relay ports are included in a single reply using the Port Separator ''|'' (Pipe character)
    * **<STATE>** = Single digit, 0 = Relay Open, 1 = Relay Closed.

=== Example ===
<sxh cflink; light: true>

// Query the state of relays in Module 2 of a modular device on CFLink ID [04]
> [F2][04][F3]QRLYSTA[F4]M2[F5][F5]
// Reply, Module has 4 relay ports, all are open except port 1 which is closed.
< [F2][04][F3]RRLYSTA[F4]M2|P01:1|P02:0|P03:0|P04:0[F5][F5]

// Query the state of relays in a CF Mini on CFLink ID [06]
> [F2][06][F3]QRLYSTA[F4][F5][F5]
// Reply - CF Mini has 4 relay ports, all are open except port 1 which is closed.
< [F2][06][F3]RRLYSTA[F4]P01:1|P02:0|P03:0|P04:0[F5][F5]

</sxh>
=== Error ===

  * 004 = Invalid Module Number

==== POS - Query Power On State ====

The ''POS'' (Power On State) query returns the power on state for all relays in a single module/device.\\
This determines the state a relay will be set to when the device starts up (eg. after a power failure, restart, etc).

=== Data ===
<sxh cflink; light: true>

// Modular devices
> [F2]<ID>[F3]QRLYPOS[F4]<MODULE>[F5][F5]
// Standalone devices
> [F2]<ID>[F3]QRLYPOS[F4][F5][F5]

</sxh>

  * **<MODULE>** = The module number to request the power on status of. 2 chars, uppercase 'M' followed by the module number.
    * eg. ''M1'' = Module 1, ''M4'' = Module 4.

=== Reply ===
<sxh cflink; light: true>

// Modular devices
< [F2]<ID>[F3]RRLYPOS[F4]<MODULE>|<RELAYSTATES>[F5][F5]
// Standalone devices
< [F2]<ID>[F3]RRLYPOS[F4]<RELAYSTATES>[F5][F5]
<RELAYSTATES> = Repeated for each relay port in the module/device, the port status is returned in P##:<STATE> format. Multiple relay ports are included in a single reply using the Port Separator | (Pipe character)
<STATE> = Single character:
0 = Relay open on power on (Default)
1 = Relay closed on power on
L = Resume last state on power on

</sxh>

=== Example ===
<sxh cflink; light: true>

// Query the power on state of relays in Module 1 of a modular device on CFLink ID [04]
> [F2][04][F3]QRLYPOS[F4]M1[F5][F5]
// Reply, Module has 4 relay ports
< [F2][04][F3]RRLYPOS[F4]M1|P01:0|P02:0|P03:1|P04:L[F5][F5]
// Port 1 and 2 = Relay open on power on
// Port 3 = Relay closed on power on
// Port 4 = Resume last relay state on power on

// Query the power on state of relays in CF Mini on CFLink ID [06]
> [F2][06][F3]QRLYPOS[F4][F5][F5]
// Reply, CF Mini has 4 relay ports
< [F2][06][F3]RRLYPOS[F4]P01:0|P02:0|P03:1|P04:L[F5][F5]
// Port 1 and 2 = Relay open on power on
// Port 3 = Relay closed on power on
// Port 4 = Resume last relay state on power on

</sxh>

=== Error ===

  * 004 = Invalid Module Number

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

==== POS - Configure Power On States ====

The POS (Power On State) command is used to configure the power on state of all relays in one or more modules/devices.\\
This determines the state a relay will be set to when the device starts up (eg. after a power failure, restart, etc).\\
If some relay port configurations are to remain unchanged, simply omit them from the message.

=== Data ===
<sxh cflink; light: true>

// Modular devices
> [F2]<ID>[F3]CRLYPOS[F4]<MODULE>|<RELAYSTATES>[F5][F5]
// Standalone devices
> [F2]<ID>[F3]CRLYPOS[F4]<RELAYSTATES>[F5][F5]

</sxh>

  * **<RELAYSTATES>** = Any relay port in the module/device that needs to be configured must be entered in ''P##:<STATE>'' format. Multiple relays can be configured in a single command by using the Port Separator ''| ''(Pipe character)
    * **<STATE>** = Single character:
      * ''0'' = Relay open on power on (Default)
      * ''1'' = Relay closed on power on
      * ''L'' = Resume last state on power on
=== Reply ===

The changes take affect immediately. See the POS Query Reply for more details.

=== Example ===
<sxh cflink; light: true>

// Set relay ports 1 and 2 to be open on power up, port 3 to be unchanged and port 4 to resume last state on power up
// For module 3 in a modular device on CFLink ID [05]
> [F2][05][F3]CRLYPOS[F4]M3|P01:0|P02:0|P04:L[F5][F5]
// Reply (relay port 3 was previously set to open on power up, default behavior)
< [F2][05][F3]RRLYPOS[F4]M3|P01:0|P02:0|P03:0|P04:L[F5][F5]

// Set relay ports 1 and 2 to be closed on power up, port 3 to be open on power up and port 4 to resume last state on power up
// For both modules 1 and 2 in a modular device on CFLink ID [05]
> [F2][05][F3]CRLYPOS[F4]M1|P01:1|P02:1|P03:0|P04:L,M2|P01:0|P02:0|P03:1|P04:L[F5][F5]
// Reply
< [F2][05][F3]RRLYPOS[F4]M1|P01:1|P02:1|P03:0|P04:L[F5][F5]
< [F2][05][F3]RRLYPOS[F4]M2|P01:1|P02:1|P03:0|P04:L[F5][F5]

// Set relay ports 1 and 2 to be open on power up, port 3 to be unchanged and port 4 to resume last state on power up
// For CF Mini on CFLink ID [06]
> [F2][06][F3]CRLYPOS[F4]P01:0|P02:0|P04:L[F5][F5]
// Reply (relay port 3 was previously set to open on power on, default behavior)
< [F2][06][F3]RRLYPOS[F4]P01:0|P02:0|P03:0|P04:L[F5][F5]
</sxh>

=== Error ===

  * 003 = Invalid Port Number
  * 004 = Invalid Module Number
  * 401 = Invalid Relay Power On State

==== TGT - Configure Notification Targets ====

The ''TGT'' (Target) command is a Common Command used across all CFLink devices.
For relay modules, this command will configure where ''STA'' (Status) notifications are sent.

The ''STA'' notification can be sent from a relay under the following circumstances:

  - Physical 'test' switch on the modular base unit is pressed.
  - A SET command is issued, including a second notification for Pulse commands.

=== Data ===
<sxh cflink; light: true>

> [F2]<ID>[F3]CRLYTGT[F4]<ID1>:<ID2>:<ID3>:<ID4>:<ID5>[F5][F5]

</sxh>

See the ''TGT'' [[hardware:cflink:common-device-protocol##tgt-configure-notification-targets|common command]] for more information.

=== Reply ===

<sxh cflink; light: true>
< [F2]<ID>[F3]RRLYTGT[F4]<ID1>:<ID2>:<ID3>:<ID4>:<ID5>[F5][F5]
</sxh>

See the ''TGT'' [[hardware:cflink:common-device-protocol##tgt-configure-notification-targets|common command]] for more information.

===== Transmission Messages =====

==== SET - Set Relay States ====

The ''SET'' command is used to set the state (open or closed) of relay ports across one or more modules/devices.

=== Data ===
<sxh cflink; light: true>

// Modular devices
> [F2]<ID>[F3]TRLYSET[F4]<MODULE>|<RELAYDATA>[F5][F5]
// Standalone devices
> [F2]<ID>[F3]TRLYSET[F4]<RELAYDATA>[F5][F5]

</sxh>

  * **<MODULE>** = The module number to change the state of. 2 chars, uppercase 'M' followed by the module number.
    * eg. ''M1'' = Module 1, ''M4'' = Module 4.
  * **<RELAYDATA>** = For each relay port in the command, the port state is written in ''P##:<STATE>'' format. Multiple relays can be changed in a single command by using the [[hardware:cflink:cflink-introduction#port-separator|Port Separator]] ''|''
    * **<STATE>** = Single character:
      * ''0'' = Open relay
      * ''1'' = Close relay.
      * ''T'' = Toggle relay state. If relay was closed, it will open. If relay was open, it will close.
      * ''P'' = Pulse relay. This requires a third parameter to the message: ''P##:P:<TIME>''.
        * **<TIME>** = The time to pulse, 00000 - 99999, 100ms resolution.
          * 00010 = Pulse for 1 second
          * 00600 = Pulse for 1 minute
          * 36000 = Pulse for 1 hour

^NOTE: ANY SET COMMAND SENT TO A PORT THAT IS IN THE MIDDLE OF A PULSE ACTION WILL CANCEL THE PULSE ACTION AND OVERRIDE THE RELAY STATE IMMEDIATELY.^


=== Reply ===
<sxh cflink; light: true>

// Modular device
< [F2]<ID>[F3]RRLYSTA[F4]<MODULE>|<RELAYDATA>[F5][F5]
// Standalone device
< [F2]<ID>[F3]RRLYSTA[F4]<RELAYDATA>[F5][F5]

</sxh>

Note that the reply data will contain relay data for port in the module/device.\\
\\
''STA'' replies can be configured for notification targeting using the ''TGT'' command.\\
All replies will be sent back to the sender, as well as any configured notification targets.\\
In the case of a pulse command, there will be two status replies sent, one for when the relay is closed, and one for when it is opened at the end of the pulse.

=== Example ===
<sxh cflink; light: true>

// Set all relays closed in module 1, and open relays 1 and 2 in module 2.
// Modular device is a DIN-MOD4 on CFLink ID [04].
> [F2][04][F3]TRLYSET[F4]M1|PZZ:1,M2|P01:0|P02:0[F5][F5]
// Reply from DIN-MOD4, if it has 3 relay modules installed in modules 1, 2 and 4.
// Module 1 is a relay module with 2 relay ports. Module 2 and 4 are relay modules with 4 relay ports.
< [F2][04][F3]RRLYSTA[F4]M1|P01:1|P02:1,M2|P01:0|P02:0|P03:1|P04:1,M4|P01:0|P02:0|P03:0|P04:0[F5][F5]

// Pulse relay 3 in module 4 for 1 second.
> [F2][04][F3]TRLYSET[F4]M4|P03:P:00010[F5][F5]
// Reply
< [F2][04][F3]RRLYSTA[F4]M1|P01:1|P02:1,M2|P01:0|P02:0|P03:1|P04:1,M4|P01:0|P02:0|P03:0|P04:1[F5][F5]
// Reply sent out 1 second later (note change to module 4, port 4)
< [F2][04][F3]RRLYSTA[F4]M1|P01:1|P02:1,M2|P01:0|P02:0|P03:1|P04:1,M4|P01:0|P02:0|P03:0|P04:0[F5][F5]

// Set relays 1 and 2 closed in a CF Mini on CFLink ID [06]
> [F2][06][F3]TRLYSET[F4]P01:1|P02:1[F5][F5]
// Reply from CF Mini - reply contains status of all relays ports on the device.
< [F2][06][F3]RRLYSTA[F4]P01:1|P02:1|P03:0|P04:0[F5][F5]

</sxh>

=== Error ===

  * 003 = Invalid Port Number
  * 004 = Invalid Module Number
  * 402 = Invalid Relay State