Interacting with NIC

In this page we describe how you can interact with NIC (Neuroelectrics Instrument Controller, the software for control with NE devices) using other software.

Sending Markers to NIC from other software or hardware

Sending Markers using TCP/IP

NIC provides a server that other software can connect to in order to send markers. Those received markers are synchronized with the EEG streaming for further analysis.

This NIC server is running in the TCP/IP port 1234. Up to five clients can simultaneously send markers to NIC by making a TCP/IP connection to this port.

Once a client is connected it needs to send the following string in order to send a marker:

<TRIGGER>XXXX</TRIGGER>

Where XXXX can represent any integer number different from zero (from -2147483647 to +2147483647). This marker will be co-registered in the output files generated by NIC to the corresponding EEG sample. For instance, in the output tabulated text file, the column just after the timestamp one is filled with zeros if no markers are received. When a marker is received its corresponding number is set to that column. See the following example:

...
26748	-27675	35631	42398	532666	64345	12376	40988	0	1382432459788
26865	-26683	35685	42450	532711	64821	12376	41046	0	1382432459790
26810	-26821	35531	41997	532821	64945	13164	41099	0	1382432459792
26749	-26995	35325	42008	532712	64377	13478	41286	0	1382432459794
26796	-27245	35932	42391	532923	64245	13620	41117	300	1382432459796  <-- Reception of the marker #300
26622	-27510	35501	42630	532876	64193	13031	40986	0	1382432459798
26751	-27912	35611	42003	532345	64344	12967	40731	0	1382432459800
...

Plot of markers received by NIC and an audio signal recorded by Enobio

Please take as an example this Matlab code which connects to NIC to send markers every time a tone is played back through the sound card. If you connected the output of the computer sound card to one of the Enobio electrodes you would be able to see the alignment between the markers and the played tones.

Sending markers using LSL

NIC is compliant with the Lab Streaming Layer (LSL) protocol so makers can be co-registered with the EEG signal by setting up a LSL marker outlet (see this example).

The LSL handles both the networking and time-synchronization isues between the sender and receiver hosts obtaining reliability on order of 1 ms (see the time-synchronization validation tests).

NIC settings for configuring the reception of markers through LSL

NIC needs little configuration in order to receive the markers from a LSL outlet present in the local network. When the LSL marker outlet sends integer-type markers only the name of the outlet needs to be configured in NIC.

Please go to "EEG Setup -> Settings -> Markers from Lab Streaming Layer" and set the name that your LSL marker outlet has. NIC will automatically look for a marker outlet with this name and will connect to it. If the outlet sends integer-type integers then no further configuration is needed. All the received makers will be co-registered along with the EEG signal to the output files.

In case the outlet sends string-type markers then there are some considerations that have to be taken into account. The LSL outlet sending string-type markers has to format them as XML tags. The following example is taken from the string markers that the Presentation software sends when the LSL extension manager is installed (see the Working with ERPs section). You can see that NIC will decode the string looking for the tag that is configured in the "EEG Setup -> Settings -> Markers from Lab Streaming Layer" settings, ecode in this case. The marker number 37 will be registered at the reception of this string:

<pevent><etype>Picture</etype><ecode>37</ecode><unc>209.638092041016</unc>test</pevent>

Receiving data streams from NIC

Receiving data streams using TCP/IP

The NIC software has a TCP/IP server that streams the EEG data received from Enobio. Up to 5 clients can connect to that server simultaneously in order to receive the EEG data ans perform the desired operations in real time.

The software clients that want to receive the EEG data in real time from NIC need to connect to the TCP/IP port 1234 of the host where the NIC software is running. Once the client software is connected to the server, it will receive the EEG data streaming according to the following format:

-------------------------------------------------------------------------------------------
|                    Channel 1                  | ... |             Channel N             | 
-------------------------------------------------------------------------------------------
| (MSB) Byte#1 | Byte#2 | Byte#3 | (LSB) Byte#4 | ... | Byte#1 | Byte#2 | Byte#3 | Byte#4 |
-------------------------------------------------------------------------------------------

Each EEG sample is sent as a two-complement 4 byte value. The unit of the EEG sample is nano volts and its range is from -400000000 to +400000000 nV. The most significant byte is sent first. The following code in 'C' shows how to decode the streaming from the received bytes to EEG sample values. The example assumes that the computer architecture is little-endian.

// byte3 = 0xFF, byte2 = 0x8F, byte1 = 0x99, byte0 = 0x61
signed int32_t sample = 0;
sample += byte3;
sample = sample << 8;
sample += byte2;
sample = sample << 8;
sample += byte1;
sample = sample << 8;
sample += byte0;
// sample = -141584031 nV

The client will receive first the four bytes from channel 1, then the next four bytes from channel 2 and so on till receiving the four bytes from the last channel of Enobio (8 or 20 depending of the type of Enobio/Starstim NIC handles). Then channel 1 bytes are receiving again.

The following links are a Java and a Matlab example clients that connects to NIC and receive the EEG streaming: Java client, Matlab client

Receiving data streams using LSL

NIC streams the received EEG data from Enobio usign the Lab Streaming Layer. NIC creates a LSL outlet with the following settings:

Name: Enobio
Type: EEG
Channel count: 8 or 20 depending of the Enobio NIC handles
Nominal sample rate: 500
Channel format: float_32
Unique source ID: The Enobio type plus its mac address

An LSL client software needs to connect to this outlet in order to receive the EEG streaming data. The received values are expressed in nanovolts and its range is from -400000000 to +400000000.

Using LSL is possible to access to the accelerometer data too. The outlet the LSL clients need to connect to has the following settings:

Name: Enobio
Type: Accelerometer
Channel count: 3
Nominal sample rate: 100
Channel format: float_32
Unique source ID: The Enobio type plus its mac address plus the "Acc" string

Controlling NIC with Matlab: the MatNIC toolkit

NIC can be remotely commanded from a third-party software through a set of commands that can be sent using a TCP/IP connection. NIC listens to the TCP/IP port 1235 for incoming connections. The clients that connect to that port can command the following actions:

/---------------------------------------------------------------------\
| Action              | Device            | Command code              |
|---------------------------------------------------------------------|
| Start EEG streaming | Enobio & StarStim | 0xF0                      |
| Stop EEG streaming  | Enobio & StarStim | 0xF1                      |
| Start Stimulation   | StarStim          | 0xFB                      |
| Abort Stimulation   | StarStim          | 0xFA                      |
| Load template       | StarStim          | String terminated with    |
                                            either '\0', '\n' or '\r' |
\---------------------------------------------------------------------/

NIC responds to those commands with a set of status commands to indicate whether the commands are successfully processed, the stimulation is ready to be started and so on. The following table shows all the possible status value that NIC might send.

/---------------------------------------------------------------------\
| Status              | Device            | Status code               |
|---------------------------------------------------------------------|
| EEG streaming is ON  | Enobio & StarStim | 0xF2                     |
| EEG streaming is OFF | Enobio & StarStim | 0xF3                     | 
| Template not loaded  | StarStim          | 0xF9                     |
| Stimulation is ready | StarStim          | 0xFC                     |
| to be started        |                   |                          |
| Stimulation is ON    | StarStim          | 0xFD                     |
| Stimulation is OFF   | StarStim          | 0xFE                     |
\---------------------------------------------------------------------/

MatNIC wraps all these commands and status code in a set of Matlab functions that allow remotely controlling NIC. The following zip file contains:

- The MatNIC manual (also available in our Downloads Area), an explanation on how to use the Matlab functions to remotely control NIC and
- RemoteStimulatioClient, a folder with all the Matlab functions for remotely controlling NIC, and an example on how to use them.

To run the example please make the following call:

>> ret = RemoteStimulationClient (templateName, '127.0.0.1', 1235)

where templaName is set with a name of an already defined stimulation template NIC, then the host where NIC is running (in the example above we use the localhost IP, so NIC is running in the same computer) and finally the port 1235 which is where the NIC server runs. Here is the header of the example client code:

function [ret] = RemoteStimulationClient (templateName, host, port)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% RemoteStimulationClient
%
% This function implements a client to connect to the NIC Remote
% Stimulation Server. The server is running on the machine where the NIC
% application runs on the port 1235.
%
% The NIC Remote Server waits for the client to send the name of the 
% template that the client wants to use. If the NIC user accepts the
% remote control session, the template is loaded and the client is
% informed when the system is ready to start the stimulation.
%
% The client then might send the code to start the stimulation or the one
% to abort it. The abort command might be sent in any moment of the
% stimulation session. If the stimulation session is aborted locally from
% the NIC GUI the connection is automatically closed so the client needs
% to connect, send the template and wait again for the permission. When
% the stimulation script execution is finished the system prepares itself
% to start again a new stimulation so the code informing about that is
% received.
%
% The client might also send commands to start and stop receiving the EEG
% streaming. The data is received through a separate server on the port
% 1234. The 8/20 channel samples are sent in 4 bytes in two's complement.
% The MSB byte is sent first.
%
% The following are the functions to connect, send the commands to the
% server and read the status the server sends:
% - NICRemoteStimulationServerConnect
% - NICRemoteStimulationServerReadStatus
% - NICRemoteStimulationServerLoadTemplate
% - NICRemoteStimulationServerStartStimulation
% - NICRemoteStimulationServerAbortStimulation
% - NICRemoteStimulationServerStartEEG
% - NICRemoteStimulationServerStopEEG
%
% The following are the status that the server might send to the client
% and can be read with the NICRemoteStimulationServerReadStatus function:
%
% STATUS               |  TYPE         |       CODE
% -------------------------------------------------------
% EEG streaming is ON  |  Byte         |       0xF2
% -------------------------------------------------------
% EEG streaming is OFF |  Byte         |       0xF3
% -------------------------------------------------------
% Template not loaded  |  Byte         |       0xF8
% -------------------------------------------------------
% Template loaded      |  Byte         |       0xF9
% -------------------------------------------------------
% Stimulation is ready |  Byte         |       0xFC
%  to be started        |               |
% -------------------------------------------------------
% Stimulation is ON    |  Byte         |       0xFD
% -------------------------------------------------------
% Stimulation is OFF   |  Byte         |       0xFE
% -------------------------------------------------------
%
% Input:
% templateName: Name of the template to be loaded on NIC.
% host: Name or IP of the host where NIC is running.
% port: Port number where the NIC server runs.
%
% Output:
% ret: Zero or positive number if the function completes successfully. A
% negative number otherwise:
% -1: The connection to the host and port number did not succeed.
% -2: Error writing template name.
% -3: Error reading from server.
% -4: Template not loaded.
% -5: Error writing command to the server.
%
% Author: Javier Acedo (javier.acedo@starlab.es)
% Company: Neuroelectrics
% Created: 16 Jan 2013
% Known issues: None
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%