Technical Reference:States of Operation

From BCI2000 Wiki
Jump to navigation Jump to search

This page describes the states of operation that apply to a BCI2000 system as a whole. These are different from the concept of BCI2000 state variables which are saved to data files.

Driven by user interaction from the operator module, the system cycles through five phases of operation: Startup, Initialization, Suspended, Running, Termination.

State Diagram

Startup -> Initialization <-> Suspended -> Termination
                                  ^
                                  |
                                  v
                               Running

System Startup

Introduction

Since the system is a distributed system of encapsulated modules, a proper and well defined information flow at start-up needs to be ensured. Each module publishes its requests for parameters and states to the Operator module, which configures those and sends them back. Once the Signal Source module receives all parameters and states, it tries to connect to Signal Processing and, upon successful connection, sends a positive status message to the Operator. In the same way, Signal Processing connects to the Application and the Application module connects to the Signal Source module. After the Operator receives status messages from all three core modules, the system is fully initialized and is triggered to start, as soon as the Operator sends the state Running with a value of 1 to the Signal Source module.

Startup Sequence

The operator module must be started first. Its IP address is provided to core modules when they are executed, defaulting to localhost to match the most typical configuration.

The operator module listens on ports 4000 (for Source), 4001 (for Signal Processing), and 4002 (for Application), and waits for the respective core module to connect. Each can connect to its assigned port on the operator module in any order.

Once connected to the operator module, each core module opens its own listening socket on an arbitrary available port, and creates a parameter to contain this port number. Later on, these sockets will be used to create connections between core modules.

Publishing Phase

Upon connection, each core module sends a protocol version message which is then matched with the operator module's protocol version, making sure that only modules with matching protocol versions are combined.

Following its protocol version, each core module publishes its parameters to the operator module as a sequence of parameter messages. After publishing its parameters, each core module publishes the states it requests as a sequence of state messages. Following the last state, each core module sends a system command containing the string EndOfState.

On receiving this command from all core modules, the operator module processes the received parameters and states. It creates a list of all parameters and all states, and creates a global state vector, ignoring all fields from state messages, except Name and Length. In order to maintain integrity throughout operation, no parameters or states should be added to or removed from the system beyond this point.

System Initialization

Information Phase

At this point, the operator module may modify the value of the parameters and states (depending on the investigator's manual input or loading a parameter file). The operator module then uses the same connections on which it received data from the core modules to send back to all core modules a list of system-wide parameters and system-wide states, in any order. Since IP addresses and port numbers on which the core modules listen for data from other core modules are represented in system parameters as described above, each module now knows where to connect to. Accordingly, each core module opens a client connection to the core module it must connect to, i.e., Source opens a connection to Signal Processing, Signal Processing to Application, and Application to Source.

The connections from core modules to the operator module remain open. All subsequent core-to-operator communication will go through these connections.

As for the publishing phase, the Information Phase ends when a system command EndOfState is sent.

Preflight Phase

In the preflight phase, each core module declares to the Operator module whether it is able to properly process data using current parameters and states. In addition, it reports the properties of its output signal to the core module next in the chain.

The Operator module opens the preflight phase by sending an empty signal properties message to the Source module. The Source module then reports its output signal properties to the Signal Processing module by sending it an appropriate signal properties message. The Signal Processing module, in turn, sends its output signal properties to the Application module.

During the preflight phase, modules indicate errors by sending status messages containing plain-text error descriptions. If any errors are found during the preflight phase, a module will not initiate its initialization phase. The operator module will display error messages received from core modules, prompting the user to fix the problems detected rather than offering a "Start" option.

Initialization Phase

Each core module uses the information in the received parameters to configure and initialize its operation. Then, each core module sends a status message to the operator that indicates either successful or failed initialization.

The Initialization Phase ends when all core modules indicate successful configuration.

System is Suspended

At the end of the Initialization Phase, the system is fully configured. All parameters, states, and state vector, are now defined and available globally.

The system's state is now determined by a special Running state variable, which is initially set to "0", indicating that the system is suspended.

As long as operation is suspended, any module might update system parameters and send them back to the Operator. Any module shall disregard a change in parameters unless the system is in suspended state.

While the system is suspended, data may still flow through the system. It is up to each module to decide how to process these data. The Application, for example, might give visual feedback that indicates that the system is suspended.

System is Running

The system is started when the Operator module sets the special state variable Running to 1 and sends it to the Source module.

During system operation, the Operator module may modify any state variable by sending state messages to the Source module. The Operator module must send states only to the Source module; Signal Processing and Application must disregard any state that the Operator does send to them.

System Termination

To each of the three core modules, the operator module indicates regular system termination by closing the connection to that module.

Irregular system termination takes place when a core module loses connection to any of the two other core modules it is connected to. In this case, it will send an error message to the operator, and then quit. The operator module, in turn, will close connections to the remaining core modules.