- NB: Document last updated for OpenViBE 1.1.0 (02.Oct.2015).
A possible problem when making new scenarios is that the result doesn’t work quite as expected, or that some boxes produce warnings or errors. This tutorial describes a few simple debugging practices that can be used to find the source of the problem.
Isolating the problem
Typically a scenario can be sprawling. In order to think of a meaningful solution, it is important to pinpoint where exactly the problem comes in from. One possibility is that some box prints an error or a warning. You can find out which box made the print by clicking at the box identifier on the Designer log line. The printing box itself might be the problem, or the reason might be a box upstream from the warning-producing box. This needs to be investigated further.
On the other hand, sometimes the problem can be that the processing pipeline mutilates the signal in an unwanted fashion. To verify that this is not the case, it is necessary to inspect the data. In particular, to find out what introduces an undesired change to a signal or a stream, it can be useful to look how the signal changes at the different stages of the pipeline. It can also be useful to look at the signal before the box that produces an error. Is the signal what is expected at each point?
Looking at the data (the streams)
The most basic thing to do is to route a copy of the data to Signal Display boxes at different stages of the signal processing pipeline. By renaming the different display boxes, you know which Signal Display corresponds to which stage. Using these, you can observe at which stage the signal changes in an unintended way.
A good practice when debugging scenarios is to use an artificial signal, so you know exactly what it contains. The easiest way to get such a signal is to use the Noise Generator, Sinus Oscillator and/or Time Signal boxes. The last can be routed through Simple DSP box with a formula
sin(2*M_PI*x*freq) to get a sine wave at a desired frequency (freq, in integer in Hz). Despite its name, the sinus oscillator does not generate a pure sine wave, but is instead a harmonizer.
When Signal Display does not give a clear intuition of the situation or does not support the stream type in question, the EBML Stream Spy box can be used for a more detailed investigation of any OpenViBE stream. The box describes the characteristics of the stream and can even print out contents. The box can print you information such as dimensions of the involved buffers. For example, a normal signal matrix buffer should have a size [channelCount x chunkSize] with a frequency greater than 0. Remember to set the LogLevel of the EBML Spy box so that you can see its output.
Stimulations are most easily investigated with the Stimulation Listener box.
Finally, you can try to route the signal to a CSV Writer box to write the stream to a file in order to investigate it with a text editor or some other software.
Are box parameters causing the problem?
If a specific box turns out to be the problem, it may be meaningful to investigate if the reason is its parameters. Carefully check that all the parameters of the box are meaningful with respect to the inputs and outputs of the box. Boxes can load some file or a configuration override as part of their operation. You can see if this is the case from the box configuration, does it mention any files? If so, check that these files contain what is expected. Typically these files are in xml or ASCII format and can be loaded to text editor.
Debugging box code
If you are developing a new box yourself, you may want to output some intermediate results inside the box code itself. For matrices, you can use the convenience function
OpenViBEToolkit::Tools::Matrix::saveToTextFile() to do this. Some pieces of code, such as
ovpCAlgorithmClassifierLDA.cpp (for Eigen matrices) and
ovpCAlgorithmConfusionMatrix.cpp (for CMatrix) contain example code to dump matrices to the log manager. This is only meaningful for small matrices, though.
On Windows, OpenViBE is best debugged using the Visual Studio IDE. Simply add breakpoints to the locations of interest after having compiled (and installed) the Debug target build. Investigating the state of the local variables can often point you to the source of the problem.
On Linux, boxes can be debugged by launching Designer with the switch “–debug”, enabling running Designer under gdb. Then you can set breakpoints to the code locations you’re interested in, or that contains the error print, before running.
After isolating the problem
If the problem comes from an existing OpenViBE box, these are often contained in some tutorial scenarios or examples, and they should work at least in that context. You could examine, using the above tools, how your situation is different from the example situation, and possibly make your case resemble the example more to sidestep the issue.
On the other hand, if there is clearly a problem in OpenViBE or its components, we would appreciate if you could report it following these instructions.
As a final piece of wisdom, often troubleshooting takes some time and patience, and requires careful thinking of what is happening, what the components do, and what they should do. Good luck!