Step Editor: Condition
Previous Top Next


The Condition tab has the following controls:
      Wait for condition - If checked, GP3EZ will not continue until this step succeeds.
      Set I/O - When checked, the GP3EZ will set the inputs (I) and output (O) on the GP3 as indicated. If not checked, the bit status does not change. Note this does not change existing outputs, it just sets pins so that they are outputs.
      Always - Always perform this step when selected.
      After - When checked, perform this step after a delay (provided in milliseconds) (implies wait). Keep in mind that the accuracy (and minimum) of this time is wholly dependent on your PC which is not a real time device (unless you are compiling your program, of course).
      Input - When checked, the input pins on the GP3 must match the specified pattern (0 is low, 1 is high, and X is don't care). So to only execute this step with a push button was pulling pin 0 to ground you would set the pattern to XXXXXXX0.
      Counter - If the GP3 hardware counter is greater than the indicated value, the step will execute. In addition, GP3EZ clears the counter if triggered when using an original GP3. The GP3A does not clear the counter (you can clear the counter explicitly on the action tab).
      Analog channel - When selected, the condition for this step is the indicated analog channel meeting the specified criteria. In version 1.2 you can select the comparison value to be in volts or the result of reading another analog channel (note: comparing to another analog channel will only compile on GP3A2 chips and GP3A1 chips shipped after 7 January 2008; contact AWC if you need a firmware upgrade). As of V1.5, you can select the number of analog samples to average (from 1 to 16). However, in compiled scripts there will always be one sample regardless of the setting on this screen.
      After time - When checked, the step will trigger if the current time is after the specified date and time. In addition, if Repeat (HMS) is not 0, GP3EZ will reset the condition time to the current time, plus the specified repeat interval (in Hours, Minutes, Seconds). For example, above, the step will execute since the date show is in the past. Then, the time will be updated to be the current time, plus 10 seconds.
      External - Run an external program, DLL, or send a custom Windows message to another application (see below). A return code of zero will allow the step to execute.  Note that to use an ampersand (&) in this box you must double it. A single ampersand will expand to the step value last set (see the Step Editor: Action topic for more details).

When an Input, Analog channel, or Counter condition is true, the step will remember the value that caused the trigger to occur and make it available in the Action tab. For example, if the condition was for channel 3 to be greater than 2V, and channel 3 was 4V, the step will remember the value 4 and make it available for the action tab's External box.

When you use the External box, you can select what kind of external trigger to execute using the drop down box. The exit code of the program determines if the step will execute or not. An exit code of 0 indicates the step can execute. The types are:

      Prog - A regular executable program
      Doc - A document (such as a WAV file, a video, or a Web URL)
      DLL - A special DLL (see below)
      Msg - A registered Windows message
      Cmp Ch - This is only used when compiling. The GP3 will trigger if it sees the first character provided on its serial port.
      GP3UI - The condition in this case is a tag (the execution string) from the TCP server. See the section on TCP Server for more details.

In place of an executable program or document in the Execute boxes in the condition and action tabs, you can call an external DLL. To do this, the DLL must export a CDECL function that accepts a char * argument and returns an integer (the integer is ignored for the action).

Suppose you build test.dll with the following code:

#include <windows.h>
extern "C" {
__declspec(dllexport) int Prompt(char *s);

int Prompt(char *s)
int rv;
rv=MessageBox(NULL,s,"From GP3EZ DLL",MB_YESNO);
return rv!=IDYES;
You can call this by placing the following in the external box:

c:\path_to_dll\test.dll#Prompt#Would you like to continue?

You can also use the Msg selection to send a registered Windows message to a window of your choice. If you had, for example, a custom program with a  main window titled "Controller" and it was able to handle a messaged registered with the name "GP3EZMSG" (for example, you can use any message names you like), you'd enter:

Controller#GP3EZMSG#<optional integer>

The message is sent with wParam=the optional integer supplied and lParam with an unknown value for a trigger.

Note that GP3EZ treats a zero return code from a DLL, external program, or a custom message as permission to continue (in a trigger) and ignores the returns for actions. Obviously, one DLL could hold many routines useful for triggering or actions or both.

The Cmp Ch selection of the external trigger box is used with compiled scripts (it is ignored when using Run or Debug). The GP3 when executing a compiled script will listen on its serial port at 57600 baud, 8 bits, 1 stop bit, and no parity. It remembers the last character received and can trigger a step based on this input. The external box (where you normally put a program name) can contain one of three choices: a single character to match, a * (which matches any character), or a decimal ASCII code that starts with the # sign. Obviously, if you want to match a # or a * character, you'll need to enter the ASCII decimal code for these.

If you do not click "Wait for condition" on this type of trigger, the GP3 remembers the last character sent until it matches. If you wait, the GP3 discards characters until it finds a match. Matching on "*" will discard whatever character is read. However, if you don't wait on "*", execution will continue if there are no characters waiting to be read.

Also note that the boxes used to set bits will respond to keys 0 to 7 to alter each bit (in addition to the mouse). So to toggle bit 0 you can either click on the rightmost box or press 0.