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