- 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.
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/’.
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.
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 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 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’.
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).
The following table summarizes the current capabilities,
|Protocol||Acquisition Server in||Acquisition Server out||Designer in||Designer out|
|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