Difference between revisions of "Contributions:AmpServerProADC"

From BCI2000 Wiki
Jump to: navigation, search
m
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
==Synopsis==
 
==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 managed by an ASP server.
+
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 a administer transcranial direct current stimulation (GTEN devices) are supported.
  
 
==Location==
 
==Location==
Line 7: Line 7:
 
==Versioning==
 
==Versioning==
 
===Author===
 
===Author===
Joshua Fialkoff, (c) 2008 Wadsworth Center, New York State Department of Health.
+
Joshua Fialkoff, (c) 2008 Wadsworth Center, New York State Department of Health. (V1)
 +
 
 +
Alex Belsten (belsten@neurotechcenter.org), NCAN. (V2)
  
 
===Version History===
 
===Version History===
 
* V1.00 - 06/11/2008 - First working version
 
* 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===
 
===Source Code Revisions===
 
*Initial development: 1998
 
*Initial development: 1998
*Tested under: 1998
+
*Tested under: 6138
*Known to compile under: 1998
+
*Known to compile under: 6138
 
*Broken since: --
 
*Broken since: --
  
 
==Using the AmpServerPro Source Module==
 
==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.
+
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.
 +
 
 +
[[File:GTEN_web_address.PNG|400px|thumb|right|EGI Amplifier webpage]]
 +
There are two computers necessary to use AmpServerPro module with BCI2000. One is the iMac Net Station and the other is the client PC on which BCI2000 is installed and run. The Net Station, client PC and the amplifier are all connected to a network switch box. The two computers are connected to the CAT 5 inputs and the amplifier is connected through the fiber optic cable inputs. The client PC's  IP address must be configured to allow the amplifier and Net Station to recognize it. On the client PC, configure the IP (IPv4) for a manual IP address (10.10.10.xx where ‘xx’ 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 client PC and enter the amplifiers IPv4 address into the address bar. If the client PC's IP address is set correctly then the page will populate with information about the amplifier as shown in the figure to the right. If a webpage similar to the one on the right is not shown, then the IP address of the client may not have been set correctly or the client PC has a firewall that is blocking the amp. Verify that the client IP is correct and firewalls have been disabled.  
  
 
===Starting Amp Server Pro===
 
===Starting Amp Server Pro===
Line 24: Line 30:
  
 
===Creating a BCI2000 Batch File===
 
===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, open up a text editor and then copy the text below into a blank text 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 <tt>BCI2000/batch/</tt>, and open it in a text editor.
cd ..\prog
+
 
start operat.exe
+
Towards the end of the file, you will see a sequence of lines beginning with
start AmpServerPro.exe 127.0.0.1
+
  start executable
start ARSignalProcessing.exe 127.0.0.1
+
 
start CursorTask.exe 127.0.0
+
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.
Then, save the file to <tt>BCI2000/batch/CursorTask_AmpServerPro.bat</tt>.  You may want to modify lines 4 and 5 to suit the needs of your experimentPlease browse the files in <tt>BCI2000/batch/</tt> for other example batch files.
+
  start executable SignalGenerator --local
 +
becomes
 +
start executable AmpServerPro --local
 +
 
 +
For more information, see [[Contributions:How_to_use_a_Contributed_Source_Module#Creating_batch_files|this page]].
  
 
===Using Amp Server Pro with BCI2000===
 
===Using Amp Server Pro with BCI2000===
Line 36: Line 46:
 
# Double click <tt>BCI2000/batch/CursorTask_AmpServerPro.bat</tt> - the batch file that was created in the previous section - to start BCI2000.
 
# Double click <tt>BCI2000/batch/CursorTask_AmpServerPro.bat</tt> - the batch file that was created in the previous section - to start BCI2000.
 
# Click the "Configure" button.
 
# Click the "Configure" button.
# Set the appropriate parameters.  The Amp Server Pro module is initialized with a number of parameters which can be configured from the "Source" tab.  A summary and description of these parameters can be found below.
+
# 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" and attend to any errors reported by the BCI2000 operator.  If there were any errors, repeat this step.
 
# Click "Set Config" and attend to any errors reported by the BCI2000 operator.  If there were any errors, repeat this step.
 
# Click "Start" to begin your experiment.
 
# Click "Start" to begin your experiment.
  
 
==Parameters==
 
==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 type 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===
 
===ServerIP===
The IP address of the computer running the Amp Server software (e.g., 192.168.0.3).
+
The IP address of the amplifier (e.g. 10.10.10.51)
  
 
===CommandPort===
 
===CommandPort===
Line 56: Line 73:
 
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.
 
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 and note its location. Copy the .mcb to the client PC. Launch BCI2000 and click the browse button for the ''ModulationPlanFile'' parameter. Navigate to the .mcb folder that was written by Reciprocity. Inside this folder, there will be multiple files and two folders. Select the file called 'plan.mcf' upload to BCI2000. DO NOT change any of the contents of the .mcb folder and be sure that ONLY 'plan.mcf' is uploaded.
 +
 +
===StimulationExpression===
 +
Expression that triggers stimulation. For more info on expressions, see [[User Reference:Expression Syntax]].
 
==States==
 
==States==
The Amp Server Pro source module introduces no additional states.
+
===GTENStim===
 +
This binary state is set to 1 when stimulation is triggered.
 +
===GTENtr===
 +
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.  
  
 
==See also==
 
==See also==

Latest revision as of 14:26, 4 August 2020

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 a administer transcranial direct current stimulation (GTEN devices) are supported.

Location

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

Versioning

Author

Joshua Fialkoff, (c) 2008 Wadsworth Center, New York State Department of Health. (V1)

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: 6138
  • Known to compile under: 6138
  • Broken since: --

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.

EGI Amplifier webpage

There are two computers necessary to use AmpServerPro module with BCI2000. One is the iMac Net Station and the other is the client PC on which BCI2000 is installed and run. The Net Station, client PC and the amplifier are all connected to a network switch box. The two computers are connected to the CAT 5 inputs and the amplifier is connected through the fiber optic cable inputs. The client PC's IP address must be configured to allow the amplifier and Net Station to recognize it. On the client PC, configure the IP (IPv4) for a manual IP address (10.10.10.xx where ‘xx’ 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 client PC and enter the amplifiers IPv4 address into the address bar. If the client PC's IP address is set correctly then the page will populate with information about the amplifier as shown in the figure to the right. If a webpage similar to the one on the right is not shown, then the IP address of the client may not have been set correctly or the client PC has a firewall that is blocking the amp. Verify that the client IP 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.

  1. Double click BCI2000/batch/CursorTask_AmpServerPro.bat - the batch file that was created in the previous section - to start BCI2000.
  2. Click the "Configure" button.
  3. 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.
  4. Click "Set Config" and attend to any errors reported by the BCI2000 operator. If there were any errors, repeat this step.
  5. 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 type 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 and note its location. Copy the .mcb to the client PC. Launch BCI2000 and click the browse button for the ModulationPlanFile parameter. Navigate to the .mcb folder that was written by Reciprocity. Inside this folder, there will be multiple files and two folders. Select the file called 'plan.mcf' upload to BCI2000. DO NOT change any of the contents of the .mcb folder and be sure that ONLY 'plan.mcf' is uploaded.

StimulationExpression

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

States

GTENStim

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

GTENtr

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.

See also

User Reference:Filters, Contributions:ADCs