User Reference:Module Command Line Options: Difference between revisions

From BCI2000 Wiki
Jump to navigation Jump to search
(20 intermediate revisions by 2 users not shown)
Line 4: Line 4:
*switch on debugging messages,
*switch on debugging messages,
*automate BCI2000 operation.
*automate BCI2000 operation.
You cannot use command line options when starting BCI2000 from [[User Reference:BCI2000Launcher|BCI2000Launcher]]. Rather, copy one of the batch files from the BCI2000/batch directory, and modify it to fit your needs, then start BCI2000 by double-clicking it (this will work on all supported platforms, not only Windows).


==Core Modules==
==Core Modules==
[[Technical Reference:Core Modules|Core modules]] (i.e., Data Acquisition, Signal Processing, and Application Module), share the same command line syntax:
[[Technical Reference:Core Modules|Core modules]] (i.e., Data Acquisition, Signal Processing, and Application Module), share the same command line syntax:
  <ModuleName> <operator IP>:<operator port> --<option1>-<value1> --<option2>-<value2> ...
  <ModuleName> <operator IP>:<operator port> --<option1>=<value1> --<option2>=<value2> ...
All arguments are optional.
All arguments are optional.


Line 25: Line 27:
*Specifying ''--version'' will display version information, and then quit.
*Specifying ''--version'' will display version information, and then quit.
*The ''FileFormat'' option will switch between [[User Reference:Data File Formats|File Formats]] used for data recording. The output file format is determined at module startup, and cannot be changed by modifying the FileFormat parameter from the operator module's parameter dialog.
*The ''FileFormat'' option will switch between [[User Reference:Data File Formats|File Formats]] used for data recording. The output file format is determined at module startup, and cannot be changed by modifying the FileFormat parameter from the operator module's parameter dialog.
*The ''Debug'' option will make a module send [[Programming Reference:Debug Output|Debug Messages]] that appear in the operator module's log window.
*The ''DebugLevel'' option will make a module send [[Programming Reference:Debug Output|Debug Messages]] that appear in the operator module's log window. By default, the debug level will be set to 1; providing a larger number, as in ''DebugLevel=5,'' will increase verbosity of debug output.
*The ''DebugLog'' option will maintain a log file in the current session directory, bearing the session name, and a ''.dbg'' extension. A ''DebugLevel>0'' will imply ''DebugLog=1'', unless ''DebugLog'' is explicitly set to 0.
*The ''LogKeyboard'', ''LogMouse'', and ''LogJoystick'' options will enable [[User Reference:Logging Input|recording of key presses, mouse and joystick position]].
*The ''LogKeyboard'', ''LogMouse'', and ''LogJoystick'' options will enable [[User Reference:Logging Input|recording of key presses, mouse and joystick position]].
*The ''SavePrmFile'' option will save a [[Technical_Reference:Parameter_File|parameter file]] for each run.
*Normally, BCI2000 automatically chooses a suitable IP address for communication between SignalSource, SignalProcessing, and Application module. Sometimes however, you want a specific address to be used. This is possible using the ''SignalSourceIP/SignalProcessingIP/ApplicationIP'' options. Note that these options must be specified on the command line of the respective module, e.g. the following lines will specify the localhost address for both the connection to the Operator module (first option), and the connection between core modules:
start executable SignalSource 127.0.0.1 --SignalSourceIP=127.0.0.1
start executable SignalProcessing 127.0.0.1 --SignalProcessingIP=127.0.0.1
start executable Application 127.0.0.1 --ApplicationIP=127.0.0.1
*The ''--local'' option provides an alternative way to set a module's listening IP to 127.0.0.1.
*By default, only one module of each kind may be running at a time. To allow for multiple instances of a module, specify the ''--AllowMultipleInstances'' option. This will also clean up any instance information that may have been left over from a crashing module.


==Operator Module==
==Operator Module==
The operator module allows to specify scripts from the command line.
The Operator Module allows to specify scripts from the command line.
Command line options correspond to script entries in the operator's preferences dialog.
Most command line options correspond to script entries in the operator's preferences dialog.
The following options exist:
The following options exist:
  --OnConnect
  --OnConnect
Line 38: Line 48:
  --OnResume
  --OnResume
  --OnStart
  --OnStart
--Title
--Hide
--StartupIdle
--Telnet
After the option, white space is expected, followed with a double-quote enclosed string.
After the option, white space is expected, followed with a double-quote enclosed string.
Examples:
Examples:
  --OnConnect "C:\scripts\onconnect.bciscript"
  --OnConnect "C:\scripts\onconnect.bciscript"
  --OnConnect "-LOAD PARAMETERFILE ..\parms\myparms.prm"
  --OnConnect "-LOAD PARAMETERFILE ..\parms\myparms.prm"
--Telnet *:3999
--Title %~n0
The last example shows how to display the name of the batch file from which the Operator Module was started under MS Windows. The ''--Title'' option takes a string that is displayed in the Operator Module's title bar. The ''--Hide'' option has no arguments. It hides the Operator module's main window (but not visualization windows). Typically, this option is used in conjunction with fully automated execution via OnConnect/OnSetConfig/OnSuspend scripts, or together with the ''--Telnet'' option.
The ''--Telnet'' option expects an IP:Port combination on which to listen for incoming connections, defaulting to "localhost:3999". Logging into the Operator Module's telnet server allows you to execute script commands interactively, or to remote-control BCI2000 from an external application using script commands. When you intend to connect to the Operator Module from a different machine, you will need to specify either an asterisk (*) in place of the IP address: "*:3999" to indicate that it should listen on all available addresses, or the listening machine's external IP address, e.g. "134.2.131.152:3999".
When the ''--StartupIdle'' option is specified, the Operator module does not wait for incoming connections from BCI2000 core modules. This allows for basic configuration to be performed via a telnet connection. To prepare for core module startup, execute
Startup System
from the telnet prompt.
By default, only one instance of the Operator module may be running on a system at a time. To allow for multiple Operator instances, specify the ''--AllowMultipleInstances'' option.


For further details and examples, see [[User Reference:Operator Module Scripting]].
For further details and examples, see [[User Reference:Operator Module Scripting]].


==See also==
==See also==
[[Technical Reference:Core Modules]], [[User Reference:Operator Module Scripting]], [[User Reference:Data File Formats]], [[Programming Reference:Debug Output]], [[User Reference:Input Logging]]
[[Technical Reference:Core Modules]], [[User Reference:Operator Module Scripting]], [[User Reference:Data File Formats]], [[Programming Reference:Debug Output]], [[User Reference:Logging Input]]


[[Category:External Interfaces]]
[[Category:External Interfaces]]

Revision as of 20:15, 5 August 2016

Using command line options allows you to

  • distribute BCI2000 modules over a network,
  • change the data format for brain signal recordings,
  • switch on debugging messages,
  • automate BCI2000 operation.

You cannot use command line options when starting BCI2000 from BCI2000Launcher. Rather, copy one of the batch files from the BCI2000/batch directory, and modify it to fit your needs, then start BCI2000 by double-clicking it (this will work on all supported platforms, not only Windows).

Core Modules

Core modules (i.e., Data Acquisition, Signal Processing, and Application Module), share the same command line syntax:

<ModuleName> <operator IP>:<operator port> --<option1>=<value1> --<option2>=<value2> ...

All arguments are optional.

Specifying the Operator Module's Network Address

At startup, each core module connects to the operator module. If no IP address is specified on the command line, the connection is opened to the local machine using 127.0.0.1 as an IP address. When no port is given, each module uses its default port as defined here. Normally, there is no need to change port numbers.

Specifying Options

Any number of options may be given, starting with a double minus sign. As indicated above, option names and values are combined with a single minus sign, to form a continuous character string. Each option is translated into a BCI2000 parameter using its name as a parameter name, and its value as a parameter value. When a parameter with the given name already exists, its value will be changed from the default to match the value given on the command line. When no parameter with that name exists, it is added to the System parameter section. Parameter values must not contain white spaces on the command line; however, white space may be encoded in HTTP fashion as described here, e.g., using '%20' as a replacement for a single space character.

Special Options

  • Specifying --version will display version information, and then quit.
  • The FileFormat option will switch between File Formats used for data recording. The output file format is determined at module startup, and cannot be changed by modifying the FileFormat parameter from the operator module's parameter dialog.
  • The DebugLevel option will make a module send Debug Messages that appear in the operator module's log window. By default, the debug level will be set to 1; providing a larger number, as in DebugLevel=5, will increase verbosity of debug output.
  • The DebugLog option will maintain a log file in the current session directory, bearing the session name, and a .dbg extension. A DebugLevel>0 will imply DebugLog=1, unless DebugLog is explicitly set to 0.
  • The LogKeyboard, LogMouse, and LogJoystick options will enable recording of key presses, mouse and joystick position.
  • The SavePrmFile option will save a parameter file for each run.
  • Normally, BCI2000 automatically chooses a suitable IP address for communication between SignalSource, SignalProcessing, and Application module. Sometimes however, you want a specific address to be used. This is possible using the SignalSourceIP/SignalProcessingIP/ApplicationIP options. Note that these options must be specified on the command line of the respective module, e.g. the following lines will specify the localhost address for both the connection to the Operator module (first option), and the connection between core modules:
start executable SignalSource 127.0.0.1 --SignalSourceIP=127.0.0.1
start executable SignalProcessing 127.0.0.1 --SignalProcessingIP=127.0.0.1
start executable Application 127.0.0.1 --ApplicationIP=127.0.0.1
  • The --local option provides an alternative way to set a module's listening IP to 127.0.0.1.
  • By default, only one module of each kind may be running at a time. To allow for multiple instances of a module, specify the --AllowMultipleInstances option. This will also clean up any instance information that may have been left over from a crashing module.

Operator Module

The Operator Module allows to specify scripts from the command line. Most command line options correspond to script entries in the operator's preferences dialog. The following options exist:

--OnConnect
--OnExit
--OnSetConfig
--OnSuspend
--OnResume
--OnStart
--Title
--Hide
--StartupIdle
--Telnet

After the option, white space is expected, followed with a double-quote enclosed string. Examples:

--OnConnect "C:\scripts\onconnect.bciscript"
--OnConnect "-LOAD PARAMETERFILE ..\parms\myparms.prm"
--Telnet *:3999
--Title %~n0

The last example shows how to display the name of the batch file from which the Operator Module was started under MS Windows. The --Title option takes a string that is displayed in the Operator Module's title bar. The --Hide option has no arguments. It hides the Operator module's main window (but not visualization windows). Typically, this option is used in conjunction with fully automated execution via OnConnect/OnSetConfig/OnSuspend scripts, or together with the --Telnet option.

The --Telnet option expects an IP:Port combination on which to listen for incoming connections, defaulting to "localhost:3999". Logging into the Operator Module's telnet server allows you to execute script commands interactively, or to remote-control BCI2000 from an external application using script commands. When you intend to connect to the Operator Module from a different machine, you will need to specify either an asterisk (*) in place of the IP address: "*:3999" to indicate that it should listen on all available addresses, or the listening machine's external IP address, e.g. "134.2.131.152:3999".

When the --StartupIdle option is specified, the Operator module does not wait for incoming connections from BCI2000 core modules. This allows for basic configuration to be performed via a telnet connection. To prepare for core module startup, execute

Startup System

from the telnet prompt.

By default, only one instance of the Operator module may be running on a system at a time. To allow for multiple Operator instances, specify the --AllowMultipleInstances option.


For further details and examples, see User Reference:Operator Module Scripting.

See also

Technical Reference:Core Modules, User Reference:Operator Module Scripting, User Reference:Data File Formats, Programming Reference:Debug Output, User Reference:Logging Input