How to Stream Data to OpenViBE

Step 1.

Install CyKIT

Step 2.

• Run CyKIT.py from its project folder.

cd CyKIT-Master

• Include the folder to Python.exe

C:\CyKit-master\Py3>c:\Python372x32\Python.exe .\CyKIT.py 127.0.0.1 5151 6 openvibe+generic+nocounter+noheader+nobattery+ovdelay:100+float+ovsamples:004

Use +float if you plan to stream 32 bits float
Use +integer if you plan to stream 16 bit unsigned integer

(Tip: Streaming 32 bits float seemed to offer slightly better performance.)

Use the correct Keymodel (6 is used for EPOC+ in 16-bit mode, 7 would be used for EPOC+ 14-bit EPOC mode)
Premium models are likely prototypes, that are not often used. If you are in doubt, always try the consumer model.

          1 - Epoc    (Premium  Model)

          2 - Epoc    (Consumer Model)

          3 - Insight (Premium  Model)

          4 - Insight (Consumer Model)

          5 - Epoc+   (Premium  Model)

          6 - Epoc+   (Consumer Model) [16-bit EPOC+ mode]

          7 - EPOC+   (Consumer Model) [14-bit EPOC  mode]

Understanding Config Flags for OpenViBE.

+openvibe This option indicates an OpenViBE data stream will be sent in a format readable by the Generic Raw Telnet Reader format. (More information in Step 5.)

+generic This option indicates a generic TCP stream has been created.
Mainly used to differentiate between a generic TCP stream, that anything can connect to and between a TCP stream that may be used by an HTTP web socket. (Requiring a handshake.)

+nocounter This option is used to remove the first two bytes of data that is typically sent in the data stream. Where the two bytes are [COUNTER] [INTERPOLATE]

[COUNTER] being the EEG packet number 0 - 127 (or 0 - 255 for 256hz mode)
[INTERPOLATE] being the number 16 for EEG data, and 32 to indicate data is gyro data.

By default, this option enables +eegmode which will send only EEG data, (ignoring Gyro data which could potentially corrupt the stream of data.) It sets this to EEG data by default, because otherwise there would be no way to indicate if the data stream is for EEG data, or Gyro data.

+noheader by default, CyKIT will send header information to both "Generic" TCP servers, and a websocket server. This header information includes various useful information about what config settings were set to run the CyKIT server. This header information is passed along, so that other programs can make use of the various settings available to CyKIT.

The header information is not however useful to programs like OpenViBE, so we include this config flag to disable sending this extra info.

+nobattery by default, the battery and quality settings are mixed into the data.
CyKIT sorts this data and sends it via two bytes, which is appended to the EEG data packet.

The battery and quality information are not in any format recognizable by OpenViBE, so this data should be removed to satisfy the OpenViBE format.

+ovdelay:NNN is a custom delay counter, designed to work in milliseconds, but results may vary by CPU speed. Where NNN is a number between 001 and 999. This delay will occur before each packet is sent to OpenViBE.

+float determines the format the microvoltage data will be sent in. (32-bit big-endian float) "Big Endian"

+integer determines the format the microvoltage data will be sent in. (16-bit unsigned integer) "Big Endian"

+ovsamples:NNN defines how many samples will be collected in a block of data, before sending to the openViBE server. (This will relate to Step 5. determining Sample counter per sent block)

Default for ovsamples is 004.

CyKIT can set the sample block to any number between 001 and 999. However OpenViBE only allows specific block sizes.

OpenViBE allows for the following sample block sizes: 004, 016, 032, 064, 128, 256, 512
Where the larger the packet block is, the longer it will take to be processed by OpenViBE functions.

(See below, for altering OpenViBE to accept 001 packet samples, for faster stream processing.)

Step 3.

3. Download and Install the latest supported releases.
   Last tested with:

Python   version 3.7.2  (Dec.2018)
OpenViBE version 2.2.0  (Dec.2018)

Step 4.

4. Start Programs.

• Start OpenViBE (Acquisition Server)
  "C:\Program Files (x86)\openvibe-2.2.0\openvibe-designer.cmd"
  

• Start OpenViBE (Designer)
  "C:\Program Files (x86)\openvibe-2.2.0\openvibe-designer.cmd"
  
  

(Must be started from their own folder, or by using shortcuts started from the OpenViBE program folder.)

Step 5.

5. In the OpenViBE (Acquisition Server) program, select the Generic Raw Telnet Reader as the driver.
   
   

The Connection Port (1024) is a local port, that the OpenViBE Designer application will connect to.
The Sample count per sent block will be 4 by default. This is how many samples must be sent from CyKIT
at one time, before being processed by the OpenViBE functions.

(Optional: See below for more information on altering the sample count to 1)

Step 6.

6. Open Driver Properties for the Generic Raw Telnet Reader Driver.
   
   Set the Device Configuration as follows:

○ Number of channels: 14
○ Sampling frequency: 128 (Use 256 if using EPOC+ in 256hz mode)
○ Telnet host name: localhost
○ Telnet host port: 5151 (a local port used to stream the CyKIT.py server)
○ Endianess: Big Endian
○ Sample type: 32 bits float (if CyKIT.py is using +float parameter)
○ Sample type: 16 bits unsigned integer (if CyKIT.py is using +integer parameter)
○ Skip at start (bytes): 0
○ Skip header (bytes): 0
○ Skip footer (bytes): 0

• Click Apply button.

• Click Connect button on the OpenVIBE Acquisition Server (CyKIT.py server should already be running.)

Step 7.

7. Verify the Acquisition Log says Connection succeeded !

Step 8.

In OpenViBE Designer We will create a scenario by dragging and dropping functions into the window.

• Drag and drop Acquisition Client from [-] Acquisiton and network IO into the window space on the left.

• Drag and drop Signal Display and Matrix Display from [-] Visualization [-] Basic into the window space.

• Hover over the pink arrow, indicating Signal Stream [signal] on Acquisition Client and drag a line from
  that arrow, to the single green arrow on Matrix Display

• Hover over the pink arrow, indicating Signal Stream [signal] on Acquisition Clientand drag a line from<br> that arrow, to the pink arrow that saysData [Signal]onSignal Display`

• Double click Acquisition Client replace ${AcquisitionServer_HostName} with the text: localhost

• Acquisition server port should be 1024, unless you changed it in the Acquisition Server

• Click Apply on Configure Acquisition client settings

Step 9.

• Turn on EEG device.

• Return to OpenViBE Acquisition Server and click Play (Verify you are already Connected.)

• Return to OpenViBE Designer and click Play button (in the top menu).

If your device is properly paired and streaming data, two OpenViBE windows will open and start
displaying data from your EEG device.

If data is being streamed properly, data should look similar to this.

Matrix Display For EPOC+ headset, you would see the microvoltage leveling off somewhere around 4200 uv in the Matrix Display Results will of course vary, but for EPOC+ it is typical for the EEG device to start somewhere around 2000 uv before it levels off at 4200 uv

Signal Display This window renders the microvoltage data to a graph. OpenViBE does a lot of "scaling" behind the scenes. This is why when it first begins rendering the data, you will see thick black data plots. This is normal, it is what the data rendering would look like if you were zoomed in close. After a number of seconds of data collection, you should notice the data plots start to look more like EEG data plots that you'd expect to see. If you tap the headset, the static electricity from your fingertip should send a spike in the data. which may be visible as both a negative and positive plot. Indicating it detected both a negative and positive static charge relative to the headsets averaged baseline it has been collecting from the reference sensors.

If you tap the headset sensors, it is normal for all of the sensors to seem to be affected.
This typically occurs when the reference sensor has not been grounded like it normally would be to the scalp of the user.

Exiting OpenViBE and CyKIT Programs

The correct procedure is as follows:

• Click Stop on the Acquisition Server
• Click Disconnect on Acquisition Server
• Close Acquisition Server Click (X)
• Save any Scenarios you want saved, and Close OpenViBE Designer Click (X)
• Press CTRL + BREAK (PRT SCR) for a clean break from CyKIT, or Click (X)

Note: Closing these programs in any other order, will likely end with  
program hangups, or a variety of error messages.  It is not crucial to close 
these programs in this order, but will just not be clean exits, and you may have 
to re-insert some settings that would ordinarily have been saved by a clean exit.

Including Counter as a Channel (Optional Step)

In the Driver Properties of the Acquisition Server, you can set

○ Number of channels: 14

instead to:

○ Number of channels: 16

Then remove the +nocounter from the CyKIT server config parameters.

This will incorporate the [Counter] data into your OpenViBE signal,
This is useful if you want to verify all of your packets are being sent.
It will however throw some of OpenViBE's signal detection off balance
(Matrix data entries red), that is to be expected.

Override OpenViBE Sample Block (Optional Step)

The lowest number of samples that can be sent at one time to OpenViBE is 4 samples.
That means that there must be 4 packets of EEG data stored up, before it can be sent and then
processed by OpenViBE. This can be overridden by making a modification to the OpenViBE interface.

• Close any OpenViBE applications.

• Open a word document a word document program (ie Notepad.exe) in Administrator mode.
  

• Open C:\Program Files (x86)\openvibe-2.2.0\share\openvibe\applications\acquisition-server\interface.ui

 Navigate to Line 53  and edit the '4' digit, to '1'
  Example:
    <col id="0" translatable="yes">1</col>

• Restart the OpenViBE Acquisition Server