Back to Top

Event synchronization between OpenSesame and Emotiv EEG Testbench

OpenSesame (experiment builder) and Testbench (EEG recording) software are operating on different computers
Figure 1
OpenSesame (experiment builder) and Testbench (EEG recording) software are operating on different computers
OTHER PHOTOS
Emotiv Testbench (Xavier SDK) Serial Port configuration
Figure 2
Emotiv Testbench (Xavier SDK) Serial Port configuration
OpenSesame (experiment builder) and Testbench (EEG recording) software are operating on the same computer
Figure 3
OpenSesame (experiment builder) and Testbench (EEG recording) software are operating on the same computer

Event triggering synchronization tutorial between OpenSesame1 and Emotiv EEG Testbench2, facilitating the use of Emotiv EPOC3 wireless Brain Computer Interface device in cognitive research experiments

1Opensesame is a state-of-the-art graphical, open-source experiment builder for the social sciences.
2Emotiv EEG Testbench is a raw EEG research data recording software included with the Research SDK of Emotiv EPOC.
3Emotiv EPOC is a revolutionary 14-channel wireless Brain Computer Interface and Scientific Contextual EEG device for research enabling entertainment, market research, usability testing and neurotherapy.

Hardware Requirements

  • One (1) workstation operating on OS X or Linux (Workstation #1)
  • One (1) workstation operating on OS X or Linux (Workstation #2)
  • One (1) Fast/Gigabit ethernet network switch & a pair of ethernet UTP/STP patchcords
  • One (1) Emotiv EPOC unit
  • One (1) USB Serial adapter supporting OS X, only if OS X version of Emotiv Research SDK (Testbench) will be used in Workstation #1*

* This is critical If you are using a modern version of OS X (>10.8), as due to OS restrictions a serial port -as expected by Testbench (/dev/cu*)- cannot be created otherwise. Thus, even if in the final setup this USB Serial adapter will not be used effectively, connecting it to workstation #1 will allow us to enable the required by Testbench serial port. For the purpose of this tutorial a PL2303 adapter was used and its appropriate driver was installed.

Software Requirements

  • One (1) Emotiv Research SDK (EEG) license (includes Emotiv Testbench software) selected for the OS of Workstation #1
  • Latest version of OpenSesame, selected for the OS of Workstation #2
  • socat installed in both Workstation #1 and #2.
    • For OS X, first install Homebrew. Then: brew install socat
    • For Linux, install using its packager (apt/yum); e.g. for debian/ubuntu use: apt-get install socat

socat?

  • socat is a relay for bidirectional data transfer between two independent data channels. Each of these data channels may be a file, pipe, device (serial line etc. or a pseudo terminal), a socket (UNIX, IP4, IP6 - raw, UDP, TCP),.., or a combination of two of these. These modes include generation of "listening" sockets, named pipes, and pseudo terminals.
  • We will use socat to setup a UDP stream between the two workstations, linking a virtual serial port in each workstation with this stream.
  • We wil also link each virtual serial port with another (physical or virtual) serial port in each workstation.
  • The latter ones (serial ports) will be used by the corresponding software in each workstation (i.e. Testbench in Workstation #1 and OpenSesame in Workstation #2).

So, the concept is...

  • Conventionally, both Emotiv Testbench and OpenSesame are supposed to be linked with a physical serial port to receive / send markers accordingly.
  • Here, instead of connecting physical serial ports between the two workstations with a physical cable, we will be using virtual serial ports and a virtual 'cable' (i.e. UDP stream between the two network hosts) instead.

Let's proceed with an example

  • Two (2) MacBooks (OS X) will be used here. OpenSesame is installed In Workstation #1 and Testbench is installed in Workstation #2.
  • Configure TCP/IP settings using IP#1=192.168.0.1/24 in Workstation #1 and IP#2=192.168.0.2/24 in Workstation #2
  • Workstation #1
  • In Workstation #1, connect the USB Serial adapter in a USB port (after having installed its driver). Then, open Terminal application (found in Utilities) and use the following command in one line. This would setup a virtual serial port in UDP listening mode, using port 12345.
  • sudo socat -d -d pty,echo=0,ispeed=115200,ospeed=115200,clocal=1,ixoff=1,link=/dev/cu.usbserial udp-l:12345

  • Using another Terminal in Workstation #1, enter the following as well (to provide read/write access to the serial port by all apps)
  • sudo chmod a+rw /dev/cu.usbserial

  • Alternatively, you may download a bash script (UDP_receive-v2.sh) including the above from here.
  • Now open Emotiv Testbench, go to serial port configuration screen, select '/dev/cu.usbserial' and configure appropriately (115200,8,N,1,N - see the second Figure of this tutorial).

  • Workstation #2
  • In Workstation #2, open Terminal application and use the following command in one line (to link its serial port /dev/ptyS13 through a UDP stream with UDP port 12345 of host 192.168.0.1):
  • sudo socat -d -d pty,echo=0,ispeed=115200,ospeed=115200,clocal=1,ixoff=1,link=/dev/ptyS13 udp:192.168.0.1:12345

  • Again, using another Terminal in Workstation #2, enter the following as well (to provide read/write access to the serial port by all apps)
  • sudo chmod a+rw /dev/ptyS13

  • Alternatively, you may download a bash script (UDP_send-v2.sh) including the above from here.
  • Finally, you may now switch to OpenSesame and use the following example code in an 'inline script' to send a marker of '3' to the remote host (and finally to the marker channel of Testbench).
  • import serial
    exp.serial_port = serial.Serial('/dev/ptyS13',baudrate=115200,bytesize=serial.EIGHTBITS, stopbits=1)
    exp.serial_port.write(chr(3))

  • You setup is now ready! You may proceed to test your environment, as far as your ethernet cables can reach (100m)

Other things to take into consideration

  • Using Linux in either side is almost transparent for this tutorial. Actually, you do not even need a USB Serial adapter. Your serial port names will slightly change (rename /dev/cu.usbserial and /dev/ptyS13 to /dev/tty..).
  • Using Windows is supposed to be transparent as well, providing that the use of socat will prove transparent (i.e. as any other porting of Unix/Linux packages to Windows). Although this is beyond the scope of this tutorial, this would be a good starting point.
  • The use of wireless ethernet interfaces to build the proposed network topology is strongly discouraged. This would induce an unpredictable jitter (it could even make your results useless).
  • If your research involves ERPs/EPs, the above setup is not recommended; the whole distributed setup (2 workstations + network device) will probably add an additional delay of 1-2 ms (i.e. induce a potential jitter of [7~15] samples for Emotiv EPOC or a jitter of [4-8] samples for Emotiv EPOC+).
  • If your research involves ERPs/EPs, please adapt your setup into a collapsed scheme (see Fig.3) using one workstation/OS for both software. Then, its loopback (localhost/127.0.0.1) network interface can be used to connect the two virtual ports(sockets). The scripts provided above can be easily adopted, accordingly. Again, a bash script (UDP_localhost.sh) is available for your convenience (for OS X).
  • If Windows are to be used, a more simple alternative to create and link two (2) virtual ports may be followed. This setup has also been tested and proved reliable.

(c) 2015, Thessaloniki, Greece - Dr. Dimitrios A. Adamos

Would you like to cite this work?

If you have found this tutorial useful, it would be great if you cited our article:
Dimitrios A. Adamos , Stavros I. Dimitriadis , Nikolaos A. Laskaris , Towards the bio-personalization of music recommendation systems: a single-sensor EEG biomarker of subjective music preference, Information Sciences (2016), doi: 10.1016/j.ins.2016.01.005