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 with a number that describes the length of the content:

Layout of one message in the protocol.

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)":

Detailed layout of a length field(m) for a length $n\ge 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 for each modification to the protocol that happens to be incompatible with previous versions. In version numbering, a larger version ID represents a more recent version of the protocol definition.

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 version IDs 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 decimal 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 text 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

Parameter messages are used to transfer configuration information between modules. For a parameter message, content data is a single BCI2000 parameter, encoded as a sequence of ASCII characters that represents a parameter definition line.

Descriptor=3: State Format

State messages are used to transfer information about system state variables (event markers) between modules. There, information is transferred as 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:

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 introduced 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 of arbitrary length.

The data type can be

• 0 (SignalType::int16) for integers in little endian format.
• 1 (SignalType::float24) for 3-byte floating-point values in a BCI2000-specific encoding. There, the first two bytes define the mantissa $A$ as a signed two-byte integer in little endian format, and the third byte defines the exponent $B$ as a signed one-byte integer. The actual floating point value is then calculated as follows: $value=A*10^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 sent as "length fields" in the sense explained above, using binary encoding for small numbers, and ASCII representation to allow for arbitrarily large numbers.

One message if the visualization type is 1 (signal data).

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

A state vector data structure is a bit vector that represents values of all state variables present in the system. Originally, state vector information was transmitted at single-block resolution, i.e. there was only a single state vector per sample block. At present, state vector resolution has been increased to single-sample resolution, and the protocol has been adapted to accommodate for the additional information. There, for each data block containing $N$ samples, a total of $N+1$ state vectors is transferred, with the first $N$ state vectors corresponding to samples present in the data block. The additional state vector is used to initialize the next data block's state vector prior to processing.

State vector information is 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.

For each sample, 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

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

See also

Technical Reference:State Definition, Technical Reference:Parameter Definition, Technical Reference:States of Operation