- NB: last update for OpenViBE 0.14.0 (may. 2012).
Introduction
OpenViBE Acquisition Server is a tool designed to communicate with hardware signal acquisition devices and forward acquired signals and other experiment information to OpenViBE applications in a way compliant with the OpenViBE format specification.
The acquisition server doesn’t communicate directly with acquisition devices. Instead, it provides the user with a set of drivers to choose from, each one being dedicated to a given device model. New devices can be supported by 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 tool to show what parameters must be configured before it can be used to acquire and forward data. The server GUI should look like the following :
Acquisition Device Drivers
A list of available drivers is accessible under ‘driver‘. Depending on your distribution of OpenViBE, a number of drivers may already be at hand. At least one driver should be available : the Generic Oscillator. Contrary to most drivers, this one 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 configuration file :
# 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 previous execution.
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 or ‘epoch’ of a buffer depends on the sampling frequency, which may be set in the Driver Properties dialog (see Driver Properties)
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. The ‘Driver Properties’ button opens up the settings dialog of the currently selected driver. It displays settings that can’t be retrieved from the hardware and that have to be filled in 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).
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. Most users will 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.
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, or driver dependant.
- 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.
Other settings
- Oversampling Factor : multiply the sampling frequency of the acquired signal, using linear interpolation.
- Impedance Check : some drivers make use of the Acquisition Server impedance checker, this functionnality can be turned on.
- 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 ‘playing’, 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 through the openvibe pipeline you designed.
In the acquisition server window, you should see the number of clients connected to your server (e.g. ’2 hosts 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 contact the driver author.
