Difference between revisions of "Interacting with NIC"
(→Sending TTL pulses) |
(→Sending TTL pulses) |
||
| Line 65: | Line 65: | ||
* Pin 1 (Vcc 5V) from the adapter should be connected to any data pin from 2-9 of the parallel port. This pin should be always kept at 5V. | * Pin 1 (Vcc 5V) from the adapter should be connected to any data pin from 2-9 of the parallel port. This pin should be always kept at 5V. | ||
* Pin 2 (TTL input) from the adapter should be connected to another data pin from 2-9 of the parallel port. This pin should only be activated whenever a TTL pulse is sent. | * Pin 2 (TTL input) from the adapter should be connected to another data pin from 2-9 of the parallel port. This pin should only be activated whenever a TTL pulse is sent. | ||
| − | * Pin | + | * Pin 3 (ground) from the adapter should be connected to any pin from 18-25 of the parallel port. |
== Receiving data streams from NIC == | == Receiving data streams from NIC == | ||
Revision as of 15:50, 25 February 2015
In this page we describe how you can interact with NIC (Neuroelectrics Instrument Controller, the software for control with NE devices) using other software.
Contents
About Synchronization: general principles
To coordinate different data sources or events to a single clock is known as synchronization.
When using Enobio at least there are two different clocks that need to be synchronized: The clock of the Enobio wireless sensor which is in charge of sampling the EEG data recorded by the electrodes, and the clock of the host where NIC runs and receives the EEG data from the Bluetooth connection.
NIC uses the clock from the Enobio sensor as master. The Enobio clock is received by NIC through the data streaming. The EEG data is sampled at 500 Hz, so every sample is delayed 2 ms from the previous one. In traditional wired system the data will be received by the control software as it is sampled so the two clocks might be directly synchronized. However in wireless system such as the Enobio one, some latency might be introduced in the wireless channel due to RF interference and re-transmission of data.
NIC implements an algorithm that compensates this latency and finds out the offset between the clock from Enobio and the one from the host where NIC runs. When NIC receives information from third-party applications that need to be synchronized with the EEG data, like markers that signal when external events occur, it compensates the timestamp of the received data so it is aligned with the EEG data streaming.
In the scenario described above, when NIC collects markers that are sent by other applications, another clock to be synchronized is introduced in the system. This is the clock from the host that sends the markers. NIC provides two ways of gathering such markers. Both of them are described in the following sections. The first one does not provide any synchronization mechanism, this is the reception of markers using a TCP/IP server where the clients connect to and send their markers. This method might be useful when the time synchronization requirements do not need accuracy under the 100 ms.
The second method uses the Lab Streaming Layer (LSL), which incorporates built-in network and synchronization capabilities that allow synchronization accuracy on 1 ms so it perfectly fits application like the one that detect ERPs signals.
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 ...
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 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>
Sending TTL pulses
NIC can also receive a TTL signal and display it through one of its EEG channels.
This option requires to have a parallel port in the computer running the stimulus software. If you don't have a parallel port, you can also install a PCI Express card emulating a parallel port. Please see the user manual of our TTL adapter for detailed information on how to set up the connections.
The following pins of the TTL adapter should be connected to the following pins from the parallel port:
- Pin 1 (Vcc 5V) from the adapter should be connected to any data pin from 2-9 of the parallel port. This pin should be always kept at 5V.
- Pin 2 (TTL input) from the adapter should be connected to another data pin from 2-9 of the parallel port. This pin should only be activated whenever a TTL pulse is sent.
- Pin 3 (ground) from the adapter should be connected to any pin from 18-25 of the parallel port.
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 and markers using TCP/IP
It is also possible to receive the markers that NIC collects using the TCP/IP connection. By enabling this feature from the NIC settings the markers are sent along with the EEG streaming through the same TCP/IP connection. In this case the markers are sent as a four-bytes integer after the last EEG channel. The most significant byte is sent first. The data streaming will have the following format then:
----------------------------------------------------------------------------------------------------------------------------------- | Channel 1 | ... | Channel N | Marker | ----------------------------------------------------------------------------------------------------------------------------------- | (MSB) Byte#1 | Byte#2 | Byte#3 | (LSB) Byte#4 | ... | Byte#1 | Byte#2 | Byte#3 | Byte#4 | Byte#1 | Byte#2 | Byte#3 | Byte#4 | -----------------------------------------------------------------------------------------------------------------------------------
Those markers correspond to the ones received by NIC from third-party software using TCP/IP or LSL, the manual markers that can be inserted while recording by pressing the keys from 1 to 9 and the stimulation events in the case of the StarStim device such as start and stop stimulation and when any parameter is changed from MatNIC.
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: NIC 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: NIC 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
Using LSL is possible to access markers generated from another NIC. The outlet the LSL clients need to connect to has the following settings:
Name: NIC Type: Markers Channel count: 1 Nominal sample rate: n/a Channel format: Int_32 Unique source ID: The Enobio type plus its mac address plus the "Marker" string
The names of the Outlets, are for the version 1.3.12. For previous versions, the name of the outlet is "Enobio"
Sending commands to NIC
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 | |--------------------------------------------------| | Start EEG streaming | Enobio & StarStim | | Stop EEG streaming | Enobio & StarStim | | Start Stimulation | StarStim | | Abort Stimulation | StarStim | | Online tACS Frequency Change | StarStim | | Online tACS Amplitude change | StarStim | | Online tDCS Amplitude change | StarStim | | Load template | StarStim | | Request status | Enobio & StarStim | \--------------------------------------------------/
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 | |--------------------------------------------------------| | Remote control allowed | Enobio & StarStim | | Remote control rejected | Enobio & StarStim | | Device is idle | Enobio & StarStim | | EEG streaming is ON | Enobio & StarStim | | EEG streaming is OFF | Enobio & StarStim | | Template not loaded | StarStim | | Template loaded | StarStim | | Stimulation is ready to be started | StarStim | | Stimulation is ON | StarStim | | Stimulation is OFF | StarStim | \--------------------------------------------------------/
MatNIC is a Matlab toolkit that wraps all these commands and status code in a set of Matlab functions that allow remotely controlling NIC. See the MatNIC section for more info.
