Differences between 1.x and 2.x series of OpenViBE

OpenViBE 2.0 aims to be largely compatible with OpenViBE 1.3.0. Most previous features remain available and compatible. Non-merged third-party OpenViBE scenarios and drivers should work with little or no modifications, requiring not much more work than a normal major OpenViBE update. However, backwards compatibility has not been maintained in situations where it was estimated not to be worth the development cost and the resources available.

When migrating from OpenViBE 1.3, it is useful to be aware of the known incompatibilities introduced in OpenViBE 2.0. These are as follows,

1. Configuration files

OpenViBE 2.0 will write its configuration files to %USERPROFILE%/AppData/Roaming/openvibe-2.0 folder on Windows and ~/.config/openvibe-2.0 on Linux in order to allow coexistence with a previous OpenViBE installation. However, these configuration files are not compatible with those from 1.3. It is recommended the user just lets the openvibe tools (Acquisition Server, Designer) to automatically recreate these files for 2.0 and then modify them if/when necessary.

2. Scenario and box related changes

Several boxes in OpenViBE 2.0 have either changed or been subsumed by other boxes. If some box is no longer present when you load an old custom scenario, there may be a suitable replacement box available. The following list may be helpful,

Changes in boxes,

  • Voxel Display has been replaced with 3D Tomography
  • 3D Topographic Map has been replaced with 3D Topography
  • Power Spectrum box is replaced by Instant Bars
  • Time-frequency map box is replaced by Stacked Bitmap (Horizontal)
  • Temporal Filter box has been replaced with a new version. The previous INSERM box is still available.
  • xDAWN box has been replaced with a new version. The previous INRIA box is still available.
  • CSV Reader/Writer boxes have been replaced with new versions. The previous boxes are still available (the old boxes have the tag ‘deprecated’ in the box list). However, these old boxes may vanish from future openvibe versions.
  • Classifier Trainer box no longer randomly permutes the training examples in cross-validation by default. This may change the accuracy estimates it prints even if the ultimate classifier is the same (details).

3. General changes

These changes may affect your use-cases,

  • Drift Correction in Acquisition Server is now disabled by default. This means for example that if your device/driver has startup latency, this may show up as a constant heavy drift. It is no longer in the OpenViBE design philosophy to mask this behavior with ‘drift correction’. Having the drift correction disabled may or may not suit you. If uncertain, experiment with the different options. Disabled drift correction assumes that stimulation markers are merged to the EEG data via TCP Tagging. Most BCI examples shipped with OpenViBE do this now. Disabling the drift correction also assumes that there are no serious problems in the ability of the device to deliver a steady stream of data. This should be the case for all high-class wired devices, whereas bluetooth devices may have hickups.
  • Starting with 2.0.1, Acquisition Server sends different stimulations if it tampers with the signal: It sends OVTK_StimulationId_Artifact and OVTK_StimulationId_NoArtifact for NaN replacement and OVTK_StimulationId_AddedSamplesBegin, OVTK_StimulationId_AddedSamplesEnd, and OVTK_StimulationId_RemovedSamples for drift correction operations. The previously used stimulations OVTK_GDF_Incorrect and OVTK_GDF_Correct are no longer sent by the server.
  • Configuration token Path_Samples is no longer available. Use Path_Data instead.
  • Configuration token BuildType has been removed.
  • Box mute has been replaced with box enable/disable toggles. In your custom scenarios, you may need to manually disable previously muted boxes.
  • The new kernel is much more strict about boxes conforming to OV standards, hence you may see more warnings than before. These usually indicate some components should be fixed to conform to the kernels’ expectations.

The warnings of the following kind occur when loading scenarios saved with a previous version of the software. They can be safely ignored (unless your scenarios have relied on the box messaging feature which is no longer present):

[ WARNING ] Failed to validate xml: error [no declaration found for element 'MessageLinks'], 
line number [528]
[ WARNING ] Importing scenario with legacy format: legacy scenarii might be deprecated in the 
future so upgrade to v1 format when possible

4. Dropped features

  • Box messaging functionality has been removed
  • Nonfunctional CoAdapt P300 source code is no longer included (you can get it from OV 0.18.0 if needed)
  • Simple 3D Viewer box has been removed

5. For developers

Note that 2.x series is hosted in new git repositories on Inria’s gitlab server. Please see the instructions.

If you have developed your own C++ boxes which have not been merged to the OpenViBE distribution, you may need to modify the boxes on the code level to accommodate non-backward compatible changes made to the OpenViBE kernel. To see how the boxes have to be modified, look into some box in the OpenViBE source tree that has similar characteristics. The required changes are as follows,

  • Boxes that process input now must provide a valid processInput() implementation
  • Boxes with visualizations need small code-level changes related to Visualization Context interface
  • Boxes using Spectrum Stream need code-level changes due to changes in the stream specification
  • Boxes with unstable flag will require trivial code-level changes (adding a header + replacing a value)
  • The function getSettingValue() no longer expands tokens in the parameters. Either expand the tokens manually or use the FSettingValueAutoCast() function instead.
This entry was posted in Documentation, Version migration instructions. Bookmark the permalink.