 Using the ISaGRAF simulator

The ISaGRAF Kernel simulator is started with the debugger when the "Simulate" command of the "Debug" menu in the Program Management window is run. The kernel simulator is a complete ISaGRAF target system supporting ISaGRAF standard features and all the "C" functions and function blocks of the standard library delivered by CJ International. The I/O boards are graphically simulated in a window. Any type of I/O board can be simulated. The boards defined as "Virtual boards" during the I/O connection also appear in the simulation window.

Links with the debugger

I/O simulation

Library components

Options

The ISaGRAF simulator also includes powerful tools for application simulation and diagnostic:

Saving and restoring input states

The Cycle Profiler

Simulation scripts


Links with the debugger

The kernel simulator supports full communication with the ISaGRAF debugger, so any of the debug possibilities can be used during simulation. The kernel simulator always works on the current  ISaGRAF application. During simulation, the debugger commands "Start", "Stop", "Download" or "Update" are no longer available. The simulator cannot be used if the "SIMULATE" target was not selected in compiler options before building the target code. Closing the simulator window implies that the debugger window (and any ISaGRAF window opened during the debug session) is also closed.


I/O simulation

I/O boards appear in the simulator window, titled by their name and slot number. Any of the ISaGRAF standard types of I/Os (boolean, analog or message) are handled. The channels of the input boards are displayed with special buttons and fields. The channels of the output boards are displayed with graphic status lights and data fields.

 	Boolean inputs: A boolean input is represented by a square green button. The number of the channel is displayed with the I/O button. The input value is TRUE when the button is pressed. Clicking on the button changes the corresponding I/O value. Use the right button of the mouse to set the input only when the button is pressed.

 	Boolean outputs: A boolean output is represented by a small circle. The number of the channel is displayed with the I/O. The output value is TRUE when the graphic symbol is highlighted.

 	Analog inputs: An analog input channel is a simple numerical field, where the value of the corresponding input can be entered. Clicking on the box displays the caret. A new value for the channel can then be entered. It is not necessary to use the ENTER key after input. Analog inputs can be entered in either decimal or hexadecimal base. Use up/down buttons to increase or decrease the current value.

 	Analog outputs: An analog output channel is a numerical output field. The output value can be displayed as either a decimal or hexadecimal number. No action can be performed by the user on an output channel.

 	Message inputs: A message input channel is a simple text field, where the value of the corresponding input is entered. Clicking on the box displays the caret. A new value for the channel can then be entered. It is not necessary to use the ENTER key after input.

 	Message outputs: A message output channel is a text output field No action can be performed by the user on an output channel.


Library components

The ISaGRAF simulator fully supports the standard conversions, functions and function blocks, delivered by CJ International. Below is the list of supported objects:

 Conversion functions:

bcd, scale

 Functions:

abs, acos, ArCreate, ArRead, ArWrite, ascii, asin, atan, char, cos, delete, expt, find, insert, left, limit, log, max, mid, min, mlen, mod, mux4, mux8, odd, rand, replace, right, rol, ror, sel, shl, shr, sin, sqrt, tan, trunc

 Functions blocks:

average, blink, cmp, ctd, ctu, ctud, derivate, f_trig, hyster, integral, lim_alrm, r_trig, rs, sema, sr, stackint, tof, ton, tp

User defined conversions, "C" functions and function blocks are commonly not integrated with the ISaGRAF Simulator. Typically, such objects are designed to use software and hardware resources of the target system. Such resources are generally not available on the Windows system. The ISaGRAF Simulator provides the following standard behavior for any user defined conversion, function or function block:

•	When a new conversion is processed by the simulator, it is replaced by a "null" conversion. This means that the physical value of the analog variables is always equal to the electrical value (as entered or displayed on the Simulator panel).

•	When a new "C" function or function block is run by the simulator, it does not process any operation. The result value is not set.


Options

The commands of the "Options" menu enable the user to control the display of I/Os in the simulator panel. The user can set or remove these options at any time during debug.

 When the "Color display" option is set, I/O channels are displayed as color bitmaps. If colors cannot be distinguished on some LCD screens, the user should remove this option, to get pure black and white input and output graphics for I/O channels.

 When the "Variable names" option is set, a sticker is displayed beside any I/O channel, with the name of the connected I/O variable. Removing this option enables the user to reduce the size of the simulator panel.

 When the "Hexadecimal values" option is set, any input or output analog channel is displayed or entered in hexadecimal format.

 When the "Always on top" option is set, the simulator window is always visible, even if the input focus is on another window.


The Cycle Profiler

The ISaGRAF Cycle Profiler is a powerful diagnostic tool that shows how cycle time is distributed between various programs, functions and function blocks of an application. This tool is very useful to have a quick diagnostic on the application performances, and leads the programmer to the parts of code which may need optimizations.

The Cycle Profiler is run by the "Tools / Cycle Profiler" command in the menus of the ISaGRAF Simulator window. It displays, for each program, function or function block, the percentage of the cycle time spent to execute it:

When the "View / Average" option is set, displayed information is an average of percentages calculated since the application has been started, or since the last time the "View / Reset" command has been run.

If the "View / Average" option is not set, displayed information shows measurements done during the execution of the last cycle. You can also use this feature when the application is in "Cycle to Cycle" mode to have a set of measurements depending on the application context.

Use the "View / Copy" command to copy program names and percentages to the Windows Clipboard in ASCII format. Then, data can be pasted into text documents or common SpreadSheets.

Important notes:

These are not precise measurements. Percentage calculation is based on TIC instructions counting, taking into account various instruction execution times. Calculation does not include the time spent in "C" functions and function blocks.

The value displayed for a function or a function block is the sum of all the "calling times" from the application programs in the same cycle.

Time calculation is based on TIC code and does not provide reliable information if the actual application code is generated in "C" language and built using a "C" compiler.


Simulation scripts

ISaGRAF simulator includes a tool to build and run simulation script. A script is described with an easy ST like text language, and is used to automate tests with the ISaGRAF simulator.

Editing scripts

Running scripts

Script description language

The simulation script editor is run by the "Tools / Simulation scripts" command of the Simulator window. Below is the frame of the script editor:

The upper window is a text editor where script instructions are entered. It is used as other ISaGRAF text editors and includes high level features such as mouse selection of a variable symbol. You can use commands of the "Options" menu to setup tab width and select a character font.

The lower window shows all the messages output when the script is run. The separation line between windows can be freely dragged to resize windows. The output window can be hidden during script editing, but is automatically open each time a script is run.


Editing scripts

Use the commands of the "File" menu to manage script files:

New	creates a new untitled script

Open	loads an existing script from file

Save	saves script text and contents of output window to disk, in project directory

Save as	saves script under another name

Two files are created in the ISaGRAF project directory for each script:

<scriptname>.SCC	text of the script (instructions)

<scriptname>.SCO	contents of the output window

where <scriptname> is the name of the script. Both files are standard text files and can be open using any other text editor.

 While editing a script, you can use the "Edit / Insert symbol" command to select a declared variable name to be inserted at the caret position.


Running scripts

Script must be checked and compiled before running it. If necessary, syntax checking is automatically performed on a "Run" command. Use the following commands of the "Script" menu:

Check	check syntax and compile script

Run Script	start execution of the script currently edited

In the case of a new untitled script, it must be saved (and a name must be entered for it) before it is checked. In case of a named script, script is automatically saved to disk before syntax checking.

When script is running, its contents cannot be changed. A message is displayed when end of script is reached. You can also abort a running script using the following command of the "Script" menu:

Abort Script	terminates the running script

Script execution is performed between target cycles. In the case of an infinite loop programmed in the cycle, ISaGRAF simulator ensures that this loop is always broken so that ISaGRAF cycles are still executed and other ISaGRAF applications are not blocked. The ISaGRAF script interpreter decides to break script execution if the same "label" is encountered more than once in the same target cycle. Script execution can also be normally broken by "Cycle" or "Wait" instructions.


Script description language

Script description language is a very simple text language similar to ST, but where each instruction is entered on a separate text line, and does not need to be terminated by a semi-colon. Use the following button of the toolbar to know the list of available instructions and to insert a keyword at the caret position:

insert instruction (keyword and help as comments)

There are various types of instructions. First is the assignment (forcing) of a variable:

:=	assignment

Other instructions allow the output of messages to the output window:

Print	outputs a text string or a variable value

PrintTime	outputs current time stamp

Other instructions are used to synchronize script instructions with ISaGRAF cycle:

Cycle	let ISaGRAF simulator execute one cycle

Wait	waits during a specified time

Other instructions are used to control instruction flow in the script:

Labels	can be placed anywhere in the script

Goto	unconditional jump to a label

If goto	conditional jump to a label

End	terminates script

Script language is not case sensitive. Comments can be inserted at the end of any text line. Comments can either be written according to ST conventions (between "(*" and "*)" characters), or prefixed by a ";" character.


":=" Assignment

Meaning:	Force the value of an ISaGRAF variable. It can be an internal variable, an input channel or an output channel.

Syntax:	<varname> := <constant_expression>

<varname> = <constant_expression>

Arguments:	<varname> is a valid symbol of a declared application variable, or a directly represented I/O variable using "%" writing conventions.

<constant_expression> is a valid constant expression that matches the type of the specified variable. For booleans, "0" and "1" can be used instead of "FALSE" and "TRUE". For timers, the "T#" or "TIME#" prefix can be omitted.

Notes:	Input variable forced by a script do no need to be locked. The drawing of the corresponding input channel is updated when input variable is forced by a script.

Warning: do not force input or output analog variable attached to a conversion, as script execution does not support conversion functions or tables.

Example:	MyBooVar := 1         (* same as TRUE *)

MyIntVar := 1234

MyRealVar := 1.2345

MyMsgVar := 'Hello'

MyTmrVar := t#12s


Print

Meaning:	Writes a string or the value of a variable in the output window. Text is output as one new line at the end of text already written in output window.

Syntax:	Print '<text>'

Print <varname>

Arguments:	<text> is any text string expressed between single quotes

<varname> is the valid symbol of a declared application variable, or a directly represented I/O variable using "%" writing conventions.

Notes:	Output of variable values is always formatted according to IEC conventions.

Example:	Print 'Hello'

Print MyBooVar

Output:	Hello

MyBoovar = TRUE


PrintTime

Meaning:	Writes the current time stamp in the output window. Text is output as one new line at the end of text already written in output window.

Syntax:	PrintTime

Notes:	Time stamp is formatted according to current setting of Windows System

Example:	Print 'Time now is:'

PrintTime

Output:	Time now is:

15:45:22


Cycle

Meaning:	Suspends the execution of the script until the next ISaGRAF cycle is performed.

Syntax:	Cycle

Notes:	Script instructions are executed at the beginning of an ISaGRAF cycle. If the simulator is in "Cycle to Cycle" mode, the "cycle" instruction is immediately followed by a cycle. The following instructions of the script will be performed on the next "Execute one cycle" command from the debugger.

Example:	(* the ISaGRAF program copies A to B *)

A := 0

Cycle

Print B

A := 1

Print B (* no cycle performed / B not set to 1 *)

Cycle

Print B

Output:	B = 0

B = 0

B = 1


Wait

Meaning:	Suspends the execution of the script until a delay is elapsed

Syntax:	Wait <delay>

Arguments:	<delay> delay expressed according to IEC conventions for time constant expression. The "T#" or "TIME#" prefix can be omitted. Delay value must between 10 milliseconds and 1 hour.

Notes:	Accuracy of the "Wait" instruction is not precise as it depends on the host Windows system. Also, the delay should be considered with an accuracy of plus or minus one ISaGRAF cycle.

When a "Wait" instruction is reached, ISaGRAF cycles are performed until the delay is elapsed and before continuing the script execution.

Example:	PrintTime

Wait 2s

PrintTime

Output:	15:45:27

15:45:29


Labels

Meaning:	Labels can be placed anywhere in the script. They are used as a destination by "Goto" instructions and allows flow control for script instructions.

Syntax:	<labelname>:

Arguments:	<labelname> unique name according to ISaGRAF variable naming conventions: limited to 16 characters, beginning with a letter, followed by letters, digits or underscore characters. When defined, label name should be followed by a ":" character.

Notes:	No instruction should be placed on the line where a label is defined.

Label name should not be the same as a declared ISaGRAF variable symbol

Example:	(* example of a script with an infinite loop *)

loop:

PrintTime

Wait 1s

Goto loop


Goto

Meaning:	Unconditional jump to a label

Syntax:	Goto <labelname>

Arguments:	<labelname> is the name of a label defined in the script.

Notes:	Backward jumps are allowed. In case of an infinite loop, script execution is automatically broken on each loop in order to preserve execution of ISaGRAF cycles.

Example:	Print 'Before Jump'

Goto MyLabel

Print 'Within Jump' (* instruction never performed *)

MyLabel:

Print 'After Jump'

Output:	Before Jump

After Jump


If Goto

Meaning:	Conditional jump to a label. The condition is either a comparison between two ISaGRAF variables, or a comparison between a variable and a constant expression.

Syntax:	If <var1> test <var2> Goto <labelname>

If <var1> test <constant_expression> Goto <labelname>

Available comparison tests are:

=	true if both members have same value

<>	true if members have different values

<	true if first member is less than second member

<=	true if first member is less than or equal to second member

>	true if first member is greater than second member

>=	true if first member is greater than or equal to second member

Arguments:	<var1> <var2> are valid symbols of declared application variables, or directly represented I/O variables using "%" writing conventions.

<constant_expression> is a valid constant expression that matches the type of specified variable. For booleans, "0" and "1" can be used instead of "FALSE" and "TRUE". For timers, the "T#" or "TIME#" prefix can be omitted.

<labelname> is the name of a label defined in the script.

Notes:	Backward jumps are allowed. In case of an infinite loop, script execution is automatically broken on each loop in order to preserve execution of ISaGRAF cycles.

Example:	(* This script loops until MyVar is TRUE *)

Loop:

If MyVar = TRUE Goto TheEnd

Print MyVar

Goto Loop

TheEnd:


End

Meaning:	Terminates script

Syntax:	End

Notes:	It is not mandatory to place an "End" instruction on the last line of the script

Example:	(* This script loops until MyVar is TRUE *)

Loop:

If MyVar = FALSE Goto Continue

End

Continue:

Print MyVar

Goto Loop


Saving and restoring input states

Using the ISaGRAF simulator, input channels are forced through manual operations, acting on toggle buttons and edit controls of the simulation panel. You can at any time use the following commands of the "Tools" menu to save and restore the state of all input channels:

Load input scheme	Set values of input channels with values stored in a file that has been created on disk by "Save input scheme" command.

Save input scheme	Save state of input channels in a file so that thay can be restored later using the "Load input scheme" command. File is stored in the project directory and thus is saved with other project files by the ISaGRAF archive utility.

Note: Only named input channels (the ones having a variable connected) are saved on disk.