- NB: Document updated 20.May.2016.
In the OpenViBE 0.15.0 we have introduced a new way for external applications to communicate with OpenViBE. This document describes how to send stimulations from your application directly to the Acquisition Server.
Motivation
Some BCI applications require very precise tagging of events. As an example we could look at the P300 paradigm where it is necessary to know the precise moment when the stimulus was presented to the user, in order to find the brain response 300 milliseconds later.
The best way of marking such an event is to detect the stimulus by acquisition hardware and embed the tag inside the signal. However, it is not always possible to do this. Some popular EEG headsets do not have a way to send triggers along with the signal and the majority of current PCs do not possess a parallel port which is usually necessary to send precise hardware stimulations.
In order to address this problem, the Acquisition Server now has the ability to receive stimulations from an external application. These will then be embedded in the signal at the right time.
Implementation
The current implementation uses boost interprocess messages. The advantage of this solution is that it is fast and reliable, the disadvantage is that the external application must run at the same computer as the acquisition server.
Schematically a P300 application using the software tagging would work in the following way:
The description of the bullets follows:
- The OpenViBE Acquisition Server acquires signal from the EEG device
- At the same time the External Application sends triggers to the Acquisition Server
- The Acquisition Server combines signal from the EEG and triggers from your External Application into one stream, triggers are represented as Stimulations
- The Acquisition Client box will pass the signal to the signal processing chain
- An optional controller box can give commands (such as target letter) to the External Application via VRPN
- The processing chain will give commands to the External Application (detected letter)
Example code
Please look at the external_stimulation_connection_example
program included in OpenViBE distribution.
Two files are included.
openvibeStimulationConnection.hpp
- This header contains the
OpenViBE::StimulationConnection
class, this class exists to abstract the boost interprocess messaging.
- This header contains the
ovesce_main.cpp
- This is an example application using the
StimulationConnection
class. It is a minimal example which, upon execution, sens aOVTK_StimulationId_Beep
stimulation to the Acquisition Server.
- This is an example application using the
The StimulationConnection
class communicates with the Acquisition Server through a boos interprocess messaging queue. By default the queue’s name is “openvibeExternalStimulations”. Note that if you run several Acquisition Servers on the same machine then, by default, they will all consume the same queue!
The queue’s name the Acquisition Server uses can be changed by modifying the AcquisitionServer_ExternalStimulationsQueueName
configuration token.
In order to send stimulations you will have to include the openvibeStimulationConnection.hpp in your source code:
#include "openvibeStimulationConnection.hpp"
The StimulationConnection class is initialized in the constructor:
OpenViBE::StimulationConnection* osc = new OpenViBE::StimulationConnection("openvibeExternalStimulations");
Note that you do not have to specify any parameter to the constructor if you wish to use the default queue name.
Now at any time you want to send a stimulation to the Acquisition Server you can simply call the sendStimulation(uint64 stimulationCode)
function. The stimulationCode
parameter specifies the stimulation you wish to send (using the standard OpenViBE coding).
osc->sendStimulation(OVTK_StimulationId_Beep);