Difference between revisions of "User Reference:MatlabFilter"

From BCI2000 Wiki
Jump to: navigation, search
(Troubleshooting:)
(Troubleshooting:)
Line 46: Line 46:
 
*or add the respective directory to your Matlab path.
 
*or add the respective directory to your Matlab path.
 
Generally, the first option is recommended over the second one.
 
Generally, the first option is recommended over the second one.
 +
 +
===Problems with starting up the MatlabEngine===
 +
For using the MatlabEngine on Windows systems, you need to make sure that
 +
*the processor architecture (32 or 64 bit) of the installed version of Matlab matches that of the BCI2000 module,
 +
*Matlab can be executed from the command line by running "matlab.exe".
 +
In case of multiple concurrently installed versions of Matlab, the MatlabFilter will always connect to the one that starts up when executing "matlab" from a command prompt.
  
 
==See also==
 
==See also==

Revision as of 15:00, 9 September 2013

Synopsis

The Matlab filter implements an interface between BCI2000 and a standalone Matlab engine. It allows you to implement and/or use Matlab functions for filtering data within the BCI2000 pipeline.

Parameters

The Matlab filter does not have a set of default parameters that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the parameters. After initialization, these parameters are displayed in the Operator and can be modified there.

The Matlab filter recognizes --MatlabWD command line option, which allows to set Matlab's working directory at startup, as in

MatlabSignalProcessing --MatlabWD="C:\Documents and Settings\bill\bcimatlab"

States

The Matlab filter does not have a set of default states that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the states.

Detailed explanation

The Matlab filter does not implement any algorithms itself, but instead allows you to implement the algorithms of your choice in Matlab.

Once BCI2000 is running with the Matlab filter, you will see that a very simple Matlab command line window has opened. In that command line window you can type commands that show you the variables that BCI2000 communicates to the Matlab engine. For example, you can do

 % show the variables
 whos
 
 % plot the first channel of the data (see below)
 plot(bci_InSignal(1,:))
 
 % plot the first channel of the data and continuously update the plot (see below)
 while(1); plot(bci_InSignal(1,:)); pause(0.01); end

If you try these examples above like this, you will notice that Matlab takes quite a considerable amount of time to open a new figure. While the figure is being opened by Matlab, the engine is blocked, which causes the MatlabFilter to fail writing new data to the engine. Hence the MatlabFilter will return an error and you will have to restart BCI2000. The reason is that the Matlab engine gives you access through the command window, but that the Matlab engine is not capable of executing the commands that it receives from BCI2000 and the commands that it receives from you through the command window simultaneously.

To get the above example to run correctly, you will have to open the figure prior to starting BCI2000 by typing figure (this will open an empty figure). Subsequently, once BCI2000 is running, the content of the figure can be updated.

However, the above example already shows that the Matlab engine is not intended to be used concurrently from the BCI2000 MatlabFilter and from the command window. Instead of typing your own commands in the command window, you will have to give full control of command execution to the MatlabFilter to ensure that timing is controlled. The way that BCI2000 and Matlab interact is that each of the components of a standard filter is mapped onto a corresponding Matlab function. If the Matlab filter is running within BCI2000, it will call the Matlab engine and execute the required Matlab function. The easiest way of getting started with the Matlab filter is by using one of the provided programming tutorials:

A detailed description of how to implement your own signal processing functions in Matlab can be found in the Programming reference for the Matlab filter.

Troubleshooting:

Matlab doesn't find your functions

Make sure to

  • either set Matlab's working directory to the directory containing your functions, using the --MatlabWD command line option described above,
  • or add the respective directory to your Matlab path.

Generally, the first option is recommended over the second one.

Problems with starting up the MatlabEngine

For using the MatlabEngine on Windows systems, you need to make sure that

  • the processor architecture (32 or 64 bit) of the installed version of Matlab matches that of the BCI2000 module,
  • Matlab can be executed from the command line by running "matlab.exe".

In case of multiple concurrently installed versions of Matlab, the MatlabFilter will always connect to the one that starts up when executing "matlab" from a command prompt.

See also

Programming_Reference:MatlabFilter, Contributions:FieldTripBuffer