Sequencer: Difference between revisions

From MidasWiki
Jump to navigation Jump to search
 
(17 intermediate revisions by 2 users not shown)
Line 18: Line 18:


For instructions on '''getting started with the sequencer''', see [[Sequencer Page]]
For instructions on '''getting started with the sequencer''', see [[Sequencer Page]]
= Controlling the sequencer from custom pages =
The normal interface is the "Sequencer" status page in MIDAS. In addition, the sequencer can be controlled by other means. The ODB contains a directory '''/Sequencer/Command''', which contains the currently loaded filename and three switches. To load new file and compile it, set the '''Load filename''' and the '''Load new file''' to '''yes'''.
  modbset(['/Sequencer/Command/Load filename',
          '/Sequencer/Command/Load new file',
          ['test.msl', 'Yes'])
After a script has been loaded, all '''PARAM''' values are extracted and placed under '''/Sequencer/Param/Defaults'''. Before a script is actually started, the default values may be modified and must be placed under '''/Sequencer/Param/Value''' before the sequencer is started. To start the script, set '''Start script''' to '''yes'''. This can be done in a combined way on a custom page via
  modbset(['/Sequencer/Param/Value/First parameter',
          '/Sequencer/Param/Value/Other parameter',
          '/Sequencer/Command/Start script'],
          ['123', '456', 'Yes'])
The parameter names of course have to be adjusted to the current script.
The starting of the script via above '''modbset''' can be put in the '''onclick=...''' method of a button, or even into a side menu via an alias by putting an ODB key into '''/Alias/xxx''' and setting it to '''javascript:modbset(...)'''.


= Sequencer Commands =
= Sequencer Commands =
Line 29: Line 48:
|-
|-
||INCLUDE ''name''
||INCLUDE ''name''
||Include another XML file ''name''.xml
||Include another MSL file ''name''.msl
|-
||BREAK
||Break (finish prematurely) a loop. This is usually used together with an IF statement to abort a loop like
<pre>
LOOP 10
  IF ($x > 0)
    BREAK
  ENDIF
ENDLOOP
</pre>
|-
|-
||CALL ''name'', ''a'', ''b'', ''c'', ...
||CALL ''name'', ''a'', ''b'', ''c'', ...
Line 39: Line 68:
||COMMENT ''comment''
||COMMENT ''comment''
||A comment for this XML file, for information only. This comment is shown in the title bar next to the file name if one runs a script. This can be helpful if one has many XML files and the file name only is not enough to supply enough information.
||A comment for this XML file, for information only. This comment is shown in the title bar next to the file name if one runs a script. This can be helpful if one has many XML files and the file name only is not enough to supply enough information.
|-
||EXIT
||Exit script immediately
|-
|-
||GOTO ''n''
||GOTO ''n''
Line 64: Line 96:
||MESSAGE ''message'' [,1]
||MESSAGE ''message'' [,1]
||Opens a message box in the browser containing the text message. If wait="1", then the sequencer waits until the box is closed by the user before continuing.
||Opens a message box in the browser containing the text message. If wait="1", then the sequencer waits until the box is closed by the user before continuing.
|-
||MSG ''message'' [,<type>]
||Produces a midas message going into the message buffer. The optional <type> can be any of ERROR, INFO, DEBUG, LOG, TALK. If no type is given, INFO is used.
|-
|-
||ODBCREATE ''path'', ''type'' [, ''size'']
||ODBCREATE ''path'', ''type'' [, ''size'']
Line 105: Line 140:
JSON, XML and ODB file format are supported with the value inferred by the content of the file.
JSON, XML and ODB file format are supported with the value inferred by the content of the file.
The optional path marks the position where to load the given file into the ODB, if no position is given the file is loaded from ODB root.<br>
The optional path marks the position where to load the given file into the ODB, if no position is given the file is loaded from ODB root.<br>
For the input file few options are supported: if the filename starts with "/" is is assumed as an absolute path, if it starts with a "$" the path starts from the Sequncer root folder stored in the ODB by /Sequencer/Path. In all other cases it is intended as a relative path to the local MSL file.
For the input file several options are supported: if the filename starts with "/" is is assumed to be an absolute path, if it starts with a "$" the path starts from the Sequencer root folder stored in the ODB at /Sequencer/Path. In all other cases it is intended as a relative path to the local MSL file.
|-
||ODBSAVE ''path'', ''file''
||Save part of the ODB to an external file.<br>
The file extension is used to determine the format. Possible values are ".json", ".xml" and ".odb".
The path can point to an individual value in the ODB or to a whole subtree.<br>
For the output file several options are supported: if the filename starts with "/" is is assumed to be an absolute path, if it starts with a "%" the path starts from the Sequencer root folder stored in the ODB at /Sequencer/Path. In all other cases it is intended as a relative path to the local MSL file. If the file name contains a variable (starting with '$') it gets evaluated before saving.
|-
|-
||ODBSUBDIR ''path'' ...ENDODBSUBDIR
||ODBSUBDIR ''path'' ...ENDODBSUBDIR
Line 125: Line 166:
</pre>
</pre>
|-
|-
||PARAM ''name'', ''comment'', [''a'',''b'',''c'' | bool]
||PARAM ''name'', ''comment'', [''default''], [''a'',''b'',''c'' | bool]
||When starting a script, a start page is shown where one can enter additional parameters for the script. Parameters can be defined either centrally for all scripts in the ODB under /Experiment/Edit on sequence. This subdirectory in the ODB can contain links to ODB values, which are queried at the start page. In addition, each script can define additional parameters appended to this list. They will be stored under /Sequencer/Variables and can be referenced inside the script via $name, where name can be any variable name specified in the parameter statement. The optional "comment" is shown on the start page below the parameter name. If only certain options are possible for the parameter, they can be defined via the options list. The web page will then contain a drop-down list showing the options. In case of type="bool", a checkbox will be shown.
||When starting a script, a start page is shown where one can enter additional parameters for the script. Parameters can be defined either centrally for all scripts in the ODB under /Experiment/Edit on sequence. This subdirectory in the ODB can contain links to ODB values, which are queried at the start page. In addition, each script can define additional parameters appended to this list. They will be stored under /Sequencer/Variables and can be referenced inside the script via $name, where name can be any variable name specified in the parameter statement. The optional "comment" is shown on the start page below the parameter name. An optional "default" value can be specified for each parameter. If only certain options are possible for the parameter, they can be defined via the options list. The web page will then contain a drop-down list showing the options. In case of type="bool", a checkbox will be shown.
|-
|-
||RUNDESCRIPTION ''description''
||RUNDESCRIPTION ''description''
Line 132: Line 173:
|-
|-
||SCRIPT ''script'' [, a, b, c, ...]
||SCRIPT ''script'' [, a, b, c, ...]
||To call a script on the server side. Optionally, pass parameters to the script.
||To call a script on the server side. Optionally, pass parameters to the script. Any ASCII result from the script is stored as a string in the MSL variable $SCRIPT_RESULT. The ''script'' can be a direct command to be executed on the shell level, or can be a shell script which then gets executed, or can be an executable. If one has to pass several variables back to the MSL script, one can use the trick to store them into an ODB file (ASCII, XML or JSON format) and then use the <code>ODBLOAD</code> command to put the values into the ODB. Try the <code>ODBSAVE</code> command to see how the ODB format should look like.<p>
The PATH environment is inherited from the place when the <code>msequencer</code> program is started. It can be checked with a simple shell script <code>echo $PATH</code> and then displaying the result with the MSL script command <code>message $SCRIPT_RESULT, 1<code>.
|-
|-
||SET ''name'', ''value''<br>
||SET ''name'', ''value''<br>
Line 152: Line 194:
|}
|}


= MSL Example =
= MSL Examples =
The following example is a simple script, which writes a run description to the ODB, asks for a number of runs, then executes the runs, each running for 60 seconds.
The following example is a simple script, which writes a run description to the ODB, asks for a number of runs, then executes the runs, each running for 60 seconds.


Line 162: Line 204:
LOOP $runs
LOOP $runs
     TRANSITION START
     TRANSITION START
     WAIT Seconds 60
     WAIT Seconds, 60
     TRANSITION STOP
     TRANSITION STOP
ENDLOOP
ENDLOOP
</pre>
The following script is a more complex example, which measures a I-V curve (e.g. of a SiPM detector) and stores it in the ODB. It assumes a power supply operated by a front-end and linked to /Equipment/KEYTHLEY/. The I-V curve in the ODB can be plotted with a midas custom page.
<pre>
#
# I-V-Curve test with parameter specification at startup
#
PARAM start_voltage, "Starting voltage"
PARAM stop_voltage, "Stop voltage"
PARAM num_steps, "Number of steps"
# Calculate step size
num_steps = $num_steps + 1 # add one step for stop_voltage
step_size = ($stop_voltage-$start_voltage) / ($num_steps-1)
# Initialize measurement arrays at startup
ODBCREATE /Equipment/Test/Variables/Voltage, FLOAT, $num_steps
ODBCREATE /Equipment/Test/Variables/Current, FLOAT, $num_steps
ODBCREATE /Equipment/Test/Variables/V, FLOAT
# Erase any previously stored array
ODBSET /Equipment/Test/Variables/Voltage[*], 0
ODBSET /Equipment/Test/Variables/Current[*], 0
v = $start_voltage
ODBSET /Equipment/Test/Variables/V, $v
current = 0
# Turn on Keithley
ODBSET /Equipment/KEITHLEY/Variables/Set State, 1
# Wait to turn on
WAIT SECONDS, 2
# Looping starts at 1
LOOP i, $num_steps
    # Store voltage in array and in variable
    ODBSET /Equipment/Test/Variables/Voltage[$i-1], $v
    ODBSET /Equipment/Test/Variables/V, $v
    # Set voltage and measure
    ODBSET /Equipment/KEITHLEY/Variables/Demand Voltage, $v
    # Wait for measurement to be stored in Current
    WAIT SECONDS, 10
    ODBGET /Equipment/KEITHLEY/Variables/Current, current
   
    # Outputting current to ODB array
    ODBSET /Equipment/Test/Variables/Current[$i-1], $current
    # increment voltage
    v = $v + $step_size
ENDLOOP
# Turn off Keithley
ODBSET /Equipment/KEITHLEY/Variables/Set State, 0
# Wait to turn off
WAIT SECONDS, 1
</pre>
</pre>


[[Category:Sequencer]]
[[Category:Sequencer]]

Latest revision as of 08:19, 4 December 2023


Links

Introduction

A Sequencer for starting and stopping runs is part of the MIDAS distribution. It uses a simple Midas Script Language (MSL) for commands.

The sequencer runs as a separate process and must be started before running a sequence via the command msequencer. The first time the Sequencer button on the Status Page is pressed, the ODB Sequencer Tree is created. If the Sequencer button is not present on the Status Page, it may have been suppressed.

The sequencer runs scripts in MSL (Midas Script Language) format, which reside on the server (where mhttpd is running). The sequencer state is completely stored in the ODB, meaning that even if mhttpd or the sequencer is stopped and restarted, the active sequence operation continues exactly where it has been stopped.

Refer to the /Sequencer ODB tree for more details on its organization.

For instructions on getting started with the sequencer, see Sequencer Page

Controlling the sequencer from custom pages

The normal interface is the "Sequencer" status page in MIDAS. In addition, the sequencer can be controlled by other means. The ODB contains a directory /Sequencer/Command, which contains the currently loaded filename and three switches. To load new file and compile it, set the Load filename and the Load new file to yes.

 modbset(['/Sequencer/Command/Load filename',
          '/Sequencer/Command/Load new file',
         ['test.msl', 'Yes'])

After a script has been loaded, all PARAM values are extracted and placed under /Sequencer/Param/Defaults. Before a script is actually started, the default values may be modified and must be placed under /Sequencer/Param/Value before the sequencer is started. To start the script, set Start script to yes. This can be done in a combined way on a custom page via

 modbset(['/Sequencer/Param/Value/First parameter',
          '/Sequencer/Param/Value/Other parameter',
          '/Sequencer/Command/Start script'],
         ['123', '456', 'Yes'])

The parameter names of course have to be adjusted to the current script.

The starting of the script via above modbset can be put in the onclick=... method of a button, or even into a side menu via an alias by putting an ODB key into /Alias/xxx and setting it to javascript:modbset(...).

Sequencer Commands

The following commands are implemented in the MIDAS Sequencer. The left syntax is for the XML file, the right for the MSL (Midas Script Language).

Variable names are indicated in italic, options are enclosed in [brackets].

MSL format Description
INCLUDE name Include another MSL file name.msl
BREAK Break (finish prematurely) a loop. This is usually used together with an IF statement to abort a loop like
LOOP 10
  IF ($x > 0)
    BREAK
  ENDIF
ENDLOOP
CALL name, a, b, c, ... Call a subroutine. Optional parameters a,b,c... are passed to the subroutine, where they can be referenced via $1, $2, $3, etc. The subroutine can either reside in the current file, or in a library file which is included.
CAT name, a, b, c, ... Concatenates the strings a,b,c,... into a single variable name . Can be referenced with $name. If a string must contain a comma, it can be enclosed in quotes such as in CAT title $run, ",", $n events
COMMENT comment A comment for this XML file, for information only. This comment is shown in the title bar next to the file name if one runs a script. This can be helpful if one has many XML files and the file name only is not enough to supply enough information.
EXIT Exit script immediately
GOTO n Jump to line n in script
IF con
or
IF (con)

...
ELSE
...
ENDIF

Statements between "IF" and "ENDIF" are only executed if condition "con" is true, otherwise the statements between the optional "ELSE" and "ENDIF" are executed. The condition can use any math expression using variables via $name together with operators "<", "<=", ">", ">=", "==", "!=", "&" (bitwise AND). Up to four nested IF statements are possible. An example would be "IF ($x+3 > $y*4+$z^2)".
LIBRARY name Indicates that the current file is a library (which can be included by other files). A library usually consists of a set of subroutines.
LOOP [name ,] n ... ENDLOOP To execute a loop n times. For infinite loops, "infinite" can be specified as n. Optionally, the loop variable running from 1...n can be accessed inside the loop via $name.
LOOP name, a, b, c, ... ... ENDLOOP Loop though a list of values. The loop is executed once for each value, which is stored into the variable name so it can be accessed inside the loop via $name.
MESSAGE message [,1] Opens a message box in the browser containing the text message. If wait="1", then the sequencer waits until the box is closed by the user before continuing.
MSG message [,<type>] Produces a midas message going into the message buffer. The optional <type> can be any of ERROR, INFO, DEBUG, LOG, TALK. If no type is given, INFO is used.
ODBCREATE path, type [, size] Create an ODB key of type type and optional size size (for arrays). type can be UNIT8, INT8, UNIT16, INT16, UNIT32, INT32, BOOL, FLOAT, DOUBLE, STRING
ODBDELETE path Delete an ODB key. If path points to a ODB subdirectory, delete the whole subdirectory.
ODBGET path, name To get a value from a variable name. The variable can then be referenced with $name. If the ODB value is an array, the index can be specified like via a constant or expression:
ODBGET "/Path/key[15]", v
ODBGET "/Path/key[$i + 15]", v
ODBINC path [, delta] To increment a value in the ODB. delta can be positive or negative. If no "delta" is given, 1 is used.
ODBSET path, value [, 0|1] To set a value in the ODB. value can be any math expression containing variables (preceded by a '$'). path can also contain variables (preceded by a '$'), but no math expressions.

If the ODB key referenced by path is an array, the index can be specified such as

ODBSET "/Path/value[3]", 1     # individual value
ODBSET "/Path/value[3-5]", 2   # index range 3,4,5
ODBSET "/Path/value[*]", 0     # all values of array

The path value can match multiple keys using the '?' and '*' wildcard (one or any number of characters respectively). This is useful to set the same sub-path on multiple folders:

ODBSET "/Path/to/somewhere/folder0/value", "1"
ODBSET "/Path/to/somewhere/folder1/value", "1" 
ODBSET "/Path/to/somewhere/folder2/value", "1"

can be shortened as:

ODBSET "/Path/to/somewhere/folder*/value", "1"

The notify flag specifies if possible hot-links to this ODB value are notified. This can be useful if a front-end program has many parameters, which must be set for a specific run. The front-end usually has a hot-link to its parameters, so on each modification a callback function in the front-end is called which usually modifies some hardware. If there are many ODBSet statements for all parameters, the callback would be executed on each ODBSet, so the hardware would be reconfigured many times slowing down the startup of a run. In order to prevent this, notify="0" can be specified for all ODBSet statements except the last one which contains notify="1", so the callback function is called only once at the end.

ODBLOAD file [, path] Load an external file into the ODB.

JSON, XML and ODB file format are supported with the value inferred by the content of the file. The optional path marks the position where to load the given file into the ODB, if no position is given the file is loaded from ODB root.
For the input file several options are supported: if the filename starts with "/" is is assumed to be an absolute path, if it starts with a "$" the path starts from the Sequencer root folder stored in the ODB at /Sequencer/Path. In all other cases it is intended as a relative path to the local MSL file.

ODBSAVE path, file Save part of the ODB to an external file.

The file extension is used to determine the format. Possible values are ".json", ".xml" and ".odb". The path can point to an individual value in the ODB or to a whole subtree.
For the output file several options are supported: if the filename starts with "/" is is assumed to be an absolute path, if it starts with a "%" the path starts from the Sequencer root folder stored in the ODB at /Sequencer/Path. In all other cases it is intended as a relative path to the local MSL file. If the file name contains a variable (starting with '$') it gets evaluated before saving.

ODBSUBDIR path ...ENDODBSUBDIR If one wants to se several ODB values in the same directory, the ODBSet commands can be rather long if the path is long. Using this command, the subdir can be specified for all commands between the opening and ending tags. So instead of writing
ODBSET /Very/long/path/into/the/odb/value1, 1
ODBSET /Very/long/path/into/the/odb/value2, 1
ODBSET /Very/long/path/into/the/odb/value3, 1
ODBSET /Very/long/path/into/the/odb/value4, 1

one can write

ODBSUBDIR /Very/long/path/into/the/odb
ODBSET value1, 1
ODBSET value2, 1
ODBSET value3, 1
ODBSET value4, 1
ENDODBSUBDIR
PARAM name, comment, [default], [a,b,c | bool] When starting a script, a start page is shown where one can enter additional parameters for the script. Parameters can be defined either centrally for all scripts in the ODB under /Experiment/Edit on sequence. This subdirectory in the ODB can contain links to ODB values, which are queried at the start page. In addition, each script can define additional parameters appended to this list. They will be stored under /Sequencer/Variables and can be referenced inside the script via $name, where name can be any variable name specified in the parameter statement. The optional "comment" is shown on the start page below the parameter name. An optional "default" value can be specified for each parameter. If only certain options are possible for the parameter, they can be defined via the options list. The web page will then contain a drop-down list showing the options. In case of type="bool", a checkbox will be shown.
RUNDESCRIPTION description a run description which is stored under /Experiment/Run Parameters/Run Description .
SCRIPT script [, a, b, c, ...] To call a script on the server side. Optionally, pass parameters to the script. Any ASCII result from the script is stored as a string in the MSL variable $SCRIPT_RESULT. The script can be a direct command to be executed on the shell level, or can be a shell script which then gets executed, or can be an executable. If one has to pass several variables back to the MSL script, one can use the trick to store them into an ODB file (ASCII, XML or JSON format) and then use the ODBLOAD command to put the values into the ODB. Try the ODBSAVE command to see how the ODB format should look like.

The PATH environment is inherited from the place when the msequencer program is started. It can be checked with a simple shell script echo $PATH and then displaying the result with the MSL script command message $SCRIPT_RESULT, 1.

SET name, value

or
name = value

Sets the variable name to "value". The variable can then be referenced later in the script by putting a "$" in front of the name like $"name". value can be a simple number or a complex expression containing other variables (preceded by a $) and calculations such as $v + 3*$x * sin($t). Following functions are available: abs, acos, asin, atan, atan2, ceil, cos. cosh, e, exp, fac, floor, ln, log, pi, pow, sin, sinh, sqrt, tan, tanh. A variable can be an array by using square brackets, like "a[10] = 5" or "x = $a[10]".
SUBROUTINE name ... ENDSUBROUTINE Declares a subroutine which can be called via CALL.
TRANSITION start | stop | pause | resume To start, stop, pause or resume a run
WAIT events | ODBvalue | seconds, [ODB path], [op], [value] Wait until a number of events is acquired (testing /Equipment/Trigger/Statistics/Events sent), or until a value in the ODB exceeds value, or wait for value seconds. If the operand op is given, the ODB value is compared with value using this operand. So one could wait until an ODB value is equal to value or becomes smaller than value. Here is an example of such a statement which waits until some high voltage is below 100 V.
WAIT ODBvalue, /Equipment/HV/Variables/Measured[3], <, 100

MSL Examples

The following example is a simple script, which writes a run description to the ODB, asks for a number of runs, then executes the runs, each running for 60 seconds.

COMMENT "This is a MSL test file"
RUNDESCRIPTION "Test run"
PARAM runs

LOOP $runs
     TRANSITION START
     WAIT Seconds, 60
     TRANSITION STOP
ENDLOOP

The following script is a more complex example, which measures a I-V curve (e.g. of a SiPM detector) and stores it in the ODB. It assumes a power supply operated by a front-end and linked to /Equipment/KEYTHLEY/. The I-V curve in the ODB can be plotted with a midas custom page.

#
# I-V-Curve test with parameter specification at startup
#

PARAM start_voltage, "Starting voltage"
PARAM stop_voltage, "Stop voltage"
PARAM num_steps, "Number of steps"

# Calculate step size
num_steps = $num_steps + 1 # add one step for stop_voltage
step_size = ($stop_voltage-$start_voltage) / ($num_steps-1)

# Initialize measurement arrays at startup
ODBCREATE /Equipment/Test/Variables/Voltage, FLOAT, $num_steps
ODBCREATE /Equipment/Test/Variables/Current, FLOAT, $num_steps
ODBCREATE /Equipment/Test/Variables/V, FLOAT

# Erase any previously stored array
ODBSET /Equipment/Test/Variables/Voltage[*], 0
ODBSET /Equipment/Test/Variables/Current[*], 0

v = $start_voltage
ODBSET /Equipment/Test/Variables/V, $v

current = 0

# Turn on Keithley
ODBSET /Equipment/KEITHLEY/Variables/Set State, 1
# Wait to turn on
WAIT SECONDS, 2


# Looping starts at 1
LOOP i, $num_steps
    # Store voltage in array and in variable
    ODBSET /Equipment/Test/Variables/Voltage[$i-1], $v
    ODBSET /Equipment/Test/Variables/V, $v

    # Set voltage and measure
    ODBSET /Equipment/KEITHLEY/Variables/Demand Voltage, $v
    # Wait for measurement to be stored in Current
    WAIT SECONDS, 10
    ODBGET /Equipment/KEITHLEY/Variables/Current, current
    
    # Outputting current to ODB array
    ODBSET /Equipment/Test/Variables/Current[$i-1], $current

    # increment voltage
    v = $v + $step_size
ENDLOOP

# Turn off Keithley
ODBSET /Equipment/KEITHLEY/Variables/Set State, 0

# Wait to turn off
WAIT SECONDS, 1