Welcome
 Top Next
Welcome to GP3EZ

GP3EZ is the exciting new software from AWC that makes it possible to sense and control the real world with minimal programming experience.

Applications include:
· Industrial control
· Animatronics
· Museum display applications
· Theatric control
· Holiday effects

To use GP3EZ you must have a GP3 board assembled and working along with a PC running the GP3EZ software. The PC must have a serial port or you can use a USB to serial adapter.


ContactingAWC
 Previous Top Next
You can contact AWC on the Web at:
http://www.awce.com

There you'll find white papers, software updates, examples, FAQs, and a wealth of other products that can simplify your next embedded design.


What's New V1.5
What's new in Version 1.5?
· Beta support for optional TCP server to build user interfaces.
· Compiling code that uses I/O direction bits now works.
· Units for pulse out is now actually microseconds (was 2uS units previous even though user interface said uS)
· Analog inputs can now be averaged (non-compiled only)


What's New V1.4
What's new in Version 1.4.3?
· General user interface improvements

What's new in Version 1.4.2?
· Single character tags work
· Deleting steps now works better
· Files with missing step numbers are now renumbered when read
· HTML output now marks "do not wait for completion" and does not mark the default

What's new in Version 1.4.1?
· Tone frequencies are now correct
· Compiled bookmarks (subroutines) are now correct

What's new in Version 1.4?
· Long duration pulses and tones automatically adjust write time out
· Added an option to allow scripts to wait for GP3 actions to complete before advancing to the next step. The default is to wait which matches behavior in compiled scripts. Unchecking this box allows parts of your script that don't use the GP3 (for example, a condition delay) to continue while the GP3 is still performing the last action.


What's New V1.3
What's new in Version 1.3?
· Improved write pace timing on fast computers
· Indication of write time out errors
· Added frequency to PWM output action (default is the same as before, 4096Hz)


What's New V1.2
What's new in Version 1.2?

· Completely optional state machine management. Check the Script | Show States menu option to enable (this setting is remembered; scripts that have state automatically will show them regardless of this setting)
1. Each step has a state tab that allows you to define up to 14 states.
2. Steps can be active for selected states.
3. Steps can set a new state after they execute.
4. HTML output shows steps only if steps are used.
5. Using a $ in external programs will provide the current state to external programs (use $$ to get a single $). NOTE: This may require a change to any script you have that passes $ to an external program.
· Export to HTML now offers to view the generated page.
· Analog conditions can now compare to another analog input voltage as well as a constant. Note that the step value is always computed using the first analog value. In addition an analog condition that compares to another channel is only compilable on a GP3A2 or a GP3A1 shipped on or after 8 January 2008.
· New external actions allow (non-compiled) scripts to log the step value, time and date, and other information to a comma delimited file.


About GP3 Versions
There are several GP3 versions:
· The GP3 has been available since 2003. GP3EZ can drive the original GP3 but this type of board can't accept compiled scripts. GP3EZ detects this type of board and produces an error if you try to download a script to a GP3A. The chips in these devices are marked 16F873 or 16F873A.
· The GP3A1 is an interim device that uses the 16F873A. These can accept small downloads (40 or 50 steps). In addition, GP3A1s shipped on January 8, 2008 or later have the ability to compile scripts with analog conditions that compare two analog channels.
· The GP3A2 is the same as a GP3A1 but it has more program storage (hundreds of steps) and twice the EEPROM of the GP3A1.


IntroducingGP3EZ

The above picture shows the main GP3EZ screen. GP3EZ uses "scripts" to control the GP3 board. Each script contains one or more steps. You can see the steps numbers 1 to 7 in the script just above the bottom row of buttons.

You'll need to know which serial port (or USB to serial adapter port) you connected to the GP3. You should select the proper port using the Port select box near the top right of the window. Once you set it, GP3EZ will remember it as the default port in future sessions.

When executing, GP3EZ starts with step 1 in the script and works its way down the list (although the steps can change this, see below). If nothing special happens, when the last step executes, GP3EZ halts.

The main idea behind the steps in the GP3EZ scripts is that each step has four distinct parts:
1. A tag - This is just an optional short name that you can use to refer to the step. The script above has two tagged steps, "Start" and "Flash".
2. A condition - Sometimes called a trigger. This is what causes the step to occur. For example, some steps always occur, while some wait for a certain time to elapse. You can also have a step that waits for a certain digital input or analog input condition.
3. An action - When the condition is met, what should the step do? A GP3EZ step can set digital outputs, control PWM, generate a pulse, or even launch an external program.
4. A next step - By default, after processing a step, GP3EZ goes to the next step. However, if the condition for a step is met, the step can cause GP3EZ to go to a different step next. In addition, when going to a different step, you can save a bookmark which allows you to go back to where you were later.


MainScreen

The controls on the screen are:

· File - This box contains the name of the current file. You can enter a file name here if you like.
· ... - This button allows you to select a file which will be put in the file box and loaded. [ Same as menu File | Open ]
· Load - Load the file named in the file box. [ Same as menu File | Reopen ]
· New - Start a new GP3EZ script. [ Same as menu File | New ]
· Notes - You can put anything you like in this box to describe the script.
· Port - Select the port connected to the GP3. Note that this port will be saved in any scripts you save, and remembered next time GP3EZ starts. However, scripts only load the port number if you have not manually set the port. If you want to use the script's port number, blank out the port field before loading the file.
· Help - Brings up this help. [Same as menu Help | Help ]
· About - Brings up an about box. You can also find controls here to disable balloon help and reset the stored size of the GP3EZ window. [ Same as menu Help | About ]
· Script Box - The box above the bottom row of buttons contains the script. There are 4 fields on each line:
1. A flag. A - means the step is not enabled. A < character means the step passes control to a different step when it executes, not the next step. A * means the step passes control back to the last bookmark saved. A space means the step is enabled and does not alter control flow.
2. The step number.
3. The step's tag (optional). The screen above has two tags, Start and Flash.
4. The step's notes field.
· Up arrow - Move the selected step up in the script list. (You can also use Control+Up to do this from the keyboard)
· Insert - Insert a new step into the step list.
· Dup - Duplicate a step in the step list.
· Delete - Delete a step in the step list.
· Down arrow - Move the selected step down in the script list (or use Control+Down).
· Edit - Edit the current step. You can also double click the step to get the same effect.
· Save - Saves the script using the name in the file box. [ Same as menu File | Save ]
· Save As - Saves the script using a name of your choice. [ Same as menu File | Save As ]
· Run - Connect to the GP3, reset it, and start with step 1 of the current script. (Note: naming a file on the command line will cause GP3EZ to load it and run it on start up. [Same as menu Script | Run ]
· Debug - Run with the debugger active. [ Same as menu Script | Debug ]
· Compile - This button will compile the current script and send it to the GP3 board for execution independent of the PC. You must have a GP3A board for this to work (the program will alert you if you need a firmware upgrade). [ Same as menu Script | Compile ]
· Exit - End GP3EZ. [ Same as menu File | Exit ]

Note that to compile and download a script, RC1 must be grounded at reset. This is also the default configuration for running scripts from the PC. To make the GP3A execute the compiled script, connect RC1 to +5V and reset the board.


StepEditor

The Step Editor has the following controls:
· Enabled - Uncheck to have GP3EZ ignore this step
· Tag - A short name for the step
· Notes - Any text you wish to use to describe the text. The first line will appear in the script box on the main screen.
· Save - Save the current step and close the editor.
· <- - Save the current step and go back one step.
· -> - Save the current step and go forward one step. If there is no next step, a new step will be created.
· Cancel - Close the editor without saving.
· Revert - Reload the original copy of this step.

In addition there are three tabs:
Condition
Action
Next Step


Step Editor: Condition

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.


Step Editor: Action

The step editor's action tab has several boxes you can check to control the step's action:

· Reset Device - Resets the GP3. Note that in compiled code, this restarts everything. When not complied, this simply resets the GP3 to its power on state.
· Reset Counter - Resets the GP3 hardware counter.
· Output - Sets output bits on the GP3. Note that if you set any bit to X (don't care) then any bits you set to 0 or 1 will be forced to be outputs, but it will be less efficient than setting all the bits. If you set all the bits to either 1 or 0, the execution will be more efficient, but only the bits selected as outputs (see the Set I/O field in the Condition tab) will actually be affected. Note that the Set I/O command stays in force until overridden, so once you set the I/O you don't need to set it on every step that has output.
· Pulse - Sets the specified pin to be an output (if it isn't already) and then inverts its state for the specified number of microseconds.
· Set PWM - Sets the GP3's hardware PWM to a duty cycle from 0 to 255 (0 to 100%). Note that as of version 1.3 you can also specify the frequency from 1 to about 32kHz.
· Frequency - Sets the specified pin to be an output (if it isn't already) and then generates the specified frequency for the specified duration in milliseconds.
· Set Loop - Allows you to initialize one of the three loop counters (A, B, or C). The value can range from 0 to 8191.
· Disable step - Disable a step in the script (this step can even be the current step). This allows you to set a timed condition and then disable it so the step only executes once.
· Enable step - Enables a step in the script.
· Execute - Run an external program, document, DLL, or custom message. If you use an external program or document, you can optionally wait for it to complete before proceeding.

The execute choice has several types of external item to execute in the drop down box:

· 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
· Comp - Compile time external serial transmission (this is the only external action that will compile)
· New File - Starts a new file and writes the following (delimited by commas): Date and time, step value, step name or number, and current state.
· Add File - Similar to new file but appends the data to an existing file.
· GP3UI - This sends the data to a remote program using the TCP Server. The text is the GP3UI tag to associate with the data. 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

If you use a registered message named GP3EZCTL to a Window titled Controller you'd use this entry:

Controller#GP3EZCTL#<optional integer>

The Windows message is sent with wParam = the optional integer supplied and lParam=to the step value (see below). If the wait box is checked the message is sent with SendMessage, otherwise it is sent with PostMessage.

Note that GP3EZ ignores any return code from a custom action.

In an action, an external program, DLL, or message can receive the step's "value." The value is the counter, digital, or analog value that allowed the step to trigger (if an analog condition uses two analog channels, the first one -- the one to the left -- sets the step value). If this doesn't apply to the current step, the value is the value of the last step that was triggered by one of these events. So if the condition is a digital input of XXXXXXX1 and the input bits were 00001001 (which is 9 in decimal) then the step's value is 9. To use this, place a single & in the external box which will be replaced by the value. If you need to actually send the & character to the DLL or program, double it. That is, && is interpreted as a single &. Note that the value will remain active until another step changes it, so it is possible to use && in other steps to refer to the last value set. This will also work in an external condition, although in that case, the value is always one that was previously set.

You can also include the current state by using $ (use $$ to get a single $ into the command line). Note that if the current step changes the state, that state change will not occur until the end of the step, so the $ will report the "old" state, not the new one.

When the step value is an analog quantity, it will be sent as a string representation of the floating point voltage for programs and DLLs. For custom messages, the number of counts (where 1023 counts is 5V) is sent in lParam.

If you select Comp in the external action, this will only apply to compiled scripts. When executed, the GP3 will transmit a single character you provide in the box followed by 4 hex digits that correspond to step value (see above). In addition, a single carriage return is sent.

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.


Step Editor: Next Step

This tab lets you select the next step to execute when the step meets its condition. By default the next step is executed. However you can also go to a different step. If you check the "Bookmark Place" box, GP3EZ will "hold your place" and then go to the new step. This allows you to call subroutines.

As of V1.4 there is an additional option on this screen (which is set by default) that causes GP3EZ to wait for the GP3 hardware to complete any actions pending before advancing to the next step. This matches the behavior of compiled scripts. If you uncheck the box, some operations will occur at the same time as the GP3 operations. This is easy to notice when working with long pulses or tones. For example, if you produce a tone with a 1000mS time, and the next step has a 1000mS delay on the condition tab, you'll see the difference. If you make the tone-generating step wait for completion, the first step will wait until the tone completes before continuing. If you clear the option, the first step will start the tone and the second step's delay will be (mostly) concurrent with the tone. Unless you have a specific reason, keep the option checked (which is the default).

GP3EZ maintains three "loop counters" A, B, and C. You can initialize them on the action tab. If the Loop box is checked, GP3EZ decreases the indicated counter. If the count is greater than zero, the go to you specify is executed. If the count is 0 or less, GP3EZ proceeds with the next step.

If you build a subroutine, the last step would use the "Last Bookmark" selection to go back to the previous bookmark. In non-compiled code you can have up to 255 pending bookmarks.


Tutorial
Here's a simple tutorial to help you get started with GP3EZ. In traditional programming you learn how to write "Hello World." This example will do the embedded system equivalent -- blinking a light. Launch the program and select the COM port that your GP3 board connects to. In this example, the port is COM5:

There is a single step already in place. Double click on it to bring up the step editor:

Note the step is enabled. That's good because if it isn't enabled, it won't have any effect when you run the script, and GP3EZ will just skip it and go to the next step (if any). This step also has a tag of "Start" by default. This is just a nickname you use to refer to the step. You could change if you like. Steps don't have to have a tag if you don't need to refer to them in other parts of the script. However, having unneeded tag names is harmless. The Notes field is a place for you to make any comments or notes you need to remember what this step does. GP3EZ doesn't really pay any attention to this. You can leave it blank or write as much as you like to document this step.

Note there are three tabs:
· Condition - What makes this step actually occur?
· Action - What does this step do when it activates?
· Next Step - Where to go next?

Normally, GP3EZ will start with the first step (this one) and move on to step #2, then step #3, and so on. If this step is disabled, or the condition is not met, then step #2 will definitely be the next step (assuming we make a step #2, which we will shortly). However, if the condition is met, the next step will be determined by the "Next Step" tab. By default, however, it simply moves to the next step. If there is no next step, the GP3EZ software halts the script execution.

Each step can have only one condition. By default the condition is "Always" which means this step is always executed. If you need to wait for more than one condition, you'll have to break your logic up into multiple steps.

Notice that you can wait for some conditions. For example, if you were waiting for a particular input pattern, the behavior will change based on the "Wait for condition" check mark. If checked, GP3EZ will wait on this step until the condition is met. If the the check mark is not checked, GP3EZ will check the condition. If it is met, the action and the next step will take effect. If it is not met, GP3EZ will just go on to the next step. Of course, not all conditions make sense to wait and those conditions will gray out the wait check box.

To blink the onboard LED, we will make this step wait a short period of time and turn the LED on. Then we'll make a second step which will wait a little while, turn the LED off, and go back to this step (named Start, if you recall).

To complete this condition step, click on "After" and type in 250 in the milliseconds box. This will delay for 1/4 second (there are 1000 milliseconds in a second).

Now click the Action tab. You can select more than one action at a time, but in this case we just need one: the check box marked LED. This is a "three state" LED. By default it is grayed out (the exact appearance depends on how your computer is set up). When grayed out, GP3EZ won't change the state of the LED. Each time you click on the check box it will cycle between on, off, and "gray." For this step, we want the check mark to be on:

That's it for this step. We need to make a second step, and you can do that by pressing the -> button at the bottom of the window. This takes you to the "next" step, but since there isn't a next step, the editor makes one.

Note the new step starts out with the Enabled check box turned off. So the first thing to do is click that box to turn the step on. Also, notice the editor has put you back at the Condition tab. Click on "After" again and enter 250 in the milliseconds box. This step doesn't need a tag. You can put something in the notes if you wish, although this is just for your benefit, so you don't have to change it if you don't want. Switch to the Action tab and select the LED check box to be off (remember, it starts out in the "don't change" position, so you'll need to click the box to select the off state. It should look something like this:

Finally, you need to select the Next Step tab. There are three buttons on this tab. The default button, "Next," tells GP3EZ to just continue on with the next step when this step is done. That's not what we want. The second button ("Goto") will let GP3EZ jump to another step. That's what we want. We want to go to the "Start" step. Remember, this will only happen when the current step's condition is true, but in this case, the condition is a timed wait, so it will eventually be true every time.

You can click the Goto button or you can just drop down the list and pick Start from the list which will automatically pick the Goto button at the same time:

Leave the "Bookmark Place" and "Loop" boxes unchecked. You'd check the bookmark box if you wanted to call a subroutine that would later come back to the next step by using the "Last Bookmark" button (if you don't know what that means, don't worry about it; you don't have to use this feature). The loop box is used for repeating a sequence of steps a certain number of times.

Now you can press the Save button at the bottom of the window to return to the main window. The script list should now look like:

If you changed the Notes on the steps you might have a slightly different appearance, of course. The "<" to the left of the second step is a clue that the step doesn't continue on to the next step.

You might want to save the script using the "Save As..." button. If you have the GP3 connected and powered on, pressing Run should show you a blinking LED! Congratulations! You just wrote your first GP3EZ script.


Debugging

When debugging, you can use several controls:

· Step - Execute the next step
· Resume - Start running the script at the current place
· Pause - Stop running the script (use Resume or Step to continue execution)
· Break at - Select a step number you'd like GP3EZ to stop when it reaches (presumably you'll press Resume after setting a break).

The bottom of the window shows the current step number and the next step (which may be a tag, {next}, or {last}. Note that the main window shows the current step highlighted in the script box as well.


Compound Conditions
You may have noticed that the Condition tab can only take one condition at a time. You might wonder what happens if you need to handle multiple conditions. The answer is to break the condition up into multiple steps.

There are two ways you might combine conditions. As an example, consider if wanted to perform a step depending on the values of analog channels 2 and 3. You might want to look for channel 2 to exceed 2V OR channel 3 to exceed 2V. Alternately, you might want to look for channel 2 AND channel 3 to both exceed 2V. In addition, you might want to wait for the condition or you may wish to not wait.

Suppose you have three steps: Tag20 is the step that will check analog channel 2. Tag21 is the step that will check analog channel 3. Tag30 is the next step after the two analog tests. You may need to add one more step between Tag21 and Tag30 to get the result you want.

V2 OR V3 (wait)

Tag20:
Condition: A2>2
Action: Whatever action you want to occur
Next Step: Tag30
Tag21:
Condition: A3>2
Action: Whatever action you want to occur
Next Step: Tag30
Tag25:
Note: A2 and A3 didn't trigger so, try again
Condition: Always
Action: None
Next Step: Tag20
Tag30:
. . .

V2 OR V3 (no wait)
Tag20:
Condition: A2>2
Action: Whatever action you want to occur
Next Step: Tag30
Tag21:
Condition: A3>2
Action: Whatever action you want to occur
Next Step: Next
Tag30:
. . .

V2 AND V3 (wait)
Tag20:
Condition: A2>2 (Wait)
Action: None
Next Step: Next
Tag21:
Condition: A3>2 (Wait)
Action: Whatever action you want to occur
Next Step: Next
Tag30:
. . .

V2 AND V3 (no wait)
Tag20:
Note: Note that <= is the opposite of >, so the condition is "backwards"
Condition: A2<=2
Action: None
Next Step: Tag30
Tag21:
Condition: A3<=2
Action: None
Next Step: Tag30
Tag25:
Note: A2 and A3 met threshold
Condition: Always
Action: Whatever action you want to occur
Next Step: Next
Tag30:
. . .


Looping and Subroutines
Two advanced GP3EZ techniques are looping and subroutines.

Consider a script that looks like this:
ID | Tag | Condition | Action | Next
1 | Start | Always | Set Loop A 5 |
2 | blinkloop | Always |  | Goto blinker (bookmark)
3 |  | Always |  | Goto blinkloop (Loop A)
4 |  | After 5000ms |  | Goto Start
5 | blinker | After 250ms | LED off |
6 |  | After 250ms | LED on | Last Bookmark

Step 1 sets loop counter A (there are three loop counters: A, B, and C) to 5.

Step 2 jumps to the blinker "subroutine" (in other words, a chunk of steps we want to use more than once from different parts of the script). Note that it sets the bookmark so blinker can come back here. In this simple example, blinker is only used once, but a complex script might use the same subroutine in many places.

After step 2, the next step that runs is step 5 which just delays and turns the LED on. Step 6 also delays. Then it turns off the LED and jumps back to the last set bookmark which means the next step will be step 3.

Step 3 doesn't do anything except jump to the blinkloop step (step 2). However, it does so with the Loop A box checked. that means GP3EZ will decrease the loop counter by 1 and only jump to blinkloop if A is greater than 0. So the first time through, A will be set to 4 (remember it was set to 5 in step 1) and GP3EZ will continue at step 2. However, after 5 times, A will be set to 0 and the jump will not occur. In that case, the GP3EZ will continue at step 4.

Step 4 waits 5 seconds and starts the whole script over again by jumping to the Start tag.


GP3Connections
The GP-3 Connections used with GP3EZ are:
JP1-1 | Ground
JP1-2 | PWM Output
JP1-4 | Counter Input
JP1-5 | Analog input #4
JP1-6 | Analog input #3
JP1-8 | Analog input #2
JP1-9 | Analog input #1
JP1-10 | Analog input #0
RB0 | Digital I/O #0
RC4 | Digital I/O #1
RC5 | Digital I/O #2
RB3 | Digital I/O #3
RB4 | Digital I/O #4
RB5 | Digital I/O #5
ICSP-5 | Digital I/O #6
ICSP-6 | Digital I/O #7
RC1 | Compiled Script select (GP3A only); tie to ground for normal operation (including programming compiled code) or tie to +5V to execute the previously stored compiled program).


Menu Only Functions
There are a few functions available only from the menu:

File | Export as HTML - Exports the open script as an HTML page which is useful for printing or documentation. Note: When entering notes about a script or a step, your text will be converted to HTML automatically. However, if you wish to use HTML in your comments, make sure the first character of the note is a < (for example, start with a <P> tag). In this case, NO conversion of the note will take place (so be sure to use <P> or <BR> tags for line breaks, for example).

Script | Reset GP3 - Resets the GP3 to its initial power up state immediately.

Script | Show States - Shows the States tab in the step editor. Note that if you open a script with steps, this setting is automatically checked.

Script | Start GP3UI Server - Starts the TCP Server on the indicated port. Note you can only change the port number using the command line.


Command Line
You may name a single file on the command line which will cause GP3EZ to open this file on start up (you may wish to associate GP3 files with GP3EZ.

If you wish to run a file automatically place the word "run" (without quotes) on the command line after the file name. For example, you could create a shortcut with the command line:

GP3EZ c:\main.gp3 run

If you wish to automatically start the TCP server for interfacing with external programs, you can provide a port number prefixed with a colon anywhere after the file name. So to start the server on port 1234, you could write:

GP3EZ c:\main.gp3 run :1234
GP3EZ c:\main.gp3 :1234 run
GP3EZ c:\main.gp3 :1234 (in this case, the script would not run automatically)

Naturally, you should be certain the COM port setting stored in the file is correct for your hardware so that execution will succeed.


Compiling
Once you have a script working as you like it, you can compile it, download it to the GP3 (this requires the GP3A firmware), and then it will execute on the GP3 hardware with out connection to the PC. It will continue to do this until you reprogram it.

If you don't have the GP3A firmware, contact AWC about upgrading. However, the original GP3 will work fine with GP3EZ, it simply won't handle compiled scripts.

There are a few limitations in compiled code:
· Most external triggers and actions are not allowed
· After time triggers are not allowed
· Disable/Enable step actions are not supported
· There are more limitations on the amount of bookmarking allowed in a compiled program.

There is also some difference in short timing and loop timing. This is to be expected as the PC is not a real time platform and is not good at handling very short delays. When you ask GP3EZ on the PC to delay for, say, 10 milliseconds, the actual time may vary considerably. However, when compiled, the GP3 board -- which is very deterministic and isn't running a large operating system and other programs -- will produce a delay very close to 10 milliseconds. You'll notice that compiled loops execute much faster than loops run from the PC. This is partially due to the PC's time instability and partially because the compiled loop doesn't have to feed commands down the serial port. The bottom line is to realize that compiled code will run faster than non-compiled code.

In addition, some script arguments have stricter limits when compiled. See the readme.txt file for the latest information on these limitations. In addition, the compiler will warn you when you exceed one of these limits

With the GP3A firmware, you must ground RC1 for normal operation. This includes downloading compiled scripts. When you connect RC1 to +5V and reset the board, the GP3A will execute the compiled script you last downloaded. By default, the GP3A has a simple script that blinks the onboard LED a few times, pauses, and repeats. You can use this to verify the operation of the GP3A. If you want to use the GP3A with the PC again, or download a new compiled script, just connect RC1 to ground and reset the board.


State Management
State management is a completely optional capability for advanced users. If you don't check the Script | Show States menu item, you won't see states and never have to think about them.

If you do check this item, or load a script that uses states, the step editor will have a new tab, States, that allows you to do three things. First, you can define up to 14 named states for your script. These are "global" -- that is, they apply to the whole script. If you change a state name on one step, it will apply to all other steps as well.

The second thing you can do is make a step "sensitive" to the current state (the current state is initially undefined). That is, you can make a step only execute if the current state matches certain values.

The third thing you can do with the state tab is to select a new state to enter when the step completes execution. This will occur after any other actions in the step.

The step below shows a script with three states "Off, On, and Idle". The current step will only execute when in the off or idle state and after it executes, the new state will be #2 (On). Of course, that assumes the step executed -- so the current state had to be Off or Idle, the step had to be enabled, and any condition on the condition tab had to be met.

Normally, the first step in a state-enabled script will set the initial state.


GP3UI TCP Server

TCP Server

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.


About Timing
About Timing

When using GP3EZ to drive the GP3 from your PC, you should be aware of certain timing limitations inherent in the Windows operating system. In general, you can expect any timing performed by the GP3 hardware to be quite accurate (controlled by the ceramic resonator on the board). However, timing performed by the PC (such as the delay in an "After" milliseconds condition) will be subject to the PC's timing accuracy.

For long delays on a fast PC, this isn't usually a big deal. However, trying to do fast or precise timing will pose a problem. A common task, for example, is to control a continuous rotation RC servo. To do this you have to send a pulse near 1.5 mS in length about every 20mS or so.

Since the GP3 can produce pulses, the 1.5mS pulse isn't a problem. However, the 20mS delay is problematic. Tests on a 2.5Ghz AMD dual core processor running XP showed that even simple instructions with no delays take about 60mS to execute. This is partially because of the GP3's serial interface speed and partially because the program is sharing time with other Windows programs, etc. What's more is that on the PC it is hard to assure exact timing. So even the 60mS will vary depending on a variety of factors.

However, if you compile the code, the length of time drops dramatically. For example, a simple two step script that toggles an output bit produces a square wave with a period of 155mS on the same test hardware. The same script when compiled produces a 230uS square wave (that is 0.23mS). That speed, of course, is independent of the PC since the GP3 doesn't use the PC to run compiled code.


FAQ
Q: When will the compile function be available? What will it do?
A: In an upcoming release, you'll be able to compile a GP3EZ script and download it to the GP3 hardware. Then you won't need to use a PC to operate the script. Note that some features won't be available (like launching an external program) in a compiled script. Also, be aware that this feature will require updated GP3 firmware.

Q: Can my external program manipulate the GP3?
A: No. GP3EZ has control of the GP3.

Q: How can I work with more than one condition?
A: This is explained in the online help article " Compound Conditions "


License
 Previous Top
GP3EZ is (c) 2007 by AWC. All Rights Reserved.
You are permitted to use the software in conjunction with GP3 hardware you've bought from AWC or its authorized resellers. You may not distribute GP3EZ without the associated AWC hardware.