User Tools
hardware:cflink:cflink-introduction
Differences
This shows you the differences between two versions of the page.
|
hardware:cflink:cflink-introduction [2012/08/10 04:18] aaron [CFLink Protocol Introduction] |
hardware:cflink:cflink-introduction [2014/02/20 11:57] (current) jarrod [Commands and Replies] |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== CFLink Protocol Introduction ====== | ====== CFLink Protocol Introduction ====== | ||
| This document is an overall view of the CFLink Protocol, used by CommandFusion hardware.\\ | This document is an overall view of the CFLink Protocol, used by CommandFusion hardware.\\ | ||
| - | CFLink is a RS485 5-wire bus, used to interconnect various CommandFusion devices. For more details on the physical bus characteristics, please see the [[hardware:cflink:cflink-bus|CFLink Bus documentation]].\\ | + | CFLink is an RS485 5-wire bus, used to interconnect various CommandFusion devices. For more details on the physical bus characteristics, please see the [[hardware:cflink:cflink-bus|CFLink Bus documentation]].\\ |
| ===== Basic Structure ===== | ===== Basic Structure ===== | ||
| Line 12: | Line 12: | ||
| The basic structure of all messages on the CFLink bus is as follows: | The basic structure of all messages on the CFLink bus is as follows: | ||
| - | <code> | + | <sxh cflink; light: true> |
| // Basic message format | // Basic message format | ||
| > [F2]<ID>[F3]<COMMAND>[F4]<DATA>[F5][F5] | > [F2]<ID>[F3]<COMMAND>[F4]<DATA>[F5][F5] | ||
| - | </code> | + | </sxh> |
| All messages start with ''[F2]'' followed by a single ID byte representing the target (or source in the case of replies) device on the bus.\\ | All messages start with ''[F2]'' followed by a single ID byte representing the target (or source in the case of replies) device on the bus.\\ | ||
| Line 21: | Line 21: | ||
| Then an ''[F4]'' byte, followed by optional Data associated with the command. The Data can be empty if the command does not require any associated data.\\ | Then an ''[F4]'' byte, followed by optional Data associated with the command. The Data can be empty if the command does not require any associated data.\\ | ||
| Finally, all messages are terminated with two ''[F5]'' bytes.\\ | Finally, all messages are terminated with two ''[F5]'' bytes.\\ | ||
| - | \\ | + | |
| - | **NOTE: THROUGHOUT THIS DOCUMENTATION, ALL CFLINK EXAMPLES WILL START WITH > OR < - THIS IS NOT PART OF THE COMMAND, BUT JUST USED TO SIGNIFY THE START OF A NEW SENT OR RECEIVED PACKET.** | + | <WRAP center round important 80%> |
| + | **NOTE: THROUGHOUT THIS DOCUMENTATION, ALL CFLINK EXAMPLES WILL START WITH ''>'' (greater than) OR ''<'' (less than) - THIS IS NOT PART OF THE COMMAND, BUT JUST USED TO SIGNIFY THE START OF A NEW SENT OR RECEIVED PACKET WITHIN THE DOCUMENTATION.** | ||
| + | </WRAP> | ||
| ===== CFLink ID ===== | ===== CFLink ID ===== | ||
| Line 33: | Line 35: | ||
| In some circumstances, you may want to send a broadcast to all devices on the network. This can be done by using the Broadcast ID: ''[FF]''. | In some circumstances, you may want to send a broadcast to all devices on the network. This can be done by using the Broadcast ID: ''[FF]''. | ||
| + | <WRAP center round important 80%> | ||
| **NOTE: BROADCAST MESSAGES CANNOT BE GUARANTEED TO BE DELIVERED TO ALL DEVICES ON LARGE NETWORKS. BROADCASTING IS ONLY RECOMMENDED FOR NON-CRITICAL MESSAGES.** | **NOTE: BROADCAST MESSAGES CANNOT BE GUARANTEED TO BE DELIVERED TO ALL DEVICES ON LARGE NETWORKS. BROADCASTING IS ONLY RECOMMENDED FOR NON-CRITICAL MESSAGES.** | ||
| + | </WRAP> | ||
| ===== Commands and Replies ===== | ===== Commands and Replies ===== | ||
| - | The <COMMAND> part of each message is always 7 characters, always upper case, and formatted as follows: ''<TYPE><DEVICE><COMMAND_NAME>''\\ | + | The **<COMMAND>** part of each message is always 7 characters, always upper case, and formatted as follows: ''<TYPE><DEVICE><COMMAND_NAME>''\\ |
| - | + | ||
| - | * <TYPE> = 1 char, types are documented below.\\ | + | |
| - | * <DEVICE> = 3 chars representing the model name of the device or type of port we are targeting (or the device/port type that the reply came from).\\ | + | |
| - | * The <DEVICE> name ''CFX'' can be used to target any device. It is useful for when you are sending a command that any device should respond to, ''WHO'' for example.\\ | + | |
| - | * <COMMAND_NAME> = 3 chars representing the name of the actual command being performed. | + | |
| + | * **<TYPE>** = 1 char, types are documented below.\\ | ||
| + | * **<DEVICE>** = 3 chars representing the model name of the device or type of port we are targeting (or the device/port type that the reply came from).\\ | ||
| + | * The **<DEVICE>** name ''CFX'' can be used to target any device. It is very useful for when you are sending a command that any device should respond to, ''WHO'' for example.\\ It is also useful when you don't need to know the exact device type receiving the command, such as for [[hardware:cflink:on-board-rs232-port-protocol|on-board COM ports]] which share a common protocol across all devices.\\ However, all //replies/notifications// will be sent with the correct 3 character device identifier for the device sending the data (''CFX'' is never used in replies except from bootloader notifications). | ||
| + | * **<COMMAND_NAME>** = 3 chars representing the name of the actual command being performed. | ||
| ==== Queries ==== | ==== Queries ==== | ||
| - | Query messages begin with <TYPE> character ''Q''. These messages are used to retrieve the configuration details or state of a specific device property.\\ | + | Query messages begin with **<TYPE>** character ''Q''. These messages are used to retrieve the configuration details or state of a specific device property.\\ |
| \\ | \\ | ||
| A query will always get a reply, unless the target device could not be found (CFLink ID does not exist on the bus).\\ | A query will always get a reply, unless the target device could not be found (CFLink ID does not exist on the bus).\\ | ||
| - | If the query was successful, the reply would contain the same <COMMAND_NAME> along with the <DATA> associated with the query.\\ | + | If the query was successful, the reply would contain the same **<COMMAND_NAME>** along with the **<DATA>** associated with the query.\\ |
| \\ | \\ | ||
| If there was an error in the query, the reply would be an Error Reply with details of why the error occurred. | If there was an error in the query, the reply would be an Error Reply with details of why the error occurred. | ||
| Line 54: | Line 56: | ||
| ==== Configuration ==== | ==== Configuration ==== | ||
| - | Configuration messages begin with <TYPE> character ''C''. These messages are used to manipulate the configuration settings of a device.\\ | + | Configuration messages begin with **<TYPE>** character ''C''. These messages are used to manipulate the configuration settings of a device.\\ |
| \\ | \\ | ||
| A configuration message will always get a reply, unless the target device could not be found (CFLink ID does not exist on the bus).\\ | A configuration message will always get a reply, unless the target device could not be found (CFLink ID does not exist on the bus).\\ | ||
| Line 63: | Line 65: | ||
| - The configuration property requires a reboot of the device to take affect. | - The configuration property requires a reboot of the device to take affect. | ||
| - | If the configuration change requires a reboot (ie. changing the DHCP mode for a LANBridge), the reply to the configuration message will contain the current configuration data.\\ | + | If the configuration change requires a reboot (ie. changing the DHCP mode for a LAN Bridge), the reply to the configuration message will contain the current configuration data.\\ |
| The new configuration data will only be available after rebooting the device.\\ | The new configuration data will only be available after rebooting the device.\\ | ||
| If the configuration change is instant (ie. changing the CFLink ID of a device), the reply will contain the new configuration data.\\ | If the configuration change is instant (ie. changing the CFLink ID of a device), the reply will contain the new configuration data.\\ | ||
| Line 71: | Line 73: | ||
| ==== Transmission ==== | ==== Transmission ==== | ||
| - | Transmission messages begin with <TYPE> character ''T''. These messages are used to tell the device to perform an action, such as set a relay state or send data out a serial port.\\ | + | Transmission messages begin with **<TYPE>** character ''T''. These messages are used to tell the device to perform an action, such as set a relay state or send data out a serial port.\\ |
| \\ | \\ | ||
| A transmission message will always get a reply, unless the target device could not be found (CFLink ID does not exist on the bus). | A transmission message will always get a reply, unless the target device could not be found (CFLink ID does not exist on the bus). | ||
| - | Most replies will simply echo the <COMMAND_NAME> along with any <DATA> from the transmission message.\\ | + | Most replies will simply echo the **<COMMAND_NAME>** along with any **<DATA>** from the transmission message.\\ |
| - | But some replies will not include the <DATA> in order to reduce flooding of the network. These replies are from commands such as sending RS232 data or sending IR hex data, both of which can be quite long.\\ | + | But some replies will not include the **<DATA>** in order to reduce flooding of the network. These replies are from commands such as sending RS232 data or sending IR hex data, both of which can be quite long.\\ |
| \\ | \\ | ||
| If the was an error in the transmission message, the reply would be an Error Reply with details of why the error occurred. | If the was an error in the transmission message, the reply would be an Error Reply with details of why the error occurred. | ||
| Line 81: | Line 83: | ||
| ==== Replies ==== | ==== Replies ==== | ||
| - | Reply messages begin with <TYPE> character ''R''. Replies are always initiated by the device, in response to any of the other command types.\\ | + | Reply messages begin with **<TYPE>** character ''R''. Replies are always initiated by the device, in response to any of the other command types.\\ |
| - | Generally the reply will contain the <DEVICE> name for the device sending the reply, along with echoing the <COMMAND_NAME>.\\ | + | Generally the reply will contain the **<DEVICE>** name for the device sending the reply, along with echoing the **<COMMAND_NAME>**.\\ |
| The only time a reply will not be sent is if the target CFLink ID does not exist on the CFLink bus.\\ | The only time a reply will not be sent is if the target CFLink ID does not exist on the CFLink bus.\\ | ||
| More details on the reply formatting is given in the other message type documentation above.\\ | More details on the reply formatting is given in the other message type documentation above.\\ | ||
| Line 89: | Line 91: | ||
| If there is an error in any message, the device will reply with details via an error message in the following format: | If there is an error in any message, the device will reply with details via an error message in the following format: | ||
| - | <code> | + | <sxh cflink; light: true> |
| // Error reply format example | // Error reply format example | ||
| < [F2]<ID>[F3]R<DEVICE>ERR[F4]<ERRCODE>:<SUMMARY>:<SENDERID>:<SENT_CMD>:<SENT_DATA>[F5][F5] | < [F2]<ID>[F3]R<DEVICE>ERR[F4]<ERRCODE>:<SUMMARY>:<SENDERID>:<SENT_CMD>:<SENT_DATA>[F5][F5] | ||
| - | </code> | + | </sxh> |
| - | * <ERRCODE> = 3 digits unique to each error type (000 to 999). | + | * **<ERRCODE>** = 3 digits unique to each error type (000 to 999). |
| - | * <SUMMARY> = A variable length summary in English of what the error was. | + | * **<SUMMARY>** = A variable length summary in English of what the error was. |
| - | * <SENDERID> = 2 bytes representing the ID that the incorrect command was sent from (ID shown in plain text). | + | * **<SENDERID>** = 2 bytes representing the ID that the incorrect command was sent from (ID shown in plain text). |
| - | * <SENT_CMD> = 7 chars echoing the command that was sent which caused the error. | + | * **<SENT_CMD>** = 7 chars echoing the command that was sent which caused the error. |
| - | * <SENT_DATA> = If there was any data in the command that caused the error, it will be echoed in the error reply. | + | * **<SENT_DATA>** = If there was any data in the command that caused the error, it will be echoed in the error reply. |
| ===== Data ===== | ===== Data ===== | ||
| Line 108: | Line 110: | ||
| When the protocol requires a port number to be defined, it is always written in P## format. The number must be two chars, 01-99 or ZZ.\\ | When the protocol requires a port number to be defined, it is always written in P## format. The number must be two chars, 01-99 or ZZ.\\ | ||
| ''P01'' = Port 1, ''P10'' = Port 10, etc.\\ | ''P01'' = Port 1, ''P10'' = Port 10, etc.\\ | ||
| - | ''PZZ'' = All Ports. This allows you to manipulate all ports of a single type at once. eg. Open all relays in a CFMini. | + | ''PZZ'' = All Ports. This allows you to manipulate all ports of a single type at once. eg. Open all relays in a CF Mini. |
| ==== Module Definitions ==== | ==== Module Definitions ==== | ||
| Line 135: | Line 137: | ||
| When a command or reply targets multiple ports of a device, the port data is separated by a single pipe ''|'' character.\\ | When a command or reply targets multiple ports of a device, the port data is separated by a single pipe ''|'' character.\\ | ||
| The port separator is also used to separate a Module Number from the port data.\\ | The port separator is also used to separate a Module Number from the port data.\\ | ||
| - | <code> | + | <sxh cflink; light: true> |
| // Port Separator example - Close relay port 1, open relay port 2 on a CF Mini on CFLink ID [04] | // Port Separator example - Close relay port 1, open relay port 2 on a CF Mini on CFLink ID [04] | ||
| > [F2][04][F3]TRLYSET[F4]P01:1|P02:0[F5][F5] | > [F2][04][F3]TRLYSET[F4]P01:1|P02:0[F5][F5] | ||
| - | // Port Separator example, with module number - Close relay port 1, open relay port 2 on Module 2 of a MOD4 on CFLink ID [04]> [F2][04][F3]TRLYSET[F4]M2|P01:1|P02:0[F5][F5] | + | // Port Separator example, with module number - Close relay port 1, open relay port 2 on Module 2 of a MOD4 on CFLink ID [04] |
| - | </code> | + | > [F2][04][F3]TRLYSET[F4]M2|P01:1|P02:0[F5][F5] |
| + | </sxh> | ||
| ==== Data Separator ==== | ==== Data Separator ==== | ||
| - | The data separator, '':'' (colon), is used to separate piece of data for a single target port or device.\\ | + | The data separator '':'' (colon), is used to separate pieces of data for a single target port or device.\\ |
| - | <code> | + | <sxh cflink; light: true> |
| - | // Data Separator example - Device discovery reply for a LANBridge on ID [02] | + | // Data Separator example - Device discovery reply for a LAN Bridge on ID [02] |
| < [F2][02][F3]RLANWHO[F4]LANBridge:192.168.0.100:00.04.A3.19.D5.70:1.0.0.0:1.0.0.0[F5][F5] | < [F2][02][F3]RLANWHO[F4]LANBridge:192.168.0.100:00.04.A3.19.D5.70:1.0.0.0:1.0.0.0[F5][F5] | ||
| // Note: model, IP address, MAC address, boot loader version and firmware version data are all separated by colons. | // Note: model, IP address, MAC address, boot loader version and firmware version data are all separated by colons. | ||
| - | </code> | + | </sxh> |
| ==== Module Separator ==== | ==== Module Separator ==== | ||
| - | When a command targets a modular device, it is possible to target multiple modules in one message. This is done by using the module separator, '','' (comma)\\ | + | When a command targets a modular device, it is possible to target multiple modules in one message. This is done by using the module separator '','' (comma)\\ |
| - | <code> | + | <sxh cflink; light: true> |
| // Module Separator example - Module 1, Close relay ports 1 and 2, Module 2, Open relay ports 1 and 2 | // Module Separator example - Module 1, Close relay ports 1 and 2, Module 2, Open relay ports 1 and 2 | ||
| // Within a MOD4 on CFLink ID [04] | // Within a MOD4 on CFLink ID [04] | ||
| > [F2][04][F3]TRLYSET[F4]M1|P01:1|P02:1,M2|P01:0|P02:0[F5][F5] | > [F2][04][F3]TRLYSET[F4]M1|P01:1|P02:1,M2|P01:0|P02:0[F5][F5] | ||
| // Note the comma after the module 1 data, before the module 2 data. | // Note the comma after the module 1 data, before the module 2 data. | ||
| - | </code> | + | </sxh> |
hardware/cflink/cflink-introduction.1344572309.txt.gz · Last modified: 2012/08/10 04:18 by aaron
