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 1.1)

Fig. 1.1 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)". (See Figure 1.2)

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

Overview of content descriptors

descriptor	description
1	status information string
2	system parameter
3	system state
4	visualization data or brain signal
5	state vector
6	system command

Descriptor=1: Status Information Format

This section describes the format of the message when the core message is a status information string (i.e., the message's descriptor is 1). In this case, the aforementioned content data is a line 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. This procedure is used to communicate errors and to convey status information (e.g., the operator module may display the remaining disc space on the Source module's machine.)

Descriptor=2: Parameter Format

For parameter messages, content data is a line of ASCII characters representing a parameter definition line.

Descriptor=3: State Format

State messages contain a line 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 message's descriptor is 4). In this case, the content descriptor describes the requested visualization type. The currently defined types are 1 (a graph of n channels and m samples), 2 (a text memo), and 255 (visualization configuration). For brain signals, the content descriptor is 1. (See Figure 6.1)

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

Figure 6.2 illustrates the protocol when the visualization type is 1. The source identifier defines a unique number identifying the process/filter that generated the data. 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: $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 self explanatory.

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

Figure 6.3 illustrates how the data is transferred.

Fig. 6.3 Graphical representation of the transmitted visualization data format

Figure 6.4 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.

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

Figure 6.5 illustrates the protocol when the visualization type is 255. The source identifier is a number identifying the process/filter that generated the data. The different 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 and 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."

Fig. 6.5 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 Section (visualizationdata_format)). The visualization type is set to 1 (i.e., graph), 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

The state vector is defined by a series of StateVectorLength subsequent 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.