- NB: cursory update for OpenViBE 2.0.0 (28.Dec.2017).
Introduction
OpenViBE Acquisition Server is a tool designed to communicate with various hardware signal acquisition devices (list here). The task of the server is to forward the acquired signals and other experiment information to OpenViBE applications in a standardized and generic OpenViBE format.
The acquisition server communicates with the acquisition devices using modules called drivers. The server provides the user with a set of drivers to choose from, each dedicated to one or more devices. Support for new devices can added to the server by developing new drivers. See Tutorial: creating a new driver for the acquisition server for details on this.
Configuration
Let’s have a look at the graphical interface of the acquisition server to see what parameters must be configured before the server can be used to acquire and forward data. The server will remember these settings across the launches, but in order to do so, it must be closed properly.
The server GUI should resemble the following :
Acquisition Device Drivers
A list of available drivers is accessible under ‘driver‘. Depending on your distribution of OpenViBE, a number of drivers are usually available. At least one driver should be available : the Generic Oscillator. Contrary to most drivers, the oscillator doesn’t connect to any hardware device, but generates sinusoidal signals. It is appropriate for testing purposes. To change the default driver presented when launching the Acquisition Server, add the following token to your openvibe.conf configuration file (.rc on Linux):
# set the default driver : AcquisitionServer_DefaultDriver = Generic Raw Telnet Reader
If you don’t specify any driver that way, the driver presented upon startup is the latest used during the previous run.
Connection Settings
In order to use a driver, connection details should be set so that the server communicates with connected OpenViBE applications as desired. The port to which to send data can be changed under ‘Connection Port‘ (e.g. 1024 is a standard default setting). An OpenViBE application will then have to fetch data from this port once an experiment is started. Also, the size of the buffers sent to connected applications may be configured under ‘Sample count per sent block‘. This defines how many samples should be sent per acquired channel in a single buffer. Valid values are powers-of-two and 32 is the default. The duration of a buffer depends on the sampling frequency, which may be set in the Driver Properties dialog (see Driver Properties). The receiving applications can later convert the data to new buffer sizes (the buffers are usually called epochs if they have been segmented from the signal stream using specific rules).
Driver Properties
Once a driver is selected from the drop-down list and before it can be used, its settings should be configured appropriately. Settings provide information about the experiment being conducted and the subject undergoing the experiment. Additionally, these settings include configurable device parameters. The ‘Driver Properties’ button opens up the settings dialog of the currently selected driver. It displays settings that are available for the hardware and that can be changed by the user. They may vary between drivers. For example, the Generic Oscillator settings include information about the subject (identifier, age, gender) and the experiment (number of channels to be acquired, sampling frequency, channel names). Some hardware may also provide different operating modes, such as the impedance checking mode. If available, this can be selected in the driver properties.
Changing the channel names can be done easily, by specifying a label for each channel index. The possible labels must be chosen in a list that includes all the extended 10-20 system labels.The list can then be saved in a file for later use. The format of the file produced is very simple : a text file with one name per line.
Acquisition Server Preferences
Various global settings can be accessed through the ‘Preferences‘ button. The contents of these settings may depend a little on the plugins that have been loaded. Most users can leave these parameters as default.
Drift Correction
The Acquisition Server monitors the behaviour of the driver in order to ensure that it actually sends the number of samples it should, based on the theoretical sampling frequency of the device. Note that this simply means that the AS ‘trusts’ the computer clock to be ‘more accurate’ than the amplifier clock, which may or may not be the case.
When a drift is detected, you will see a progress bar moving on the left or right (not enough or too many samples). When the drift reaches a threshold, an automatic correction is done : the Acquisition Server removes or duplicates some samples, and sends stimulation(s) to any acquisition client connected, so you know in the signal that a correction just occured.
If samples have been added, the portion of signal is delimited by the stimulations OVTK_GDF_Correct and OVTK_GDF_Incorrect. If samples have been removed, OVTK_GDF_Incorrect tags the corresponding moment.
Here are the parameters you can set for the Drift Correction:
- Drift correction : either Forced, Disabled (default ov 2.0), or let driver decide (default ov 1.3).
- Drift Tolerance (ms) : when reaching a drift duration of that value, a correction is triggered.
- Jitter Estimation Count for Drift : the window in number of “blocks” used to compute the drift.
For more information on drift correction, see this tutorial.
Other settings
- Oversampling Factor : multiply the sampling frequency of the acquired signal, using linear interpolation.
- Select only named channels : If this is enabled, only channels with names assigned will be forwarded by the server.
- NaN value replacement : if the device sends non-numerical values such as NaN (not-a-number) or INF (infinite), the server detects it. You can choose either to replace them by 0 or the previous correct value, or letting the server send them to the clients. Use this last option at your own risk, as most of the Designer boxes will not handle such a value. Anyway, the faulty sample range will be delimited by OVTK_GDF_Incorrect and OVTK_GDF_Correct stimulations.
Usage
Once a device driver has been selected and relevant settings configured, data acquisition can start. The server should first connect to the acquisition device, which is done by clicking the ‘Connect‘ button. A label will inform the user whether the connection was successful.
If the connection was established and the device(s) successfully connected, data sampling can be started/stopped by clicking ‘Play‘/’Stop‘.
Once a driver is ‘connected’ and ‘receiving’, the clients (e.g. acquisition client boxes in a Designer scenario) may be started : press ‘play’ in the designer. Data should be received, decoded and sent to all the connected clients.
In the acquisition server window, you should see the number of clients connected to your server (e.g. ‘2 clients connected’)
Troubleshooting
If you don’t receive any signal from the acquisition client (e.g. you don’t manage to display any signal), look in the Designer console. If you find the following message :
[WARNING] At time 1.02 sec <Box algorithm::Acquisition client>
Could not receive memory buffer size
[WARNING] Box algorithm <Acquisition client> has been deactivated because
process phase returned bad status
The acquisition server is connected, but stopped. Press ‘Play’ in the acquisition server then play your scenario again.
If you receive the following error message in the Acquisition Server console :
[ INF ] Starting the acquisition...
[ INF ] Now acquiring...
[WARNING] After 5000 milliseconds, did not receive anything
from the driver - Timed out
[ INF ] Stoping the acquisition.
[ INF ] Disconnecting.
This means that the OpenViBe driver managed to connect to the device and start the acquisition, but the device somehow failed to send the samples to OpenViBE, thus stopping the acquisition. Please be sure that your EEG device is compatible with the openvibe driver, correctly plugged in, turned on and configured before starting the acquisition. If the problem persists, please see if there is a contact person available for the driver, as listed in the driver table.
