Overview: Sending data & stimulations to/from OpenViBE

  • NB: Document updated for OpenViBE 2.1.0 (21.May.2018).

There are various ways to stream data and events (stimulations) between OpenViBE and external applications in real time. For example, classification results can be sent from Designer to control a game, or a robotic arm, and processed data can be forwarded to show custom visualizations, etc. Whatever technique you choose to use, you’ll have to add a corresponding receiving or sending capability into your application or device. Below, you’ll find list of techniques currently supported by OpenViBE and links to some documentation to assist in building the connections.

Special case: EEG markers

One of the most common requirements in EEG and BCI experiments is to have the EEG recording annotated with a marker timeline describing the time course of the experiment. For example, flashes in P300 and the starts and stops of motor imagery trials fall into this category. In OpenViBE, such timeline defining markers are called stimulations. It is usually important to get these markers as accurately aligned to the EEG data as possible, regarding the time the event occurred. The currently recommended way to do this is to send the occurrence of the event from the rendering component directly to the amplifier or Acquisition Server after it has been shown. A software solution to this in OpenViBE is called the TCP Tagging technique. The received markers will be appended to the EEG stream by the Acquisition Server as stimulations. The alternative is to use hardware tagging, and send the markers directly to the amplifier.

Note that it is usually not very accurate to merge EEG data and stimulations inside Designer. This is because Designer operates in simulated time. Hence the software/hardware tagging approaches described above are recommended. Also, for new developments, it is not recommended to use the old External Stimulations approach which has been deprecated and is only retained for backwards compatibility.

Data and stimulations in general

The commonly used techniques to transmit information from/to the OpenViBE Designer in real time are the following,

External Processing box

The External Processing box is a new technique contributed by Mensia Technologies and introduced in OpenViBE 2.1. The documentation is here. The box works as a server that can send and receive streams and stimulations between OpenViBE Designer and an external application. The data is sent/received exactly as it is handled inside OpenViBE. For example, if the box is used to transmit streams to a client, the client will receive a set of EBML streams, similarly as an OpenViBE box would.

It is possible that the external processing box approach may replace the Python and Matlab scripting boxes in the future.

You can find simple examples using external processing box in the ‘box-tutorials/’ folder and example C++ source code under ‘sdk/applications/examples/external-processing/’.

VRPN

The classic OpenViBE way to send stimulations and data to external applications is the VRPN protocol. See the tutorial here. It is not very convenient for sending multichannel data, but for stimulations it is appropriate. VRPN can also receive stimulations and small-scale numeric data into OpenViBE.

TCP/IP (low-level)

Data and stimulations can be sent using the TCP/IP protocol, if no ‘exotic’ dependencies are wanted. The TCP/IP approach is efficient for large amounts of data. The corresponding box is called the TCP Writer. In Acquisition Server, the Generic Telnet Reader driver can receive signal data over TCP/IP. The telnet driver can be configured to accept the TCP Writer box stream format.

LabStreamingLayer (LSL)

LabStreamingLayer is another protocol for exchanging data and stimulations between streaming applications. It can be used with a corresponding box, see here for a description. OpenViBE Acquisition Server also has LSL plugins both to receive and send numeric data and stimulations.

OpenSoundControl (OSC)

OpenSoundControl is usually used to control synthetizers, but can also be used as a general output channel from OpenViBE Designer to anything that can receive data from an OSC controller. For details, see the box documentation. At the moment OSC can not be used to send data into OpenViBE, only out from it.

Python and Matlab

Using either the Python box or the Matlab box, it is possible to stream data and stimulations to/from an application using some further communication mechanism that has been implemented in these languages. There can be some overhead from the run-time interpretation of the scripts, and in general from having this kind of ‘middle layer’.

Lua

The Lua Stimulator box allows sending and receiving stimulations from Lua scripts. The box does not currently support any other type of data.

Other techniques / Do-It-Yourself

With C++, you can of course implement whatever communication channel you desire by developing the corresponding box or driver. You can use the source codes of the boxes mentioned above as starting points.

It is sometimes asked if the serial port or parallel port can be used to send data or stimulations to. This is not currently supported, as there is no standard what to write to the serial port. If a serial port communication is needed, the user is recommended to write their own box sending stimulations to the serial port in a desired manner. In C++, the Stimulation Listener box code can be used as a starting point, and you can try to combine it with a serial port library such as inpout32 (on Windows).

Summary

The following table summarizes the current capabilities,

Protocol Acquisition Server in Acquisition Server out Designer in Designer out
External processing No No Yes Yes
VRPN(1) No No Yes Yes
TCP/IP (low-level) Yes(2) Yes(3) Yes(3) Yes(4)
LSL Yes Yes No Yes
OSC No No No Yes
Python No No Yes Yes
Matlab No No Yes Yes
Lua No No Yes (stimuli only) Yes (stimuli only)
Do it yourself Yes Yes Yes Yes

1) Not suited for large scale data
2) Data in with ‘Generic Telnet Reader’ driver, stimuli in with ‘TCP Tagging’.
3) You need to encode/decode the OpenViBE EBML Acquisition Stream (see here).
4) TCP Writer box: data and stimuli may not be easy to synchronize with this approach

 

This entry was posted in Documentation, Developer documentation, Connecting OpenViBE and other applications. Bookmark the permalink.