User Reference:Operator Module Scripting
Operator scripts automate actions that the otherwise would be performed by the user, e.g. starting or suspending system operation. Scripts may be contained in script files, or given immediately in the operator module's preferences dialog. There is also an option to specify scripts from the command line when starting the operator module. When using the Operator Library from your own application, you may execute scripts at any time.
Also, the operator scripting language is used to control an operator module over a telnet connection.
In the Operator GUI, script execution is bound to a number of events that occur during various stages of BCI2000 system operation:
This event is triggered at startup, as soon as all modules are connected to the operator module.
This event is triggered each time a set of parameters is applied to the system. This happens when the user clicks the SetConfig button. Execution of the SETCONFIG command also triggers this event.
These events correspond to the Start/Resume button. One of these events is also triggered when the Running state variable is set to 1 from a script. Whether OnStart or OnResume is triggered depends on whether the system has been running before with the current set of parameters.
Triggered when the system goes from running into suspended mode. This happens whenever the Running state variable changes from 1 to 0. This may happen when the user clicks Suspend, when the application module switches the system into suspended mode, or when a script sets the Running state variable to 0.
Triggered when the operator module shuts down connections, and switches into idle state.
Triggered when the operator module exits. Execution of the QUIT command also triggers this event. This event is not available to the SET SCRIPT and CLEAR SCRIPT commands. Also, when both an OnShutdown and an OnExit script are defined, the OnExit script will be executed before the OnShutdown script.
Commands operating on Scripts
SET SCRIPT <events> <scripting commands>
Associates a sequence of scripting commands with the given events. Events are specified by names as given above. Multiple events may be specified by concatenating their names with a pipe character, e.g. "OnStart|OnResume".
Scripting commands must be included in double quotes, unless they consist of a single word. When specifying a sequence of scripting commands, they must be separated with a semicolon character: "SetConfig; Start". In order to use double quotes or semicolons within the commands themselves, encode these as you would in an URL, i.e. replace a double quote character with %22, and a semicolon with %3B: "Load Parameters %22my file%22".
To associate an event with a script file rather than a literal script, use the EXECUTE SCRIPT command:
SET SCRIPT OnConnect "EXECUTE SCRIPT myscript.txt"
CLEAR SCRIPT <events>
Clears scripts for the given events. Equivalent to calling SET SCRIPT with an empty script.
EXECUTE SCRIPT <file or event>
Executes a script contained in a file. To execute a script associated with an event, provide an event name rather than a file.
Commands operating on Parameters
LOAD PARAMETERFILE <file>, LOAD PARAMETERS <file>
Loads a parameter file specified by its path and name. Relative paths are interpreted relative to the operator module's working directory at startup. Usually, this matches the executable's location in the prog directory. As the parameter file name must not contain white space, please use HTML-type encoding for white space characters, such as Documents%20and%20Settings when referring to a user's "Documents and Settings" folder.
INSERT PARAMETER <parameter definition>
Adds a parameter to the system. The parameter is specified as a parameter line. This command may not be used after system initialization has completed, i.e. its use is restricted to the "Idle" and "Publishing" phases of system operation. In terms of events, its use is restricted to the OnConnect event.
SET PARAMETER <name> <value>
Sets the named parameter to the specified value. Values that contain special characters, or whitespace must use the parameter value encoding. Use parentheses to specify indices or labels.
SET PARAMETER <parameter line>
Replace a parameter's value and definition with the information given in the parameter line. The parameter must exist in the system when this command is executed. 0
GET PARAMETER <name>
Prints the value of the named parameter. Use parentheses to specify indices or labels.
LIST PARAMETER <wildcard expression>, LIST PARAMETERS
Prints all parameters with names matching the wildcard expression, in form of parameter lines.
Clears the list of parameters in the system. May only be executed in Idle and Publishing system states.
Commands operating on States
INSERT STATE <name> <bit width> <initial value>
Adds a state variable to the system. State variables are defined by name, bit width, and initial value (see Technical Reference:State Definition). This command may not be used after system initialization has completed, i.e. its use is restricted to the "Idle" and "Publishing" phases of system operation. In terms of events, its use is restricted to the OnConnect event.
SET STATE <name> <value>
Sets the named state variable to the specified integer value. Setting the Running state to 1 will start system operation, setting it to 0 will suspend the system.
GET STATE <name>
Gets the value of the named state. Note that state values are not updated from the application module when the OperatorBackLink parameter is 0. In that case, GET STATE will return the state's initial value.
LIST STATE <wildcard expression>, LIST STATES
Lists all states, or states with names matching the given wildcard expression, in form of state lines.
Clears the list of states in the system. May only be executed in Idle and Publishing system states.
Commands operating on Events
Events are a special type of state, which are recorded asynchronously, at single-sample resolution. Events may only be added while the system is in "idle" state.
INSERT EVENT <name> <bit width> <initial value>
Adds an event to the system. Like state variables, events are defined by name, bit width, and initial value (see Technical Reference:State Definition). This command may not be used after the system has started up, so it is typically executed within a telnet session before STARTUP has been called.
SET EVENT <name> <value>
Asynchronously sets an event to the given value. Recording events requires the EventLink logger component to be present in the source module.
GET EVENT <name>
Gets the value of the named event. Note that evemt values are not updated from the application module when the OperatorBackLink parameter is 0.
LIST EVENT <wildcard expression>, LIST EVENTS
Lists all events, or events with names matching the given wildcard expression, in form of state lines.
Clears the list of events in the system. May only be executed in Idle state.
Commands operating on VisProperties
SET VISPROPERTY <visID>.<name> <value>
Sets the named visualization property for the specified visualization ID to the given value. If the visualization ID contains a dot character, it must be encoded in parameter value encoding. E.g., setting the window width for the visualization ID "2.D1" would be written
SET VISPROPERTY 2%2ED1.Width 200.
GET VISPROPERTY <visID>.<name>
Prints the value of the named visualization property for the specified visualization ID.
SET VISPROPERTIES <property set ID>
Applies a set of visualization property values as given in the VisPropertySets parameter. In that matrix-valued parameter, row labels specify visualization properties such as "SRCD.Left", and columns represent sets of property values. Column labels are IDs of the corresponding property sets.
Commands operating on the Control Signal
GET SIGNAL( <channel index>, <element index> )
Prints the value of the control signal at the given indices. Indices are 1-based.
GET SYSTEM STATE
Prints the current system state. This will be one of Unavailable, Idle, Startup, Initialization, Resting, Suspended, ParamsModified, Running, Termination, Busy.
WAIT FOR <system state> <timeout seconds=5>
Waits until the system is in the specified state. This may be one of Unavailable, Idle, Startup, Initialization, Resting, Suspended, ParamsModified, Running, Termination, Busy, or a combination of these, separated with a pipe character: "Resting|Suspended". When timeout occurs, an error message is returned.
GET SYSTEM VERSION
Prints BCI2000 version information.
SETCONFIG, SET CONFIG
Applies current parameters to the system. Corresponds to the SetConfig button in the GUI version of the Operator module.
Starts or resumes system operation, corresponding to the Start/Resume button in the GUI version of the Operator module.
Stops system operation. Corresponds to the Stop button in the GUI version of the Operator.
When in idle state, starts up the system to wait for incoming connections from core modules.
Shuts down core modules, and enters idle system state.
Quits the operator module after terminating all BCI2000 modules.
SYSTEM <command line>
Executes a shell command, redirecting any console output into the command's script result. E.g., to obtain a directory listing, under Windows, you would enter
START EXECUTABLE <command line>
Starts the specified executable with options. This command returns immediately after the started program has finished initialization.
Append the specified message to the system log.
Append the specified message to the system log, formatted as a warning.
Append the specified message to the system log, formatted as an error message.
CAPTURE MESSAGES <message types>
Captures system log messages into a background buffer. When no message type is given, all messages are captured. When "None" is given as a message type, message capturing is disabled. Otherwise, the message type must be one of "Errors", "Warnings", "Debug", "Log". Multiple message types may be specified in a single command. When "None" appears within a single command, all preceding message types are ignored. Multiple CAPTURE MESSAGES commands are cumulative, except when "None" is specified as a message type.
Clears the background message buffer, and returns its previous content. Use CAPTURE MESSAGES to capture messages into the background message buffer.
Scripts consist of sequences of the above commands, terminated with either a DOS line ending sequence, or a semicolon (;). When the semicolon is used to terminate commands, a line may contain multiple commands. Commands are case-insensitive, values are case-sensitive.
Command arguments containing white space must be included in double quotes, or the white space must be encoded in URL-fashion, e.g. %20 instead of a space character. Similarly, when an argument contains a semicolon (;), it must be included in double quotes, or the semicolon must be encoded in URL-fashion, i.e. as %3B.
Associating Scripts with Events
In the operator module's preferences dialog, scripts may be entered for each of the events listed above. Scripts may be specified as paths to script files, or as immediate one-line scripts. Entries that start with a minus sign (-) are treated as one-line scripts, which may contain multiple commands separated with semicolons.
Scripts may also be specified from the command line used to start up the operator module. There, event names are followed with the content of the respective preference entry, enclosed in double quotes ("...").
Finally, scripts may be specified using the SET SCRIPT command of the scripting language itself.
To add a state variable called "Artifact", and to set it using the operator's function buttons, do this:
- Enter the following line under "After All Modules Connected" in the operator's preferences dialog (note the minus sign):
-INSERT STATE Artifact 1 0
- Under "Function Buttons", enter "Set Artifact" as the name of button 1, and as its command, enter (note there is no minus sign):
SET STATE Artifact 1
- Enter "Clear Artifact" as the name of button 2, and as its command, enter
SET STATE Artifact 0
The following example shows how to specify script commands from the command line. It fully automates BCI2000 operation by loading a parameter file, applying parameters, starting the system once the parameters are applied, and quitting the system once the run is over. For better readability, the example is broken across lines; for execution, the command needs to be entered as a single line.
operator.exe --OnConnect "-LOAD PARAMETERFILE ..\parms\examples\CursorTask_SignalGenerator.prm; SETCONFIG" --OnSetConfig "-SET STATE Running 1" --OnSuspend "-QUIT"