Technical Reference:State Definition
This page describes the concept of BCI2000 states, in conjunction with their textual representation as a "state line".
States are variables that represent the internal state of a BCI2000 system as it is evolving over time in response to:
- brain signal input
- user interaction through the operator interface
- trial sequencing by the application module.
Typical quantities/qualities encoded by states are:
- whether the system is running or suspended
- the time when a block of data was recorded
- stimulus or task being presented
- the classification result
- the state of an external marker (trigger) to be saved for off-line analysis.
Typically, state values change once per block of data, or once per trial. In a BCI2000 data file, the full set of states is stored along with the data, allowing for reconstruction of on-line system state off-line.
In a BCI2000 system, a collection of states is maintained as a State List. For each state present in that state list, its value is kept as a range of bits in a bit vector called State Vector. BCI2000 modules and filters may read and write state values during processing. The state vector's content is saved, in its binary form, into BCI2000 data files per-block. Using the ByteLocation, BitLocation, and Length fields from the state definitions present in a file, a state's value may be read from the data file.
A state vector is a narrowly packed bit field in little endian ordering. This implies that, for a state containing more than a single bit, more significant bits are placed at higher bit and byte locations.
As an example, consider a state vector consisting of a 1-bit state "Running", and a 16-bit state "SourceTime". This will result in a three-byte state vector layout like this:
|State Vector Byte 0||State Vector Byte 1||State Vector Byte 2|
State lines are a human-readable format used to represent individual states in
Core modules and the operator module use this format to communicate in the system initialization phase, as well as during system performance and for system termination.
The format of a state line is
Name Length Value ByteLocation BitLocation CRLF
where Length refers to the number of bits used to represent the state's value, and ByteLocation and BitLocation refer to its position in the State Vector, with BitLocation ranging from 0 to 7.
Depending on the context of a state line, one or more of its fields may be ignored:
- In a State message sent from the operator module to a core module, Length, ByteLocation, and BitLocation will be ignored.
- In a State line contained in a data file, the Value field matches the state's value stored with the first block of data samples.
Generally, the Value field specifies an initial value of a state. Actual values are stored in the State Vector data structure.
State values are interpreted as unsigned integers, and limited to 32 bit in the current implementation (as defined by the State::ValueType typedef in BCI2000/src/shared/types/State.h).