Gryphon Communication Protocol : Client How-To

Gryphon Communication Protocol Overview

This section outlines the interface requirements for communication with over the TCP/IP link. It defines the protocol used for client applications running on host computers. Clients will communicate with the by means of a TCP connection to port 7000. When a connection is established, the client application can initiate communication with the . During a session, the client application and the will communicate using commands, responses, and event notifications sent over the TCP/IP link. Each communication frame that is sent between the and the client over the TCP/IP link shall conform to the format specified in the following sections.

Gryphon Communication Frame Format

This section describes the Gryphon Communication (GC) frame format; it details the commands and responses sent to and from the . These commands and responses are sent in TCP/IP frames over the TCP/IP link. All fields longer than one byte are transferred in the appropriate network byte order.

All GC frames consist of two parts:


GC frame header

The frame header is made up of eight bytes and ends on a 32-bit even boundary. Frame data, if any, will follow and is tagged at the end of the frame header. The frame header defines the command and specifies the number of bytes of frame data that follow the header. The header consists of the following fields:
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:

Please see gmsg.h for defined values.

Reserved (one byte)
This field is reserved for future use.


GC Frame Body

The GC frame body format is dependent on the frame type. Format specifics for individual GC frames are provided in the sections below.

Command Frames

When a GC frame is marked as a command frame (frame type = FT_CMD), the frame data always begins with a command header followed by command data and padding. Every command frame will have a response frame returned to the command frame source. The command frame format is described below.
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.


Response Frames

When a GC frame is marked as a response frame (frame type = FT_RESP), the frame data always begins with a command header (identical to the original command frame's command header) followed by data. The response frame format is shown below.
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.


Event notification frames

The sends out event notification frames whenever it needs to inform the connected clients about certain events and error conditions (e.g. when a service requested by the client has been completed, or when an error condition has been detected on one of the channels). When a GC frame is marked as an event notification frame (frame type = FT_EVENT), the frame data begins with an event header followed by event data and padding. No response frames are required for event notification frames. The event frame format is shown below.
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.


Data Frames

When a GC frame is marked as a Data frame (frame type = FT_DATA), the frame body contains a message in the format described below.

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:

Please see Hardware-Specific Information for details about the assignment of these fields for a particular type of network. The layout of a Data Frame is shown below:
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:

(see gmsg.h for defined values)

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.


Signal Frame

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
18First 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.


Miscellaneous Frame

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


Text Frames

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


Broadcast Frames

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.)
|Top|