Contributions:BCI2000SimulinkConnector

The BCI2000 Simulink connector allows data to be sent to Simulink in real-time, allowing data to be processed in your own custom Simulink model.

Video Overview

Location

http://www.bci2000.org/svn/trunk/src/contrib/ExternalLinks/Simulink

Versioning

Author

mellinger@neurotechcenter.org

Source Code Revisions

Initial development: 7669
Tested under: 7669

Functional Description

The BCI2000 Simulink connector is a means to send signal data from BCI2000 into a Simulink model. It consists of a BCI2000 filter that listens for connections on a TCP port, and a Simulink S-function that connects to that port and reads data from it. As an optimization in case of a machine-local TCP connection, signal data is transmitted through a shared memory block instead of the TCP connection. Still, the TCP connection is necessary to synchronize arrival of new data on the BCI2000 side with consumption on the Simulink side.

Building the Simulink Connector

The BCI2000 Simulink connector consists of two projects: A BCI2000 SignalProcessing module, called SimulinkConnectorSignalProcessing, and a Simullink S-function mex file, called BCI2000OnlineLink.

Building the S-function mex file relies on a Matlab installtion being present, and thus requires enabling through a CMake switch.

In your BCI2000 build folder, execute Configure.sh.bat. Then, navigate to BUILD_CONTRIB and make sure it is checked. Likewise, navigate to BUILD_SIMULINK_MEX_FILES, and make sure it is checked. Then, click "Generate" in the CMake GUI to re-generate the BCI2000 project files (Makefile or Solution file).

In case you have multiple versions of Matlab installed, CMake will pick a random one. To control which Matlab version is used, set the Matlab_ROOT variable to the root directory of the desired version (i.e., the directory that has "Matlab R…" in its name).

Similarly, if you have the Matlab Compiler Runtime (MCR) installed, CMake may pick it but will fail to identify the Simulink include directory, which is not present in the MCR installation. If this happens, set the Matlab_ROOT variable to the root directory of a full Matlab installation, and re-generate project files.

Once built, Simulink related files are located in BCI2000/prog/Simulink, and the BCI2000/batch directory contains a batch file called SimulinkConnector.bat.

Using the Minimal Example

BCI2000 comes with a minimal example Simulink model, containing just the BCI2000OnlineLink block with its two output ports, a muxer block, and a "to file" block that saves the output to a file.

To try the BCI2000 Simulink Connector, navigate to the BCI2000/prog/Simulink directory using the Matlab file explorer. Then, double-click the MinimalExample.slx Simulink model file. The test consists of the following steps:

Double-click BCI2000/batch/SimulinkConnector.bat in your OSes file explorer. BCI2000 will start and display status information in the system log.
In the MinimalExample window, click the arrow in the green circle to run the model. It will run indefinitely, reading data from BCI2000, and recording it into a Matlab data file.
To end the run, click the the black square ("stop symbol") right to the green circle.
You may now inspect the contents of the recorded data file by typing data=load('bci2000.mat'); into the Matlab prompt. The data.ans field consists of the following rows:
- 1: Time in seconds (one row),
- 2: BCI2000 signal data, upsampled to the original sampling rate if necessary (one row per BCI2000 channel),
- 3: BCI2000 state data in the order specified in the SimulinkConnectorStates parameter on the BCI2000 side (one row per BCI2000 state).

Adding BCI2000 your own model

To add the BCI2000 block to your own model, open the BCI2000.mdl library in Matlab, and drag-and-drop the BCI2000 block into your model window. Then, connect its output signals as you see fit.

NOTE: If the target model is located in a different directory than BCI2000/prog/Simulink, you need to add BCI2000/prog/Simulink to the Matlab path in order to use the BCI2000 block.

Changing the IP:Port setting

To change the port or the IP address for connecting to BCI2000, double-click the BCI2000 block in Simulink. Under "S-function parameters", you see a single entry, which is by default 'localhost:1905' (take care of the single quotes—without them, Simulink will try to find a variable with name "localhost"). Modify as desired, and close the window.

On the BCI2000 side, the equivalent setting is stored in the "SimulinkConnectorAddress" parameter on the "Connector" tab:

Note that connections between different machines are supported but data transport through TCP will be much less efficient than local transport, which takes place through shared memory.

Addresses will always be identical on both ends. When switching to a non-local connection, “localhost” will have to be replaced with the IP address of the machine running BCI2000 (e.g., 192.168.1.15:1905).

Transferring State/Event information

State/Event information may be transferred by specifying State/Event names in the "SimulinkConnectorStates" parameter (see image above). States listed there will be appended to the signal as additional channels.

Depending on where the SimulinkConnector is located in the filter chain, its input signal may have more or fewer elements (samples) than the State Vector (which has as many samples as the source signal). In that case, a warning is issued, and state data is either truncated, or appended with NaN values, as appropriate.