|
GUIterm 2.0 Protocol
This page gives a brief overview of the GUIterm protocol. |
Command Line Parameters
GUIterm accepts a variety of command line parameters, detailed as follows: |
| — | console: Enables the console (default disabled) |
|
| — | nomonitor: Disables the status monitor (default enabled) |
|
| — | file <filename>: Executes a script file |
|
| — | port <1-9>: Listens to only a single port (default all ports scanned) |
|
| | | • | noport: Disables all port listening |
|
| | | • | baud <baud>: Sets the baud rate over the COM port (default 2400 baud) |
|
Protocol Definition
The GUIterm protocol consists of "commands" and "responses". The device sends commands to GUIterm, which then returns responses. All commands cause GUItem to generate a response, though some responses might be generated by GUIterm without a command (such as due to user input). |
Commands and responses adhere to a strict protocol. This protocol is defined as follows: |
| | <commandname>(<parameter0>,<parameter1>,...)
|
| | <responsename>(<parameter0>,<parameter0>,...)
|
| | <commandname> is either the full or abbreviated name of a given command
|
| | <responsename> is the abbreviated name of a given response
|
| | <parameterX> is either an <integer> or <string>, where:
|
| | | <integer> is any number of hexadecimal digits [0-9a-fA-F]
|
| | | <string> is any number of printable ASCII characters [32-126] surrounded by single-quotes.
|
| | | | NOTE: Non-printable characters will be replaced by a space (ASCII 32) |
| | | | NOTE: The following characters must be replaced by its escape sequence: |
So as to simplify processing on the device, GUIterm always adheres to a strict a strict response protocol: |
| — | Response names are always capitalized |
|
| — | Integers are always two-byte (four digit) hexadecimal values |
|
| — | Extraneous whitespace is never inserted |
|
Likewise, GUIterm is lenient in accepting commands from the device: |
| — | Extraneous whitespace will be ignored |
|
| — | Command names are case-insensitive, and can be shorted to their two-character abbreviations |
|
| — | Integers can be any number of hex digits long (though only the last four will be used) |
|
| — | Unquoted words comprising characters [a-zA-Z0-9_] are interpreted as strings |
|
| | NOTE: It is possible that the same input be interpreted as a valid integer or string. In the event of ambiguity, it will be interpreted as an integer. To resolve the confusion, ambiguous non-integer data should be surrounded in single quotes. For example: |
| — | Dead -> Integer value 57005 (0xDEAD) |
|
| — | 'Dead' -> String value 'Dead' |
|
Thus, the following commands are equivalent: |
| — | ListAdd( 0001, 00a0, 'Line ) |
|
Startup/Shutdown Sequence
By default, GUIterm attempts to scan COM1-9 for GUIterm-enabled devices. It does this by sending a GT(0200,0200) response on each COM port it finds on startup, or that becomes available after startup (such as by plugging in a USB COM device). This response notifies any listening devices that GUIterm is available, as well as specifies its lowest and highest protocol version, respectively. |
The first command a device must execute is SessionOpen(0200), which instructs GUIterm to open a session using version 2.0 of the GUIterm protocol. If this version is accepted, GUIterm responds with OK(). After opening the session, all other GUIterm commands become active. |
A device can close the session by executing SessionClose(). After closing the session, it must be re-opened with SessionOpen(0200) to re-enable the other commands. Closing the session initializes the connection and frees up all resources. Alternatively, SessionReset() closes and re-opens the session with a single command. |
If the user shuts down the application while the session is open, GUIterm responds to the device with SC(). This is the last response GUIterm sends on a connection; after receiving SC() the device should assume GUIterm has been terminated and will accept no more commands and return no further responses. |
|
