====== Common Device Protocol ======

The following CFLink protocol messages are common to all CFLink devices.

===== Queries =====

==== WHO - Device discovery ====

The ''WHO'' query is used to discover what device is at a specific address. The reply is different depending what device is discovered.\\
Details on the exact replies can be found in the documentation for each specific device if it differs from below (extra parameters are replied by some devices such as modular base units and Ethernet devices).\\
\\
The ''WHO'' reply will be automatically broadcast to the CFLink network when a device is powered up or reset. It will also be sent to any notification targets configured via the TGT command.\\

=== Data ===

The ''WHO'' query does not have any associated data.\\

=== Reply ===

The specific data that is replied is unique to each device. See the documentation for each devices specific for more details.\\
If no device is at a particular ID, there will be no reply.\\
\\
At a minimum, the device will reply with its product code, serial number, application version and CFLink version.
<sxh cflink; light: true>
> [F2]<ID>[F3]R<DEVICE>WHO[F4]<PRODUCTCODE>:<SERIAL#>:<APP_VER>:<CFLINK_VER>:<DATA>[F5][F5]
</sxh>

== Example ==
<sxh cflink; light: true>
// Request the details for the device at CFLink ID [03]
> [F2][03][F3]QCFXWHO[F4][F5][F5]
// The Reply if the unit was a LAN Bridge would be as follows
< [F2][03][F3]RLANWHO[F4]LANBridge:192.168.0.100:00.04.A3.19.D5.70:1.0.0.0:1.0.0.0[F5][F5]
</sxh>

==== TGT - Query Notification Targets ====

The ''TGT'' (Target) query is used to return a the notification target configuration.\\
\\
=== Data ===

The ''TGT'' query does not have any associated data. Instead, the <DEVICE> name used as part of the query determines which notifications to return the configuration for.\\
<sxh cflink; light: true>
> [F2]<ID>[F3]Q<DEVICE>TFT[F4][F5][F5]
</sxh>
== Reply ==
<sxh cflink; light: true>
< [F2]<ID>[F3]R<DEVICE>TGT[F4]<ID1>:<ID2>:<ID3>:<ID4>:<ID5>[F5][F5]
</sxh>

  * **<ID>** = The CFLink ID of the unit retrieving configured notifications from. Single byte.
  * **<DEVICE>** = The device name the notifications are for. Examples including (but not limited to):
    * ''IOX'' is for IO port notifications (modules or onboard IO ports).
    * ''RLY'' is for relay port notifications (modules or onboard relay ports).
    * ''COM'' is for serial port read notifications (modules only).
    * ''MOD'' is for on-board serial port read notifications and on-board dry contact input notifications from a modular base unit.
    * ''MIN'' is for on-board serial port read notifications from a CFMini.
    * ''SWX'' is for Dry Contact Input notifications from a SW16.
    * ''LAN'' is for on-board serial port read notifications from a LAN Bridge.
    * ''IRB'' is for IR receive notifications from an IRBlaster.
  * **<ID1> - <ID5>** = The CFLink ID of a device on the CFLink bus that notification messages will be sent to. In plain text format, 2 chars (A-F, 0-9).
The same ID cannot exist twice in the one command.\\
None of these ID's can be the same as the ID of the unit being configured (ie. no infinite loops!)\\

== Example ==
<sxh cflink; light: true>
// Retreive the notification settings for all IO modules in a MOD4 on CFLink ID [04]
> [F2][04][F3]QIOXTGT[F4][F5][F5]
// Reply, notification config for any IO modules in the MOD4
< [F2][04][F3]RIOXTGT[F4]07:2C:0D:00:00[F5][F5]
// Retreive the notification settings for the on-board serial port of a CFMini on CFLink ID [05]
> [F2][05][F3]QMINTGT[F4][F5][F5]
// Reply
< [F2][05][F3]RMINTGT[F4]07:2C:0D:00:00[F5][F5]
// Retreive the notification settings for the on-board serial port and dry contact input of a MOD4 on CFLink ID [03]
> [F2][03][F3]QMODTGT[F4][F5][F5]
// Reply
< [F2][03][F3]RMODTGT[F4]04:05:06:07:08[F5][F5]
</sxh>

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

==== DID - Change the Device ID ====

The ''DID'' (Device ID) command is used to set the CFLink ID of a specific device.

=== Data ===

The data for the ''DID'' command is formatted as follows:
<sxh cflink; light: true>
> [F2]<ID>[F3]CCFXDID[F4]<NEWID>:<SERIALNUM>[F5][F5]
</sxh>

  * **<NEWID>** = The new CFLink ID to assign to the device, in plain text (2 bytes).
  * **<SERIALNUM>** [optional] = The serial number of the device to set the ID for. The serial number is used to ensure that only a single device in the network is affected. Otherwise if there is an ID conflict where multiple devices are on the same ID, all the conflicting devices would change to the **<NEWID>**.

=== Reply ===

The ''DID'' configuration takes affect immediately, and the reply will come from the **<NEWID>** with the **<OLDID>** as data.\\
If the ''DID'' configuration message included the optional **<SERIALNUM>** parameter, then the reply will also include the serial number.\\
<sxh cflink; light: true>
< [F2]<NEWID>[F3]R<DEVICE>DID[F4]<OLDID>[F5][F5]
< [F2]<NEWID>[F3]R<DEVICE>DID[F4]<OLDID>:<SERIALNUM>[F5][F5]
</sxh>

== Example ==
<sxh cflink; light: true>
// Change the ID of a LAN Bridge from [03] to [04]
> [F2][03][F3]CCFXDID[F4]04[F5][F5]
// Reply (note the ID change takes affect immediately)
< [F2][04][F3]RLANDID[F4]03[F5][F5]
// Change the ID of an IR Blaster from [04] to [05], where the device serial number is 00000132
> [F2][04][F3]CIRBDID[F4]05:00000132[F5][F5]
// Reply (note the new ID takes affect immediately)
< [F2][05][F3]RIRBDID[F4]04:00000132[F5][F5]
</sxh>

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

The ''TGT'' (Target) command is used to configure notification targets for any self reporting messages a device can send out.\\
These messages are different for each device, so please see each device's documentation for information on exactly what messages are self reporting.\\

=== Data ===
<sxh cflink; light: true>
> [F2]<ID>[F3]C<DEVICE>TGT[F4]<ID1>:<ID2>:<ID3>:<ID4>:<ID5>[F5][F5]
</sxh>

  * **<ID>** = The CFLink ID of the unit configuring notification for. Single byte.
  * **<DEVICE>** = The device name sending the notifications. Examples including (but not limited to):
    * For a complete list of the device types that can be set up for notification targets, please see the notification targets documentation.
  * **<ID1> - <ID5>** = Parameters for the CFLink ID of a device that notification messages will be sent to. In plain text format, 2 chars (A-F, 0-9).
    * The same ID cannot exist twice in the one command.
    * None of these ID's can be the same as the ID of the unit being configured (ie. no infinite loops!).
    * You can specify the Broadcast CFLink ID ''FF'' as one of the ID's to have notifications sent to every device on the CFLink bus. But notifications are not guaranteed to arrive at every device, so we recommend only using them for non-critical data.
  * Use ''00'' to clear any ID parameter. So for example if you have all 5 ID's set from a previous configuration command, and now you want to only use 4 of them, use ''00'' to clear the one CFLink ID param that no longer needs to receive notifications.
  * Use the No Change Option ''XX'' to leave a specific ID parameter unchanged.

== Reply ==
<sxh cflink; light: true>
< [F2]<ID>[F3]R<DEVICE>TGT[F4]<ID1>:<ID2>:<ID3>:<ID4>:<ID5>[F5][F5]
</sxh>

== Example ==
<sxh cflink; light: true>
// Configure the notification targets for the status command of IO modules in a MOD4 on CFLink ID [04]
// Notifications for this command should be sent to IDs [05], [06] and [07] (without changing the last two ID's if previously configured)
> [F2][04][F3]CIOXTGT[F4]05:06:07:XX:XX[F5][F5]
// Reply (if the 4th and 5th <ID> param had not previously been set)
< [F2][04][F3]RIOXTGT[F4]05:06:07:00:00[F5][F5]

// Configure the notification targets for on-board serial port of a LAN Bridge on CFLink ID [04]
// Notifications for this command should be sent to IDs [07], [2C] and [0D] only (disabling the last two ID's if previously configured)
> [F2][04][F3]CLANTGT[F4]07:2C:0D:00:00[F5][F5]
// Reply
< [F2][04][F3]RLANTGT[F4]07:2C:0D:00:00[F5][F5]
</sxh>

== Error ==

  * 004 = Invalid Module Number
  * 006 = Invalid ''TGT'' CFLink ID
  * 007 = Duplicate ''TGT'' CFLink ID Defined

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

==== RST - Reset ====

The ''RST'' (Reset) command is used to reset a specific device based on its CFLink ID.

=== Data ===

The ''RST'' command does not have any associated data.
<sxh cflink; light: true>
> [F2]<ID>[F3]TCFXRST[F4][F5][F5]
</sxh>

=== Reply ===

The ''RST'' command will not get a reply. Instead the device will announce itself as soon as it has finished resetting.

== Example ==
<sxh cflink; light: true>
// Reset device on ID [05]
> [F2][05][F3]TCFXRST[F4][F5][F5]
// After the device has reset and is operational again, it will announce itself with a WHO reply.
< [F2][05][F3]R<DEVICE>WHO[F4]<DATA>[F5][F5]
</sxh>

===== Notifications =====

==== LDR - Boot Loader Notification ====

The ''LDR'' (Loader) notification is sent as a broadcast to the CFLink bus as soon as the device has powered up, but before it has loaded the application firmware.\\
If the application firmware is verified OK, then it will continue to load the application firmware.\\
Otherwise it will remain in bootloader state, waiting for a new firmware upload.\\

=== Data ===
<sxh cflink; light: true>
> [F2]<ID>[F3]RCFXLDR[F4]<PRODUCT>:<FIRMWARE_STATE>:<BOOTVERSION>[F5][F5]
</sxh>

  * **<PRODUCT>** = The product code for the device.
  * **<FIRMWARE_STATE>** = ''App_OK'' if application firmware is verified. ''App_Err'' if the application firmware failed verification.
  * **<BOOTVERSION>** = The version number for the bootloader. Version numbers are from range ''0.0.0'' to ''999.999.999''.
    * First digit represents major release version
    * Second digit represets minor release version (new feature or change)
    * Third digit represents build number, generally incremented when testing internally before public release, for bug fixes, etc.

== Example ==
<sxh cflink; light: true>
// LAN Bridge powerup notification, on CFLink ID [04]
> [F2][04][F3]RCFXLDR[F4]LANBridge:App_OK:1.0.1[F5][F5]

// DIN-MOD4 powerup notification, on CFLink ID [05], app firmware is missing.
> [F2][04][F3]RCFXLDR[F4]DIN-MOD4:App_Err:1.0.4[F5][F5]
</sxh>