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
andOVTK_StimulationId_NoArtifact
for NaN replacement andOVTK_StimulationId_AddedSamplesBegin
,OVTK_StimulationId_AddedSamplesEnd
, andOVTK_StimulationId_RemovedSamples
for drift correction operations. The previously used stimulationsOVTK_GDF_Incorrect
andOVTK_GDF_Correct
are no longer sent by the server. - Configuration token
Path_Samples
is no longer available. UsePath_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
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.