All GC frames consist of two parts:
Offset | Label | Description |
00 | Source | Frame Header |
01 | Source Channel | |
02 | Destination | |
03 | Destination Channel | |
04 | Data length | |
05 | ||
06 | Frame Type | |
07 | Reserved | |
08 ... | Data | Frame Body |
(x) | Padding (0 to 3 bytes) |
Description of Fields:
Source (one byte)
This field identifies the originator of the GC frame. Individual
frames have specific valid sources. (Please see
Source/Destination specification for details. )
Source channel (one byte)
This field further defines the source. For example, if the
source is a "client," the source channel field will specify the
"Client ID." Similarly, if the source is an expansion module
channel, the source channel field will specify the "Channel ID."
(Values are defined in the specific frame sections.)
Destination (one byte)
This field identifies the destination of the GC frame.
Individual frames have specific valid destinations. (Please see
Source/Destination specification for details. )
Destination channel (one byte)
Like the source channel byte, this byte value further defines
the destination. (Values are defined in the specific frame
sections.)
Data length (two bytes)
The number of bytes of frame data that follow the header. This
is an unsigned short value. The valid values range from zero to
7168 (1c00 hex), in network byte order.
Frame type (one byte) This field identifies the frame body format. There are seven types of GC frames:
Reserved (one byte)
This field is reserved for future use.
Offset | Label | Description | Section |
00 | Frame Type = FT_CMD | See above | GC Frame Header |
... | |||
07 | |||
08 | Command Id | Command Header | GC Frame Body |
09 | Context | ||
10 | Reserved | ||
11 | |||
12 | [fields vary by command] | Command Data | |
... | |||
(x) | Padding (0 to 3 bytes) | Padding |
Command ID (1 byte)
Identifies the command to be executed at the destination.
Command context (1 byte)
The source-specified data that will be returned with the
response to this command. This data field is optional and does
not modify the command in any way. Clients can use this field to
uniquely identify responses to specific commands.
Reserved (2 bytes)
These bytes are reserved for future use.
Command data ( (msglen - 4) bytes)
This data is command-specific; please see Commands for further information.
Padding (0-3 bytes)
Frame is padded, if required, to ensure that the data ends on a
32-bit boundary.
Offset | Label | Description | Section |
00 | Frame Type = FT_RESP | See above | GC Frame Header |
... | |||
07 | |||
08 |
Command Header (same as in original command) | Response Header | GC Frame Body |
09 | |||
10 | |||
11 | |||
12 | Return Code | ||
13 | |||
14 | |||
15 | |||
16 | [fields are command-specific] | Response Data | |
... | |||
(x) | Padding (0 to 3 bytes) | Padding |
Command Header (4 bytes)
This is identical to the Command Header from the command which
elicited this response.
Return code (4 bytes)
A four-byte value that indicates the result of the command
execution.
Please see command specific
documentation for return codes for a particular command.
Response data ((msglen - 8) bytes)
Response data returned by a command
Please see command specific
documentation for response data for a particular command.
Padding (0-3 bytes)
Used to end the data section on a 32-bit boundary.
GC Frame Header | GC Frame Body | |||||
Frame Type = FT_EVENT | Event-Frame Header | Event-Frame Data | ||||
Event ID | Event Context | Reserved | Timestamp | Data | Padding | |
1 byte | 1 byte | 2 bytes | 4 bytes | n bytes | 0-3 bytes |
Event Header Event ID (1 byte)
Identifies the event being reported.
Event context (1 byte)
(Dependent on the source of the event.)
Reserved (2 bytes)
(Field reserved for future definition by Dearborn Group, Inc.)
Timestamp (4 bytes)
Indicates the time an event occurred.
Timestamp is in units of 10 microseconds.
Event data ((msglen - 8) bytes)
Data specific to the event.
Please see Generic Events and
Hardware-specific details
for event definitions. Padding (0-3 bytes)
Frame is padded, if required, to ensure that the data ends on a
32-bit boundary.
The uses Data frames to inform the connected clients of new messages from network channels it is attached to, or any other channels it supports. Clients also use Data frames to transmit messages over network channels. A response is not required when a client sends a Data frame to a network channel; the message contained therein is transmitted quietly on the appropriate channel. Alternately, a CMD_CARD_TX can be used if Response Frames are desired.
The actual contents of a network message is divided into three sections:
Offset | Label | Description | Section |
00 | Frame Type = FT_DATA | See above | GC Frame Header |
... | |||
07 | |||
08 | Header Length | Data Header | GC Frame Body |
09 | Header Bits | ||
10 | Data Length | ||
11 | |||
12 | Extra Length | ||
13 | Mode | ||
14 | Priority | ||
15 | Status | ||
16 | Timestamp | ||
17 | |||
18 | |||
19 | |||
20 | Context | ||
21 | Reserved Char | ||
22 | Reserved Short | ||
23 | |||
24 | Header Bytes | Data | |
... | |||
(x) | Data Bytes | ||
... | |||
(y) | Extra Bytes | ||
... | |||
(z) | Padding (0 to 3 bytes) | Padding |
Header Length (1 byte)
This field specifies the length in bytes of the header segment
of the message.
Header Bits (1 byte)
This field specifies the length in bits of the actual header for
cases where the number of bits in the header is not an even
multiple of eight (such as is the case for CAN, with 11 and 29
bit headers).
Data Length (2 bytes)
This field specifies the length in bytes of the data segment of
the message.
Extra Length (1 byte)
This field specifies the length in bytes of the extra
information segment of the message.
Mode (1 byte)
This field contains the following flags:
Priority (1 byte)
Not currently used- should be treated as a reserved byte.
Stat (1 byte)
This field contains network-specific flags and status
information.
See network specific information
for details.
Timestamp (4 bytes)
This field contains a 4-byte timestamp for the data message.
This is the time at which the last byte of the message arrived.
This timestamp is in units of 10 microseconds.
Context (1 byte)
This field is not currently used- should be treated as a
reserved byte.
Reserved (3 bytes)
These bytes are not currently used. They should be set to zero.
Message (Header Length + Data Length + Extra Length)
These bytes contain the actual message header, data and extra
information.
Padding (0-3 bytes)
These bytes are used to pad the entire GC frame to an even
multiple of 4 bytes.
When a GC frame is marked as a Signal frame (frame type = FT_SIG), the frame body contains one or more signals in the format described below.
The uses Signal frames to inform the connected clients of new signals contained in messages from network channels it is attached to, or any other channels it supports. A response is not required when a client receives a Signal frame from the . Frames of this type have a variable message body length:
Offset | Label | Description | Section | |
00 | Frame Type=FT_SIG | See Above | GC Frame Header | |
... | ||||
07 | ||||
08 | Timestamp | Copied from Timestamp in the FT_DATA frame |
Signal Header |
GC Frame Body |
09 | ||||
10 | ||||
11 | ||||
12 | Mode | Copied from Mode in the FT_DATA frame |
||
13 | Request Index | Signal Index in response from CMD_CNVT_REQ_VALUES |
||
14 | Number of Signals | |||
15 | Reserved Char | |||
16 | First Flag | Value type | Signals | |
17 | First Index | Index from CMD_CNVT_REQ_VALUES |
||
18 | First Value | Integer, float, null terminated string |
||
... | ||||
(x) | ||||
(x+1) | Intermediate flags, indexes & values |
|||
... | ||||
(y) | ||||
(y+1) | Last Flag | Value type | ||
(y+2) | Last Index | Index from CMD_CNVT_REQ_VALUES |
||
(y+3) | Last Value | Integer, float, null terminated string |
||
... | ||||
(z) | ||||
(z+1) | Padding (0 to 3 bytes) | Padding |
Request Index (1 byte)
This field specifies the Signal Request Index returned by the
requesting
CMD_CNVT_REQ_VALUES command.
Number of Signals (1 byte)
This field specifies the number of signals present in the message. It
may be between 1 and the number of signals present in the requesting
CMD_CNVT_REQ_VALUES command.
Flag(s) (1 byte each)
This field is present for each signal in the message. It is used to
inform the recipient of the signal's format. One or more of the bits
defined below may be set. If two or more bits are set, the signal's
values are present in the order of the least significant bit (0) to the
most significant bit (8).
Index(es) (1 byte each)
This field specifies the index of the signal in reference to the
signal list in the requesting
CMD_CNVT_REQ_VALUES command. The first signal's index is zero.
Not all signals (and their indexes) are required to be present.
Index numbers may not be ordered.
Frames of the type FT_MISC may be used to transfer any data between a specified source and destination. Frames of this type have an arbitrary message body format:
Offset | Label | Description | Section |
00 | Frame Type=FT_MISC | See Above | GC Frame Header |
... | |||
07 | |||
08 | Data (Arbitrary) | Data Header | GC Frame Body |
... | |||
... | |||
... | |||
... | |||
... | |||
(x+1) | Padding (0 to 3 bytes) | Padding |
A frame of this type is similar to a FT_MISC frame, but its message body is a null-terminated ASCII string, allowing clients to specify how user-related messages should be displayed (e.g., in a pop-up dialog box or a separate log window):
Offset | Label | Description | Section |
00 | Frame Type=FT_TEXT | See Above | GC Frame Header |
... | |||
07 | |||
08 | Text | Data Header | GC Frame Body |
... | |||
... | |||
... | |||
... | |||
... | |||
X | Padding (0 to 3 bytes) | Padding |
FT_MISC, FT_EVENT, or FT_TEXT frames may utilize the special
destination channel CH_BROADCAST
, which indicates a
broadcast. Any such "broadcastable" messages sent to this
destination channel will be forwarded to all clients that have
their broadcast flags set.
Broadcast Flags Clients' broadcast flag settings are by default cleared, to prevent broadcasts from reaching destinations like the scheduler or responder. Two commands support the enabling and disabling broadcast reception, respectively:
EXAMPLE:
A broadcast event's frame header might look something like
this:
src= sd_client
srcchan = my_client_id
dst = sd_client
dstchan = CH_BROADCAST (= 0xff)
frametype = FT_EVENT
(etc.)