Contributions:BCI2000Command

From BCI2000 Wiki
Revision as of 15:25, 23 April 2012 by Mellinger (talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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/BCI2000Automation

Versioning

Author

juergen.mellinger@uni-tuebingen.de

Source Code Revisions

  • Initial development: 3946
  • Tested under: 3948

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".

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.

Execute <scripting command>

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

StartupModules <module1> <module2> ...

Starts up BCI2000 modules.

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.

SetConfig

Applies the current set of parameters.

Start

Starts a new run (recording).

Stop

Stops the current run (recording).

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.

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.

GetControlSignal <channel index> <element index>

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

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
for /f "tokens=*" %%i in ('BCI2000Command GetSystemState') do set state=%%i
BCI2000Command GetControlSignal 1 1
if %state%==Running goto loop
BCI2000Command Quit

Linux/Unix bash shell

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

</pre>

  1. !/bin/sh

BCI2000Command Run || exit BCI2000Command StartupModules "SignalGenerator --LogMouse=1" ARSignalProcessing CursorTask || ( BCI2000Command Quit && exit ) BCI2000Command LoadParametersLocal myfile.prm if BCI2000Command Start; then

 while [ `BCI2000Command GetSystemState` = Running ]; do
   BCI2000Command GetControlSignal 1 1;
 done

fi BCI2000Command Quit </pre>

See also

Programming Reference:BCI2000Remote Class, Contributions:BCI2000PresentationLink, Contributions:BCI2000Automation Contributions:Applications