GP3EZ Server Protocol (GP3UI)

NOTE: THIS CAPABILITY IS BETA QUALITY AS OF V1.5

Starting with V1.5, GP3EZ can listen on a TCP socket for commands from a program – typically a user interface program. You can write such a program using any language that can send and receive strings from a TCP socket. Each string is sent as a line terminated by a carriage return/line feed. Return values, if any, are in the same format.  You can start the server by using the menu or via the command line (use :portnumber after the file name as in "gp3ez c:\main.gp3 :333)".

Here are the commands available:

:0 – This command informs GP3EZ that you are using version 0 of the protocol. I t will respond with :0 which tells you the same thing. This should be the first command sent on a new connection as it will allow future versions to negotiate capabilities. Currently, it doesn’t matter if you send this or not, but in future versions it may be mandatory that this is sent before any other commands or transactions occur. The version numbers are always single characters.

? – Returns status of the GP3EZ software. A 0 means the GP3EZ script is not running. A 1 indicates the script is running.  A state of 2 means the software is in the process of stopping a script.

!start – Start running the script.

!stop – Stop a running script.

!quit – Exit GP3EZ.

!hide – Hide the GP3EZ window. Note that disconnecting will cause the window to become visible again.

!show – Show the GP3EZ window.

!bye – Disconnect from the GP3EZ.

!treset – Reset all triggers to zero (see below).

In addition, you can send arbitrary tags that can be read by the GP3EZ external condition. The tag must be followed by a colon and a single character command. Each trigger is really a counter. If the count is zero, the trigger is not active. If the count is positive, the trigger is set and when the GP3EZ reads the trigger it will decrease the count by 1. The trigger tag commands are:

+ - Add 1 to the trigger

- - Remove 1 from the trigger

! – Invert the trigger from set to unset and vice versa

0 – Force the trigger to zero

1 – Force the trigger to one

So if you send (without quotes): “mantrig:+” this causes the “mantrig” trigger to be set and a GP3EZ script can test to see if that trigger was set in the condition tab.

When an external action sends you a current value, it also has a tag. In this case the value follows the colon. You can also use the special tag $state to send the current state name instead of the step value. So presume you have an analog condition with an external GP3UI action tagged VOLTS and the reading was 2.35 volts. You’d get the following data on the socket:

VOLTS:2.35

Example interfaces using Visual Basic Express are available on the AWC Web site.