SIMIT 7. Automatic Control Interface (ACI) User manual

Transcription

1 SIMIT 7 Automatic Control Interface (ACI) User manual

2 Edition January 2013 Siemens offers simulation software to plan, simulate and optimize plants and machines. The simulation- and optimizationresults are only non-binding suggestions for the user. The quality of the simulation and optimizing results depend on the correctness and the completeness of the input data. Therefore, the input data and the results have to be validated by the user. Trademarks SIMIT is a registered trademark of Siemens AG in Germany and in other countries. Other names used in this document can be trademarks, the use of which by third-parties for their own purposes could violate the rights of the owners. Copyright Siemens AG 2013 All rights reserved The reproduction, transmission or use of this document or its contents is not permitted without express written authority. Offenders will be liable for damages.all rights, including rights created by patent grant or registration or a utility model or design, are reserved. Siemens AG Industry Sector Industry Automation Division Process Automation SIMIT-HB-V7ACI en Exclusion of liability We have checked that the contents of this document correspond to the hardware and software described. However, deviations cannot be entirely excluded, and we do not guarantee complete conformance. The information contained in this document is, however, reviewed regularly and any necessary changes will be included in the next edition. We welcome suggestions for improvement. Siemens AG 2013 Subject to change without prior notice.

3 Contents 1 PREFACE Target group Contents Symbols 1 2 INTRODUCTION 2 3 USING SCRIPTS Creating a script Executing a script External scripts 7 4 THE SCRIPT SYNTAX Comments Including scripts Signals Controlling the simulation Initialising a simulation Starting the simulation Starting and waiting for an absolute time Starting and waiting for a relative time Starting and waiting for a certain number of cycles Starting and waiting for an event Stopping the simulation Executing an individual step Saving a snapshot Loading a snapshot Resetting the simulation time Controlling the script Pausing the script Terminating the script The query dialogue Logging Opening and closing log files Unformatted output Formatted output 16 Process Automation Page I

4 4.6.4 Outputting time and date Outputting version information The _printlog system function Signal curves Opening and closing a plot file Specifying signals Specifying a cycle Setting signals Setting individual values Defining a signal curve Conditional execution Accessing the simulation time 23 Process Automation Page II

5 Table of figures Figure 2-1: Basic principle Figure 3-1: Creating a new script Figure 3-2: Opening a script Figure 3-3: The script editor Figure 3-4: Script properties Figure 3-5: Dialogue when interface is blocked Figure 3-6: Starting a script Figure 3-7: Ending a script Figure 3-8: Error message dialogue Figure 3-9: Error message in the status bar Figure 4-1: Simulation state transition diagram Figure 4-2: Example of a query dialog Process Automation Page III

6 List of tables Table 3-1: Keywords for script properties Table 4-1: Buttons for dialogs Table 4-2: Format statements Table 4-3: System variables Table 4-4: Arithmetic operators Table 4-5: Boolean operators Table 4-6: Comparison operators Process Automation Page IV

7 Preface 1 PREFACE 1.1 Target group This manual is intended for anyone who uses the SIMIT simulation system. It describes the options that the module Automatic Control Interface (ACI) offers to the basic SIMIT system. It assumes knowledge of the basic SIMIT system, in particular how SIMIT is used to create and run a simulation, in addition to an in-depth knowledge of the use of PCs and their Windows user interface. 1.2 Contents The introduction in section 2 explains how scripts are incorporated into SIMIT. It also outlines the interaction between scripts and the simulation model. Section 3 describes how you can incorporate scripts into your simulation project. Instructions on how to create and run scripts are also provided. The syntax needed to create scripts is explained in section 4. This section provides all the information needed to assign your scripts with syntactically correct statements. 1.3 Symbols Particularly important information is highlighted in the text as follows: NOTE Notes contain important supplementary information about the documentation contents. They also highlight those properties of the system or operator input to which we want to draw particular attention. CAUTION This means that the system will not respond as described if the specified precautionary measures are not applied. STOP WARNING This means that the system may suffer irreparable damage or that data may be lost if the relevant precautionary measures are not applied. Process Automation Page 1

8 Introduction 2 INTRODUCTION A simulation is made functional in SIMIT by defining the graphical interconnections and configuration of components. When the simulation is started, all the diagrams of a simulation project are brought together to generate an executable simulation model that is then processed cyclically. The SIMIT user interface for ongoing simulations gives you access to all input and output signals, statuses and component parameters that can be changed online. The Automatic Control Interface (ACI) of SIMIT allows you to use scripts to access simulation variables at specific times in ongoing simulations. You will then be able to automate manual interventions through the user interface, monitor processes within the simulation and create logs from output information. A script is a sequence of statements that are followed in consecutive order from beginning to end. Cycles are used to synchronise the script and the cyclically executed simulation model. Within each time slice, the script is executed before the simulation model contained in this time slice. You can stop a script to wait for specific events in the simulation model or at points in time. You can also use statements in the script to influence the simulation model control system, such as creating and loading snapshots. Figure 2-1 shows how scripts are incorporated into the SIMIT architecture. Process Automation Page 2

9 Introduction Figure 2-1: Basic principle Process Automation Page 3

10 Using scripts 3 USING SCRIPTS You can both create and execute scripts in your simulation project. Use the script editor to edit scripts. 3.1 Creating a script Scripts are elements of a SIMIT project and are managed in the Scripting folder in the project tree. You can create and edit scripts whenever SIMIT is open, i.e. when the simulation has not been started (offline) and when it has been started (online). Double click on New Script (Figure 3-1) in this folder to create a new script. Figure 3-1: Creating a new script To edit a script, open the script editor from the context menu (Figure 3-2) or double-click on the script in the navigation window. Figure 3-2: Opening a script The editor that then opens (Figure 3-3) lists the line numbers in a column in the left of the pane in order to facilitate the allocation of error messages. Process Automation Page 4

11 Using scripts Figure 3-3: The script editor Enter the time slice in which the script is to be executed in the Properties window of the script editor (Figure 3-4). The time slice does not have to be entered for additional scripts included in the statement - the time slice specified in the initial script applies to them all. Figure 3-4: Script properties If you enable the Block interface option, the dialogue shown in Figure 3-5 appears when the script is started. This dialogue prevents users from accessing the simulation currently running through the interface. If you close this dialogue the script will be cancelled. Figure 3-5: Dialogue when interface is blocked 3.2 Executing a script A script can only be executed when a simulation is running. You can start a script either through its shortcut menu in the project tree or by using the toolbar in the script editor (Figure 3-6). Process Automation Page 5

12 Using scripts Figure 3-6: Starting a script A flashing symbol ( ) appears in the status bar alongside the running simulation symbol ( ) whenever a script is started. You can stop a script at any time using the context menu of the Scripting (Figure 3-7) folder. Figure 3-7: Ending a script Only one script can be running at a time. A script is stopped once all the statements in the script have been completed, if stopped by a command or if the simulation is closed or reinitialised on the interface. After a script is started, the syntax is checked and the script is converted into a list of executable statements. If an error is discovered in the script, this is flagged (Figure 3-8) and the script is not started. Figure 3-8: Error message dialogue Problems can also arise that only become apparent once the script is executed. Should such problems occur, a message appears in the status bar (Figure 3-9) and the script is ended. Figure 3-9: Error message in the status bar Process Automation Page 6

13 Using scripts 3.3 External scripts We recommend that you only create and edit scripts using the SIMIT script editor, as this will ensure that they remain in the simulation project. This is because only scripts in the SIMIT project navigator can be executed and archived with the project. However, if you wish to create scripts externally using a different editor, please note the following. Scripts are text files with the standard Windows character coding (Codepage 1252). Script files must always have the extension.script. The script properties that are listed in the properties window of the script editor must be set in the first two lines of the script file as per the details listed below in Table 3-1. Keyword = Value Example: META_BLOCKGUI = False META_CYCLE = 2 Keyword META_BLOCKGUI META_CYCLE Table 3-1: Description True: The user interface is blocked while the script is being executed False: The user interface is not blocked while the script is being executed Time slice (1 to 8) in which the script is to be run Keywords for script properties STOP WARNING Please note that only the scripts in the simulation project (i.e. in the Scripting folder) are archived when a project is archived. External scripts are not archived with the project. The archived project is therefore incomplete. Process Automation Page 7

14 4 THE SCRIPT SYNTAX A script is a series of statements that are executed in sequence. All the statements available, including their exact syntax, are described below. Examples are used to illustrate how the syntax is used. 4.1 Comments Comment lines start with two forward slashes. They are ignored when the script is executed. Example: // This is a single line comment You can also comment out entire areas in the script by starting a comment with /* and ending it with */. Example: /* This is a multi-line comment */ You cannot close one comment area and open a new one in the same line. 4.2 Including scripts You can compile a script from several individual scripts. below means that the current script will continue with another script. INCLUDE "Name" The name of the script is entered relative to the calling script. Hyphens in the name must be doubled. Example: INCLUDE "..\\subscripts\\test2" The INCLUDE statement is executed once the script that has been included has ended. Multiple scripts can also be linked into chains in which the included scripts also contain INCLUDE statements. No more than 10 scripts may be linked into a chain. External scripts can also be included by specifying an absolute path and the name of the script file: INCLUDE "C:\\scripts\\test3" The included script file must have the file extension.script. The file extension is not specified in the INCLUDE statement, just the file name. Process Automation Page 8

15 NOTE Once a script is started, an executable list of statements is created for this script and all the included scripts. The included scripts must therefore exist before the calling script is started; changes made to an included script after the calling script is started have no effect. 4.3 Signals You can use scripts to access inputs, outputs, states and simulation model parameters that can be changed online. Signals are identified in SIMIT with the Source of the signal and Signal name. The signal designation comprises both items separated by a forward slash and framed by speech marks as follows: Source/signal name Example: ADD#1/IN1 NOTE The following rules apply in the unusual event that the source or signal name contains speech marks or forward slashes: All speech marks must be preceded by a '\'. If the signal name itself contains a forward slash, then the forward slash that demarcates the source and signal must be preceded by a '\'. If the source name contains a forward slash but not the signal name, then no marking is required. This is due to the fact that the last forward slash in the signal name is assumed to be the seperator between source and signal name. 4.4 Controlling the simulation A simulation is always in one of the following three states: "Offline", "Stopped" or "Running" (Figure 4-1). Process Automation Page 9

16 Figure 4-1: Simulation state transition diagram The simulation state can be changed by a script. For example, the simulation can be stopped and started again. However, script commands are only effective if the simulation state is "Stopped" or "Running". Scripts cannot start an "Offline" simulation, nor can they end a simulation Initialising a simulation INIT is used to initialise the simulation. This statement is the same as the Simulation Initialise command in the SIMIT menu. Process Automation Page 10

17 This command is invalid if the simulation has already been started. If an attempt is made to initialise a simulation that has already been started, the following error message appears in the status bar and the script is terminated: Wrong simulation state, Script '...', Line.... NOTE Please note that the INIT script command cannot change the state from "Offline" to "Online", as a script can only be executed in Online mode Starting the simulation START is used to start the simulation. This statement is the same as the Simulation Start command in the SIMIT menu and the button on the SIMIT toolbar. A START statement in the script is ignored if the simulation has already been started. NOTE Please note that the START script command cannot change the state from "Offline" to "Online", as a script can only be executed in Online mode Starting and waiting for an absolute time GO-TO time is used to pause the script until the simulation time is equal to or exceeds time in milliseconds. is ignored if the simulation time is already equal to or greater than time. If the simulation is initialised but has not yet been started, this command will cause the simulation to begin Starting and waiting for a relative time GO-FOR time is used to pause the script until time in milliseconds has passed. If the simulation is initialised but has not yet been started, this command will cause the simulation to begin. Process Automation Page 11

18 4.4.5 Starting and waiting for a certain number of cycles GO n is used to pause the script for n cycles. The cycles are counted in the script time slice. The parameter n can be omitted if the script is to be paused for just one cycle, i.e. for n=1. If the simulation is initialised but has not yet been started, this command will cause the simulation to begin Starting and waiting for an event GO-UNTIL Condition TIMEOUT time is used to pause the script until the Condition is met or the TIMEOUT time specified in the simulation in milliseconds has expired. Example: GO-UNTIL OR#1/Y TIMEOUT You do not have to enter a time value for TIMEOUT. The script would then no longer exit of its own accord if the condition was not met! If the simulation is initialised but has not yet been started, this command will cause the simulation to begin Stopping the simulation STOP is used to stop the simulation. This statement is the same as the Simulation Stop command in the SIMIT menu. A STOP statement in the script is ignored if the simulation has already been stopped Executing an individual step STEP is used to carry out an individual step in the simulation. This statement is the same as the Simulation Individual step command in the SIMIT menu. This statement is invalid if the simulation is already running cyclically. Otherwise the following error message appears in the status bar and the script is terminated: Wrong simulation state, Script '...', Line.... Process Automation Page 12

19 NOTE A simulation step is always one step of the fastest submodule, i.e. the submodule with the shortest cycle time Saving a snapshot SAVE-IC "name" is used to save a snapshot in the simulation project under the name name. The snapshot is always saved at the highest level in the Snapshot folder. The specifying of subfolders is not permitted. STOP WARNING Snapshots with the same name that already exist in your simulation project will be overwritten without any warning prompt and any data saved in this snapshot will be lost Loading a snapshot LOAD-IC "name" is used to load a snapshot with the name name from the simulation project Snapshot folder. The specifying of subfolders is permitted. Any hyphens in the name must be doubled. Example: LOAD-IC name LOAD-IC subfolder\\name If no snapshot with this name exists, the following error message appears in the status bar and the script is terminated: Snapshot '...' cannot be loaded, possibly the file does not exist, Script '...', Line.... After a snapshot is loaded, the simulation is stopped and must be restarted using either the STEP or START statement Resetting the simulation time SIMTIME-RESET is used to reset the simulation time to zero. The simulation state otherwise remains unchanged. Process Automation Page 13

20 CAUTION Please note that resetting the simulation time will cause inconsistencies in the TME expansion module graphs. This is because all the values in the graph are recorded against the simulation time. 4.5 Controlling the script You can exit a running script using a statement in the script or a by initiating a dialogue during the script runtime to display various processing options Pausing the script BREAK is used to pause the script. If the BREAK statement is used in an included script, processing resumes with the calling script Terminating the script QUIT is used to terminate the script. If the QUIT statement is in an included script, the calling script will also be terminated The query dialogue DIALOG "text" MODE is used to stop the simulation and a query dialog with the content text is opened. The Mode parameter can be used in conjunction with Table 4-1 to determine which buttons this dialog will have. Mode Button Yes No OK Cancel YESNOCANCEL X X - X OKCANCEL - - X X YESNO X X - - OK - - X - Table 4-1: Buttons for dialogs Process Automation Page 14

21 YESNOCANCEL is the default mode. Pressing Cancel in the dialog will terminate the script and the simulation stays stopped. In all other cases, the simulation is restarted and script execution resumes. In the example DIALOG "Ready?" YESNOCANCEL the dialog shown in Figure 4-2 appears. Figure 4-2: Example of a query dialog If a log file has already been opened in the script before the DIALOG statement, it will be noted in the file whether the dialog was closed using the Yes or No button. Therefore the entry or DIALOG text True DIALOG text False is made in the log file. It is possible to use the binary variables and _result _ok. in the script to check which action the user took using a YESNOCANCEL dialog. The variable _result is marked with True if the most recently opened dialog was closed with "Yes", whereas False indicates it was closed with "No". The variable _ok is also set to False if the dialog was closed with "No". This variable is not automatically reset to True, but this can be performed using a statement if desired. 4.6 Logging You can log the results of your simulation, i.e. signal values or events. Script statements can be used to create log files in which outputs are documented. Script statements to output data are ignored if no log file is open when the script is executed Opening and closing log files OPEN-LOG "name" Process Automation Page 15

22 is used to open a log file with the name name. Any log file that may already be opened is closed first. The log file must be entered with your absolute path. Any hyphens in the name must be doubled. Example: OPEN-LOG "c:\\protocol\\log.txt" STOP WARNING Any log file that already exists with the same name will be overwritten without warning. Data already saved in the log file will be lost. You must close the log file either at the end of the script or at the point where you no longer wish to record any more data. CLOSE-LOG closes the log file. STOP WARNING The outputs are not saved in the log file if the log file was not closed by a statement before the end of a script. The log file is then empty Unformatted output PRINT "Signal" saves the current value of the signal Signal in the open log file. Inputs, outputs, states and component parameters that can be changed online may be used as signals. Binary values are output as True or False Formatted output PRINTF "Formatstring", "Signal1", "Signal2", saves in the open log file the current values of the signals listed in the statement. The Formatstring contains the format specification for each signal; every signal must contain precisely one format specification. The format string may also contain text. The permitted format statements are listed in Table 4-2. Signal type Format statement Process Automation Page 16

23 analogue, integer, binary integer %i binary %f or %.nf (n: number of decimal places), binary values are output as "0" or "1". %b (provides "True or "False ) Table 4-2: Format statements A backslash must be placed in front of the percentage sign if you would like the percentage sign to be output as a normal character: \%. Use the PRINTF statement without a signal specification if you want to output a fixed text only. Signals may be any input signals, output signals, states and component parameters that can be changed online - see section 4.3. In the example PRINTF "Ramps: %.2f [ULR=%b] [LLR=%b]", "Ramp#1/Y", "Ramp#1/ULR", "Ramp#1/LLR" the following log file is created: Ramps: 0.00 [ULR=False] [LLR=True] Outputting time and date You can enter the time and date of your computer into the log file using the system variables listed in Table 4-1: Syntax _t_day _t_mon _t_year _t_hour _t_min _t_sec Table 4-3: Description Day Month Year Hour Minute Second System variables All figures appear as two digits. For example, the following statements PRINTF "Date: %.0f.%.0f.%.0f", "_t_day", "_t_mon", "_t_year" PRINTF "Time: %.0f:%.0f:%.0f", "_t_hour", "_t_min", "_t_sec" generate the following entries in the log file: Date: Time: 12:55:13 Process Automation Page 17

24 NOTE The system variables in Table 4-1 can only be used for logging and cannot be used for general calculations within a script Outputting version information You can enter the version of your current project and the currently used SIMIT version into the log file using the system variables _ProjectVersion and _SIMITVersion. For example, the following statements PRINTF "Project version: %", "_ProjectVersion" PRINTF "SIMIT version: %s", "_SIMITVersion" generate the following entries in the log file: Project version: AA SIMIT version: The _printlog system function It is also possible to write to an open log file directly from the components. However, to do this you will have modify the behaviour description of the relevant component types, i.e. the system function _printlog("string"); to add output text. When called, this function writes the text in the string directly to the open log file. NOTE You will need the SIMIT component type editor (CTE) if you want to edit the behaviour description of component types. The component type editor is a SIMIT expansion module that enables you to create your own component types. 4.7 Signal curves You can define signals in the script whose values are to be written cyclically to a plot file. Only one plot file can be open in a script at any time Opening and closing a plot file OPEN-PLOT "File name" Process Automation Page 18

25 opens the plot file File name and starts to record the signals. The name of the file (File name) must be specified with its absolute path; any hyphens must be doubled. A plot file that is already open is closed first. An existing file called File name will be overwritten without warning. NOTE The signals to be recorded must be defined before the file is opened. The first line of the plot file shows the signal names of the signals to be recorded. In each remaining line, the simulation time is recorded in milliseconds and the signal values, separated by tabs, are entered in the sequence specified in the first line. CLOSE-PLOT closes the plot file and the list of signals to be recorded is deleted. sequence STOP INIT START PLOT "Ramp#2/Y" PLOT "Ramp#2/ULR" PLOT-CYCLE 500 OPEN-PLOT "D:\\plot.txt" GO-FOR 4000 CLOSE-PLOT would add the following to the plot file: Ramp#2/Y Ramp#2/ULR False False False False False False True True True Specifying signals PLOT "Signalname" adds the signal Signalname to the list of signals to be recorded. Please note that the list of signals to be output must be created before the plot file is opened. You can record input signals, output signals, states and component parameters that can be changed online within your simulation project. Process Automation Page 19

26 4.7.3 Specifying a cycle PLOT-CYCLE time specifies the cycle in which the signals are to be recorded. The cycle time time specified in milliseconds is rounded to the next multiple of the script cycle time. If you do not add this statement to your script, the script cycle time will be used for the recording. Please note that the cycle time must be specified before the plot file is opened. 4.8 Setting signals Input signals, state variables and component parameters that can be changed online can be set by statements in the script. You can also set these variables to predefined values or apply a linear change to the values. NOTE If you set inputs that are linked to the outputs in the simulation project, or give values for states of a component that are set in the component itself, the value specified in the script will be completely ignored or will only be effective during one computing cycle Setting individual values "Signal" = Value sets the specified Signal to the given Value. Example: "Status/1/BI" = True Instead of a constant value, you can also specify an expression. An expression consists of constants or signals that are linked to each other by operators. The permitted mathematical operators are listed in Table 4-4, while the permitted Boolean operators are listed in Table 4-5. Operator Description ( ) Brackets * / + - Multiplication Division Addition Subtraction Table 4-4: Arithmetic operators Operator Description Process Automation Page 20

27 ( ) Brackets! not && and or Table 4-5: Boolean operators The operators are listed in both tables from highest to lowest priority. Example: "Display/E" = 2 * ("Slider/A" + 0.5) NOTE Please note that a value that has been assigned to a signal will not be available in that signal until the next execution cycle. If, for example, you have set a signal using a statement in the script, and you want to use this signal to assign a value or output its value in the statement that immediately follows, then the signal will still have the value that it had at the beginning of the cycle Defining a signal curve RAMP "Signal" FROM start TO end IN time allows you to set an analogue input signal or the state of a component to a linearly rising or falling value. This statement sets the value start and then increases or decreases the value until it reaches the value end over the time in milliseconds; i.e. the value changes linearly (ramp). Script execution continues during the specified time time, i.e. other statements in the script are executed without waiting for the signal to reach its specified end value. A script is only terminated once all the signals set using ramps have reached their end values. Examples: RAMP "Display#1/X" FROM 20.0 TO 10.0 IN RAMP "variable" TO end IN time There is no start value (FROM start) in the second statement. The start value in this case is the current value. 4.9 Conditional execution s IF expression THEN block1 ELSE block2 Process Automation Page 21

28 ENDIF allow you to set conditions for the execution of statements. If the condition expression is true, the statement list block1 is executed; otherwise list block2 is executed. Both statement lists comprise one or several lines containing any statements you wish and may therefore contain conditional statements. The conditional statement can be nested. The ELSE statement can also be omitted: IF expression THEN block ENDIF Please note that every IF statement has to have a corresponding ENDIF statement. Examples: IF "Button/1/Z" == True THEN "Display/E" = 2.0 * ("Slider/A" + 0.5) ELSE "Display/E" = "Slider/A" ENDIF IF "Button#1/Z" THEN "Display/E" = 2.0 * ("Slider/A" + 0.5) ELSE IF!"Button#2/Z" THEN "Display/E" = 3.0 * ("Slider/A" + 0.5) ELSE "Display/E" = "Slider/A" ENDIF ENDIF The condition expression can be used to access component input signals, output signals and states. You may choose from the following comparison operators: Operator Description < Less than <= Less than or equal to > Greater than >= Greater than or equal to == Equal to!= Not equal to Table 4-6: Comparison operators Process Automation Page 22

29 CAUTION When checking analogue signals for equality/non-equality, please note that a floating point format is used for the signals. The values calculated for these signals may therefore be different from the expected value as they will have been rounded; a comparison provides different results to those expected. A condition can be made up of several expressions that are linked by Boolean operators (see Table 3-1) Accessing the simulation time The system variable _Time contains the current simulation time in milliseconds. In the example IF ("_Time" > 20000) THEN PRINTF "Simulation time: %.0fms", "_Time" ENDIF the output sent to the log file might be: Simulation time: 26600ms Process Automation Page 23