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:

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) when encoding 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 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. Note that, for transportation of state values between core modules during processing, state vector messages (Descriptor=5) are used rather than state messages. Typically, state messages are used to transfer information about states, or values of individual states, and state vector messages are used to transfer the values of all existing states at a given point in time.

Descriptor Supplement=0: Original State Format

State information is transferred in the original state format.

Descriptor Supplement=1: Alternate State Format

State information is transferred in the alternate state format.

Descriptor=4: Visualization and Brain Signal Data Format

When the core message is a visualization data/brain signal message, the message's descriptor is 4. In this case, the descriptor supplement further specifies the type of data transferred. 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.

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.

Descriptor Supplement=1: Signal Data

For brain signals, the descriptor supplement is 1. 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 $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 sent as "length fields" in the sense explained above, using binary encoding for small numbers, and ASCII representation to allow for arbitrarily large numbers.

Note that the Source identifier field may be set to 0xff and is then followed with a null-terminated string representing a string-valued source identifier.

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

Graphical representation of the transmitted visualization data format.

If data transmission is done locally (i.e, between modules on the same machine), the data type can have its 6th bit set (add 64 to the values above). In this case, only a reference to a region of shared memory is transmitted in the message; the actual data is located in the shared memory region as a sample-first matrix in 8-byte IEEE 754 double format, in the machine's native byte order. Note that the lower bits of the data type still carry information about the actual resolution of the data, even if the representation is double. If the shared bit is set in the data type field, it is followed with the number of channels and samples as normal, but then followed with a null-terminated string which is the name or path of a shared memory object, allowing the receiving end to connect to that object and read the actual data.

Descriptor Supplement=2: ASCII Text

For messages transferring ASCII text, the descriptor supplement is 2. The ASCII text field itself is of arbitrary length, and zero delimited.

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

Descriptor Supplement=3: Signal Properties

For messages transferring Signal Properties, the descriptor supplement is 3. The Signal Properties type represents information about a signal, i.e.

a signal name,
channel and element (sample) indices,
a signal type, and
physical units in the signal's dimensions (channels, elements, and values).

For channels as well as elements, an index is defined, consisting of a label for each entry in the list of channels resp. elements. Labels may be either trivial, i.e. consist of the numbers from 1 to the number of entries, or nontrivial, consisting of arbitrary character strings. In the first, trivial, case, the index' representation in the message will be the number of its entries. In the second, nontrivial, case, it will be represented by a white-space separated list of its entries (labels), enclosed in curly braces.

In a message, the signal type is represented by its ID, which is one of "int16", "int32", "float24", or "float32".

Physical units are encoded as an offset $a$ , gain $b$ , and a symbol $Σ$ , such that a physical value $ϕ$ is computed from the raw value $r$ as follows:

$ϕ = (r - a) * b * Σ$

In a Signal Properties message, a physical unit is represented as a white-space separated list of

offset,
gain,
symbol,
raw minimum,
raw maximum.

Physical units for data values are transmitted per-channel without further separation, and the entire list is enclosed in curly braces.

All values are separated by white space. When containing braces or white space, these are encoded according to the URL convention, i.e. a character is encoded by its corresponding hexadecimal number in Latin-1 encoding, prepended with a percent sign.

Descriptor Supplement=4: Bitmap Data

The Bitmap data type represents a bitmap picture. Bitmap pictures are transferred in the system, e.g. to display a miniaturized view of the user's screen on the operator's screen. For efficient transmission, a sequence of bitmap pictures is first color-reduced to 3x5-bit color depth. Then, difference frames are computed between subsequent frames. Finally, difference frames are transmitted in run-length encoding, with each difference frame corresponding to a separate bitmap message.

In a bitmap message, first width and height of the picture are transmitted as two-byte integers in little-endian format. Then, run-length data follow in this format: For each run, run-length reduced by 1 is transmitted as an unsigned byte first. Then, its associated color value follows, as a two-byte integer in little-endian format. Thus, maximum run length is 256. Runs are wrapped at the picture's right edge, and runs follow each other until the picture's specified height and width are filled with color data.

Descriptor Supplement=5: VideoFrame Data

Similar to the Bitmap data type, a VideoFrame represents a bitmap picture. Bitmap data are specialized for screen content, which may be color reduced and RLE-compressed efficiently, whereas VideoFrame data are intended for video content, and are transferred as raw RGB24 data. To increase efficiency of transmission, VideoFrame data may be stored in shared memory, and only transmitted by a reference to that shared memory in case of a local connection.

In a VideoFrame message, a leading flag byte is transmitted first, followed by width and height of the picture as two-byte integers in little-endian format. Then, width*height*4 bytes of content follow. The flag byte holds two pieces of information:

endianness of the data, and
a flag that indicates whether transmission content is the full image, or a reference to shared memory. In the second case, the video data is replaced with a zero-delimited string holding the name of an existing shared memory object.

Descriptor Supplement=255: Visualization Configuration

The following figure illustrates the protocol when the visualization type is 255. For a list of available visualization properties, see Technical Reference:Visualization Properties. Constants for configuration IDs associated with visualization properties, as well as a function to convert between string and numeric representation of configuration IDs, are defined in the shared/types/CfgID.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.

One message if the visualization type 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 descriptor supplement is set to 1 (i.e., signal data), and the 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 must 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.