User Reference:BCI2000Watchdog

Introduction

BCI2000Watchdog is a program that monitors the function of a running BCI2000 instance, and restarts it if malfunction is detected. Functioning of BCI2000 is determined by monitoring "Canary expressions" which are evaluated in the context of BCI2000 and are expected to change on a regular basis, e.g. the time stamp of the currently processed data block, and/or the frame number of a video recorded alongside brain signal signal data.

The Watchdog program is located in the BCI2000/prog directory.

Using BCI2000Watchdog Interactively

Selecting a BCI2000 Startup Batch File

The top element of BCI2000Watchdog holds the full path to a BCI2000 startup batch file. This may be any BCI2000 batch file, except that it must contain the SET CONFIG and START commands. If the batch file does not contain these commands, SetConfig and Start must be pressed manually, so the watchdog will be unable to start operation of BCI2000 when it tries to restart it.

Pressing the "..." button at the right side of the edit field will bring up a file selection dialog, so you don't need to enter the full path manually.

Also, dragging a batch file onto the edit field will enter the file's full path.

In addition, a batch file may be given on the command line when starting up BCI2000Watchdog, or by dragging-and-dropping onto the program's icon.

Pressing the "Edit..." button will bring up the batch file in a simple text editor, so you don't have to leave the program in order to modify the batch file.

Choosing the Timeout for reaching the "Running" State

Depending on system components involved (such as webcams, eye trackers, etc.), the BCI2000 startup time can be considerable. If it takes longer than the selected "Running" timeout, the watchdog will think that BCI2000 has failed to start up, and attempt another try. In such cases, setting the timeout to a larger value will fix the issue.

Choosing the Timeout for Process Termination

Similar to the "Running" state timeout, the process termination timeout applies to the amount of time allowed for BCI2000-related processes to shut down by themselves after the "exit" command has been sent to the BCI2000 Operator module. Again, depending on the number and kind of components involved, the shutdown may take longer than the default timeout of 2 seconds, and processes will be terminated by force, which means that not all data may be saved or written to disk. To avoid this situation, increase the amount of time that is allowed for processes to terminate gracefully.

Entering Canary Expressions (Watches)

The watches table allows you to enter expressions in the BCI2000 expression syntax. These expressions will be evaluated in the context of the Operator module each time a data block arrives. Expressions are then evaluated for each sample in the data block. Whenever an expression changes, a message will be sent to the Watchdog program, indicating that BCI2000 is "alive". If no message has been received for the duration of the timeout specified for an expression, BCI2000 will be assumed to be "dead", and will be restarted.

In addition, an "initial timeout" may be specified for an expression. If no activity is found during the initial timeout period, the expression is considered initially dead, and is not observed any further. This may be useful to avoid constant restarting in cases where a partial functionality, such as a webcam, is not available. To disable initial timeout functionality, set the "initial timeout" value to 0.

By default, the watchdog observes changes in the SourceTime BCI2000 state and gives alarm when the SourceTime state has not changed for 2 seconds. In a live BCI2000 system, the SourceTime state changes with each BCI2000 data block, so if it stays constant for 2 seconds, this is an indication that the BCI2000 system has ceased to function. The default of 2 seconds has been chosen to make sure not to interfere with recordings that have very large sample block duration.

For testing data acquisition functionality in BCI2000, observing the SourceTime state should be sufficient. However, when recording video or other auxiliary data, the respective data stream might be broken without affecting the SourceTime state. In these cases, it will be useful to add an expression that covers the respective partial functionality. E.g., to ensure functionality of recording from the first attached webcam, you would enter an expression of WebcamFrame0.

Starting BCI20000

To start up BCI20000 by executing the specified BCI2000 batch file, click the "Start BCI20000" button at the bottom of the window.

Terminating BCI2000

Whenever BCI20000 is running, the "Start BCI2000" button is disabled, and the "Terminate BCI2000" button is enabled. Clicking the "Terminate BCI2000" button will terminate BCI2000, and then switch the watchdog to idle mode.

Note that quitting BCI2000 from the Operator GUI will prompt the watchdog to start it again. You will need to use the "Terminate BCI2000" button to stop running it.

Recovering from an Error

Certain conditions may put the watchdog into an error state. Typically, these represent unexpected behavior of BCI2000. If an error condition is met, an error message is appended to the log, and printed in red. Also, both the start and the termination button will be disabled, and the watchdog will not perform any actions any more. To recover from an error condition, click "Reset" at the bottom left of the watchdog window, and quit BCI2000 manually from the Operator GUI.

Automating BCI2000Watchdog from the Command Line

For scenarios in which interactive use is not desired (e.g., in a clinical setting), BCI2000Watchdog's behavior may be determined through command line arguments which may be put into an operating system batch or script file.

The following command line options are supported:

--Ini=<IniFile>

Specify the path of a .ini file to use instead of the default. The given .ini file will be used both for reading at program startup and writing at program termination.

--UILevel=<n>

User interface level from 1 to 3:

1 Only display "Start BCI2000" and "Terminate BCI2000" buttons,

2 Display "Reset", "Start BCI2000", "Terminate BCI2000" buttons and the log,

3 Display full UI.

--Autostart

Start BCI2000 operation as if "Start BCI2000" had been clicked after startup.

<BCI2000 Batch file>

An argument without leading '--' will be treated as the name of a BCI2000 startup batch file.