Acquisition Server

  • NB: last update for OpenViBE 1.1.0 (05.oct.2015).

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 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 specific 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 look like the following :

 

acquisition_server_gui.png

Acquisition Server GUI.

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 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. 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.

 

driver_settings.png

Generic Oscillator settings.

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.

 

Acquisition Server Preferences.

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.
  • 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 ‘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 see if there is a contact person available for the driver, as listed in the driver table.

This entry was posted in Acquisition Server documentation. Bookmark the permalink.