Technical Reference:BCI2000 Messages

Information transferred between BCI2000 modules is packed into messages. Each message content corresponds to a BCI2000 data type such as Parameter, State, or Signal, and is wrapped into a layer that allows for routing the message to an appropriate handler. BCI2000 data types know how to write themselves to, and read themselves from, a data stream. For example, when the wrapper indicates that a message contains a brain signal, the framework code will route the message to a "brain signal" handler function that, in turn, asks a brain signal object to read itself from the message. As another example, when the operator module receives a visualization message, the message wrapper layer will not only be used to direct the message to a visualization handler but also to the visualization window to which the message is addressed.

Protocol Definition

Each message starts with a one-byte content descriptor and a one-byte descriptor supplement, followed by a number that describes the length of the content. (See Figure below)

The element denoted by "length field(2)" was originally a two-byte integer field for the content length in little endian format. To allow for messages longer than 64k, we introduced a backwards-compatible extension: if the length is below 65535, it will still be transmitted as a two-byte integer in little endian format. Otherwise, the two bytes will contain the value 65535, and be followed by a decimal ASCII representation of the length, terminated with a zero byte. For other one- and two-byte length fields occurring in the protocol, the same scheme applies, generalized to be a "length field (original number of bytes)". (See Figure below)

Detailed layout of a length field(m) for a length $n \geq 2^{m} - 1$

Overview of Content Descriptors
descriptor	description
0	protocol version
1	status information string
2	system parameter
3	system state
4	visualization data or brain signal
5	state vector
6	system command

Descriptor=0: Protocol Version

When the message descriptor is 0, the message content is an unsigned integer sent in decimal ASCII representation, and terminated with a zero byte. The integer number uniquely identifies the protocol version, and is incremented on each modification to the protocol that is incompatible with previous versions, such that a larger ID represents a more recent version.

Core modules send protocol version messages to the operator module to indicate their protocol version. If there is no protocol version sent, a version ID of zero is implied.

When protocol numbers do not match between a core module and the operator module, connection is refused. As far as possible, changes to the protocol will be backward compatible to avoid incrementing the protocol version.

Descriptor=1: Status Information Format

Messages with a descriptor of 1 transport status information strings as their content data. A status information string is a sequence of ASCII characters in the following format:

xxx: status-line-text

xxx is a three digit number that describes the content of the status information string. A first digit of `1' indicates status information, a first digit of `2' indicates successful operation, a first digit of `3' indicates recoverable errors and a first digit of `4' indicates fatal errors. The two remaining digits define the exact nature of the message, followed by a plain description.

Typically, status messages are used to communicate

status information (e.g., reporting successful module configuration),
informational messages (e.g., warnings about possible misconfiguration),
error messages (e.g., reporting misconfiguration, or runtime error conditions),
debugging information.

Descriptor=2: Parameter Format

For a parameter message, content data is a single [[BCI2000 Glossary#Parameter[BCI2000 parameter]], encoded as a sequence of ASCII characters that represents a parameter definition line.

Parameter messages are used to transfer configuration information between modules.

Descriptor=3: State Format

State messages contain a sequence of ASCII characters representing a state definition line.

Descriptor=4: Visualization and Brain Signal Data Format

This section describes the format of the message when the core message is a visualization data/brain signal message (i.e., the descriptor on the message is 4). In this case, the content descriptor describes the requested visualization type. The currently defined types are

1 a signal with n channels and m samples,
2 ASCII text,
3 signal properties (physical units, labels),
4 bitmap data (e.g., a decimated version of the feedback display),
255 visualization configuration.

Content Descriptor=1: Signal Data

For brain signals, the content descriptor is 1. (See Figure below)

One message in the protocol of type "visualization data".

The source identifier defines a unique number identifying the process/filter that generated the data. To allow for greater flexibility, BCI2000 2.0 introduces string-valued source identifiers. If these are used, the traditional source identifier byte is 0xff, and immediately followed by a null-terminated source identifier string.

The data type can be

0 (SignalType::int16) for integers in little endian format.
1 (SignalType::float24) for 3-byte floating-point values: The first two bytes (i.e., A) define the mantissa (signed two-byte integers in little endian format) and the third byte (i.e., B) defines the exponent (signed one-byte integer). The actual floating point value is then calculated as follows: $v a l u e = A * 1 0^{B}$ .
2 (SignalType::float32) for 4-byte floating-point values in IEEE 754 format transmitted in little endian byte order.
3 (SignalType::int32) for 4-byte signed integer values transmitted in little endian byte order.

The number of channels and samples are self explanatory.

The following figure illustrates the protocol when the visualization type is 1.

One message if the visualization type is 1 (i.e., a graph).

The following figure illustrates how the data is transferred.

Graphical representation of the transmitted visualization data format.

Content Descriptor=2: ASCII Text

The following figure illustrates the protocol when the visualization type is 2. The source identifier is a number uniquely identifying the process/filter that generated the data. (0 for brain signals.) The following ASCII text is zero delimited.

One message if the visualization type is 2 (i.e., a text memo).

Content Descriptor=255: Visualization Configuration

The following figure illustrates the protocol when the visualization type is 255. The source identifier is a number identifying the process/filter that generated the data. Configuration IDs are defined in the CfgID enumeration in the shared/defines.h header file.

The ASCII string then contains the configuration option, as defined by the configuration ID. For example, it might contain "128" if the configuration ID is 4. This will configure the graph to contain exactly 128 samples. When the configuration ID is 5 or 6 (axis labels), the ASCII string consists of a sample number (three digits), a space, and the axis label. Thus, one message configures exactly one axis label. As an example, for an X-axis label, the string "003 4.75 Hz" would result in a graph, in which the third sample is labeled "4.75 Hz."

One message if the visualizationtype is 255 (i.e., visualization configuration).

Brain Signal Format

The brain signal is transmitted similarly to visualization data (i.e., as described in the Visualization and Brain Signal Data Format above). The visualization type is set to 1 (i.e., signal data), source identifier is set to 0. Data type, channels and samples reflect the actual format of data transmitted.

Control Signal Format

Control signals are transmitted identically to the Brain Signal.

Descriptor=5: State Vector

Originally, state vector information was transmitted at single-block resolution, i.e. there was only a single state vector per block. At present, state vector resolution has been increased to match sample resolution; the protocol has been adapted to accommodate for the additional information, and state vectors are now transmitted as follows:

the number of bytes in the binary state vector (StateVectorLength), in decimal ASCII representation, terminated with a zero byte;
the number of subsequent state vectors transmitted, in decimal ASCII representation, terminated with a zero byte;
binary state vector data.

Binary state vector data is given as a series of StateVectorLength bytes. The value of a given state within the state vector is determined by its byte/bit location and length definition. The bits in the state vector are always sorted in ascending order, e.g., for a state with a length of 7 bits, starting at byte location 2, bit location 3, bit zero is first (byte 2, bit 3), and the highest bit (bit 7) is last (byte 3, bit 1).

Descriptor=6: System Command

The system command consists of an ASCII string that may end with a zero byte (i.e., ASCII code 0). The nature of these system commands is defined by the specific implementation of the modules.