OpenViBE User Documentation version 2014.06.

27

OpenViBE: the open-source platform for Brain-

Computer Interfaces

User Documentation
Version 2014.06.27

BY

FOR

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Table of Contents
Author’s Note ................................................................................................................................................ 5
1. Generals................................................................................................................................................. 7
1.1 What is OpenViBE ? ....................................................................................................................... 7
1.2 A modular system .......................................................................................................................... 7
1.3 Different views, for different users ............................................................................................... 7
1.4 Hardware and software abstraction ............................................................................................. 8
1.4.1 Supported OS Architectures .................................................................................................. 8
1.4.2 Supported Devices................................................................................................................. 9
1.5 Content of the OpenViBE software platform package ................................................................ 11
2. Configuration ....................................................................................................................................... 13
2.1 Configuration files ....................................................................................................................... 13
2.2 Syntax .......................................................................................................................................... 13
2.3 Existing tokens ............................................................................................................................. 14
2.4 Defining and using custom tokens .............................................................................................. 14
3. Acquisition Server................................................................................................................................ 16
3.1 Introduction ................................................................................................................................. 16
3.2 The Graphical User Interface (GUI) ............................................................................................. 16
3.2.1 Acquisition Device Drivers ................................................................................................... 16
3.2.2 Connection Settings............................................................................................................. 17
3.2.3 Driver Properties ................................................................................................................. 17
3.2.4 Acquisition Server Preferences ........................................................................................... 18
3.2.5 Cap montages and channel names...................................................................................... 19
3.3 Usage ........................................................................................................................................... 20
3.4 Troubleshooting .......................................................................................................................... 21
4. Designer Overview .............................................................................................................................. 23
4.1 Introduction ................................................................................................................................. 23
4.2 Menubar ...................................................................................................................................... 24
4.3 Toolbar ........................................................................................................................................ 25
4.4 Box algorithms tree view ............................................................................................................. 28
4.4.1 Box algorithms ..................................................................................................................... 28
4.4.2 Optional : Algorithms treeview ........................................................................................... 29

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

4.5 Status bar..................................................................................................................................... 29

4.6 Console ........................................................................................................................................ 29
4.7 Edition Area ................................................................................................................................. 29
4.7.1 Boxes ................................................................................................................................... 29
4.7.2 Box status ............................................................................................................................ 30
4.7.3 Box editing functionalities ................................................................................................... 31
4.7.4 Scenario editing functionalities ........................................................................................... 31
5. Designer Tutorial 1: Creating a simple scenario .................................................................................. 33
5.1 Step 1: Creating a new scenario .................................................................................................. 33
5.2 Step 2: Adding a box algorithm ................................................................................................... 34
5.3 Step 3: Connecting boxes ............................................................................................................ 34
5.4 Step 4: Saving a scenario ............................................................................................................. 35
5.5 Step 5 : Playing a scenario ........................................................................................................... 36
6. Designer Tutorial 2: Customizing a scenario ....................................................................................... 37
6.1 Step 1 : Identifying customizable boxes ...................................................................................... 37
6.2 Step 2: Offline settings modification ........................................................................................... 37
6.3 Step 3: Online settings modification ........................................................................................... 38
7. Designer Tutorial 3: Advanced box configuration ............................................................................... 40
7.1 Connectors configuration ............................................................................................................ 40
7.1.1 Adding connectors............................................................................................................... 40
7.1.2 Configuring the type of a connector ................................................................................... 41
7.2 Settings configuration ................................................................................................................. 43
7.2.1 Adding settings .................................................................................................................... 43
7.2.2 Configuring the settings ...................................................................................................... 44
8. Designer Tutorial 4: Window Manager ............................................................................................... 46
8.1 Introduction ................................................................................................................................. 46
8.2 Why is this tool needed? ............................................................................................................. 46
8.3 A Practical Look at the Window Manager ................................................................................... 46
8.3.1 The Window Manager popup.............................................................................................. 46
8.3.2 Default behaviour ................................................................................................................ 47
8.3.3 Arranging plugins in a hierarchy .......................................................................................... 48
8.3.4 Modifying a hierarchy.......................................................................................................... 50

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

8.3.5 Custom windows and tabs .................................................................................................. 50

Appendix A: Using Configuration Tokens to Setup an Experiment Environment ....................................... 54
Introduction............................................................................................................................................. 54
OpenViBE tokens ..................................................................................................................................... 54
Paths .................................................................................................................................................... 54
OpenViBE Kernel ................................................................................................................................. 54
OpenViBE Designer.............................................................................................................................. 55
OpenViBE Acquisition Server............................................................................................................... 55
Core and environment tokens................................................................................................................. 56
Setting up an experiment environment .................................................................................................. 56

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Author’s Note

OpenViBE is a complete program for Brain-Computer Interface and neuroscience research developed
initially by the Inria research Institute, available immediately and freely, with amazing capabilities in the
hands of a well-trained user. Founded by the OpenViBE pioneers, Mensia Technologies is the technology
startup that pushes the OpenViBE BCI software to the next level!

The version of the software you have now in your hand includes specific developments for use with Brain
Products GmbH EEG devices. OpenViBE for Brain Products is a whole new version of the software with
many improvements towards stability, usability and capabilities of OpenViBE.

This Document is based on the online documentation you can find on the official OpenViBE website at
http://openvibe.inria.fr. We expanded the official documentation with a first section containing general
purpose information, and arranged the existing pages into a meaningful user documentation
compendium.

Please note that the information written here matches the online documentation available when writing
the document, as taken from the website. Therefore, the information presented here may differ slightly
from their online counterparts you will find when browsing the official website, if they have been
updated recently.

While this document covers the initial perimeter, focusing on the first hands-on sessions, you may need
some help when dealing with more specific or complex needs.

If you reach the point where you need help to use OpenViBE to its full potential, don’t hesitate to
contact us at Mensia Technologies. We can provide:

 Extended and specific documentation, individualized support

 Practical training courses
o For users and developers
o Generic or adapted to your projects
 Specific development
o Signal processing components, visualization tools, etc.
o BCI or neurofeedback applications

Website: www.mensiatech.com

Email: [email protected]

Enjoy OpenViBE!

The Mensia Team

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

1. Generals

1.1 What is OpenViBE?

OpenViBE is a software platform dedicated to designing, testing and using brain-computer interfaces.

OpenViBE is a software for real-time neurosciences (that is, for real-time processing of brain signals). It
can be used to acquire, filter, process, classify and visualize brain signals in real time.

OpenViBE is free and open source software. It works on Windows and Linux operating systems.

The main OpenViBE application fields are medical (assistance to disabled people, real-time biofeedback,
neurofeedback, real-time diagnosis), multimedia (virtual reality, video games), robotics and all other
application fields related to brain-computer interfaces and real-time neurosciences.

OpenViBE users can either be programmers or people not familiar with programming. This includes
medical doctors, video game developers, researchers in signal-processing or robotics, etc.

1.2 A modular system

The main concept kept in mind when designing OpenViBE was the modularity: OpenViBE is a very
modular system allowing to quickly and efficiently arrange small processing components into a high level
/ complex composition.

Figure 1 - OpenViBE: a modular system

1.3 Different views, for different users

OpenViBE is a complete software platform, for different users, programmers and non-programmers,
engineers and clinicians.

The Programmer implements new features, new modules in OpenViBE (e.g. new signal processing). The
Author, e.g. a BCI specialist, designs his BCI scenario using the OpenViBE Designer application, arranging
the different components to do a precise processing task. The Operator, e.g. a clinician, executes the
scenarios in the Designer, acquires the EEG with the OpenViBE Acquisition Server and monitors the
signals and other relevant variables during an experiment session. The Subject from whom EEG signal is
acquired gets sensorial stimulations and feedback through integrated (in the Designer) or external
applications.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Figure 2 - OpenViBE: adapted to different users

1.4 Hardware and software abstraction

OpenViBE is highly portable, being independent of the acquisition hardware thanks to a generic
Acquisition Server. On the software side, the portability is achieved through cross-platform compatibility
on Linux and Windows, thanks to a dependency policy focused on using only open-source and cross-
platform software.

You will find below the list of operating systems and acquisition devices currently supported by
OpenViBE.

1.4.1 Supported OS Architectures

OpenViBE is a multi-platform software. It works on Windows and Linux operating systems. For best
performance use one of the officially supported Windows versions or Linux distributions.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

List of supported architecture to date when writing this documentation:

Microsoft Windows XP 32bit

Microsoft Windows 7 32bit and 64bit
Note: Some third party drivers might not work on 64bit systems.

Latest Ubuntu Linux (non-LTS) distribution 32 bit and 64 bit

Current version : Ubuntu 11.10

Latest Ubuntu Linux LTS distribution 32 bit and 64 bit

Current version : Ubuntu 12.04

The two latest versions of Fedora Linux distribution

Current versions : Fedora 15 and Fedora 16

1.4.2 Supported Devices

OpenViBE can use a vast selection of hardware EEG devices. You should assure yourself that the device
you are using is compatible.

List of supported acquisition devices to date when writing this documentation:

Manufacturer Amplifier Driver Name OS Status Officialy Supported

Neuro ASALAB Either MindMedia Has been

EEG / ERP Nexus32B or TMSi reported to No
amplifier drivers work
ANT
Either MindMedia
Others TMSi
Nexus32B or TMSi Untested No
derived devices
drivers

Community :
Brainmaster Atlantis
Atlantis Stable
and Discovery  Mensia Technologies
BrainMaster
Community :
Brainmaster Atlantis
Discovery Stable
and Discovery  Mensia Technologies

Brain Brain Products V- Yes, contact Mensia

V-Amp Stable
Products Amp Technologies

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Manufacturer Amplifier Driver Name OS Status Officialy Supported

Brain Products Yes, contact Mensia

actiCHamp Stable
actiCHamp Technologies

Either MindMedia Has been

QuickAmp Nexus32B or TMSi reported to No
drivers work

Community :
Brain Products
BrainAmp Series Stable
BrainAmp Series  Yann Renard

Community :
Brain Products
BrainAmp Standard  Emmanuel Maby
All Stable
(through BrainVision (INSERM)
Recorder)  Pierre-Emmanuel
Aguera (INSERM)

Community :

CTF/VSM MEG CTF/VSM MEG Unstable  Emmanuel Maby

(INSERM)
 Pierre-Emmanuel
Aguera (INSERM)

EGI Net Amps 300

EGI Net Amps 300 Unstable Community
(through AmpServer)

Emotiv EPOC Emotiv EPOC Stable Yes

g.Tec gUSBamp
gUSBamp Stable Yes
Gipsa-lab

gTec
Community :
gMobilab+ gTec gMOBIlab+ Stable
 Lucie Daubigney
(Supelec)

Micromed SD LTM
Micromed SD LTM (through SystemPlus Stable Yes
Evolution)

MindMedia
MindMedia NeXus32 Stable Yes
Nexus32B

Neurosky MindSet NeuroSky MindSet Stable Yes

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Manufacturer Amplifier Driver Name OS Status Officialy Supported

MindWave NeuroSky MindWave Stable Yes

Community :

 Christoph Veigl
OpenEEG Modular (University of Applied
MonolithEEG Stable
EEG P2 Sciences Technikum
Wien)
 Yann Renard
OpenEEG
Community :

 Christoph Veigl
OpenEEG Modular (University of Applied
ModularEEG Stable
EEG P2 Sciences Technikum
Wien)
 Yann Renard

Either MindMedia
Porti32 Nexus32B or TMSi Stable Yes
drivers

Either MindMedia
TMSi Refa32 Nexus32B or TMSi Stable No
drivers

Either MindMedia
Others devices Nexus32B or TMSi Untested No
drivers

1.5 Content of the OpenViBE software platform package

When installing OpenViBE, you get the following set of applications:

 The Acquisition Server

o A generic application that connects and acquires from any kind of device as long as an
OpenViBE driver has been developed for it. The data is then made available in real time
over a network connection.
 The Designer
o An intuitive graphical interface to build a processing pipeline, from the acquisition client
(that connects to the server) to the presentation of data and stimuli.
 BCI Demos
o Motor Imagery, P300, SSVEP BCI

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

The main applications are the Acquisition Server and the Designer, we will detail them in dedicated
tutorials. The Demos will be covered in the documentation sections of the corresponding scenarios.

OpenViBE for Brain Products is a complete software package for BCI research that adds many
new features compared to the open-source version. The Acquisition Server and Designer
applications have been upgraded with stability fixes and quality-of-life improvements. The BCI
demos can be launched directly using the Scenario Launcher, a user-friendly program to rapidly
test and demonstrate OpenViBE capabilities.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

2. Configuration
In this section we review a component common to the whole OpenViBE software platform: the
configuration manager. We start with this component as we will mention several times in this document
how specific behavior can be changed according to this configuration manager.

The OpenViBE Configuration Manager is a software component in charge of configuring OpenViBE

applications and modules according to the user’s wishes. Configuration settings are saved in a
configuration file, which is loaded at application startup. This file uses a simple syntax, where
configuration tokens are listed and given a value. You can check all the configuration tokens in the
Designer (Menu Edit/Preferences).

2.1 Configuration files

OpenViBE comes with a default configuration file (share/openvibe/kernel/openvibe.conf), automatically
loaded at startup. This file lists configuration tokens used by the applications.

Users can edit a personal configuration file in order to customize their OpenViBE software platform, by
overwriting existing token or declaring new ones.

On Windows, the user-defined configuration file is either:

C:\Documents and Settings\[user-login]\openvibe.conf
or
C:\Users\[user-login]\openvibe.conf

On Linux it is:
~/.openviberc

WARNINGS:
1. The personal configuration file is not created by OpenViBE. Users have to create this file manually if
they need to.

2. The configuration files are loaded at startup. You must restart the application (Designer, Acquisition
Server) for any change to be considered.

2.2 Syntax
A configuration file basically looks like successive token = value statements.

For example, the application can retrieve its root path (OpenViBE installation path) from
the Path_Root variable. The path is expressed relative to the execution directory bin, so the root path
is simply:

Path_Root = ..Telnet Reader

Leading and tailing spaces are allowed, and are removed automatically :

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Path_Root = ..

Telnet Reader
Comments may be stored on their own lines. They begin after the ‘#’ character :

#this is a valid comment

Path_Root = ..

Reader
Lines ending with a ‘\’ character continue to the next line (the last ‘\’ character of a line is automatically
removed by the parser) :

#this is a line that extends\

to the next line
Path_Root = ..

Tokens declared anywhere in the configuration file may be used as values for other tokens. The syntax to
be used is : ${token}

For example, the binaries path may be declared as such :

Path_Root = ..
Path_Bin = ${Path_Root}/bin

Configuration files can include other configuration files thanks to a simple syntax:

Include = path/to/my/config/file.conf

All tokens are read sequentially, and thus can be overwritten during the process.

2.3 Existing tokens

Several tokens such as Path_Root and Path_Bin are defined in the default configuration file, and
can be overwritten in user-defined configuration files. We won’t list them here, however in the following
sections they will be mentioned when necessary.

2.4 Defining and using custom tokens

Defining your own token can be very useful as you can use them afterwards everywhere in OpenViBE.
For example, you can define a token LowPassFrequency = 40. You can then use it as a setting in
several temporal filters (${LowPassFrequency}). Changing the token value will automatically
change the filtering frequency in every temporal filter at once, which can be very handy: modification is
global and switching from one frequency to another is fast and easy.

We will describe a concrete example that illustrates the use of custom configuration tokens, in “

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Appendix A:
Using Configuration Tokens to Setup an Experiment Environment”.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

3. Acquisition Server

3.1 Introduction
OpenViBE Acquisition Server is a tool designed to communicate with hardware signal acquisition devices
and forward acquired signals and other experiment information to OpenViBE applications in a way
compliant with the OpenViBE format specification.

The acquisition server doesn’t communicate directly with acquisition devices. Instead, it provides the
user with a set of drivers to choose from, each one being dedicated to a given device model. New
devices can be supported by the server by developing new drivers. See Tutorial: creating a new driver for
the acquisition server for details on this.

3.2 The Graphical User Interface (GUI)

Let’s have a look at the graphical interface of the acquisition server tool to show what parameters must
be configured before it can be used to acquire and forward data. The server GUI should look like the
following:

Figure 3 - Acquisition Server GUI.

OpenViBE for Brain Products comes with a modified version of the acquisition server, thus the
interface differs from the open-source version you may be used to. We will describe these new
features in the following sections.

3.2.1 Acquisition Device Drivers

A list of available drivers is accessible under ‘driver‘. Depending on your distribution of OpenViBE, a
number of drivers may already be at hand. At least one driver should be available : the Generic
Oscillator. Contrary to most drivers, this one doesn’t connect to any hardware device, but generates
sinusoidal signals. It is appropriate for testing purposes. To change the default driver presented when
launching the Acquisition Server, add the following token to your configuration file :

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

# set the default driver :

AcquisitionServer_DefaultDriver = Generic Oscillator

If you don’t specify any driver that way, the driver presented upon startup is the latest used during
previous execution.

OpenViBE for Brain Products comes with all the drivers for Brain Products devices: BrainAmp
series, actiCHamp, VAmp. The Generic Oscillator is also included for testing purpose.

3.2.2 Connection Settings

In order to use a driver, connection details should be set so that the server communicates with
connected OpenViBE applications as desired. The port to which to send data can be changed under
‘Connection Port‘ (e.g. 1024 is a standard default setting). An OpenViBE application will then have to
fetch data from this port once an experiment is started. Also, the size of the buffers sent to connected
applications may be configured under ‘Sample count per sent block‘. This defines how many samples
should be sent per acquired channel in a single buffer. Valid values are powers-of-two and 32 is the
default. The duration or ‘epoch’ of a buffer depends on the sampling frequency, which may be set in the
Driver Properties dialog (see Driver Properties)

3.2.3 Driver Properties

Once a driver is selected from the drop-down list and before it can be used, its settings should be
configured appropriately. Settings provide information about the experiment being conducted and the
subject undergoing the experiment. The ‘Driver Properties’ button opens up the settings dialog of the
currently selected driver. It displays settings that can’t be retrieved from the hardware and that have to
be filled in by the user. They may vary between drivers. For example, the Generic Oscillator settings
include information about the subject (identifier, age, gender) and the acquisition (number of channels
to be acquired, sampling frequency).

When using another device, we suggest you read the corresponding documentation if any available, or
contact the driver author if any problem persist.

We provide with OpenViBE for Brain Products the documentation of every driver in a dedicated
PDF document. Please refer to these document if you have trouble using the Brain Products
device driver.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Figure 4 - Generic Oscillator settings.

3.2.4 Acquisition Server Preferences

Various global settings can be accessed through the ‘Preferences‘ button. Most users will leave these
parameters as default.

Figure 5 - Acquisition Server Preferences.

3.2.4.1 Drift Correction

The Acquisition Server monitors the behavior of the driver in order to ensure that it actually sends the
number of samples it should, based on the theoretical sampling frequency of the device. On a long run, a
device may drift (e.g. 3 missing samples every 5 minutes). The drift correction will ensure the acquired
signal is still time-stamped accurately.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

When a drift is detected, you will see a progress bar moving on the left or right (not enough or too many
samples). When the drift reaches a threshold, an automatic correction is done : the Acquisition Server
removes or duplicates some samples, and sends stimulation(s) to any acquisition client connected, so
you know in the signal that a correction just occurred.

If samples have been added, the portion of signal is delimited by the

stimulations OVTK_GDF_Correct and OVTK_GDF_Incorrect. If samples have been
removed, OVTK_GDF_Incorrect tags the corresponding moment.

Here are the parameters you can set for the Drift Correction:

 Drift correction : either Forced, Disabled, or driver dependent.

 Drift Tolerance (ms) : when reaching a drift duration of that value, a correction is triggered.

 Jitter Estimation Count for Drift : the window in number of “blocks” used to compute the drift.

The drift correction mechanism is very useful for BCI paradigms that necessitate a good synchronization
between the acquisition server and the processing application (e.g. P300 speller in the Designer). It
ensures that the signal tagging done in the Designer will be accurate. If the device you are using has
hardware tagging capabilities and the acquisition server gets the tags directly, the drift correction can be
disabled as there should not be any more synchronization issues.

3.2.4.2 Other settings

 Oversampling Factor : multiply the sampling frequency of the acquired signal, using linear
interpolation.

 NaN value replacement : if the device sends non-numerical values such as NaN (not-a-number)
or INF (infinite), the server detects it. You can choose either to replace them by 0 or the previous
correct value, or letting the server send them to the clients. Use this last option at your own risk,
as most of the Designer boxes will not handle such a value. Anyway, the faulty sample range will
be delimited by OVTK_GDF_Incorrect and OVTK_GDF_Correct stimulations.

 With OpenViBE for Brain Products, the acquisition server preferences have already been set with
good default values. You can safely start using your device with OpenViBE, and come back in
tweaking these settings when you need and feel comfortable doing so.

3.2.5 Cap montages and channel names

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

In OpenViBE for Brain Products, the acquisition server features a “Cap montage” selection, a
dropdown menu from which you can select the electrode layout from a list of Brain Products cap
models (actiCAP, easyCap, etc). The “Custom Montage” menu entry and the “Channel Names”
button allows you to manually rename your channel if need be.

Figure 6 - Selecting a cap montage and channel names

3.3 Usage
Once a device driver has been selected and relevant settings configured, data acquisition can start. The
server should first connect to the acquisition device, which is done by clicking the ‘Connect‘ button. A
label will inform the user whether the connection was successful.

When impedance check is requested and the driver presents such feature, a window will pop up showing
a gauge for every channel, and the impedance values. Default configuration considers that an impedance
below 5kΩ is “good”. You can change this limit by modifying the configuration token:

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

# limit for a good impedance in ohm :

AcquisitionServer_DefaultImpedanceLimit = 5000

Above twice this limit, the impedance gauge will be maxed.

If the connection was established and the device(s) successfully connected, data sampling can be
started/stopped by clicking ‘Play‘/’Stop‘.

Once a driver is ‘connected’ and ‘playing’, the clients (e.g. acquisition client boxes in a Designer scenario)
may be started : press ‘play’ in the designer. Data should be received, decoded and sent through the
openvibe pipeline you designed.

In the acquisition server window, you should see the number of clients connected to your server (e.g. ’2
hosts connected’).

3.4 Troubleshooting
If you don’t receive any signal from the acquisition client (e.g. you don’t manage to display any signal),
look in the Designer console. If you find the following message :

[WARNING] At time 1.02 sec <Box algorithm::Acquisition client>

Could not receive memory buffer size

[WARNING] Box algorithm <Acquisition client> has been deactivated

because process phase returned bad status

The acquisition server is connected, but stopped. Press ‘Play’ in the acquisition server then play in your
Designer scenario again.

If you receive the following error message in the Acquisition Server console :

[ INF ] Starting the acquisition...

[ INF ] Now acquiring...
[WARNING] After 5000 milliseconds, did not receive anything
from the driver - Timed out
[ INF ] Stopping the acquisition.
[ INF ] Disconnecting.

This means that the OpenViBE driver managed to connect to the device and start the acquisition, but the
device somehow failed to send the samples to OpenViBE, thus stopping the acquisition. Please be sure
that your EEG device is compatible with the OpenViBE driver, correctly plugged in, turned on and
configured before starting the acquisition. If the problem persists please contact the driver author or
official support for help.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Various error messages can be also printed in the console depending on the driver itself. In this case
please refer to the driver documentation or contact the support for further information.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

4. Designer Overview
NB: last update for OpenViBE 0.11.0 (aug-2011).

4.1 Introduction
The OpenViBE Designer is an authoring tool dedicated to creating and executing OpenViBE scenarios. It is
targeted at a broad range of users, including

 students and researchers of the BCI community

 neurophysiology experts who need a tool for signal processing and visualisation in the context
of brain activity

 clinicians looking for a tool to conduct neurofeedback experiments

It relies on a graphical user interface to provide signal processing tools in an intuitive way, and doesn’t
require any programming skills.

Each of these tools comes as a plugin, which communicates with the application via a generic interface
hiding implementation details. As a result, it is easy for a programmer to extend the range of tools
provided with the platform.

Thanks to an active open-source community, an ever growing number of these signal processing boxes,
or ‘box algorithms’ in OpenViBE terminology, are available in the Designer. Users may arrange any
number of these boxes in a very flexible fashion, considering there is virtually no limit as to the number
of boxes that may be included in a given BCI scenario.

Once a scenario is created, it may be run from the Designer, which provides a toolbar for playing,
pausing and stepping through a scenario. A number of box algorithms are available for
direct visualization of results, from simple 2D displays such as power spectrum and signal display to 3D
paradigms such as 3D topographical mapping. The layout of these displays may be customized as desired
at scenario editing time using the window manager module of the Designer.

The following sections are an overview of the main features of the Designer tool, and make for a quick
and easy introduction to its usage. Here are the topics covered in this overview :

 the top level menu bar

 the toolbar, which provides immediate access to the most common actions

 the ‘boxes‘ tree view

 the status bar, which provides performance information when a scenario is being run

 the console which prints Info, Warning or Error messages

 a scenario editor window, where boxes may be arranged together in order to fulfill the task at
hand.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Figure 7 - Designer interface (Windows7)

4.2 Menubar
Options available from the menu bar are presently restricted to actions involving handling and exiting
the application. Scenarios may be saved to XML files. Several scenarios may be edited simultaneously,
and the active scenario may be changed by clicking onto the corresponding tab at the top of the scenario
editor window. Here is a list of options from the menu bar and their shortcuts if available:

 File

 New – Ctrl+n: open a new scenario in a new tab

 Open – Ctrl+o: open a file selection dialog to select an existing scenario file

 Save – Ctrl+s: save current scenario

 Save As: save the current scenario in another file

 Close - Ctrl+w: close current scenario tab

 Quit – Alt+F4: quit the Designer

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

 Edit

 Undo – Ctrl+z: cancel the last edition operation

 Redo – Ctrl+y: redo the operation you just cancelled

 Cut – Ctrl+x: cut current selection

 Copy – Ctrl+c: copy current selection

 Paste – Ctrl+v: paste current selection

 Delete – Del: delete current selection

 Preferences: see below

The File menu handles standard scenario operations such as creation, saving and closing. Note that the
application won’t quit as long as at least one scenario is running.

The Edit menu allows the user to cut/copy/paste selections (in a scenario or across scenarios). These
options can also be accessed when right-clicking on a box. User actions are saved during scenario editing
and can be retrieved through undo-redo.

The last item, called ‘Preferences’, displays the Configuration Manager dialog. It contains a list of all
configuration tokens and their values. This list is read only. To know more about the Configuration
Manager, refer to The Configuration Manager documentation section.

4.3 Toolbar
The first section of the toolbar offers direct access to the scenario handling options that you can find in
the menu ‘File’.

A second section comprises two toolbuttons:

The first is a toggle button ( ) , allowing for displaying and hiding the window manager. This tool is
displayed in a popup window when the button is pressed. It takes care of arranging visualisation boxes in
a layout. Such boxes (if any in the current scenario) initially appear under the ‘Unaffected display plugins’
node of the tree view in the upper left corner. A window containing one tab is also created by default
and displayed on the right.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Figure 8 - Window manager popup dialog for a scenario with 4 visualization boxes, before and after making changes.

Users may create any number of windows containing any number of tabs, and then drag and drop
visualisation boxes onto such tabs in a tree-like structure. If the user chooses to not use the window
manager all visualisation boxes will be given their own window, displayed when the scenario is being
played. For a more in-depth review of the window manager usage, see the Window Manager
documentation section.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

The next toolbar button displays the log levels dialog ( ). It may be used to configure which log
messages should be displayed in the console. It contains 8 levels as shown in the following figure :

Figure 9 - Log levels dialog.

‘Warnings’ and ‘Errors’ should always be selected. ‘Information’ displays useful messages from signal
processing boxes. ‘Trace’ can be used to check step-by-step the processing in the boxes and the kernel.
‘Benchmark’ and ‘Debug’ are very verbose and should not be used with the designer console (only in log
files).

Two buttons then allow the user to customize the scenario with useful comments. One button (
) adds a dedicated comment box to the scenario. These boxes have of course no input and outputs.
Double click on them to edit the comment they display. The syntax of the comments uses pango font
style. To add a line feed, use Shift+Enter in the comment edition window.

Figure 10 - adding a comment in the scenario using pango font style

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

The other button ( ) allows to edit some information that will be saved with the scenario
(authors, date, description, etc.).

The next section is dedicated to scenario playing. It comprises the following buttons:

 Stop – F5
go back to scenario edition mode

 Step – F6
play scenario one step of simulation at a time

 Play/Pause – F7

 Fast Forward – F8
play scenario as fast as possible

Once a scenario is being played, it is not possible to modify it. Press ‘Stop’ to go back in edition mode.
Shortcuts from F5 to F8 can be used only if the focus is on the Designer main window (not on
visualisation windows for example).

Finally, the toolbar contains a time counter which displays the simulation time as a scenario is being run.
It is reset to 0 as a scenario is stopped.

4.4 Box algorithms tree view

The right-hand part of the Designer window displays a list of existing box algorithms, which are the
building blocks of OpenViBE scenarios.

4.4.1 Box algorithms

Under the ‘Box algorithms’ tab lies a tree view listing available box algorithms, along with a short
description of their respective roles. Box algorithms are the smallest granular elements that may be
manipulated by a Designer user. They act as black boxes which can be connected together by their inputs
and outputs. In order to facilitate their selection, they are grouped into categories, which make up the
top level nodes of the tree view. Some categories are related to signal processing, others to scenario
serialization or visualisation purposes.

The default treeview shows only stable and fully supported boxes. If you want to use old ‘deprecated‘
boxes please set the configuration token Designer_ShowDeprecated to TRUE. To use ‘unstable‘
boxes set Designer_ShowUnstable to TRUE or tick the corresponding box on top of the treeview.
As stated in their documentation pages, you are using these deprecated or unstable boxes at your own
risk.

The status of a box varies with the context, and is reflected by the color of the font used in the tree view.
The box name and description will use a green font if the box is deprecated, and a light grey font if it is
unstable. To know more about box status, go to Edition Area.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

4.4.2 Optional : Algorithms treeview

While box algorithms can be arranged together by the user to make up a scenario, algorithms lie at a
lower level in the OpenViBE object diagram and aren’t meant to be directly manipulated by the user.
Instead, they can be seen as reusable components which box algorithms relie on. A tree of existing
algorithms can be found next to the box algorithms tree if the configuration
tokenDesigner_ShowAlgorithms is set to TRUE. It is similarly sorted by category, only this time, it is
merely a reminder of what algorithms are available in the current state of the platform. They can’t be
added to a scenario.

4.5 Status bar

The status bar that lies at the bottom of the Designer window provides performance information. When
a scenario is being run, OpenViBE keeps track of the time used by each box and of the overall execution
time.

Overall performance is displayed in a green gauge overlaid with the same information in percent. A
system load 100 percent means the system is barely able to handle the computation load induced by the
scenario to run in real-time.

To identify the bottlenecks in a scenario, one can press the button to the right of the gauge as a scenario
is being run. This will highlight boxes from green to red, depending on how much time is spent in each
box relative to the others.

4.6 Console
The Designer console can be expanded/hidden by a simple click. You can choose the log levels you want
to see in this particular window (does not modify the active application log levels).

The Designer console has been developed in order to be sure to see any warning or error messages, that
otherwise appear in the background console discretely.

4.7 Edition Area

The last section of this overview covers the working area of the Designer, which is where OpenViBE
scenarios are assembled by connecting box algorithms together.

4.7.1 Boxes
Box algorithms are added to the active scenario by drag and dropping them from the tree view to the
scenario edition window. They appear as rounded rectangles with their name inside the box, inputs (if
any) on top and outputs (if any) at the bottom. These connectors are displayed as color-coded triangles.
Colors vary with the connector type, and help users to make sure they connect boxes properly. See
Connector Types for an overview of the different connector types and hierarchy.

Figure 11 - A file reading box algorithm which has 3 outputs (experiment information, signal and stimulations streams)

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Additionally, if the box has customizable settings, they may be set by double clicking on the box (tip :
when a box has such settings, its name is displayed in bold case). The settings are listed in the popup
dialog that appears, along with their default values. Settings may be overridden by directly typing in their
desired values, or they may be read from a file. In the latter case, one should expand the ‘Override
settings with configuration file’ section to check the ‘File’ button and pick a configuration file.

Figure 12 - Settings of a ‘GDF file reader’ box : filename text entry and number of samples to be stored per buffer.

4.7.2 Box status

By default, the status of a box is ‘normal’, and the box is drawn with a white background. However, some
boxes may have a different status depending on the situation. Here are the other possible status of a
box:

 Unstable: a box which is under development should be flagged as ‘unstable’, meaning it has
probably not been tested enough to guarantee correct behaviour. Such a box is drawn with a
dark grey background in the Designer, and the ‘unstable’ label appears below the box name.

 Update : when a box is not up to date with the latest version used in a given distribution of
OpenViBE, it is drawn with a light grey background and the mention ‘update’ appears below the
box name. This situation arises when the prototype of a box has changed between the time the
scenario it is stored in is saved and the time it is loaded again. Since scenario files contain
information about box prototypes, such as the number of connectors, they may need to be
updated when the OpenViBE distribution used to manipulate scenarios changes. To update such
a box, simply delete the box from the scenario then add it again. The new box will use the latest
version. Tip : after such an update, one should make sure to reconfigure the box settings if
needed!

 Deprecated : as OpenViBE evolves with time, some boxes are added to the platform and others
are deleted. It can also happen that a box is replaced with another one (maybe for performance
reasons). However, the ‘old’ box is not necessarily deleted from the platform, but may be kept
for backward compatibility with older versions (ensuring older scenarios may still be run, for

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

example). In that case, the documentation should mention that from that time on, the new box
should be preferred over the deprecated one (which may be removed from the platform at any
time, and in any case which probably won’t be maintained anymore). Such boxes are displayed
with a dark green background and the ‘deprecated’ label below the box name.

Note : when a box is deprecated and also needs to be updated to the newest version, both ‘deprecated’
and ‘update’ labels will appear below its name in the Designer. As to its color, it will appear as dark
green, reflecting its deprecated state.

4.7.3 Box editing functionalities

All box algorithms may be configured in the Designer. However, not all boxes offer the same
configuration options. In this overview, we’ll focus on functionalities that are common to all boxes. More
advanced possibilities are detailed in another tutorial (Designer Tutorial 4: Advanced box configuration).

To illustrate box editing functionalities, let’s start by creating a new scenario, and drop a couple of boxes
from the box algorithms tab. Simple boxes such as ‘Clock’ and ‘Nothing’ (found under the ‘Samples’
category) will do for this tutorial. Drag and drop these boxes in the scenario working area, then right-
click on the ‘Nothing’ box. A context menu should appear, listing different editing functionalities.

Box editing functionalities appear in the lower part of the menu :

 ‘Rename box (F2)’ allows to rename the box. Click this option and enter a new name such as
‘Dummy Box’ to test this functionality.

 ‘Delete box (Del)’ removes this box from the scenario. Note that a box may also be deleted by
selecting it, then pressing the ‘Delete’ key.

 ‘About box’ displays a dialog containing a summary of the box details, such as its author, version,
class name, as well as a short and long description of its purpose. Note that the ‘short
description’ field also appears in the second column of the box algorithms tab.

Another option only gets listed for those boxes that offer configurable settings, such as the Clock box
(this may be guessed from its name displayed in bold case). Right click on this box and select :

 ‘Configure box’, which displays the Box Settings dialog. Note that this dialog may also be
displayed by double clicking on the box itself.

4.7.4 Scenario editing functionalities

Standard cut/copy/paste functionalities are supported in Designer. Select a box and right click on it to
display a menu from which to select these options.

Groups of boxes may be edited in the same way. Select several boxes at once by maintaining the Ctrl key
pressed then clicking on the boxes you want to cut or copy. You may also draw a selection area by left
clicking in the scenario editing area then drawing a selection rectangle while keeping the button
pressed. Ctrl+a selects everything in the scenario.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Cut/copy your selection by right clicking on it then selecting the corresponding entry, or by
pressing Ctrl+X/Ctrl+C.

Paste your selection by right clicking anywhere in the edition area, or pressing Ctrl+V. Note that you may
also paste selections from one scenario to another.

Delete your selection by selecting ‘Delete boxes’ in the contextual menu, or pressing the ‘Delete‘ key.

Finally, the origin of the scenario editing area may be changed by pressing and holding the Shift key and
left click then moving the mouse as desired. This allows you to explore your scenario window without
using the scrolling bars.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

5. Designer Tutorial 1: Creating a simple scenario

NB: last update for OpenViBE 0.11.0 (aug-2010)

In this first tutorial, we are going to build a basic signal processing scenario demonstrating the steps
involved in creating and executing a scenario.

5.1 Step 1: Creating a new scenario

First off, we must start the Designer by :

 [Windows] Using the corresponding shortcut, or double-clicking on the openvibe-

designer.cmd file in the OpenViBE installation directory,

 [Linux] executing openvibe-designer.sh

The Designer main window should appear, and a default untitled scenario should be open and ready to
be edited.

Figure 13 - Designer main window upon startup

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

5.2 Step 2: Adding a box algorithm

Boxes are the building blocks of OpenViBE scenarios. A number boxes are included in your distribution of
OpenViBE. They can be found under the ‘Boxes’ tab on the right hand side of the Designer’s main
window.

Most scenarios need signal data to work on. A simple way to obtain such data consists in generating
random signals using a Sinus Oscillator box. Let’s expand the ‘Samples’ category. This should display a list
of sample boxes, along with a short description. There should be a Sinus oscillator box among them. Let’s
drag and drop this item in the scenario edition window. The box should appear where the item was
dropped.

Figure 14 - Drag and dropping the Sinus Oscillator samples box in the scenario edition area

5.3 Step 3: Connecting boxes

The Sinus Oscillator box generates random sinusoidal signals on a varying number of channels. We are
going to display them on the screen using one of OpenViBE Designer visualisation boxes.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

A simple way to do that is to add a Signal Display box to our scenario. This box displays signals for a
varying number of channels in a popup window. It can be found under ‘Visualisation’, in the ‘Basic’ sub-
category, along with other visualisation plugins. Drag and drop the Signal Display under the Sinus
Oscillator box.

To forward data from the first box to the second, we must connect the Signal output of the Signal
Oscillator to the Signal input of the Signal Display. Move the mouse cursor over box connectors (they lie
on the box top and bottom edges and are represented as color-coded triangles). As the cursor is moved
over a connector, a tooltip containing the connector name and type should appear. Once you have
identified the right connectors, connect them by pressing the left mouse button on one connector,
moving the mouse over the second connector and releasing the button. A link should now connect both
connectors (to know more about the different types of connectors, see Connector Types).

Figure 15 - Linking box algorithms using their input and output connectors

5.4 Step 4: Saving a scenario

Before running a scenario, it is a safe practice to save it. There are two ways to do this :

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

1. open the File menu situated in the top menubar and select the ‘Save As’ item, or

2. click the ‘Save As’ icon, which can be found in the toolbar (right under the menubar) Enter a
suitable name and click ‘Save’ to dump the scenario contents in a file.

5.5 Step 5 : Playing a scenario

Our scenario is now ready to be executed. Press the ‘Play’ button in the toolbar. A popup window should
appear, displaying random sinusoidal signals.

Figure 16 - Signal Display box displaying sinusoidal signals

To stop the scenario, just press the ‘Stop’ button in the toolbar. The popup window should disappear,
and you should be back to the scenario edition panel.

Congratulations, you have just completed your first tutorial!

To know more about OpenViBE Designer capabilities, including its window layout editor and how to
customize scenario settings, proceed to the next tutorial.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

6. Designer Tutorial 2: Customizing a scenario

NB: last update for OpenViBE 0.11.0 (aug-2010).

This second tutorial demonstrates how scenario settings can be customized both offline (at scenario
editing time) and online (as the scenario is being played).

6.1 Step 1 : Identifying customizable boxes

Some box algorithms expose settings for configuration by the scenario editor. When working in the
Designer, there is an easy way to know whether a box exposes configurable settings : look at the box
name:

 Bold font means the box exposes at least one configurable setting, whereas

 Normal font means the box is not configurable.

Let’s open the scenario that was designed in the first tutorial (see Tutorial 1). Both boxes have bold
name, meaning they can be customized offline.

Figure 17 - Two customizable boxes

6.2 Step 2: Offline settings modification

To open the settings dialog of a box, double click on the box. Let’s double click on the Sinus Oscillator
box. This pops up a dialog divided in two parts :

 the upper part shows the list of settings, where values can be entered via input fields,

 the lower part handles an alternate way of specifying settings by reading them from a file. This
part can be unfolded by clicking the ‘+’ character. Tick the checkbox on the right and specify the
file you want to use. Configuration file format is described in a dedicated page, Box Algorithm
‘settings override’ file format.

The most straightforward way to customise a box consists of modifying settings values from this dialog.
The Sinus Oscillator has several settings, and the input field of each setting displays its default value.
Let’s modify the number of channels for which to generate sinusoidal signals, by entering “2″ in the
Channel count input field. Validate the configuration by clicking the ‘Apply‘ button.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Figure 18 - Sinus Oscillator settings dialog

Save the new scenario settings by selecting the ‘Save’ option from the ‘File’ menu, or clicking the ‘Save’
button in the toolbar.

Now let’s observe the changes made to the scenario by playing it. There is no need to modify the Signal
Display box, which dynamically adapts itself to the number of channels in use in the scenario. Click
the Play button to start the scenario : the visualisation box should automatically restrict its display to 2
channels only:

Figure 19 - Offline modification of the number of channels

6.3 Step 3: Online settings modification

The previous step demonstrated how scenario settings may be initialized and saved along with other
scenario information.

Now we are going to see how some settings can also be accessed as a scenario is being played, making it
possible to dynamically modify some parameters.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

The prototype of a box specifies what inputs, outputs and (offline) settings it exposes. However,
visualisation boxes (that is, boxes that display 2D or 3D data when a scenario is being played) offer
another possibility to tune some of their parameters. The visualisation box developer has the possibility
to create a toolbar for the box. When such a toolbar exists, it may be displayed by clicking the button
named after the box which is displayed on top of the popup visualisation window.

Figure 20 - Visualisation boxes with a toolbar have an active title button (highlighted in this figure)

Click the toolbar button : the toolbar is displayed in a popup window. A number of settings and
commands are accessible from the toolbar, including zooming options, left and bottom rulers toggle
buttons, a time scale setting, channel selection options and a button popping up a scenario information
dialog. To know more about this plugin, refer to its user documentation here : Signal Display

The time scale, i.e. the time span covered by the displayed signals, can be modified using the dedicated
spin button. Try entering a new value such as 3 (it is expressed in seconds). The bottom time ruler, if
displayed, reflects this change immediately.

Figure 21 - Modifying the time scale using the toolbar

Now try out the other options to learn how the Signal Display plugin may be customised, then move on
to Tutorial 3 to learn about advanced box configuration!

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

7. Designer Tutorial 3: Advanced box configuration

NB: last update for OpenViBE 0.11.0 (aug-2010).

This tutorial details advanced box configuration settings, which require a general understanding of the
Designer application. Not all settings are available for each box. This document goes through all existing
ways a box may be configured, illustrating each setting with a concrete example. For more information
about advanced box configuration, one should refer to the box algorithms documentation pages.

7.1 Connectors configuration

Some boxes are too generic for the box developer in that he is not able to specify how many connectors
this box should own, or what type these connectors should be. Thus the design of such boxes allows the
user to configure the number and/or type of connectors.

When the number of connectors a box should own is not known a priori, developers may choose to
initialize the box with only one input and/or output connector, or none at all.

When the type of connector is configurable, the box developer may choose to initialize it with the
‘undefined’ type. Such connectors appear as white in the Designer, which will alert the author at
scenario editing time and remind him that the connectors of the box should be configured depending on
the context in which they are used.

In any case, when a box can handle a varying number of connectors, or when the type of its connectors
may be changed, it displays green ‘In’ and/or ‘Out’ labels below the box name. These labels tell the
author that the box has configurable input and/or output connectors.

7.1.1 Adding connectors

Some boxes are designed to handle a varying number of input or output connectors. For example,
the Generic stream reader box (found under ‘File reading and writing/OpenViBE’) is a reader which
doesn’t know in advance what kind of data it is supposed to output. It is up to the author to specify what
the box should output. For example, let’s assume the input stream contains signal data as well as
stimulations information. If both data types are relevant in the scenario being edited, the author can
choose to add one ‘signal’ output connector and one ‘stimulations’ output connector. As the scenario is
being run, the box will check what data types it should forward in the output stream and retain signal
and stimulations, discarding other input data.

To add a new output connector, right-click the box and select the ‘new…‘ action. You can then specify
a name and a type for the new connector.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Figure 22 - Adding a connector on a Generic Stream Reader box

Similarly, the generic stream writer is a generic file writer. It’s up to the author to specify what kind of
data should be saved to disk by adding the appropriate output connectors to the box.

7.1.2 Configuring the type of a connector

To illustrate the usefulness of setting the type of a connector at scenario editing time, let’s take the
example of the Epoch Average box. This box performs matrix averages, and is thus initialized with one
streamed matrix input connector and one similarly typed output connector.

Since the spectrum type derives from the matrix type, a ‘spectrum’ output connector can be connected
to the default ‘streamed matrix’ input connector of the epoch average box. However, doing so would

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

result in the loss of some data specific to the spectrum type (such as the list of frequency bands min and
max thresholds). To perform matrix averages while retaining type-specific information in the output
flow, one can modify the type of the input and output connectors and downcast them to ‘spectrum’
type.

To do so, right-click on the box, and select the ‘configure…’ action for the first input, and then change the
type to ‘Spectrum’.

Figure 23 - Changing the connector type of an Epoch average box

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

7.2 Settings configuration

Some boxes allow the user to modify its settings. For example it can be useful when the box can perform
an unknown number of different tasks, each one specified by a given group of settings.

7.2.1 Adding settings

The Run Command box (category ‘Stimulation’), which can be used to execute a system command when
a given stimulation is received, can be configured with a number of various settings. Right-click the box
and click New to add new settings.

When you do so, the box will have 2 more settings: one is the stimulation needed to trigger the comand,
the other is the command itself.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Figure 24 - Adding new settings in a Run Command box

Used on windows, this illustrative configuration will execute MS notepad when the
OVTK_StimulationId_Label_01 is received, and the MS calculator when OVTK_StimulationId_Label_02 is
received. Try it with a Keyboard Stimulator!

7.2.2 Configuring the settings

The Lua Stimulator box (category ‘Stimulation’) executes a user-defined script written in Lua that can
receive and send stimulations. The box can expose settings that can then be accessed in the Lua script at
runtime. In the following example, we add an Integer setting. We want to modify it with a new name and
default value. Right-click the box and select the setting you want to modify. Then configure its name,
type and/or default value at will.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Figure 25 - Configuring a setting in a Lua Stimulator box

Now move on to the Window Manager Tutorial!

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

8. Designer Tutorial 4: Window Manager

NB: last update for OpenViBE 0.11.0 (aug-2010).

8.1 Introduction
The Window Manager is a module dedicated to the handling of 2D and 3D graphical windows in an
OpenViBE scenario. It provides the user with an intuitive tool to arrange windows in space in a very
flexible manner. Window layouts designed with this tool are then saved to disk in scenario files along
with other scenario data and settings.

8.2 Why is this tool needed?

OpenViBE scenarios are essentially made up of one or several box algorithms linked together to forward
data as it is processed. Some of these box algorithms, or boxes, are meant to display information, and
will therefore open one or several windows at runtime. Examples of such boxes include the Signal
Display, Power Spectrum or 3D Topographic Map plugins.

The default behaviour of the window manager as a scenario is being run is popping up as many toplevel,
independent windows as required depending on the number of graphical plugins contained in the active
scenario. While this may work fine for simpler cases, the screen may become cluttered with windows
when more complex scenarios are being run. This is where more clever window layouts can help, by
arranging graphical plugins in window hierarchies so that, e.g. all display plugins fit in one window,
saving the user having to resize or place windows next to each other every time a scenario is played.

By designing a window layout offline, the user ensures graphical plugins will always appear at the same
location. Also, it makes it possible to set relative sizes, so that windows requiring more screen space
always do get more than their neighbours both at player launch time and when windows containing a
hierarchy of windows get resized. All that is required is just a little extra time at scenario editing time.

8.3 A Practical Look at the Window Manager

8.3.1 The Window Manager popup
Let’s have a look at the window manager interface.

First, let’s create a new scenario. The window manager is popped up by clicking on the ‘window
manager’ button in OpenViBE Designer’s top toolbar. Alternate presses on this button will show/hide the
window manager.

The window manager graphical interface is divided in two sections. Left is a tree view containing a list of
graphical plugins used in the active scenario and the current window layout. Right is a preview of the
currently selected window, if any. By default, a single window is created and selected. Its preview should
appear on the right hand side, with an ‘Empty’ placeholder widget filling its single tab.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Figure 26 - Window manager popup window.

As graphical plugins are added to the scenario, they are automatically registered by the window
manager, and will appear in its interface under ‘Unaffected display plugins‘ in the tree view. This means
such plugins aren’t included in any custom window, but will instead show up in their own top level
window as the scenario is played.

8.3.2 Default behaviour

Let’s add a few graphical plugins to our scenario to illustrate the default behaviour of the window
manager.

Let’s drag and drop a Signal Display, a Power Spectrum, a 2D Topographic Map (which can all be found in
the ’2D Visualisation’ plugin category) and a 3D Topographic Map (found in ’3D Visualisation’). As each
box is added to the scenario, it also appears in the window manager tree view.

If we play our scenario now, we get 4 equally sized top level windows that appear at random places on
the screen.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Figure 27 - 4 graphical plugins in a scenario, unaffected in the window manager.

8.3.3 Arranging plugins in a hierarchy

Let’s make things a bit more practical by arranging plugins in a layout. One way this can be done is by
drag and dropping ‘unaffected’ plugins over the window created by default on the right hand side of the
window manager.

Let’s select the Signal Display plugin and drop it over the ‘Empty’ placeholder widget. This empty widget
gets automatically destroyed and replaced with the Signal Display plugin. Note how the tree view
structure has changed, reflecting the modified layout. The signal display plugin is now listed under the
default window/default tab node.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Figure 28 - Adding a plugin to a window.

We can add more than one plugin to a single tab : let’s drag the Power Spectrum plugin and move it over
the areas surrounding the Signal Display plugin. Possible drop zones, or ‘targets’, become highlighted as
the cursor is moved over them. Let’s drop the plugin over the target situated to the right of the Signal
Display. Following the same procedure, it is possible to arrange all 4 plugins in custom hierarchies.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Figure 29 - One possible way of arranging 4 plugins in a single tab: windows manager setup and result

8.3.4 Modifying a hierarchy

It is possible to modify the plugins arrangement at any time, even as they have been placed in windows
and tabs.

The size of a plugin relative to the others lying on the same tab are modifiable by dragging the handles
separating one plugin from its neighbours. Handle positions are saved along with the tree structure.

Plugins can be removed from their hierarchy and placed back under the ‘Unaffected’ node by selecting
them in the tree view and clicking ‘Remove’ in the context menu that pops up on a right click. The tree
structure is then automatically updated and simplified. The same mechanism is applied on the tree
whenever a graphical plugin is deleted from the scenario.

Plugins may also be swapped by drag and dropping one from the tree view or window preview and
dropping it over another plugin in the preview window.

8.3.5 Custom windows and tabs

For further flexibility, one can create custom windows and tabs.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Let’s pop up the window contextual menu by right clicking the ‘Default window’ item in the tree view.
This should pop up a menu containing three options :

 ‘New tab‘ to add tabs to the selected window

 ‘Rename‘ to rename the selected window

 ‘Remove‘ to remove this window and its hierarchy from the layout (any plugin it contains would
then be listed again under the ‘Unaffected’ node)

Let’s create a new tab and name it “3D Tab”. Now we want to move the 3D Topographic Map plugin to
this tab, which can be done by selecting it in the tree view or the preview window, moving the cursor
over the desired tab until it becomes active and dropping the plugin on this tab. Note that you cannot
drag items around inside the tree view, but must drag them to a tab. And when dragging an item to a
tab, you need to drag the item to the intended workplace slot inside the opened tab, not just to the tab
header at the top.

We should now rename the first tab by right clicking on it in the tree view, selecting ‘Rename’ and typing
in a new name such as “2D Tab”.

Figure 30 - Adding a tab to a window.

More windows may also be created by right clicking the ‘Unaffected display plugins’ node in the tree
view and selecting ‘New window’ (Note: window names should be unique within a given layout).

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Note:

When all the windows are removed, a situation is likely to happen where the visualization widgets are
listed on the left side but no window is present on the right side. In this situation, the user can be
confused on where to drag and drop his widgets. The correct way to solve this problem is just to create a
new empty window, right clicking the ‘Unaffected display plugins’ node in the tree view and selecting
‘New window’. Then the user is able to drag and drop his widgets in the newly created window!

Now it’s up to you to arrange your plugins to best fit your needs!

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Appendix A:
Using Configuration Tokens to Setup an Experiment Environment
Introduction
The configuration manager object provides access to different variables than can be used in OpenViBE, in
any path or file name. The Configuration Manager dedicated section shows you how to set up the
Designer and Acquisition Server configuration tokens (to show unstable drivers and boxes for example).
We focuses here on the other tokens.

These configuration tokens can be divided in 3 groups:

 the “openvibe” variables are those declared in the Kernel or in the local configuration file.

 the “core” variables are predefined, and different each time they are called.

 the “environment” variables are those declared in the operating system.

OpenViBE tokens
The following subsections list a selection of token defined in the default configuration file, grouped by
category. All these tokens can be used in user-defined tokens or overwritten.

Paths
These tokens tell applications about OpenViBE installation directories.

 Path_Root is the root installation directory of OpenViBE

 Path_Bin is the binaries directory

 Path_Lib is the libraries directory

 Path_Data is the data directory. Default: ${Path_Root}/share/openvibe

 Path_UserData is a writeable location. Default: $APPDATA/openvibe (Windows)

and $HOME/.config/openvibe (Linux)

 Path_Log is the directory where logs are saved. Default: ${Path_UserData}/log

 Path_Tmp is the application temporary directory. Default: ${Path_UserData}/tmp

OpenViBE Kernel
This section lists tokens that may be used to configure the OpenViBE kernel.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

 Kernel_MainLogLevel specifies the log level threshold below which all messages should be
ignored.

 Kernel_ConsoleLogLevel specifies the console log level. It should be equal or greater than the
main log level.

 Kernel_FileLogLevel specifies the application file log level. It should be equal or greater than the
main log level.

 Kernel_PlayerFrequency specifies the frequency at which to run the player. For example, it can
be set to 128 (Hz).

OpenViBE Designer
One can configure several OpenViBE Designer parameters using the following tokens :

 Designer_ShowAlgorithms specifies whether to display the ‘Algorithms’ tab in the Designer. The
value can be TRUE or FALSE.

 Designer_ShowUnstable specifies whether to display the ‘unstable’ boxes in the Designer.

Unstable boxes are work-in-progress and have not been fully tested. The value can
be TRUE or FALSE.

 Designer_FullscreenEditor specifies whether to start the Designer in fullscreen or windowed

mode

 Designer_DefaultWorkingDirectory is a path to the default directory where to load and save

scenario files, relative from the execution directory.

OpenViBE Acquisition Server

A few acquisition server parameters may be initialized in the configuration file :

 AcquisitionServer_DefaultSampleCountPerBuffer is the default number of samples to send per

buffer (example : 32)

 AcquisitionServer_DefaultDriver is the default driver to be used (example : Generic oscillator)

 AcquisitionServer_DefaultConnectionPort is the default port to use to send data (example :

1024)

 AcquisitionServer_ShowUnstable specifies if ‘unstable’ drivers should be available in the

acquisition server. The value can be TRUE or FALSE.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Core and environment tokens

Group Variable Value

$core{date} Current date (y-m-d)

$core{index} A value incremented each time the variable is called

core $core{random} Random value in [0,2^32]

$core{real-time} Time elapsed since start of the scenario

$core{time} Current time (h.m.s)

Environment $env{VariableName} Any environment variable set in the operating system

Setting up an experiment environment

The custom file that you can edit depending on your needs and preferences is ~/.openviberc on Linux
and C:\Document & Settings\your-name\openvibe.conf on Windows. The syntax of the file is quite
simple: 1 line per token, token_name = token value, e.g.:

Example1 = this is an example

Example2 = this is another example

Example3 = Example 1 is ${Example1}

# this is a comment

OpenViBE expands several box settings such as the filenames, thanks to the configuration manager. For
example, if you put this in your configuration file :

ExperimentPath = /home/me/openvibe-data/signals

Then your file writer boxes (be it GDF, OpenViBE, CSV or whatever other box writer) could use a filename
such as ${ExperimentPath}/record.gdf

You can use a token value inside a token name. Suppose you have a configuration file with :

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.
 OpenViBE User Documentation version 2014.06.27

Current = Experiment1
CurrentPath = ${${Current}Path}

In this example, CurrentPath will automatically be expanded to ${Experiment1Path}. To take

advantage of this, you could add the following to your configuration file :

## Configures what experiment is being performed

# ExperimentName = MotorImagery
ExperimentName = P300Speller
# ExperimentName = Neurofeedback

## Configures who is doing the experiment

SubjectName = yann.renard
# SubjectName = someone
# SubjectName = noname

ExperimentMotorImageryPath = /openvibe-data/motor-imagery
ExperimentP300SpellerPath = /openvibe-data/p300-speller
ExperimentNeurofeedbackPath = /openvibe-data/neurofeedback

ExperimentPath = ${Experiment${ExperimentName}Path}

ExperimentFilename = ${ExperimentPath}/record-${SubjectName}-
$core{date}-$core{time}.gdf

The interesting line here is ExperimentPath =

${Experiment${ExperimentName}Path} that allows you to quickly switch from an experiment
environment to another, depending on a single token: ExperimentName.

OpenViBE is the property of Inria, Fr. licensed to Mensia Technologies SA, Fr.
This document is © Mensia Technologies SA all right reserved.