- Study Name: OpenViBE’s native MI-CSP demonstration
- Fields: OpenViBE, BCI, Motor Imagery
- Hardware used: any Brain Products amplifier (for best results, BrainAmp is not recommended), LiveAmp is used in this tutorial
- Software used: OpenViBE
- Difficulty: Beginner
This tutorial illustrates the steps necessary to run a simple Motor Imagery paradigm in OpenViBE using a Brain Products amplifier (in this case, a LiveAmp). Although this is one of the simplest examples of a working BCI, such systems are, by nature rather complicated. This tutorial walks through the procedure step by step.
2. Getting started with OpenViBE
OpenViBE (http://openvibe.inria.fr/) is an open source platform for designing and implementing BCI experiments and applications. It provides a straightforward graphical interface, full integration of many hardware devices, compatibility with Python, Lua, and LSL, and it is under active development.
The first step is to download the OpenViBE installer for Windows (http://openvibe.inria.fr/downloads/) and install the software on your system. The default directory for an OpenViBE installation (on Windows) is C:\Program Files (x86)\openvibe-2.1.0. Here you will find a directory tree that houses OpenViBE’s libraries, applications, and associated configuration and xml files. You can ignore all of this for now.
2.1 OpenViBE Acquisition Server
The OpenViBE Acquisition server is how OpenViBE gets EEG and other device data in. After you have run the OpenViBE installer, you can access the Acquisition Server and the Designer through the Windows Start menu. First, run the OpenViBE Acquisition Server. A command terminal will also launch, which displays useful information about the system and what is going on. In this tutorial we will select the Brain Products LiveAmp as the driver, but other amplifiers will work just as well. However, the specific settings discussed below may need to be altered for optimal performance.
Click the Driver Properties button, enter the serial number of your device and select the appropriate number of EEG channels (i.e., the number of electrodes connected to the amplifier). Leave bipolar and AUX channels at ‘0’ and do not include the ACC data.
Connection port can be left at ‘1024’ and Sample count per sent block (on my PC) should be ‘256’. In general, it is important to have the Device drift under 2ms. The Acquisition Server reports this at the bottom of the GUI. Adjusting the number of Samples count per sent block setting will affect this value. You can also change the tolerance in the Acquisition Server Preferences dialogue. It is important that this value stays in range or the BCI will not work properly. Connect to the amplifier and hit Play to check the drift.
2.2 OpenViBE Designer
The Designer is where the actual stimulation, recording, offline, and online processing of data occurs. It needs to run in parallel to the acquisition server. The Designer allows for the graphical editing and the running of ‘scenarios’ which are written to disk as xml. You will rarely need to deal with the xml itself. You should be able to run and control everything with the Designer.
3. Running the Motor Imagery CSP Example
OpenViBE comes with a number of out of the box BCI example scenarios and associated data and configuration files. This tutorial describes how to use the one called ‘motor-imagery-CSP’ which is, of course, a motor imagery task that features a common spatial patterns stage.
3.1 Accessing the Scenario
By default (on Windows), when you open a file from designer, you will be prompted to a folder inside your AppData folder, something like C:\User\AppData\Roaming\openvibe-2.1.0 scenarios. Navigate from here to the folder bci-examples\motor-imagery-CSP and select all the files ending with .xml. These are the 6 scenarios we will be dealing with, primarily scenarios 1-4.
The example, itself, is fairly well documented with comment boxes, but we will briefly go through each step in order to make the BCI work. There are 4 basic steps (each in its own scenario):
- Acquire training data
- Train the CSP coefficients with the training data
- Train the classifier with the training data and the (trained) CSP filter
- Go live
3.2 Monitoring the Data
Scenario 0 (mi-csp-0-signal-monitoring.xml) is simply for monitoring the EEG data. For clarity and robustness’ sake, it is recommended to use BrainVision Recorder to check impedance values (if using wet electrodes) and for signal quality, before entering the realm of OpenViBE. However, it is a good idea to have the monitor scenario running during the experiment to make sure nothing fails. OpenViBE Designer and Acquisition Server also reports error and warnings in their respective command consoles.
Run the scenario by clicking the little grey ‘play’ arrow at the top of the Designer GUI. Especially with a sample count of 256, this visualization is not particularly smooth. This is why it is recommended to use Recorder to prepare the subject’s cap and make sure the signals are good.
3.3 Acquiring Training Data
Scenario mi-csp-1-acquisition.xml acquires the data for the training phase. But before we begin, we will need to make one small change to the scenario. Right-click on the box called Generic stream writer and select configure box…. A dialogue will pop up that allows you to change where the data is written. You will want to change this to a reasonable location because on Windows the AppData folder is difficult to access inside of many applications (including OpenViBE Designer). For the purposes of a quick demonstration, it is wise to simply store the data on the Desktop. For a real study, some care must be taken to organize sub-folders for different subjects etc.
When run, a small black window will pop up. As documented in the scenario, after 40 seconds, the window will display stimuli for the BCI. Make this window full screen in the display monitor. The epochs consist of a fixation cross followed by (randomly) either a left or right pointing arrow. The subjects’ task is to imagine moving her left hand when the left arrow appears and the right hand when the right arrow appears. It is wise to instruct the subject to imagine a vivid action, like performing a left-hand piano exercise or swinging a hammer with the dominant hand. There are 40 runs with 20 examples each.
3.4 Calculating Coefficients for the Spatial Filter
In the next step we switch to the scenario mi-csp-2-train-CSP.xml. Now that we have acquired the training data, we can train the spatial filter. The data file (assuming it was stored on the Desktop) will have a name like <user>\\Desktop\\motor-imagery–csp1-acquisition-[<date and time>].ov. We need to tell the Generic stream reader box where the file is. Again, right-click, configure box…, choose the Desktop as the folder and enter the full name of the recorded file. Then, click apply.
With this done, you will want to click the Fast Forward button to run the scenario. Be patient, it takes some time to finish.
3.5 Training the Classifier
Scenario mi-csp-3-classifier-trainer.xml uses both the acquired data and the newly calculated CSP coefficients to train and LDA classifier. Again, you will have to point the Generic stream reader box to your data file but the coefficients for the CSP Spatial Filter box should be automatically loaded from the results in the last scenario.
3.5 Running the BCI Online
The last scenario we are concerned with here is mi-csp-4-online.xml. This uses the CSP coefficients as well as the results from the LDA to run the MI BCI online. A visualizer similar to the stimulation program visualizes the results.