Contributions:AmpServerProADC

Synopsis

The AmpServerProADC component implements the client side of EGI's TCP/IP-based Amp Server Pro (ASP) protocol. Thus, it may be used to interface BCI2000 with an EGI amplifier. Amplifiers that record data and administer transcranial direct current stimulation (GTEN devices) are supported.

Location

http://www.bci2000.org/svn/trunk/src/contrib/SignalSource/AmpServerPro

Versioning

Author

Alex Belsten (belsten@neurotechcenter.org), NCAN. (V2)

Version History

V1.00 - 06/11/2008 - First working version
V2.00 - 05/10/2020 - Added support for GTEN devices and packet format 2

Source Code Revisions

Initial development: 1998
Tested under: 9297
Known to compile under: 9297
Stimulation broken since: 7273 - Race condition in AmpServerProADC allows stimulation to start before train upload completes, causing “train not uploaded” errors and SignalSource crashes.

Video Overview

Using the AmpServerPro Source Module

For using the AmpServerPro source module, you will need to obtain a license for the AmpServerPro SDK. Without such a license, you may be able to connect to the machine running the EGI software, but it will not send any real-time data when asked to. In order to obtain an AmpServerPro SDK license, you will need to contact EGI at http://www.egi.com.

Setting Up the Hardware

The EGI system comes with many hardware and cables, so connecting everything in a step-by-step manner is helpful for getting everything connected correctly. There are a few steps to this process. First, make sure you have all of the necessary cables and hardware. These items can be seen in the two images below (Fig. 1 and Fig. 2).

Figure 1: The necessary cables.
Figure 2: EGI hardware.

In addition to the hardware shown in Fig. 1 and 2, you will need the EGI iMac that comes with the amplifier and a research PC. This PC must be running Windows and needs an ethernet port or an adapter that connects to an ethernet cable. Once sure that all of the necessary hardware/cables are present, it is time to connect all the hardware. For your reference, the general architecture is shown in the figure below.

Figure 3: General hardware architecture.

Setting up the Power Supplies

The transformer is the first piece of hardware to set up. It provides isolated power to the EGI amplifier, switch box, and EGI iMac. Each of these devices connects to the plugs on the back of the transformer, as shown in Fig. 4.

Figure 4: Three different types of plugs on the back of the transformer.

Verify that the transformer is off and use plug type 3 in Fig. 4 to plug into a standard wall socket. Now, connect the EGI iMac to plug type 2. Next, you will need two cables of type 1 (IEC plug cable). Connect one to the amplifier power supply and the other to the switch box. Keep the transformer off for now. Lastly, you will need to use the amplifier power cable to connect the amplifier power supply to the amplifier.

Setting up the Network Cables

Next, the network cables need to be connected. Fig. 5 and 6 serve as a reference through this process.

Figure 5: Connections to back of amplifier.
Figure 6: Network connections to switch box.

Start by connecting the orange fiber optic cable to the back of the amplifier and then connect the other end to the front of the switch box. Then, connect one of the network cables to the EGI iMac and connect the other end to any one of the eight ports on the switch box. Lastly, connect the other network cable to your research PC and then to the switch box. Now that everything is connected, the transformer and amplifier power supply can be turned on. Next, boot up the EGI iMac. Navigate to the browser and enter the amplifier's IPv4 address into the address bar. You can find the IPv4 address of your amplifier by launching Net Station Acquisition on the EGI iMac and expanding the sharing tab. All of the EGI amplifiers have an IPv4 address of the form 10.10.10.X where X is some integer between 0 and 256. You should now see the amplifier's web page, similar to the one shown in Fig. 7. If you cannot see this web page, verify that all network connections are secure and the amplifier is powered on.

Figure 7: Amplifier webpage that is accessible from amplifier's IPv4 address.

Configuring and Setting Up BCI2000 on the Research PC

Now it is time to set up the research PC. First, install BCI2000 (a guide to do this can be found at Programming_Howto:Building_and_Customizing_BCI2000) and make sure the BUILD_CONTRIB option is enabled in CMake before compiling.

The research PC's IP address must be configured to allow the amplifier and Net Station to recognize it. On the research PC, configure the IP (IPv4) for a manual IP address (10.10.10.Y where Y is any digits other than the last two digits used by the amp); with the manual IPv4 address configured, set the subnet mask to 255.255.255.0. Once this has been completed, open a browser on the research PC and enter the amplifier's IPv4 address into the address bar. If the research PC's IP address is set correctly, the page will populate with information about the amplifier shown in Fig. 7. If the web page fails to load, then the PC's IPv4 address may not have been set correctly, or the research PC has a firewall that is blocking the amplifier. Verify that the research IPv4 address is correct and firewalls have been disabled.

Starting Amp Server Pro

Amp Server Pro is capable of working with many amplifiers concurrently. To begin using Amp Server Pro with BCI2000, ensure that at least one amplifier is connected to the server. If no amplifier is connected, the Amp Server software emulates an amplifier. If you choose to use the emulated amplifier, you should expect to see a smooth sine wave signal for all channels. To start the amp server simply navigate to the Amp Server Pro directory and double click the file named "Amp Server".

Creating a BCI2000 Batch File

Although it is not necessary, it is convenient to create a batch file to run BCI2000 with the Amp Server Pro module. To create the batch file, start out with a copy of a suitable batch file in BCI2000/batch/, and open it in a text editor.

Towards the end of the file, you will see a sequence of lines beginning with

start executable

These lines are responsible for starting up source, signal processing, and application module, in that sequence. To use the AmpServerPro module, you will need to replace the executable name in the first entry, e.g.

start executable SignalGenerator --local

becomes

start executable AmpServerPro --local

For more information, see this page.

Using Amp Server Pro with BCI2000

Once you have started the Amp Server and compiled the Amp Server Pro module, you can begin collecting data with BCI2000 by following the steps below.

Double click BCI2000/batch/CursorTask_AmpServerPro.bat - the batch file that was created in the previous section - to start BCI2000.
Click the "Configure" button.
Set the appropriate parameters. The Amp Server Pro module is initialized with a number of parameters that can be configured from the "Source" tab. A summary and description of these parameters can be found below.
Click "Set Config".
Click "Start" to begin your experiment.

Parameters

SourceCh

Enter the number of channels that have electrodes connected (32, 64, 128, or 256). Make sure that SourceChOffset and SourceChGain are set to "auto" or you may get an error message about a mismatching number of entries.

BlockSize

This parameter should always be set to auto. If the amp uses packet format 1, then the block size is fixed at 40 samples per block. If the amp uses packet format 2 then the block size specified by SampleBlockSize will be used. The packet format will be displayed in the operator window of BCI2000 after clicking 'Set Config' and successful connection to amp.

ServerIP

The IP address of the amplifier (e.g. 10.10.10.51)

CommandPort

The port number of the port used for command layer communication. Unless you have explicitly set the port number via Amp Server's configuration, the default of 9877 should be correct.

NotificationPort

The port number of the port used for notification layer communication. Unless you have explicitly set the port number via Amp Server's configuration, the default of 9878 should be correct.

StreamPort

The port number of the port used for data streaming. Unless you have explicitly set the port number via Amp Server's configuration, the default of 9879 should be correct.

AmplifierID

Amp Server Pro is capable of managing many amplifiers concurrently. BCI2000, however, operates with a single amplifier. If only a single amplifier is connected, you may enter the value "auto" here and allow BCI2000 to automatically determine the Amplifier ID. If multiple amplifiers are connected, however, you must enter a valid ID from 0 to N-1, where N is the number of amplifiers connected.

Packet Format 2 Parameter

SampleBlockSize

If the connected amp uses packet format 2, then the user can configure the number of samples per block using this parameter.

GTEN Parameters

The GTEN parameters are only used when using a GTEN device. If the connected amp cannot perform stimulation, disable RunTranscranialStim.

RunTranscranialStim

Enables stimulation. If stimulation is enabled, the following parameters are used.

ModulationPlanFile

The modulation plan file contains all of the information about the stimulation train. This file is created on the Net Station iMac with the EGI program Reciprocity. Reciprocity allows the user to configure all of the parameters of the stimulation train such as electrode location, waveform amplitude, duration, etc. See EGI's GTEN manual for information related to Reciprocity use.

Once the train is designed in Reciprocity, save the .mcb plan file and note its location. Copy the .mcb file and transfer it to the research PC. Launch BCI2000 and click the browse button for the ModulationPlanFile parameter. On windows, the .mcb file will now be a folder. Navigate to this folder and inside, there will be multiple files and two other folders. Select the file called 'plan.mcf' as the ModulationPlanFile. Select ONLY the 'plan.mcf' file as the BCI2000 parameter value, but also DO NOT change any of the other contents of the .mcb folder.

StimulationExpression

Expression that triggers stimulation. For more info on expressions, see User Reference:Expression Syntax.

AbortExpression

Expression that aborts stimulation. If this is never triggered, the stimulation will continue until the duration_ms, specified in the uploaded Modulation Plan, runs to its full duration.

States

GTENStimulationTriggered

This binary state is set to 1 when stimulation is triggered.

GTENTrainRunning

This state is one byte in size and contains information sent back from the amplifier about stimulation. If bit 2 is low (XXXX X0XX) then current is being injected by the amp. If bit 4 is low (XXX0 XXXX) then a new block in the neuromodulation train has just begun.

EGIDigitalInputStream

This state is 16 bits and records the digital inputs on the back of the amplifier as seen in Fig. 5.

DigitalInput1-4

These 4 binary states are 1 when there is a digital input, or 0 in the absence of one. This information is parsed from the EGIDigitalInputStream, but separated for user convenience.

Certification Results

The AmpServerPro certification was performed to give a better understanding of the restraints that must be placed on the system when using this device. Certification success criteria was determined internally and without rigor, and reflects our experience with psychophysical experiments and the performance we expect to need for the system. More information about certification testing can be found on the certification wiki page.

PC Specifications

Lenovo Thinkpad E580 (https://www.lenovo.com/us/en/laptops/thinkpad/thinkpad-e-series/ThinkPad-E580/p/22TP2TEE580)
Processor: Intel(R) Core(TM) i5-7200U CPU @ 2.50GHz 2.7GHz
Installed Ram: 8.00 GB
Graphics Card: Intel(R) HD Graphics 620
System Type: 64-bit operating system, x64-based processor
BCI2000 compiled with MSVC2019 and Qt 5.15.2

Certification Tests Performed

Certification testing varied block size (50, 100 ms), and task (P3Spell (7x7 grid), P3Spell (1x1 grid), CursorTask, CursorTaskLow, and StimulusPresentation), and tested audio and video latency, for a total of 12 performed tasks. The audio latency and video latency are partitioned into separate windows, as we tested them in different runs.

Success Criteria and Overall Results

Name	Actual Latency	Success Criteria	Result
Timestamp Latency Mean	509µs	1 ms	passed
Timestamp Latency STD	2.02ms	1 ms	failed
Processing Latency Mean	44.7ms	20 ms	failed
Processing Latency STD	20.3ms	10 ms	failed
Video Latency Mean	73.1ms	65 ms	failed
Video Latency STD	17.7ms	20 ms	passed
Audio Latency Mean	62.9ms	65 ms	passed
Audio Latency STD	3.33ms	20 ms	passed

Stimulation Latency

The Stimulation Latency for the EGI system seems to be dependent on the stimulation width and ISI width. When the stimulation width plus the ISI width is less than 8 seconds, it has a large latency and can also miss stimulation (see Figure 8).

Figure 8: The jitter of the stimulation latency, showing a large mean and variation of latency for ISI's less than 6 seconds.
Figure 9: The latency of the EGI system. Run for 100 trials, with a 2s stimulation width and an 8s ISI width. The block size was 40 ms with a sampling rate of 1 kHz.

The stimulation latency seems to be inconsistent, however for large enough ISI widths, it is usually around 1.1 seconds. For the trial shown in Figure 9, the average latency was 1,159 ± 5 ms.