Difference between revisions of "Contributions:BCI2000Command"

From BCI2000 Wiki
Jump to: navigation, search
(Functional Description)
(See also)
Line 142: Line 142:
 
[[Programming Reference:BCI2000Remote Class]], [[Contributions:BCI2000PresentationLink]], [[Contributions:BCI2000Automation]], [[Contributions:BCI2000PythonBindings]], [[User Reference:BCI2000Shell]], [[Contributions:Applications]]
 
[[Programming Reference:BCI2000Remote Class]], [[Contributions:BCI2000PresentationLink]], [[Contributions:BCI2000Automation]], [[Contributions:BCI2000PythonBindings]], [[User Reference:BCI2000Shell]], [[Contributions:Applications]]
  
[[Category:Contributions]][[Category:User Application]]
+
[[Category:Contributions]][[Category:User Application]][[Category:External Interfaces]]

Revision as of 18:15, 5 July 2012

Synopsis

BCI2000Command is a command line program that controls the BCI2000 Operator. It allows remote control of BCI2000 from command interpreters (shells), such as the WIndows CMD interpreter, or the bash or tcsh shells on Unix systems., or any environment that provides access to Windows automation components. It wraps up the functionality of the BCI2000Remote C++ class. When writing C++ code, you should consider using that class directly rather than BCI2000Command.

Before you can use it, BCI2000Command must be in your operating system's path variable. Typically, you will keep BCI2000Command inside the BCI2000/prog directory, and add that directory to the path variable.

Location

http://www.bci2000.org/svn/trunk/src/contrib/ExternalLinks/BCI2000Command

Versioning

Author

juergen.mellinger@uni-tuebingen.de

Source Code Revisions

  • Initial development: 3946
  • Tested under: 3953

Functional Description

BCI2000Command is a command line interface to the BCI2000 Operator module, and allows to start up, configure, and run BCI2000 from the command line, or from command line scripts (batch files).

Calling "BCI2000Command Run" will start up the Operator module residing in the same directory as BCI2000Automation. You may then use "BCI2000 Command StartupModules" in order to start up BCI2000 core modules.

Alternatively, you may specify the path to a BCI2000 batch file in the BCI2000/batch directory in the BCI2000OperatorPath environment variable. An appropriate batch file should start up Operator and core modules, and needs to forward its command line arguments to the Operator module. All batch files coming with BCI2000 fulfil this condition. When a batch file is specified, there is no need to call the StartupModules command.

As yet another option, you may connect to an Operator module that is already running, e.g., on a remote machine on the network. In this case, set the BCI2000OperatorPath environment variable to an empty string, and the BCI2000TelnetAddress environment variable to the address that the remote Operator module is listening on, i.e. the remote machine's IP address, followed with a colon, and the port specified when starting up the remote Operator module. The remote Operator module must have been started with the --Telnet command line option, followed with the address to listen on. On the remote machine, this would typically be "localhost:3999". Don't use any of the ports between 4000 and 4002, as this will interfere with the communication between the Operator module, and BCI2000 core modules. Depending on whether the remote Operator module has been started up together with its core modules, or not, you may then call "BCI2000Command StartupModules" in order to start up BCI2000 core modules on the remote machine.

Once all BCI2000 modules are running, you may load parameter files locally or remotely using the LoadParametersLocal and LoadParametersRemote commands. Subject ID, Session ID, and data directory are set using the BCI2000SubjectID, BCI2000SessionID, and BCI2000DataDirectory environment variables.

A recording may then be started by calling the Start command. Depending on configuration, the recording will terminate automatically, or needs to be terminated by calling the Stop command.

To run BCI2000 in a different configuration (i.e., with different core modules), it is not necessary to terminate the Operator module. Rather, you may execute StartupModules multiple times in order to terminate currently running core modules, and start different ones.

Once you are done using BCI2000, you may quit the Operator module using "BCI2000Command Quit".

BCI2000Command vs. BCI2000Shell

BCI2000Command provides functionality similar to BCI2000Shell, which is a shell that executes Operator scripting commands. The choice between the two is mainly a choice between writing a shell script vs. writing a BCI2000 Operator script. One would choose BCI2000Command to integrate BCI2000 remote control into an existing system of shell scripts, whereas one would choose BCI2000Shell to use Operator scripting as the main language. However, some amount of overlap exists: BCI2000Command is able to execute arbitrary Operator scripting commands, and BCI2000Shell's -c option allows it to be run within shell scripts in a way similar to BCI2000Command. Still, BCI2000Command provides a higher-level interface than BCI2000Shell does.

Reference

BCI2000Command calling syntax is

BCI2000Command [--property1=value1 --property2=value2 ...] command [argument1 argument2 ...]

Properties

Properties correspond to the properties of the BCI2000Remote class, and may be given on the command line, or as environment variables named "BCI2000property". Existing properties are:

Timeout
TelnetAddress
OperatorPath
WindowVisible
WindowTitle
SubjectID
SessionID
DataDirectory

Commands

Commands are applied to the BCI2000 operator module listening at the address given by the TelnetAddress property (defaults to localhost:3999). You may use the "Run" command to start up BCI2000 locally with appropriate parameters. Available commands are:

Run [<script file 1> <script file 2> ...]

Makes sure BCI2000 is started up, and optionally executes BCI2000 script files. Script files are local to the system that runs BCI2000Command, and are specified relative to the current directory of the calling script or shell.

Quit

Terminates BCI2000.

StartupModules <module1> <module2> ...

Starts up BCI2000 modules.

SetConfig

Applies the current set of parameters.

Start

Starts a new run (recording).

Stop

Stops the current run (recording).

GetParameter <name>

Returns the value of the specified parameter.

SetParameter <name> <value>

Sets the value of the specified parameter. This command fails when the parameter does not exist. Use the Execute command in conjunction with the INSERT PARAMETER scripting command to add a parameter to the system.

LoadParametersLocal <parameter file>

Loads a parameter file relative to the current working directory.

LoadParametersRemote <parameter file>

Loads a parameter file relative to BCI2000's working directory.

AddStateVariable <variable name> <bit width> <initial value>

Adds a state variable to the system. This is only possible before core modules are connected to the Operator module.

GetStateVariable <variable name>

Returns the value of the named BCI2000 state variable.

SetStateVariable <variable name> <variable value>

Sets the value of the named BCI2000 state variable.

GetSystemState

Returns the current system state (i.e., state of operation). This will be one of Unavailable, Idle, Startup, Initialization, Resting, Suspended, ParamsModified, Running, Termination, Busy.

GetControlSignal <channel index> <element index>

Gets the value of the BCI2000 control signal. Indices are 1-based.

Execute <scripting command>

Executes a scripting command. Scripting commands with arguments must enclosed in quotes to be seen as a single argument.

SetScript <event> <scripting commands>

Associates Operator scripting commands with event, which is one of OnConnect, OnSetConfig, OnStart, OnResume, OnStop, OnShutdown.

GetScript <event>

Returns Operator scripting commands associated with event, which is one of OnConnect, OnSetConfig, OnStart, OnResume, OnStop, OnShutdown.

Examples

Windows cmd interpreter

It is assumed that the BCI2000/prog directory is the current directory, or in the path.

@echo off
setlocal
BCI2000Command Run
BCI2000Command StartupModules "SignalGenerator --LogMouse=1" ARSignalProcessing CursorTask || BCI2000Command Quit && exit /b 1
BCI2000Command LoadParametersLocal "path to myfile.prm"
BCI2000Command Start
:loop
BCI2000Command GetControlSignal 1 1
for /f "tokens=*" %%i in ('BCI2000Command GetSystemState') do set state=%%i
if %state%==Running goto loop
BCI2000Command Quit

Linux/Unix bash shell

It is assumed that the BCI2000/prog directory is in the path.

#!/bin/sh
BCI2000Command Run || exit
BCI2000Command StartupModules "SignalGenerator --LogMouse=1" ARSignalProcessing CursorTask || ( BCI2000Command Quit && exit )
BCI2000Command LoadParametersLocal "path to myfile.prm"
if BCI2000Command Start; then
  while [ `BCI2000Command GetSystemState` = Running ]; do
    BCI2000Command GetControlSignal 1 1;
  done
fi
BCI2000Command Quit

See also

Programming Reference:BCI2000Remote Class, Contributions:BCI2000PresentationLink, Contributions:BCI2000Automation, Contributions:BCI2000PythonBindings, User Reference:BCI2000Shell, Contributions:Applications