Send stimulations from your application to the Acquisition Server

  • NB: Document updated 20.May.2016.
Warning: The External Stimulations technique has been deprecated in OpenViBE 1.2.0. The currently recommended approach for the same purpose is TCP Tagging. This document has been retained as a reference.

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.


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.


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:

Software tagging schema

The description of the bullets follows:

  1. The OpenViBE Acquisition Server acquires signal from the EEG device
  2. At the same time the External Application sends triggers to the Acquisition Server
  3. The Acquisition Server combines signal from the EEG and triggers from your External Application into one stream, triggers are represented as Stimulations
  4. The Acquisition Client box will pass the signal to the signal processing chain
  5. An optional controller box can give commands (such as target letter) to the External Application via VRPN
  6. 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.
  • ovesce_main.cpp
    • This is an example application using the StimulationConnection class. It is a minimal example which, upon execution, sens a OVTK_StimulationId_Beep stimulation to the Acquisition Server.

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).



This entry was posted in Deprecated and old documents and tagged , , , . Bookmark the permalink.