Drivers: OpenBCI

OpenViBE logo
OpenBCI logo

(documentation written for OpenViBE 1.2.2)

Document contributed by Yann Renard in collaboration with Puzzlebox

n.b. This html doc has been more or less automatically generated from a Markdown source (.md in ov source tree).

Welcome

Welcome in the documentation of the OpenBCI driver for OpenViBE. This document gives you step by step details on how to configure your system, hardware and software to get the best possible experience. For further details about OpenBCI and OpenViBE, please refer to their respective documentation.

Getting Started

This section gives guidelines on how to set-up your environment configuration to get the best experience using OpenBCI with OpenViBE

Linux

In order to use the OpenBCI driver on Linux, you need to be granted read/write access to the serial port that is used to communicate with the dongle. Unfortunately, this does not come as a standard configuration on many Linux distributions and you will need to configure your setup so that the user is granted these access. On Ubuntu and its derivative, as well as on Debian, this can simply be achieved by adding the user to the dialog group with the following command :

sudo adduser username dialout

Please note that you may need to close and reopen the session for changes to take effect.

On Fedora and its derivative, a similar command should be used to add the user in the dialout group :

sudo usermode -a -G dialout username

Again, please note that you may need to close and reopen the session for changes to take effect.

Windows

It is necessary to walk through a litlle bit of configuration to have the best experience with OpenBCI and OpenViBE on Windows. Indeed, when Windows first installs a serial port, its default configuration is not optimal for realtime streaming of the data. It especially configures large buffering and latencies, causing delays in the communication which eventually lead in delays in the acquired signals. While this only delays the detection of Motor Imagery or SSVEP tasks by a few hundreds of milliseconds, this also delays the ERP (eventually leading to a misdetection) and in all cases, alters the neurophysiological validity of the acquired data by a significant fraction. Consequently, it is recommended to configure the serial ports so that they are suitable for realtime use.

Note that this configuration is necessary each time Windows creates a new serial port. This may unfortunately happen every time you move the dongle on a new USB port on the computer !

In order to open the configuration dialog of the serial port, please follow these steps:

  • Right click on the Computer icon and chose Manage
  • After the Computer Management tool is opened, browse the tree in the left pane to the Device Manager section
  • After the Device Manager tree is opened, browse in the right pane to the Ports (COM & LPT) section
  • Then double click your port (in my case, USB Serial Port (COM3)

The Windows Device Manager

The Windows Device Manager


  • In the USB Serial Port Properties dialog, go to the Port Settings tab and click Advanced

The Port Settings dialog

The Port Settings dialog

  • This opens the Advanced Settings for your COM port

The Advanced Port Settings dialog

The Advanced Port Settings dialog

From this window, there are three settings we need to change :

  • The Receive and Transmit settings of the USB Transfer Sizes section should both be changed from 4096 to 64 as this will reduce the time taken by the OS to deliver the data to either the dongle or the OpenViBE driver
  • The Latency Timer of the BM Options section should be reduced down to 1 as this will dramatically reduce the latency induced by the OS.

After you changed the settings as shown on the following figure, please click OK.


The tweaked configuration of COM ports to have best experience with OpenViBE and OpenBCI

The tweaked configuration of COM ports to have best experienece with OpenViBE and OpenBCI

It is not necessary to restart the computer for the changes to take effect.

Configuration

The configuration dialog of the OpenBCI driver comes with a number of settings that one can change or pick depending on his preference.


The OpenBCI configuration dialog

The OpenBCI configuration dialog

The following table documents each option that is specific to the OpenBCI device. Please refer to the OpenViBE documentation for anything generic to the OpenViBE Acquisition Server.

Option Default value Documentation
Device empty This allows you to pick a serial port to connect on. The drodown list shows the serial ports that can currently be opened on this computer. If no port is found, the mention No valid serial port is shown in this list. If you cannot find your device in this list, please refer .
Use Daisy Module false This allows you to configure the daisy module. Four cases should be considered. 1/ if the daisy module is present and this option is set to true, then the device will turn to 16 channels samples 125 Hz. 2/ if no daisy module is present and this option is set to false, then the device will turn to 8 channels, 250 Hz. 3/ if the daisy module is not present on the board and this option is set to true, then the initialization of the driver will fail. 4/ if the daisy module is present on the board and this option is set to false, the daisy module will be disabled and the acquisition will be done as if the daisy module was not present on the board, turning the device back to 8 channels sampled at 125 Hz.
Custom Command On Initialization empty This option contains additional commands to send to the device at initialization. You must use one line per command, some command may contain multiple characters. For details about the commands, please refer to the OpenBCI protocol documentation. Be advised that this will increase the delay of initialization by an order of magnitude that is a direct relation of the number and types of commands you want to add. Finally, not all the commands take the same time to be executed, if you include custom commands, you should consider adjusting the timeout values.
Board Reply Reading Timeout 5000 This allows to define the maximum time until reading a reply from the board after sending a command times out. Many commands end with a $$$ pattern, which can handily be captured and release the waiting loop when reading the board reply, but not all the commands have this $$$ pattern. Consequently, it is necessary to have a timeout for the other commands. The default value has been chosen to behave well even with custom commands that need a long time to reply such as ?. If you don’t use such command in your Custom Command On Initialization, you may reduce that delay. But be aware that if you reduce it too much, the driver may miss the $$$ pattern even though the board has sent it, resulting in unexpected behavior.
Board Reply Flushing Timeout 500 This option allows to flush and get rid of the streaming buffer. This is especially used when the driver asks the board to stop streaming and makes the streaming state absolutely clean when the driver needs to send a new command after stopping the streaming. You may reduce this value to make (re)connection faster, but if the buffer came not to be completely flushed, the remaining would be taken as the begining of the next command and this may result in unexpected behavior.

The Configuration Summary gives information on the current configuration, especially the number of channels and the sampling rate of the device.

Advanced Configuration

In addition to the above settings, another few settings are available to the user as advanced configuration. They are not exposed in the GUI and should be directly set in the [OpenViBEConfig][OpenViBE configuration] file instead. Refere to the Configuration Manager section of the OpenViBE documentation for further details on the configuration file format, location and others.

Token Default Value Documentation
AcquisitionDriver OpenBCI MissingSampleDelayBeforeReset 1000 This defines the size of the window to continuously monitor reception of samples from the driver. If no sample is received within that timeframe, the board is requested to stop and restart streaming. While the non-reception of samples from the board may reflect an unexpected state in the board, this strategy seems to sometimes recover and let the streaming go back to normal. The default value allows a good compromise between dealing with buffering and actual transmission delays and recovering fast when something goes wrong. If you experience such unstability in the transmision, we recommend that you first explore anything that may (in)directly affect the quality of the transmission before tweaking this setting.
AcquisitionDriver OpenBCI DroppedSampleCountBeforeReset 5 This defines the number of sample loss events until a recovery is attempted. It happens that the board gets in an unstable state where some sample would be missing in the stream. Stopping and restarting the streaming has proved to recover well. The default setting has been set so that a few occasional sample loss may occur (due to e.g. quality transmission) and be corrected by the drift correction process, while not waiting too long to attempt recovery when too many sample are lost.
AcquisitionDriver OpenBCI DroppedSampleSafetyDelayBeforeReset 1000 This defines a sefety delay where no reset should be attempted because of sample loss (see AcquisitionDriver OpenBCI DroppedSampleCountBeforeReset). This prevents a reset on the first sample where the driver synchronises with the streaming protocol and may miss a few samples until it is perfectly synced with the header and tail of the protocol frame.
This entry was posted in Acquisition Server documentation and tagged , . Bookmark the permalink.