User Tutorial:Obtaining P300 Parameters in a Calibration Session

2009-09-02T18:34:00Z

Awilson: /* Creating a subject-specific parameter file */

==Obtaining P300 Parameters in the Calibration Session==

Although the basic properties of the P300 evoked potential are the same for all individuals, the response's latency, width, and spatial pattern varies, and adaptation to individual parameters improves accuracy.

Thus, it is necessary to obtain these individual parameters prior to performing spelling experiments.

==Design of Calibration Session==

During the calibration session, the subject is asked to spell out a given word by using a P300 character matrix, pictured below. During each run, the subject is asked to focus on the next letter in the word he is spelling, as the rows and columns flash randomly and successively so that sometimes the flashing corresponds to the column or row containing the target character and sometimes it will not. As the subject counts the number of times the desired letter in the word flashes, a P300 response is generated. The purpose of the calibration session is to identify those features that discriminate between the desired and undesired rows/columns.

[[Image:P3SpellerMatrix.PNG|298px]]

After the first few runs are collected, an analysis tool will be used to generate a configuration file with weights that will determine what portions of the input data correspond to selecting the desired letter. These weights are applied to the configuration session for one more run, and then the data from this run is also analyzed with the analysis tool, and the number of flashes needed to ensure 100% accuracy is determined. This second configuration file constitutes the final set of parameters, and is saved as that subject's parameter file for future spelling sessions.

==Performing the Calibration Session==

*Start BCI2000 by running <tt>batch/P3Speller_<Your_Amplifier>.bat</tt>
*Press '''Config''', and load the baseline parameters for copy spelling that you made earlier.
*In the '''Storage''' tab:
**Set ''SubjectName'' to the subject's initials.
**Set ''SubjectSession'' to <tt>001</tt>
**Set ''SubjectRun'' to <tt>01</tt>
*In the '''Application''' tab:
**Make sure that ''InterpretMode'' is set to <tt>copy mode</tt>, and ''DisplayResults'' (directly below InterpretMode) is unchecked
**Find the ''TextToSpell'' field. This should be set to ‘THE’, and you will be changing it after each run.
*Press '''Set Config''' to apply this configuration.

*Request that the subject sit in a relaxed position, and that the subject not move or speak during the runs.
*Turning off or dimming the lights can improve the subject's focus and performance.
*Showing the brain wave readouts to the subject can help understanding how artifact-generating behavior can be detrimental to the data.
*Press '''Start''' to show the flashing character matrix, and describe what the subject is expected to do.
*After you’ve explained the procedure, click '''Suspend''' to stop.
*Delete that run of data (the file will be found at <tt>data\P300\<Subject Initials>001\<Subject Initials>S001R01.dat</tt>).

*Press '''Start''' to record the run.
*Once it has finished automatically, click '''Config''' and change the ''TextToSpell'' in the '''Application''' tab to <tt>QUICK</tt>.
*Press '''Start''' to record the run.
*Once it has finished automatically, click '''Config''' and change the ''TextToSpell'' in the '''Application''' tab to <tt>BROWN</tt>.
*Press '''Start''' to record the run.
*Once it has finished automatically, click '''Config''' and change the ''TextToSpell'' in the '''Application''' tab to <tt>FOX</tt>.
*Press '''Start''' to record the run.
*Once this recording has finished, close BCI2000 and locate the saved data files below the BCI2000 <tt>data</tt> directory.

==Analyzing The Calibration Session with Offline Analysis==
We will now perform an ‘Offline Analysis’ with a tool that is provided with BCI2000.
*Start the [[User Reference:BCI2000 Offline Analysis|BCI2000 Offline Analysis]] tool:
**If you have a version of Matlab installed, run <tt>tools/OfflineAnalysis/OfflineAnalysis.bat</tt>.
**Otherwise, follow the instructions provided [[User_Reference:BCI2000_Offline_Analysis#Systems_that_do_not_have_MATLAB_installed_or_with_versions_that_predate_MATLAB_v7.0|elsewhere]].
[[Image:OfflineGUI.PNG|right]]
*In the ''Analysis Domain'' field, choose '''Time (P300)'''
*In the ''Acquisition Type'' field, choose '''EEG'''
*Next to ''Spatial Filter'', choose '''Common Average Reference (CAR)'''
*For '''Trial Change Condition''' enter <tt>states.StimulusBegin == 1</tt>
*For '''Target Condition 1''' enter <tt>(states.StimulusCode > 0) & (states.StimulusType == 1)</tt>
*For '''Target Condition Label 1''' enter <tt>Attended Stimuli</tt>
**‘Attended Stimuli’ refers to the letter or character the person is counting the flashes of, and triggers when the desired letter is flashed
*For '''Target Condition 2''' enter <tt>(states.StimulusCode > 0) & (states.StimulusType == 0)</tt>
*For '''Target Condition Label 2''' enter <tt>Unattended Stimuli</tt>
**‘Unattended stimulus’ refers to the letters or characters the person is not counting the flashes of, and triggers when the desired letter is not flashed
*Click the '''Add''' button by ''Data Files''
*In this new dialog, select all of the data files taken during this configuration session, and click '''Open'''

*Click '''Generate Plots''' and wait for the feature plot to appear

{|
|height=160px|
|}

[[Image:FeaturesPlot.PNG|right|500px]]

*When this is complete, you will see a feature plot similar to the one to the right. The vertical axis corresponds to the locations while the horizontal corresponds to the time delay after the stimulus. The color coding shows the r-squared value of that datapoint, with dark red colors indicating a high predictability that a response is produced by the desired letter being flashed.
*The largest of these r-squared values between 250 and 550ms are what we are interested in. Pick the 4 points with the largest r-squared values between these times and record their time points and channels. The plot’s ''Data Cursor'' tool (Tools Menu → Data Cursor) allows for discrete identification of time points.

*With these four points, close the feature plot, and enter the channel numbers of the data points you found into the ''Waveform Channels'' field and the time points into the ''Topo Times'' field.
**In the example above, the four best data points have r-squared values <tt>0.02218</tt>, <tt>0.02179</tt>, <tt>0.01928</tt>, and <tt>0.019</tt>, occur at times <tt>388.7ms</tt>, <tt>392.6ms</tt>, <tt>384.8ms</tt>, and <tt>365.2ms</tt> respectively, and all four are located in channel six. <tt>6, 6, 6, 6</tt> would be entered into ''Waveform Channels'' and <tt>388.7, 392.6, 384.8, 365.2</tt> would be entered into the ''Topo Times'' field. The order of the data points here does not matter, only that they are in the same order in both fields.
**If there are less than four points that seem appropriate, either because they are at the wrong electrodes, at the wrong times, or simply have too low of an r-squared value, that is fine, three or two values can work, though the fewer values used the lower the accuracy will be.
**Additionally, it may be helpful to re-run the analysis by setting the ''Spatial Filter'' to '''None''', particularly when few channels are used.
*Click '''Generate Plots''' to create the features plot again with a set of four graphs that show the correlation between the selected times after the desired stimulus is given (the red line) and the brain’s responses to when the desired stimulus is not given (the blue line).
**As seen below, the attended-stimulus reaction will typically be stronger than for the unattended stimuli, but in some cases the reverse is true. If the ‘unattended’ curve is larger than the ‘attended’ curve then make a note of this before moving on. The waveform seen here is similar to the others generated, only one is shown here for simplicity.
**Additionally before moving on, determine the location of the response seen. The P300 response is generally observed centered on the Cz electrode, or just behind and directly in between the ears, and does not involve the frontal regions of the brain. Assuming these characteristics are present, it is proper to proceed.

[[Image:Waveform.PNG|center|800px]]

==Creating a subject-specific parameter file==
Now we will save these customizations to a subject-specific parameter file that will allow the subject to free-spell with very high accuracy.
*Start BCI2000 using <tt>batch/P3Speller_<Your_Amplifier>.bat</tt> file
*Click '''Config''', and load the configuration file you saved previously
*Under the '''Storage''' tab, set the ''SubjectSession'' parameter to "002", and the '''SubjectName''' parameter to the subject's initials.
*Under the '''Filtering''' tab, click the '''Edit Matrix''' button by ''Classifier'' near the bottom
*Change this matrix to have 4 columns and as many rows as values you are using, and click '''Set New Matrix Size'''
**In the first column, labeled ''Input Channel'', enter the channel of the first value you use
**In the second column, labeled ''Input Element (bin)'', enter the time of the best classification, immediately followed with <tt>ms</tt>, as in <tt>388.7ms</tt>
**In the third column, enter 1 as the output channel
**In the fourth column, enter 1 if the ''Attended'' line was larger than the ''Unattended'' line, -1 if the ''unattended'' line was larger than the ''attended'' line
**Repeat these steps for the remaining rows, and close the matrix when finished
* If a '''Common Average Reference''' was used in the analysis, under the '''Filtering''' tab change the '''SpatialFilterType''' parameter to '''Common Average Reference (CAR)'''; otherwise, leave it as '''None'''.
*Click '''Save Parameters''' to save this file, naming it however you deem fit
*Use this new parameter file to repeat the configuration session and data analysis a few times, adding new rows to the classifier matrix each time for new data points to be utilized.
*When accuracy is reliably above 90%, click '''Config,''' and click on the '''Application''' tab:
**Delete the contents of the ''Text to Spell'' field
**Set ''InterpretMode'' → <tt>online free mode</tt>
**Make sure the ''DisplayResults'' box is checked
**Click on '''Edit Matrix''' next to ''TargetDefinitions'' and scroll to the bottom:
***In the first column replace <tt>9</tt> with <tt>BS</tt> (for "BackSpace")
***In the second column replace <tt>9</tt> with <tt><BS></tt>
*Click '''Save Parameters''', and change the <tt>copy_spell</tt> portion of this parameter file name to <tt>free_spell</tt>
*This parameter file is now ready to use for that specific subject for future P300 spelling experiments

One program contributed to, and provided with, the BCI2000 system is the P300 GUI. This Matlab-based program automatically sifts through data files for datapoints indicative of a positive P300 reaction, and builds a classifier matrix with those datapoints. The largest benefit to using this program is the obviated need for repeated configuration sessions, at the expense of decreased hands-on experience with the BCI2000 program itself. For a tutorial on how to perform the offline analysis with this GUI program, [[User Tutorial:P300 GUI for Offline Analysis Tutorial|please click here]].

==Next Step==
To continue onto performing P300 spelling experiments, continue to [[User Tutorial:Performing a P300 Spelling Session|Performing a P300 Spelling Session]].

==See also==
[[User Tutorial:P300 BCI Tutorial]]

[[Category:Tutorial]]

User Tutorial:Obtaining P300 Parameters in a Calibration Session

2009-09-02T17:12:26Z

Awilson: /* Creating a subject-specific parameter file */

==Obtaining P300 Parameters in the Calibration Session==

Although the basic properties of the P300 evoked potential are the same for all individuals, the response's latency, width, and spatial pattern varies, and adaptation to individual parameters improves accuracy.

Thus, it is necessary to obtain these individual parameters prior to performing spelling experiments.

==Design of Calibration Session==

During the calibration session, the subject is asked to spell out a given word by using a P300 character matrix, pictured below. During each run, the subject is asked to focus on the next letter in the word he is spelling, as the rows and columns flash randomly and successively so that sometimes the flashing corresponds to the column or row containing the target character and sometimes it will not. As the subject counts the number of times the desired letter in the word flashes, a P300 response is generated. The purpose of the calibration session is to identify those features that discriminate between the desired and undesired rows/columns.

[[Image:P3SpellerMatrix.PNG|298px]]

After the first few runs are collected, an analysis tool will be used to generate a configuration file with weights that will determine what portions of the input data correspond to selecting the desired letter. These weights are applied to the configuration session for one more run, and then the data from this run is also analyzed with the analysis tool, and the number of flashes needed to ensure 100% accuracy is determined. This second configuration file constitutes the final set of parameters, and is saved as that subject's parameter file for future spelling sessions.

==Performing the Calibration Session==

*Start BCI2000 by running <tt>batch/P3Speller_<Your_Amplifier>.bat</tt>
*Press '''Config''', and load the baseline parameters for copy spelling that you made earlier.
*In the '''Storage''' tab:
**Set ''SubjectName'' to the subject's initials.
**Set ''SubjectSession'' to <tt>001</tt>
**Set ''SubjectRun'' to <tt>01</tt>
*In the '''Application''' tab:
**Make sure that ''InterpretMode'' is set to <tt>copy mode</tt>, and ''DisplayResults'' (directly below InterpretMode) is unchecked
**Find the ''TextToSpell'' field. This should be set to ‘THE’, and you will be changing it after each run.
*Press '''Set Config''' to apply this configuration.

*Request that the subject sit in a relaxed position, and that the subject not move or speak during the runs.
*Turning off or dimming the lights can improve the subject's focus and performance.
*Showing the brain wave readouts to the subject can help understanding how artifact-generating behavior can be detrimental to the data.
*Press '''Start''' to show the flashing character matrix, and describe what the subject is expected to do.
*After you’ve explained the procedure, click '''Suspend''' to stop.
*Delete that run of data (the file will be found at <tt>data\P300\<Subject Initials>001\<Subject Initials>S001R01.dat</tt>).

*Press '''Start''' to record the run.
*Once it has finished automatically, click '''Config''' and change the ''TextToSpell'' in the '''Application''' tab to <tt>QUICK</tt>.
*Press '''Start''' to record the run.
*Once it has finished automatically, click '''Config''' and change the ''TextToSpell'' in the '''Application''' tab to <tt>BROWN</tt>.
*Press '''Start''' to record the run.
*Once it has finished automatically, click '''Config''' and change the ''TextToSpell'' in the '''Application''' tab to <tt>FOX</tt>.
*Press '''Start''' to record the run.
*Once this recording has finished, close BCI2000 and locate the saved data files below the BCI2000 <tt>data</tt> directory.

==Analyzing The Calibration Session with Offline Analysis==
We will now perform an ‘Offline Analysis’ with a tool that is provided with BCI2000.
*Start the [[User Reference:BCI2000 Offline Analysis|BCI2000 Offline Analysis]] tool:
**If you have a version of Matlab installed, run <tt>tools/OfflineAnalysis/OfflineAnalysis.bat</tt>.
**Otherwise, follow the instructions provided [[User_Reference:BCI2000_Offline_Analysis#Systems_that_do_not_have_MATLAB_installed_or_with_versions_that_predate_MATLAB_v7.0|elsewhere]].
[[Image:OfflineGUI.PNG|right]]
*In the ''Analysis Domain'' field, choose '''Time (P300)'''
*In the ''Acquisition Type'' field, choose '''EEG'''
*Next to ''Spatial Filter'', choose '''Common Average Reference (CAR)'''
*For '''Trial Change Condition''' enter <tt>states.StimulusBegin == 1</tt>
*For '''Target Condition 1''' enter <tt>(states.StimulusCode > 0) & (states.StimulusType == 1)</tt>
*For '''Target Condition Label 1''' enter <tt>Attended Stimuli</tt>
**‘Attended Stimuli’ refers to the letter or character the person is counting the flashes of, and triggers when the desired letter is flashed
*For '''Target Condition 2''' enter <tt>(states.StimulusCode > 0) & (states.StimulusType == 0)</tt>
*For '''Target Condition Label 2''' enter <tt>Unattended Stimuli</tt>
**‘Unattended stimulus’ refers to the letters or characters the person is not counting the flashes of, and triggers when the desired letter is not flashed
*Click the '''Add''' button by ''Data Files''
*In this new dialog, select all of the data files taken during this configuration session, and click '''Open'''

*Click '''Generate Plots''' and wait for the feature plot to appear

{|
|height=160px|
|}

[[Image:FeaturesPlot.PNG|right|500px]]

*When this is complete, you will see a feature plot similar to the one to the right. The vertical axis corresponds to the locations while the horizontal corresponds to the time delay after the stimulus. The color coding shows the r-squared value of that datapoint, with dark red colors indicating a high predictability that a response is produced by the desired letter being flashed.
*The largest of these r-squared values between 250 and 550ms are what we are interested in. Pick the 4 points with the largest r-squared values between these times and record their time points and channels. The plot’s ''Data Cursor'' tool (Tools Menu → Data Cursor) allows for discrete identification of time points.

*With these four points, close the feature plot, and enter the channel numbers of the data points you found into the ''Waveform Channels'' field and the time points into the ''Topo Times'' field.
**In the example above, the four best data points have r-squared values <tt>0.02218</tt>, <tt>0.02179</tt>, <tt>0.01928</tt>, and <tt>0.019</tt>, occur at times <tt>388.7ms</tt>, <tt>392.6ms</tt>, <tt>384.8ms</tt>, and <tt>365.2ms</tt> respectively, and all four are located in channel six. <tt>6, 6, 6, 6</tt> would be entered into ''Waveform Channels'' and <tt>388.7, 392.6, 384.8, 365.2</tt> would be entered into the ''Topo Times'' field. The order of the data points here does not matter, only that they are in the same order in both fields.
**If there are less than four points that seem appropriate, either because they are at the wrong electrodes, at the wrong times, or simply have too low of an r-squared value, that is fine, three or two values can work, though the fewer values used the lower the accuracy will be.
**Additionally, it may be helpful to re-run the analysis by setting the ''Spatial Filter'' to '''None''', particularly when few channels are used.
*Click '''Generate Plots''' to create the features plot again with a set of four graphs that show the correlation between the selected times after the desired stimulus is given (the red line) and the brain’s responses to when the desired stimulus is not given (the blue line).
**As seen below, the attended-stimulus reaction will typically be stronger than for the unattended stimuli, but in some cases the reverse is true. If the ‘unattended’ curve is larger than the ‘attended’ curve then make a note of this before moving on. The waveform seen here is similar to the others generated, only one is shown here for simplicity.
**Additionally before moving on, determine the location of the response seen. The P300 response is generally observed centered on the Cz electrode, or just behind and directly in between the ears, and does not involve the frontal regions of the brain. Assuming these characteristics are present, it is proper to proceed.

[[Image:Waveform.PNG|center|800px]]

==Creating a subject-specific parameter file==
Now we will save these customizations to a subject-specific parameter file that will allow the subject to free-spell with very high accuracy.
*Start BCI2000 using <tt>batch/P3Speller_<Your_Amplifier>.bat</tt> file
*Click '''Config''', and load the configuration file you saved previously
*Under the '''Storage''' tab, set the ''SubjectSession'' parameter to "002", and the '''SubjectName''' parameter to the subject's initials.
*Under the '''Filtering''' tab, click the '''Edit Matrix''' button by ''Classifier'' near the bottom
*Change this matrix to have 4 columns and as many rows as values you are using, and click '''Set New Matrix Size'''
**In the first column, labeled ''Input Channel'', enter the channel of the first value you use
**In the second column, labeled ''Input Element (bin)'', enter the time of the best classification, immediately followed with <tt>ms</tt>, as in <tt>388.7ms</tt>
**In the third column, enter 1 as the output channel
**In the fourth column, enter 1 if the ''Attended'' line was larger than the ''Unattended'' line, -1 if the ''unattended'' line was larger than the ''attended'' line
**Repeat these steps for the remaining rows, and close the matrix when finished
* If a '''Common Average Reference''' was used in the analysis, under the '''Filtering''' tab change the '''SpatialFilterType''' parameter to '''Common Average Reference (CAR)'''; otherwise, leave it as '''None'''.
*Click '''Save Parameters''' to save this file, naming it however you deem fit
*Use this new parameter file to repeat the configuration session and data analysis a few times, adding new rows to the classifier matrix each time for new data points to be utilized.
*When accuracy is reliably above 90%, click '''Config,''' and click on the '''Application''' tab:
**Set ''NumberOfSequences'' to this number as well '''(to which number? jm)'''
**Delete the contents of the ''Text to Spell'' field
**Set ''InterpretMode'' → <tt>online free mode</tt>
**Make sure the ''DisplayResults'' box is checked
**Click on '''Edit Matrix''' next to ''TargetDefinitions'' and scroll to the bottom:
***In the first column replace <tt>9</tt> with <tt>BS</tt> (for "BackSpace")
***In the second column replace <tt>9</tt> with <tt><BS></tt>
*Click '''Save Parameters''', and change the <tt>copy_spell</tt> portion of this parameter file name to <tt>free_spell</tt>
*This parameter file is now ready to use for that specific subject for future P300 spelling experiments

One program contributed to, and provided with, the BCI2000 system is the P300 GUI. This Matlab-based program automatically sifts through data files for datapoints indicative of a positive P300 reaction, and builds a classifier matrix with those datapoints. The largest benefit to using this program is the obviated need for repeated configuration sessions, at the expense of decreased hands-on experience with the BCI2000 program itself. For a tutorial on how to perform the offline analysis with this GUI program, [[User Tutorial:P300 GUI for Offline Analysis Tutorial|please click here]].

==Next Step==
To continue onto performing P300 spelling experiments, continue to [[User Tutorial:Performing a P300 Spelling Session|Performing a P300 Spelling Session]].

==See also==
[[User Tutorial:P300 BCI Tutorial]]

[[Category:Tutorial]]

User Tutorial:Obtaining P300 Parameters in a Calibration Session

2009-09-02T17:11:58Z

Awilson: /* Creating a subject-specific parameter file */

==Obtaining P300 Parameters in the Calibration Session==

Although the basic properties of the P300 evoked potential are the same for all individuals, the response's latency, width, and spatial pattern varies, and adaptation to individual parameters improves accuracy.

Thus, it is necessary to obtain these individual parameters prior to performing spelling experiments.

==Design of Calibration Session==

During the calibration session, the subject is asked to spell out a given word by using a P300 character matrix, pictured below. During each run, the subject is asked to focus on the next letter in the word he is spelling, as the rows and columns flash randomly and successively so that sometimes the flashing corresponds to the column or row containing the target character and sometimes it will not. As the subject counts the number of times the desired letter in the word flashes, a P300 response is generated. The purpose of the calibration session is to identify those features that discriminate between the desired and undesired rows/columns.

[[Image:P3SpellerMatrix.PNG|298px]]

After the first few runs are collected, an analysis tool will be used to generate a configuration file with weights that will determine what portions of the input data correspond to selecting the desired letter. These weights are applied to the configuration session for one more run, and then the data from this run is also analyzed with the analysis tool, and the number of flashes needed to ensure 100% accuracy is determined. This second configuration file constitutes the final set of parameters, and is saved as that subject's parameter file for future spelling sessions.

==Performing the Calibration Session==

*Start BCI2000 by running <tt>batch/P3Speller_<Your_Amplifier>.bat</tt>
*Press '''Config''', and load the baseline parameters for copy spelling that you made earlier.
*In the '''Storage''' tab:
**Set ''SubjectName'' to the subject's initials.
**Set ''SubjectSession'' to <tt>001</tt>
**Set ''SubjectRun'' to <tt>01</tt>
*In the '''Application''' tab:
**Make sure that ''InterpretMode'' is set to <tt>copy mode</tt>, and ''DisplayResults'' (directly below InterpretMode) is unchecked
**Find the ''TextToSpell'' field. This should be set to ‘THE’, and you will be changing it after each run.
*Press '''Set Config''' to apply this configuration.

*Request that the subject sit in a relaxed position, and that the subject not move or speak during the runs.
*Turning off or dimming the lights can improve the subject's focus and performance.
*Showing the brain wave readouts to the subject can help understanding how artifact-generating behavior can be detrimental to the data.
*Press '''Start''' to show the flashing character matrix, and describe what the subject is expected to do.
*After you’ve explained the procedure, click '''Suspend''' to stop.
*Delete that run of data (the file will be found at <tt>data\P300\<Subject Initials>001\<Subject Initials>S001R01.dat</tt>).

*Press '''Start''' to record the run.
*Once it has finished automatically, click '''Config''' and change the ''TextToSpell'' in the '''Application''' tab to <tt>QUICK</tt>.
*Press '''Start''' to record the run.
*Once it has finished automatically, click '''Config''' and change the ''TextToSpell'' in the '''Application''' tab to <tt>BROWN</tt>.
*Press '''Start''' to record the run.
*Once it has finished automatically, click '''Config''' and change the ''TextToSpell'' in the '''Application''' tab to <tt>FOX</tt>.
*Press '''Start''' to record the run.
*Once this recording has finished, close BCI2000 and locate the saved data files below the BCI2000 <tt>data</tt> directory.

==Analyzing The Calibration Session with Offline Analysis==
We will now perform an ‘Offline Analysis’ with a tool that is provided with BCI2000.
*Start the [[User Reference:BCI2000 Offline Analysis|BCI2000 Offline Analysis]] tool:
**If you have a version of Matlab installed, run <tt>tools/OfflineAnalysis/OfflineAnalysis.bat</tt>.
**Otherwise, follow the instructions provided [[User_Reference:BCI2000_Offline_Analysis#Systems_that_do_not_have_MATLAB_installed_or_with_versions_that_predate_MATLAB_v7.0|elsewhere]].
[[Image:OfflineGUI.PNG|right]]
*In the ''Analysis Domain'' field, choose '''Time (P300)'''
*In the ''Acquisition Type'' field, choose '''EEG'''
*Next to ''Spatial Filter'', choose '''Common Average Reference (CAR)'''
*For '''Trial Change Condition''' enter <tt>states.StimulusBegin == 1</tt>
*For '''Target Condition 1''' enter <tt>(states.StimulusCode > 0) & (states.StimulusType == 1)</tt>
*For '''Target Condition Label 1''' enter <tt>Attended Stimuli</tt>
**‘Attended Stimuli’ refers to the letter or character the person is counting the flashes of, and triggers when the desired letter is flashed
*For '''Target Condition 2''' enter <tt>(states.StimulusCode > 0) & (states.StimulusType == 0)</tt>
*For '''Target Condition Label 2''' enter <tt>Unattended Stimuli</tt>
**‘Unattended stimulus’ refers to the letters or characters the person is not counting the flashes of, and triggers when the desired letter is not flashed
*Click the '''Add''' button by ''Data Files''
*In this new dialog, select all of the data files taken during this configuration session, and click '''Open'''

*Click '''Generate Plots''' and wait for the feature plot to appear

{|
|height=160px|
|}

[[Image:FeaturesPlot.PNG|right|500px]]

*When this is complete, you will see a feature plot similar to the one to the right. The vertical axis corresponds to the locations while the horizontal corresponds to the time delay after the stimulus. The color coding shows the r-squared value of that datapoint, with dark red colors indicating a high predictability that a response is produced by the desired letter being flashed.
*The largest of these r-squared values between 250 and 550ms are what we are interested in. Pick the 4 points with the largest r-squared values between these times and record their time points and channels. The plot’s ''Data Cursor'' tool (Tools Menu → Data Cursor) allows for discrete identification of time points.

*With these four points, close the feature plot, and enter the channel numbers of the data points you found into the ''Waveform Channels'' field and the time points into the ''Topo Times'' field.
**In the example above, the four best data points have r-squared values <tt>0.02218</tt>, <tt>0.02179</tt>, <tt>0.01928</tt>, and <tt>0.019</tt>, occur at times <tt>388.7ms</tt>, <tt>392.6ms</tt>, <tt>384.8ms</tt>, and <tt>365.2ms</tt> respectively, and all four are located in channel six. <tt>6, 6, 6, 6</tt> would be entered into ''Waveform Channels'' and <tt>388.7, 392.6, 384.8, 365.2</tt> would be entered into the ''Topo Times'' field. The order of the data points here does not matter, only that they are in the same order in both fields.
**If there are less than four points that seem appropriate, either because they are at the wrong electrodes, at the wrong times, or simply have too low of an r-squared value, that is fine, three or two values can work, though the fewer values used the lower the accuracy will be.
**Additionally, it may be helpful to re-run the analysis by setting the ''Spatial Filter'' to '''None''', particularly when few channels are used.
*Click '''Generate Plots''' to create the features plot again with a set of four graphs that show the correlation between the selected times after the desired stimulus is given (the red line) and the brain’s responses to when the desired stimulus is not given (the blue line).
**As seen below, the attended-stimulus reaction will typically be stronger than for the unattended stimuli, but in some cases the reverse is true. If the ‘unattended’ curve is larger than the ‘attended’ curve then make a note of this before moving on. The waveform seen here is similar to the others generated, only one is shown here for simplicity.
**Additionally before moving on, determine the location of the response seen. The P300 response is generally observed centered on the Cz electrode, or just behind and directly in between the ears, and does not involve the frontal regions of the brain. Assuming these characteristics are present, it is proper to proceed.

[[Image:Waveform.PNG|center|800px]]

==Creating a subject-specific parameter file==
Now we will save these customizations to a subject-specific parameter file that will allow the subject to free-spell with very high accuracy.
*Start BCI2000 using <tt>batch/P3Speller_<Your_Amplifier>.bat</tt> file
*Click '''Config''', and load the configuration file you saved previously
*Under the '''Storage''' tab, set the ''SubjectSession'' parameter to "002", and the '''SubjectName''' parameter to the subject's initials.
*Under the '''Filtering''' tab, click the '''Edit Matrix''' button by ''Classifier'' near the bottom
*Change this matrix to have 4 columns and as many rows as values you are using, and click '''Set New Matrix Size'''
**In the first column, labeled ''Input Channel'', enter the channel of the first value you use
**In the second column, labeled ''Input Element (bin)'', enter the time of the best classification, immediately followed with <tt>ms</tt>, as in <tt>388.7ms</tt>
**In the third column, enter 1 as the output channel
**In the fourth column, enter 1 if the ''Attended'' line was larger than the ''Unattended'' line, -1 if the ''unattended'' line was larger than the ''attended'' line
**Repeat these steps for the remaining rows
* If a '''Common Average Reference''' was used in the analysis, under the '''Filtering''' tab change the '''SpatialFilterType''' parameter to '''Common Average Reference (CAR)'''; otherwise, leave it as '''None'''.
*Close this matrix, and click '''Save Parameters''' to save this file, naming it however you deem fit
*Use this new parameter file to repeat the configuration session and data analysis a few times, adding new rows to the classifier matrix each time for new data points to be utilized.
*When accuracy is reliably above 90%, click '''Config,''' and click on the '''Application''' tab:
**Set ''NumberOfSequences'' to this number as well '''(to which number? jm)'''
**Delete the contents of the ''Text to Spell'' field
**Set ''InterpretMode'' → <tt>online free mode</tt>
**Make sure the ''DisplayResults'' box is checked
**Click on '''Edit Matrix''' next to ''TargetDefinitions'' and scroll to the bottom:
***In the first column replace <tt>9</tt> with <tt>BS</tt> (for "BackSpace")
***In the second column replace <tt>9</tt> with <tt><BS></tt>
*Click '''Save Parameters''', and change the <tt>copy_spell</tt> portion of this parameter file name to <tt>free_spell</tt>
*This parameter file is now ready to use for that specific subject for future P300 spelling experiments

One program contributed to, and provided with, the BCI2000 system is the P300 GUI. This Matlab-based program automatically sifts through data files for datapoints indicative of a positive P300 reaction, and builds a classifier matrix with those datapoints. The largest benefit to using this program is the obviated need for repeated configuration sessions, at the expense of decreased hands-on experience with the BCI2000 program itself. For a tutorial on how to perform the offline analysis with this GUI program, [[User Tutorial:P300 GUI for Offline Analysis Tutorial|please click here]].

==Next Step==
To continue onto performing P300 spelling experiments, continue to [[User Tutorial:Performing a P300 Spelling Session|Performing a P300 Spelling Session]].

==See also==
[[User Tutorial:P300 BCI Tutorial]]

[[Category:Tutorial]]

User Tutorial:Obtaining P300 Parameters in a Calibration Session

2009-09-02T17:09:21Z

Awilson: /* Analyzing The Calibration Session with Offline Analysis */

==Obtaining P300 Parameters in the Calibration Session==

Although the basic properties of the P300 evoked potential are the same for all individuals, the response's latency, width, and spatial pattern varies, and adaptation to individual parameters improves accuracy.

Thus, it is necessary to obtain these individual parameters prior to performing spelling experiments.

==Design of Calibration Session==

During the calibration session, the subject is asked to spell out a given word by using a P300 character matrix, pictured below. During each run, the subject is asked to focus on the next letter in the word he is spelling, as the rows and columns flash randomly and successively so that sometimes the flashing corresponds to the column or row containing the target character and sometimes it will not. As the subject counts the number of times the desired letter in the word flashes, a P300 response is generated. The purpose of the calibration session is to identify those features that discriminate between the desired and undesired rows/columns.

[[Image:P3SpellerMatrix.PNG|298px]]

After the first few runs are collected, an analysis tool will be used to generate a configuration file with weights that will determine what portions of the input data correspond to selecting the desired letter. These weights are applied to the configuration session for one more run, and then the data from this run is also analyzed with the analysis tool, and the number of flashes needed to ensure 100% accuracy is determined. This second configuration file constitutes the final set of parameters, and is saved as that subject's parameter file for future spelling sessions.

==Performing the Calibration Session==

*Start BCI2000 by running <tt>batch/P3Speller_<Your_Amplifier>.bat</tt>
*Press '''Config''', and load the baseline parameters for copy spelling that you made earlier.
*In the '''Storage''' tab:
**Set ''SubjectName'' to the subject's initials.
**Set ''SubjectSession'' to <tt>001</tt>
**Set ''SubjectRun'' to <tt>01</tt>
*In the '''Application''' tab:
**Make sure that ''InterpretMode'' is set to <tt>copy mode</tt>, and ''DisplayResults'' (directly below InterpretMode) is unchecked
**Find the ''TextToSpell'' field. This should be set to ‘THE’, and you will be changing it after each run.
*Press '''Set Config''' to apply this configuration.

*Request that the subject sit in a relaxed position, and that the subject not move or speak during the runs.
*Turning off or dimming the lights can improve the subject's focus and performance.
*Showing the brain wave readouts to the subject can help understanding how artifact-generating behavior can be detrimental to the data.
*Press '''Start''' to show the flashing character matrix, and describe what the subject is expected to do.
*After you’ve explained the procedure, click '''Suspend''' to stop.
*Delete that run of data (the file will be found at <tt>data\P300\<Subject Initials>001\<Subject Initials>S001R01.dat</tt>).

*Press '''Start''' to record the run.
*Once it has finished automatically, click '''Config''' and change the ''TextToSpell'' in the '''Application''' tab to <tt>QUICK</tt>.
*Press '''Start''' to record the run.
*Once it has finished automatically, click '''Config''' and change the ''TextToSpell'' in the '''Application''' tab to <tt>BROWN</tt>.
*Press '''Start''' to record the run.
*Once it has finished automatically, click '''Config''' and change the ''TextToSpell'' in the '''Application''' tab to <tt>FOX</tt>.
*Press '''Start''' to record the run.
*Once this recording has finished, close BCI2000 and locate the saved data files below the BCI2000 <tt>data</tt> directory.

==Analyzing The Calibration Session with Offline Analysis==
We will now perform an ‘Offline Analysis’ with a tool that is provided with BCI2000.
*Start the [[User Reference:BCI2000 Offline Analysis|BCI2000 Offline Analysis]] tool:
**If you have a version of Matlab installed, run <tt>tools/OfflineAnalysis/OfflineAnalysis.bat</tt>.
**Otherwise, follow the instructions provided [[User_Reference:BCI2000_Offline_Analysis#Systems_that_do_not_have_MATLAB_installed_or_with_versions_that_predate_MATLAB_v7.0|elsewhere]].
[[Image:OfflineGUI.PNG|right]]
*In the ''Analysis Domain'' field, choose '''Time (P300)'''
*In the ''Acquisition Type'' field, choose '''EEG'''
*Next to ''Spatial Filter'', choose '''Common Average Reference (CAR)'''
*For '''Trial Change Condition''' enter <tt>states.StimulusBegin == 1</tt>
*For '''Target Condition 1''' enter <tt>(states.StimulusCode > 0) & (states.StimulusType == 1)</tt>
*For '''Target Condition Label 1''' enter <tt>Attended Stimuli</tt>
**‘Attended Stimuli’ refers to the letter or character the person is counting the flashes of, and triggers when the desired letter is flashed
*For '''Target Condition 2''' enter <tt>(states.StimulusCode > 0) & (states.StimulusType == 0)</tt>
*For '''Target Condition Label 2''' enter <tt>Unattended Stimuli</tt>
**‘Unattended stimulus’ refers to the letters or characters the person is not counting the flashes of, and triggers when the desired letter is not flashed
*Click the '''Add''' button by ''Data Files''
*In this new dialog, select all of the data files taken during this configuration session, and click '''Open'''

*Click '''Generate Plots''' and wait for the feature plot to appear

{|
|height=160px|
|}

[[Image:FeaturesPlot.PNG|right|500px]]

*When this is complete, you will see a feature plot similar to the one to the right. The vertical axis corresponds to the locations while the horizontal corresponds to the time delay after the stimulus. The color coding shows the r-squared value of that datapoint, with dark red colors indicating a high predictability that a response is produced by the desired letter being flashed.
*The largest of these r-squared values between 250 and 550ms are what we are interested in. Pick the 4 points with the largest r-squared values between these times and record their time points and channels. The plot’s ''Data Cursor'' tool (Tools Menu → Data Cursor) allows for discrete identification of time points.

*With these four points, close the feature plot, and enter the channel numbers of the data points you found into the ''Waveform Channels'' field and the time points into the ''Topo Times'' field.
**In the example above, the four best data points have r-squared values <tt>0.02218</tt>, <tt>0.02179</tt>, <tt>0.01928</tt>, and <tt>0.019</tt>, occur at times <tt>388.7ms</tt>, <tt>392.6ms</tt>, <tt>384.8ms</tt>, and <tt>365.2ms</tt> respectively, and all four are located in channel six. <tt>6, 6, 6, 6</tt> would be entered into ''Waveform Channels'' and <tt>388.7, 392.6, 384.8, 365.2</tt> would be entered into the ''Topo Times'' field. The order of the data points here does not matter, only that they are in the same order in both fields.
**If there are less than four points that seem appropriate, either because they are at the wrong electrodes, at the wrong times, or simply have too low of an r-squared value, that is fine, three or two values can work, though the fewer values used the lower the accuracy will be.
**Additionally, it may be helpful to re-run the analysis by setting the ''Spatial Filter'' to '''None''', particularly when few channels are used.
*Click '''Generate Plots''' to create the features plot again with a set of four graphs that show the correlation between the selected times after the desired stimulus is given (the red line) and the brain’s responses to when the desired stimulus is not given (the blue line).
**As seen below, the attended-stimulus reaction will typically be stronger than for the unattended stimuli, but in some cases the reverse is true. If the ‘unattended’ curve is larger than the ‘attended’ curve then make a note of this before moving on. The waveform seen here is similar to the others generated, only one is shown here for simplicity.
**Additionally before moving on, determine the location of the response seen. The P300 response is generally observed centered on the Cz electrode, or just behind and directly in between the ears, and does not involve the frontal regions of the brain. Assuming these characteristics are present, it is proper to proceed.

[[Image:Waveform.PNG|center|800px]]

==Creating a subject-specific parameter file==
Now we will save these customizations to a subject-specific parameter file that will allow the subject to free-spell with very high accuracy.
*Start BCI2000 using <tt>batch/P3Speller_<Your_Amplifier>.bat</tt> file
*Click '''Config''', and load the configuration file you saved previously
*Under the '''Storage''' tab, set the ''SubjectSession'' parameter to "002", and the '''SubjectName''' parameter to the subject's initials.
*Under the '''Filtering''' tab, click the '''Edit Matrix''' button by ''Classifier'' near the bottom
*Change this matrix to have 4 columns and as many rows as values you are using, and click '''Set New Matrix Size'''
**In the first column, labeled ''Input Channel'', enter the channel of the first value you use
**In the second column, labeled ''Input Element (bin)'', enter the time of the best classification, immediately followed with <tt>ms</tt>, as in <tt>388.7ms</tt>
**In the third column, enter 1 as the output channel
**In the fourth column, enter 1 if the ''Attended'' line was larger than the ''Unattended'' line, -1 if the ''unattended'' line was larger than the ''attended'' line
**Repeat these steps for the remaining rows
*Close this matrix, and click '''Save Parameters''' to save this file, naming it however you deem fit
*Use this new parameter file to repeat the configuration session and data analysis a few times, adding new rows to the classifier matrix each time for new data points to be utilized.
*When accuracy is reliably above 90%, click '''Config,''' and click on the '''Application''' tab:
**Set ''NumberOfSequences'' to this number as well '''(to which number? jm)'''
**Delete the contents of the ''Text to Spell'' field
**Set ''InterpretMode'' → <tt>online free mode</tt>
**Make sure the ''DisplayResults'' box is checked
**Click on '''Edit Matrix''' next to ''TargetDefinitions'' and scroll to the bottom:
***In the first column replace <tt>9</tt> with <tt>BS</tt> (for "BackSpace")
***In the second column replace <tt>9</tt> with <tt><BS></tt>
*Click '''Save Parameters''', and change the <tt>copy_spell</tt> portion of this parameter file name to <tt>free_spell</tt>
*This parameter file is now ready to use for that specific subject for future P300 spelling experiments

One program contributed to, and provided with, the BCI2000 system is the P300 GUI. This Matlab-based program automatically sifts through data files for datapoints indicative of a positive P300 reaction, and builds a classifier matrix with those datapoints. The largest benefit to using this program is the obviated need for repeated configuration sessions, at the expense of decreased hands-on experience with the BCI2000 program itself. For a tutorial on how to perform the offline analysis with this GUI program, [[User Tutorial:P300 GUI for Offline Analysis Tutorial|please click here]].

==Next Step==
To continue onto performing P300 spelling experiments, continue to [[User Tutorial:Performing a P300 Spelling Session|Performing a P300 Spelling Session]].

==See also==
[[User Tutorial:P300 BCI Tutorial]]

[[Category:Tutorial]]

User Tutorial:Obtaining Mu Rhythm Parameters in an Initial Session

2009-08-27T19:35:36Z

Awilson: /* Preparing for the Initial (Screening) Session */

Although the [[User Tutorial:Introduction to the Mu Rhythm|basic properties of the Mu rhythm]] are identical for all humans, spatial patterns and exact frequencies are different across people. Thus, it is necessary to obtain these individual parameters prior to any feedback experiments, i.e., to calibrate the BCI system using data acquired from an initial session.

==Experimental Design==
In this initial session, the subject is instructed to imagine hand and/or foot movements in response to visual cues.
To identify a subject's Mu Rhythm, offline analyses then determine the frequency and location whose activity changes the most across conditions (e.g., hand imagery and rest). These analyses result in spectra calculated at different locations or in topographical plots at particular frequencies.

==Preparing for the Initial (Screening) Session==
To begin, you first need to gather some system data. This tutorial will assume that you will be using a dual-monitor setup as shown below, with the experimenter of the sessions operating on monitor 1, and the subject will be watching monitor 2.

Open Display Properties by right-clicking on an empty portion of the desktop and clicking '''Properties''', and navigating to the '''Settings''' tab.

{|
|colspan="2" align="center"|[[Image:MonitorSetupOrientation.PNG|center]]
|-
|colspan="2" align="center"|Make sure that Monitor 2, (which displays the instructions to the subject), is on the right of Monitor 1, (the experimenter's screen), and is aligned along the top.
|-
|colspan="2" align="center" height=50px|
|-
|align="center"|[[Image:MonitorSetupPrimaryRes.PNG|center]]
|[[Image:MonitorSetupSecondaryRes.PNG|center]]
|-
|colspan="2" align="center"|What we need to make a note of is the '''width''' of monitor 1, and the '''width and height''' of monitor 2.
|-
|colspan="2" align="center"|In this example we see that Monitor 1 is 2048 pixels wide, and monitor 2 is 1024 pixels wide by 768 pixels tall.
|-
|colspan="2" align="center" height=50px|
|}

Connect your amplifier to the computer, and turn it on.

If your amplifier is from the gMOBIlab family, you will need to make a note of the port it is connected to. In order to determine that port, in Windows XP, go to the Windows Start Menu, and choose '''Start → Control Panel → System → Hardware → Device Manager → Ports (COM & LPT)'''. Different versions of Windows may have the Device Manager in a different location. In this example, we see that the amplifier is connected to ''COM8''.

<gallery caption="Finding the COM port" widths="300px" heights="300px" perrow="4">
Image:ControlPanel-Circled.PNG|Accessing the Control Panel
Image:System.PNG|Opening the System Properties
Image:DeviceManager.PNG|Opening the Device Manager
Image:COMCircled.PNG|Identifying the COM Port
</gallery>
You can now close all open windows.

==Configuring BCI2000==

*Start BCI2000 by double-clicking <tt>batch/StimulusPresentation_<YourAmplifier>.bat</tt>.
**For repeated use, placing a link to this file on the desktop might be a good idea.
*In the operator module, click '''Config'''.
*Click '''Load Parameters''', and load <tt>parms/mu_tutorial/InitialMuSession.prm</tt>. Then, load <tt>parms/fragments/amplifiers/<YourAmplifier>.prm</tt>.
*In the '''Storage''' tab:
**Set ''SubjectName'' to the subject’s initials.
**Set ''SubjectSession'' to <tt>001</tt>
**Set ''SubjectRun'' to <tt>01</tt>

[[Image:SourceTabCircledMu.PNG|right|500px]]

In the '''Source''' tab, set:
*''ChannelNames'' to the electrode positions according to the 10-20 convention.
**This names the channels according to their respective electrode positions.
**In our example, <tt>F3 F4 T7 C3 Cz C4 T8 Pz</tt> has been entered.
*If using a gMOBIlab amplifier, set ''COM port'' to the port name that you found earlier.
**In this example, we would put in <tt>COM8:</tt>

{|
|height="180px"|
|}

In the '''Application''' tab, set:
*''WindowWidth'' to the width of the display monitor, found earlier.
*''WindowHeight'' to the height of the display monitor, found earlier.
**In our example, ''WindowWidth'' would be set to <tt>1024</tt> and ''WindowHeight'' would be set to <tt>768</tt>.
*''WindowLeft'' to the width of the experimenter’s monitor.
**In our example, this would be <tt>2048</tt>.
**This shifts the character display to the right 2048 pixels, making it display on the secondary monitor.
*Take note of the ''Sequence'' field:
**This field contains four single-digit numbers separated by one space. Initially it will be <tt>1 1 1 1</tt>.
**These numbers are frequencies of calling for the different subject activity. The first number corresponds to the left hand, the second is the right hand, the third for both hands, the fourth for both feet.
**Therefore, setting this field to <tt>2 1 0 1</tt> will call for the subject to move the left hand twice as often as the right or both feet, and will never call for both hands to be moved.
*Finally, save the parameter file where you deem appropriate.
*Click '''Set Config'''.
*Instruct the subject as described in the section below.

==Instructions to the Subject==
During the initial session, the subject's screen will either be blank, or displaying an arrow pointing up, down, left, or right.
*When a left or right arrow is displayed, imagine movement of the respective hand. The imagined movement should be continuous opening and closing of the hand (e.g., squeezing a tennis ball) at a rate of about one opening/closing per second.
*When an up arrow is displayed, imagine simultaneous movement of both hands. This should be the same kind of movement as described for a single hand.
*When a down arrow is displayed, imagine movements of both feet. The movement should be similar to the one described for hands, i.e., imagine opening and closing your feet as if you could use them to grip an object.
*When you see a blank screen, please relax and stop any movement imagery.

==Performing the Initial Session==
To start an experimental run, click '''Run''' in the operator window. Each run gathers 20 data points, or "trials", that differentiate between moving the left hand, the right hand, both hands, and both feet. Ideally, there should be 100 trials, meaning that five runs are suggested. This is done as five separate runs instead of one to allow the subject a chance between each run to rest, blink, swallow, speak, or have some water if so desired.

==Next Step==
Once all data have been collected, the [[User Tutorial:Analyzing the Initial Mu Rhythm Session|Analyzing the Initial Mu Rhythm Session]] page shows you how to analyze data from the initial session in order to determine parameters for online feedback.

==See also==
[[User Tutorial:Mu Rhythm BCI Tutorial]]

[[Category:Tutorial]]

User Tutorial:Analyzing the Initial Mu Rhythm Session

2009-08-25T14:35:41Z

Awilson:

This tutorial step assumes that you have [[User Tutorial:Obtaining Mu Rhythm Parameters in an Initial Session|performed an initial mu rhythm session]]. In order to identify the parameters (i.e., frequency and location) of a subject's mu rhythm, we will determine how different the EEG signal amplitude is for different types of imaginations that the subject performed during the recording. You will use the [[User Reference:BCI2000 Offline Analysis|BCI2000 Offline Analysis]] tool for this purpose.

==Generating a Feature Plot==
The first step in these analyses is to separate data into amplitudes at individual '''frequencies''' and '''locations.''' These amplitudes are called ''features,'' and their correspondence with the subject's imagination will be plotted as a so-called ''feature map.'' From a feature map, it is possible to determine those frequencies and locations whose amplitude is maximally correlated with the subject's task, i.e., those features that are most different between two conditions. These features will subsequently be used to provide feedback in a BCI experiment.

To generate a feature plot from the initial session's data, perform the following steps:
*Start the [[User Reference:BCI2000 Offline Analysis|BCI2000 Offline Analysis]] tool:
**If you have a version of Matlab installed, run <tt>tools/OfflineAnalysis/OfflineAnalysis.bat</tt>.
**Otherwise, follow the instructions provided [[User_Reference:BCI2000_Offline_Analysis#Systems_that_do_not_have_MATLAB_installed_or_with_versions_that_predate_MATLAB_v7.0|elsewhere]].
*In the '''Analysis Domain''' field, choose ''Frequency''.
*In the '''Acquisition Type''' field, choose "EEG".
*As a '''Spatial Filter''', choose "Common Average Reference (CAR)".
*Enter <tt>states.StimulusBegin == 1</tt> into the '''Trial Change Condition''' field.
*Into the field labeled '''Target Condition 1''', enter <tt>states.StimulusCode == 0</tt>.
*Enter the word "Rest" into the field labeled '''Target Condition Label 1'''.
*Similarly, enter <tt>states.StimulusCode == 2</tt> into the '''Target Condition 2''' field, and "Right Hand" into '''Target Condition Label 2'''.
*Click the "Add" button located besides the '''Data Files''' field. A file chooser dialog will appear; navigate to <tt>data/mu/<Subject>001</tt>, and select all <tt>.dat</tt> files available there (use your keyboard's ''ctrl'' button to click-select multiple files), then click the dialog's "Open" button.
*Click "Generate Plots", and wait for the feature plot to appear.

Once the computation is complete, you will see a feature plot similar to the one below. In that plot, the horizontal axis corresponds to frequencies, and the vertical axis corresponds to individual channels. Color codes represent [[Glossary#r-squared|r-squared]] values, which are numbers between 0 and 1. R-squared values provide a measure for the amount to which a particular EEG feature (i.e., amplitude at a particular frequency and location) is influenced by the subject's task (e.g., hand vs. foot imagery).

[[Image:eeg1FeaturePlt.png|600px]]

Typically, there will be clusters of large r-squared values in the feature plot. The initial step to configure the online system is to determine which brain signal feature differed the most between two particular tasks. This is accomplished by picking the largest r-squared value from the map and by noting its corresponding frequency and location. However, it is important to verify whether the feature in question is consistent with the [[User_Tutorial:Introduction_to_the_Mu_Rhythm#Physical_Properties|mu rhythm's known properties]]. This verification is necessary to avoid misconfiguration due to [[User_Tutorial:EEG_Measurement_Setup#EEG_Artifacts|EEG artifacts]], other noise, or random effects.

==Generating Spectra and Topography Plots==
*Pick the four largest r-squared values from the feature map between 9 and 36Hz, and read off their frequencies and channels. The plot's "Data Cursor" tool (''Data Cursor'' from the ''Tools'' menu) may be helpful for this.
*In the analysis program's '''Spectra Channels''' field, enter the channel numbers you read off the feature map.
*In the '''Topo Frequencies''' field, enter the frequencies you read off the feature map.
*Click the '''Generate Plots''' button.

[[Image:MuRhythmModulation.PNG|600px]]

The generated '''topography plots''' display the spatial distribution of r-squared values. In this comparison of EEG activity for right-hand movements and rest, there should be a clear maximum of r-squared values over the ''left'' motor cortex as shown in subfigure (A) and (B) above.
The generated '''spectra plots''' display amplitude distributions, and r-squared measure, over frequencies. Ideally, they should appear similar to the (C) and (D) subfigures above.

==Analyzing Remaining Conditions==
Up to now, you performed an analysis of how brain activity is related to imagined movements of the '''Right Hand.''' In order to choose the most useful channel and frequency for online feedback, perform similar analyses for the remaining conditions:
*In the analysis program's '''Target Condition 2''' field, enter <tt>states.StimulusCode == 1</tt>, and ''Left Hand'' into '''Target Condition Label 2'''.
*Make sure the '''Overwrite existing plots''' check box is unchecked.
*Click ''Generate Plots'' to create a feature plot for imagined movement of the left hand.
*As previously, pick the four largest r-squared values, and compute spectra and topographies for their channels and frequencies.
*Results should somewhat resemble that derived for the right hand, except that the colored activity changes should appear over the right and not the left motor cortex.
*Repeat the analysis for conditions <tt>states.StimulusCode == 3</tt>: ''Both Hands'', and <tt>states.StimulusCode == 4</tt>: ''Both Feet''.
**For the ''both hands'' condition, the result should resemble a combination of ''left hand'' and ''right hand'' results.
**For ''both feet,'' modulated activity should be centered around electrode Cz.

==Picking Optimal Features==

Here we are looking for the frequency with the highest r-squared value and is between 9Hz and 36Hz. Further, acceptable readings are centered on the proper electrode for the predicted stimulus; C3 for readings from the right hand, C4 for the left hand, both C3 and C4 for both hands, and Cz for both feet.

Equipped with the frequency and electrode that provides the reading with the highest r-squared value, we can begin configuring the setup for proper use.

==Next Step==
[[User Tutorial:Configuring Online Feedback|Configuring Online Feedback]] shows you how to configure the BCI system using the parameters obtained in the analysis.

==See also==
[[User Tutorial:Mu Rhythm BCI Tutorial]]

[[Category:Tutorial]]

User Tutorial:Analyzing the Initial Mu Rhythm Session

2009-08-25T14:30:52Z

2009-05-27T18:59:31Z

Awilson:

==Introduction==
BCI2000 v2.0 and higher includes a certification procedure that can determine whether a computer system is capable of running all or some BCI2000 applications. Because BCI2000 does not have a standardized hardware configuration, i.e., it can run on potentially ''any'' PC, this testing procedure is capable of running on any PC with BCI2000, with the results reporting which standard BCI2000 applications meet the minimum timing requirements. Different configurations are included in the certification procedure to test a range of likely setups for a given application, in which timing characteristics such as the sampling rate, inter-stimulus intervals, and stimulus duration, and other parameters, such as the number and size of the stimuli, are changed for each configuration.

This document serves as the instruction manual for using the certification procedure, and describes how the procedure works to determine the timing characteristics of the BCI2000 system. The primary use for the certification procedure is to determine if the PC configuration used with BCI2000 is capable of running the core BCI2000 system, which is comprised of:

*Support for the the g.tec series of amplifiers, including the g.USBamp, g.MOBIlab, and the g.MOBIlab+ (bluetooth) amplifiers.
*The AR, P3, FFT, and Matlab signal processing modules.
*The CursorTask, P3Speller, and StimulusPresentation application modules.

Additionally, due to the extensibility of BCI2000, researchers who develop custom algorithms and applications, or use amplifiers not made by g.tec, can use the certification procedure to determine whether their custom modules are capable of running on a particular PC configuration.

The certification procedure works by comparing the differences in time of when BCI2000 ''expects'' an event to occur to when that event ''actually'' occurred. These events include a change in the display, an audio output through the system speakers, or an EEG sample being stored in the amplifier buffer. The times at which such events occur are recorded with the amplifier and stored in a data file. Changes in the display are found using an optical sensor in combination with the g.TRIGbox. The g.TRIGbox is a signal conditioner that generates trigger pulses for various sensors or input signals. When the sensor exceeds a threshold, the g.TRIGbox outputs a digital signal which is recorded on the amplifier. A similar procedure is used for audio detection: the sound output from the PC is input to the g.TRIGbox, and when the volume exceeds threshold, a high digital signal is output and recorded by the amplifier. This information can be used because BCI2000 stores a time-stamp for every event during an experiment. The difference between a time-stamp value and the time that the recorded event changes values are compared to find the latency for that particular event.

These latencies can be affected by many external influences, including hardware deficiencies (such as low RAM, slow CPU speed, or a video card of low quality), and other software running in the background while the experiment is being run.

==Latencies==
Briefly, the different latencies inherent in the BCI2000 system include amplifier latency, processing latency, output latency, and the sum of these, the system latency. Additionally, the block duration jitter will be measured. The figure below provides a timeline of events that occur within a single block of data, with significant time points labeled. This figure provides an accurate account of the order in which events occur within a block of data, although the time intervals are not necessarily to scale.


[[Image:timeline3.png|frame|none|Timeline of events. Time intervals are not to scale.]]

===Defining Latencies===
====Amplifier Latency====
Amplifier Latency is the minimum delay between the time that a signal is presented at the amplifier input, to when it has been acquired in the source module. Depending on configuration, this may comprise physical signal delay in the amplifier, digitization, transmission from the amplifier to the PC, and processing time inside a hardware driver. That minimum delay occurs for the last sample of a data block, which, unlike its preceding samples in the same block, will spend only a minimum time in hardware and software buffers. In [[#TimeLine|Timeline]],

Amplifier latency = <math>t_{0}-t_{-1}</math>.

For amplifiers connected via bandwidth-limited serial interfaces, transmission latency may have a measurable impact on amplifier latency, depending on the hardware. When using USB 2.0, as is the case for the g.USBamp, transmission latency may generally neglected, as illustrated by the following example: USB 2.0 has a maximum transmission rate of 480 Mbit/s. If we are acquiring 16 channels of 32-bit data, and transmitting in blocks of 16 samples, this is 8192 bits of data; at USB 2.0 speed, this should take roughly 17 <math>\mu</math>s to transfer. However, a more realistic approximation for USB 2.0 speeds is 240 Mbit/s, which increases the transfer delay to 34 <math>\mu</math>s. For sampling rates below 30 kHz, this is less than a single sample's duration.

In addition to amplifier latency, system performance will be influenced by buffering latency. Buffering latency is dependent on the sample block buffer size: When a data sample is digitized, it is not immediately transferred to the PC, but is stored in memory on the amplifier. The PC then makes the appropriate request to the amplifier, and a block of data is transferred all at once to reduce the processing load. This implies that a signal that is digitized at the start of the buffer must wait until the buffer is full to be read into the PC. For example, if the sample block size is 16 samples, the first sample must wait 15 more samples before it can be used in the application. Fortunately, this latency is always known, and can be reduced with a higher sampling rate and/or smaller block sizes, assuming the PC can handle the increased overhead. Buffering latency does not affect the acquisition-to-display latency, because processing occurs immediately after a block's last sample, which is not affected. Still, it is an important factor to keep in mind, because a large sample block size and/or a small sample rate will decrease the refresh rate for the application (e.g., at a sample rate of 256 Hz and a sample block size of 128 samples, the application will only be refreshed every 0.5 s.)

====Processing Latency====
Processing Latency is the total time it takes for the data to be processed by all BCI2000 modules (SignalSource, SignalProcessing, and Application).

Processing latency = <math>t_{2}-t_{0}</math>.

Processing latency strongly depends on CPU speed, and if this latency becomes too large, high CPU load will probably be the cause, implying decreased or unsuitable BCI2000 performance.

====Output Latency====
Output Latency is the latency from the time that the Application module issues a command to change the display or issue a sound (or another output), to the time that this output actually occurs.

Output latency = <math>t_{3}-t_{2}</math>.

====System Latency====
System Latency is the minimum time interval between a change in amplifier input, and a causally related change in application output. This is the sum of the above latencies, Amplifier, Processing, and Output.

System latency = <math>t_{3} - t_{-1}</math>.

====Block Duration, Block Duration Jitter====
Block Duration is the time interval between adjacent blocks of data, normalized to the ideal duration of a data block as determined from sampling rate and sample block size:

Block Duration = <math>\frac{t_{5}-t_{0}}{\mathrm{SampleBlockSize}/\mathrm{SamplingRate}}</math>.

When the system operates in real time, mean Block Duration will always be 1. Measuring Block Duration has the purpose of obtaining Block Duration Jitter as its standard deviation.

===Measuring Latencies===
The procedure for measuring the system latencies are below. In general, a combination of recorded events and software time-stamps recorded in BCI2000 data files to determine when important events occur, with ms or better time resolution.
[[Image:OutTimeline1.png|thumb|500px|none|Recorded events used for measuring latencies.]]

====Measuring Amplifier Latency====
In [[#TimeLine|TimeLine]], Amplifier Latency is the time interval between the sampling of a data block's last sample, and its acquisition into the source module's data buffer:
<center><math>
\mathrm{AmplifierLatency} = t_{0} - t_{-1}
</math></center>

To measure this latency, the Source module will set a digital output on the amplifier to a high value at time <math>t_0</math> immediately following data acquisition, as indicated in [[#overview|Overview]]. The digital output level is 3.3 V, so a voltage divider may required to attenuate the signal level to the range of amplifier input. This signal is then recorded on an input channel on the amplifier (time <math>t_{1}</math>).

In the recorded data, we may then identify <math>t_{-1}</math>, which is the beginning of sample block <math>n</math>, by its sample offset, which also coincides with BCI2000 state changes. <math>t_1</math> may be identified by a change in the recorded signal, occurring in the channel that was connected to the digital output during measurement.
<center><math>
\mathrm{AmplifierLatency} \approx t_{0} - t_{-1}.
</math></center>

====Measuring Processing Latency====
The processing latency is defined as the amount of time that it takes for the computer to process the data after acquiring it, to when the application module output is changed. In [[#TimeLine|TimeLine]], this is the time from <math>t_{0}</math> to <math>t_{2}</math>. Processing latency is calculated using two timestamps saved with every block of data, <math>SourceTime</math> and <math>StimulusTime</math>. <math>SourceTime</math> is saved at <math>t_0</math>, immediately following data acquisition in the Source module, and <math>StimulusTime</math> is saved at <math>t_2</math> immediately following application presentation in the Application module. Therefore, processing latency for each block of data is calculated as the difference between time stamps:

<center><math>
\mathrm{Processing Latency} = \mathrm{StimulusTime} - \mathrm{SourceTime} = t_{2} - t_{0}.
</math></center>

====Measuring Application Output Latency====

There are many possible application output types, including visual (i.e., the computer screen), audio, or mechanical (e.g., a robotic arm). The core BCI2000 system primarily uses visual and audio output, and so the default testing system will focus on these.

Both visual and audio output can be measured using the g.TRIGbox signal conditioner, which accepts inputs from optical sensors, microphones, or any other input. The user sets a threshold for the input signals, and the g.TRIGbox outputs a digital pulse whenever this threshold is exceeded. This output is then recorded back into the amplifier system, so that the analysis program can measure the response times for each output.

We identify event <math>t_0</math> by a change in the data channel connected to the amplifier's digital output, and event <math>t_3</math> by a change in the data channel connected to the g.TRIGbox, and compute their difference. Also, both events are affected by Amplifier Latency in the same way, so we may ignore Amplifier Latency, and have
<center><math>\begin{matrix}
\mathrm{Output Latency} = t_{3} - t_{2} = (t_3-t_0)-(t_2-t_0) = (t_3-t_0)-\mathrm{ProcessingLatency}.
\end{matrix}</math></center>

====Measuring System Latency====
As defined above, System Latency is the sum of Amplifier Latency, Processing Latency, and Output Latency. It is important to realize that the system latency is dependent on the output modality used, i.e., the video system latency and the audio system latency will vary on the same system due to the differences in output latencies.
The system latency may be measured
#directly, by identifying <math>t_{-1}</math> as the beginning of a data block by its sample index, and <math>t_3</math> by the signal change in the channel connected to the g.TRIGbox, and then calculating <math>\textrm{SystemLatency}=t_3-t_{-1}</math>,
#or indirectly, by using the previously measured quantities <math>\textrm{SystemLatency}=\mathrm{AmplifierLatency}+\mathrm{ProcessingLatency}+\mathrm{OutputLatency}</math>.

====Measuring Block Duration====
Block Duration is measured as the time between adjacent blocks of data, divided by the theoretical ideal value, which is the sample block duration. For the actual measurement, we use the difference between subsequent <math>\textrm{SourceTime}</math> time stamps which are recorded at <math>t_0</math> and <math>t_8</math> in [[#TimeLine|Timeline]]:

<center><math>
\mathrm{BlockDuration} = \frac{t_{5} - t_{0}}{\mathrm{SampleBlockSize}/\mathrm{SamplingRate}}
=\frac{\Delta \mathrm{SourceTime}}{\mathrm{SampleBlockSize}/\mathrm{SamplingRate}}
</math></center>

===Latency Calculation Overview===
Latencies are calculated by comparing changes in a BCI2000 state value to changes in a recorded signal. The analysis program follows these general steps in calculating the various latencies:

#Determine which threshold values to use based on the ''thresh'' definition in the BCI2000Certification.cfg file, which defines a threshold based on the amplifier used. For example, the g.USBamp has an input range of -250 mV to + 250 mV, and the g.TRIGbox outputs from 0 to 200 mV, so the threshold used is about 12.5 mV.
#Traverse the state values for a selected state and find where the state changes from 0 to a given value (or any value). The sample at which this occurs is saved for later use in <math>stateChangePos</math>.
#When this occurs, start looking through <math>Signal_{norm}</math> to find when a rising edge exceeds the determined threshold value. The sample at which this occurs is saved in <math>sigChangePos</math>.
#The latency for the <math>n</math>th state change is calculated as:
#:<center><math>\begin{matrix}
latency_n = \frac{sigChangePos_n-stateChangePos_n}{SampleRate}
\end{matrix}</math></center>
#:and is stored in an array.
#Once the entire state vector is traversed, the mean, standard deviation, minimum and maximum values for this latency are calculated and reported.

==Getting Started With the Default Tests==
This section provides step-by-step instructions on running the default certification procedure. Note that some cables must be assembled before the testing can be done; see the end of this document for information on assembling the cables.

===Starting the Procedure===
The BCI2000 certification procedure uses different combinations of BCI2000 parameter fragments to control the tests. While it is possible to edit these by hand, in most circumstances it is simpler to use the graphical user interface provided. To do so, navigate to the BCI2000/tools/BCI2000Certification folder, and start the BCI2000Certification.exe program. This program appears as:

[[image:Certificationtool.png|frame|none|The BCI2000Certification user interface.]]

This program shows a list of all of the procedures to be tested for the loaded configuration. Detailed instructions for using the interface follow.

====Load a Configuration File====
To get started, load a provided configuration file by selecting File->Open INI. The standard configurations are for 8, 16, and 32 channels, and are located in the BCI2000/tools/BCI2000Certification/ folder. These are named BCI2000Certification_32ch_100ms.ini, BCI2000Certification_16ch_100ms.ini, and BCI2000Certification_8ch_100ms.ini, respectively.

====Sampling Rate====
This is set to 512 by default. This can be changed to another value that will apply to all tests, except those that explicitly override it in their own parameter file.

====Display parameters====
These are on the lines that begin with <code>Application:Window</code>. For many labs, the default settings should work fine; the window is setup to appear in the top-left corner of the main window (<code>WindowLeft= 0</code> & <code>WindowTop= 0</code> ), and is 800 wide by 800 pixels tall (<code>WindowWidth= 800</code> & <code>WindowHeight= 800</code> ).

Users with a dual-screen configuration may wish to change this so that the BCI2000 window is on the secondary monitor; to do so, the <code>WindowLeft</code> parameter should be changed, which depends on the resolution and orientation of both monitors. For example, if the 2nd monitor is to the right of the primary monitor, and both monitors have a resolution of 1280x1024 pixels, setting <code>WindowLeft</code> to <code>1280</code> will place the window on the 2nd monitor. Similarly, if the 2nd monitor is to the left of the primary monitor, setting <code>WindowLeft</code> to <code>-1280</code> will accomplish the same thing. If the monitors have different resolutions (e.g., monitor 1 is 1600x1200 and monitor 2 is 1024x768, located to the right of the 1st monitor), the position should change accordingly. For example, in this scenario, to set the window to the right of the main window, set <code>WindowLeft</code> to <code>1600</code> . Finally, set the <code>WindowWidth</code> & <code>WindowHeight</code> to appropriate values for full-screen, if desired. To summarize, for the dual-screen case in which monitor 1 is 1600x1200 pixels, and monitor 2, to the right of 1, is 1024x768 pixels, and the BCI2000 window should be full-screen on monitor 2, the parameters should look like:

<code>Application:Window int WindowWidth= 1024 ... 
Application:Window int WindowHeight= 768 ... 
Application:Window int WindowLeft= 1600 ... 
Application:Window int WindowTop= 0 ... 
</code>
Note that nothing following the ... needs to be changed above in the parameter file.

===Connect the Amplifier to the Trigger Box, and Attach Sensors===
[[Image:connections.png|frame|none|Connections overview]]

This section describes the steps for connecting the necessary hardware. Refer to the Connections Overview figure above for additional information; each step is numbered in this figure.

#Connect the amplifier to the computer; the supported g.tec amps are connected via USB, RS232, or Bluetooth.
#Connect the Digital I/O cable (see bottom of this document) to the amplifier on the Digital I/O port.
#Connect the reference and ground wires from the assembled amplifier cables to the amplifier reference and ground connections.
#Connect the amplifier cables with the safety connectors into channels 1, 2, and 3 on the g.USBamp.
#Connect the digital output line to the channel 1 amplifier cable.
#Connect the A output from the trigger box to the channel 2 amplifier cable.
#Connect the B output from the trigger box to the channel 3 amplifier cable.
#Connect the optical sensor plug to the g.TRIGbox, using the optical sensor input channel A.
#Connect the computer audio output using a stereo cable to the g.TRIGbox, using the high-level input channel B.

===Setup Sensor Thresholds===
The audio and optical sensors each have a threshold setting on the g.TRIGbox, along with an LED indicating whether the current input is above threshold for each channel. At rest, each trigger should be off; if any is on, turn the threshold knob counter-clockwise until the LED is off.

====Audio Threshold====
To set the audio threshold, set audio volume on the computer to maximum. On Windows, to make this process easier in the future, go to the Start menu, click the Control Panel, and go to Sounds. In the Sound window, click the box that puts the volume icon in the task bar. A small speaker should now appear in the bottom-right of the screen in the task bar. Click this icon, and slide the volume up to the max; when you click on this slider, Windows emits a short beep to give an idea of the volume level, which can be used to set the threshold. To do so, make sure that the stereo audio cable is plugged into the g.TRIGbox, and click the slider to emit a sound, checking that the green LED is flashing when you click the slider. If it is not, turn the threshold knob for channel B counter-clockwise, and click the slider again. If it is still not working after several tries, unplug the audio cable from the computer, and check that you can hear the beep through the speakers. If you cannot, make sure that the sound is not muted, and that the sound drivers are properly installed. If you can hear it, plug the audio cable back into the computer audio output (NOT the microphone input), and make sure the g.TRIGbox has power; the light next to the power switch should flash momentarily if the battery levels are OK. You can also use a wall power source (see the g.TRIGbox manual for more information). The threshold is set correctly when the channel B LED is off at rest, and is on when a sound is played.

====Video Threshold====
To set the video threshold, first tape the optical sensor to the monitor in approximately the correct location, based on the information in the latencyTest.prm file for the window position and dimensions. To activate the optical trigger on the g.TRIGbox, drag a white window, such as a Notepad window, in the background under the sensor. Move the threshold knob for channel A until the LED for that channel is just on (i.e., turning it down just a little turns the trigger off). The sensor will be placed more accurately in the following step.

===Starting the Software===
Navigate to BCI2000/tools/BCI2000Certification, and double-click the BCI2000Certification.exe program. The BCI2000 program should start, with the output window in the location specified in the latencyTest.prm file. If there are any errors at startup, the BCI2000 error log will report them. If there are errors, correct them, exit out of the BCI2000Certification.exe program, and restart the program.

===Setting up the Optical Sensor===
Each application has a unique display configuration, where the visual target of interest is located in a specific position on the monitor. Generally, the optical sensor will not likely have to be moved far in between tasks due to the design of the parameter files. However, it is still necessary to ensure that the sensor is in the correct position for each task, and to be able to change the position if necessary. This section describes the process to find the correct location on the monitor for the sensor. To begin, the certification procedure should be started.

====P3Speller====
The P3Speller task has an group of letters arranged into rows and columns. The analysis uses the letter in the 3rd column and 3rd row, which will contain the letter X when the program is run. This location should be very close to that specified for the CursorTask, described above. Fortunately, the arrangement of the letters is shown before the test starts, which allows the sensor to be adjusted if necessary. All of the following default tasks are setup so that the optical sensor does not need to be moved from this position.

====CursorTask====
In the default configuration, the optical sensory does not need to be moved from the position used for the P3Speller task. For custom tests, the flashing object must either be placed under the sensor, or the sensor needs to be moved to the correct position.

====StimulusPresentation====
For the StimulusPresentation tasks, a single large icon appears in the center of the screen, which will be detected by the sensor. The default location of the sensor as defined for the CursorTask should be able to capture the icon on the screen. However, if the task begins and it appears that it is outside the icon location, move the sensor to the middle of the icon. Keep in mind that it may have to be relocated for following tasks.

===Running the Tests===
Once the optical sensor is setup and calibrated for a task, begin the testing process. To start the process, press the Start button in the BCI2000 operator window. At the end of each task, the program will quit automatically, and the next one will start automatically. For each task, press the Start button to begin.

Occasionally, the optical sensor may not be in the exact correct place for a given task.You should be able to see changes in on the video channel (channel 2 by default) in the window showing the recorded channels. If the signal is not changing when it should be (e.g., during the correct visual stimulus), you may try increasing the threshold to catch the stimulus, or you may need to place the sensor in the correct location. To do this, place the sensor in the better location, then quit the current BCI2000 test, and quit the BCI2000Certification program. The procedure will need to be restarted.

When the testing is complete, the BCI2000CertAnalysis program will automatically start. It will analyze the data that have been collected, and return the results in the results.txt file. In general, a Pass or Fail will be written next to a task, and each task component, if it passed or failed the test. For more information on interpreting results, see below.

==BCI2000Certification: Additional Information==
The previous section on Getting Started provided information to quickly setup and run the default tests. This section provides detailed information about each file used, and how to modify the files for your specific system and applications.

===Overview of Important Files===
There are several important files that are used in the BCI2000 Certification procedure. These files and their contents are described in this section.

====BCI2000Certification.ini====
The BCI2000Certification.ini file contains the information that defines each task configuration. It is located in the BCI2000/tools/BCI2000Certification/ folder. It specifies the parameter file, the SignalSource, SignalProcessing, and Application modules, and the analysis definitions for each task. It contains all of the default tests, although it can easily be expanded to include additional or customized task configurations.

Each task is defined by a set of '''case-insensitive''' , space-separated fields, as described below. A * indicates an optional field. The % character indicates a comment, and everything following that character is ignored.

*'''name''' The name of the task, which should be unique. This generally describes the task. It must not contain any spaces. This value determines the path to the saved data file, and the name of the file itself. For example, the name StimulusPresentation_512 would create a file at <code>./Data/StimulusPresentation_512001/StimulusPresentation_512S001R01.dat</code> Example:
**<code>name StimulusPresentation_512</code>

*'''parm'''The BCI2000 *.prm file used for this task. It should be placed in the BCI2000/tools/BCI2000Certification/parms/ folder. Note that the CertificationMain.prm is included in ''all'' configurations by default, and does not need to be listed here. This file contains the information for this specific task configuration. See above for further information.
**<code>parm SimpleAV.prm</code>

*'''source''' The SignalSource module to be used for this test. The g.tec g.USBamp system is used in all configurations by default. If the g.MOBIlab or g.MOBIlab+ are used, the SignalSource module should be changed to the appropriate executable. All BCI2000 executables are located in BCI2000/prog/. Examples:
**<code>'source gUSBampSource.exe'''</code>
**<code>source gMOBIlabSource.exe</code>

*'''sigproc''' The SignalProcessing module that is used for this configuration. This is likely dependent on the application used as well. This program should be located in BCI2000/prog/. Example:
**<code>sigproc P3SignalProcessing.exe</code>

*'''app''' The application for this configuration. This program should be located in BCI2000/prog/. Example:
**<code>app StimulusPresentation.exe</code>

*'''*amp''' This is a single value that gives the channel that is used to compute the amplifier latency. Example:
**<code>amp 0</code>

*'''*dAmp''' This is a single value that specifies a digital input channel that is used to compute the amplifier latency. Example:
**<code>dAmp 15</code>

*'''*vid''' This field is followed by 3 values, that give the channel number that is recording the video output, and the state name and state value to use as a trigger for the comparison. See the example entry for more information. Example:
**<code>vid 1 StimulusCode 1</code>

*'''*aud''' This field is followed by 3 values, that give the channel number that is recording the audio output, and the state name and state value to use as a trigger for the comparison. See the example entry for more information. Example:
**<code>aud 1 StimulusCode 1</code>

*'''skip''' Entering '''skip''' will cause this task to not be run or analyzed. This is used to reduce the number of tasks that are run, which helps to repeat individual tasks that may have had problems in previous sessions.

*'''end''' This must come at the end of each task definition.

In addition to task-specific entries, there are several global entries that will apply to every task, unless explicitly overwritten in that task. This allows the user to quickly change settings for all tasks simultaneously, e.g., if tests will be run using a g.tec g.USBamp for one set of tests, and a g.tec g.MOBIlab for another. Global entries must be defined at the beginning of the BCI2000Certification.ini file outside of the task definitions. These entries are defined as:

*'''source''' The SourceModule to be used for all tests, unless explicitly overwritten by an individual task. Otherwise identical to the '''source''' definition in a task entry.
*'''export''' This entry does not use any other parameters on the line on which it is defined. If '''export''' is present in the BCI2000Certification.ini file, test results will be written to a comma-separated-value (CSV) text file that is located in the folder where data is saved for each task. For example, if the data folder is BCI2000/tools/BCI2000Certification/latencyData/, then the export file for the SimpleTarget task will be placed in the folder BCI2000/tools/BCI2000Certification/latencyData/SimpleTarget.

Here is a full example entry that includes two tasks.

<pre>
source gUSBampSource
export

name StimulusPresentation_512
parm StimulusPresentation_512.prm
sigproc P3SignalProcessing
app StimulusPresentation
amp 0
dAmp 15
vid 1 StimulusCode 3
aud 2 StimulusCode 3
end

name CursorTask_1200
parm CursorTask_1200.prm
source gMOBIlab
sigproc ARSignalProcessing
app CursorTask
amp 0
dAmp 15
vid 1 TargetCode 1
end
</pre>

The <code>StimulusPresentation</code> task uses the <code>gUSBampSource</code> source module, and records block-triggered digital outputs on channel 0, video output triggered off of stimulus code 3 on channel 1, and audio output triggered off of stimulus code 3 on channel 2. The <code>SimpleTarget</code> tasks overrides the global <code>source</code> entry, and uses its own <code>source</code> definition, specifying that a gMOBIlab should be used for acquisition instead of a gUSBamp. Finally, the <code>export</code> entry is set at the beginning, so test results for all files are output to a CSV file.

The BCI2000Certification.ini file contains many task definitions. Each entry is read by the BCI2000Certification.exe program, and is entered as a separate task to be run and then analyzed.

====BCI2000Certification.cfg====
The latencyTest.prm file is located in the BCI2000/tools/BCI2000Certification/ folder. It contains many default settings and definitions that determine how the results are interpreted, and should generally not be changed by the user. The timing definitions provide the absolute maximum latencies in ms for each step in the system chain, and include the Amp, ProcLat, VidOut, AudOut, VidSys, AudSys, and Jitter (see below for explanations). Timing definitions can include either one or two fields; the first field is mandatory, and is the mean value in ms, while the second field is optional, and is the standard deviation in ms.

*'''Amp''' The amplifier latency.
*'''ProcLat''' The processing latency.
*'''VidOut''' The video output latency.
*'''AudOut''' The audio output latency.
*'''VidSys''' The video system latency.
*'''AudSys''' The audio system latency.
*'''Jitter''' The system jitter. This is the difference, in ms, between the actual block duration and theoretical block duration, which is determined by the block size.
*'''Threshold Source Value''' This is the threshold defined for a specific SignalSource module. Individual amplifiers may have different input ranges, resulting in recording signals with different ranges of magnitude. The '''Source''' entry is a value in mV. For example, the threshold setting for the g.USBamp is '''Threshold gUSBampSource 12.5''' .
*'''ResultOut''' This is the file that contains the testing results.
*'''DataDir''' The default data directory. It defaults to latencyData in the BCI2000/tools/BCI2000Certification/ folder.

These values should not generally be changed by the user, although they may be updated in future BCI2000 versions.

====CertificationMain.prm====
This parameter file contains some of the default task parameters common to every test, including the save location, monitor configuration, sampling rate, and visualization settings. Note that these parameters can be overwritten in the *.prm files for each individual test configuration.

====BCI2000Certification.exe====
This file controls the execution of each task. It parses the BCI2000Certification.ini and BCI2000Certification.cfg files to determine which files and tasks to run, and controls the CPU load monitor. When all tasks are complete, this program calls the BCI2000Analysis.exe program to handle the analysis of the collected data.

====BCI2000CertAnalysis.exe====
This program analyzes the data collected, and reports results to a data file. It uses the DataDir parameter in the BCI2000Certification.cfg file to determine where the data is located. Results are output to results.txt in the BCI2000/tools/BCI2000Certification/ folder.

====Parameter Files====
Each task should have it's own parameter file that contains the unique configuration and settings for that task. For example, there may be several configurations that use the g.USBamp, ARSignalProcessing, and CursorTask, each with its own parameter file. These files end in .prm, and are placed in the BCI2000/tools/BCI2000Certification/parms/ folder.

===Interpreting Results===
Results are recorded to the BCI2000/tools/BCI2000Certification/results.txt file. The results for each task, and each applicable latency tested, are reported here. If the entire task passed, then each test performed met the minimum timing requirements specified in the BCI2000Certification.cfg file. If one or more did not pass, then the specific test that did not pass the test has Fail written next to it.

====What if a Task Did Not Pass?====
TO BE ADDED.

==Certification Protocol==
This section describes how the testing protocol is run, the various components involved in the certification analysis, and how to interpret results.

===Running the Tests===
The certification protocol consists of running several BCI2000 applications in multiple configurations to determine if each application meets the minimum requirements for BCI2000, and to determine if individual configurations of an application meet the requirements. For example, the CursorFeedback task may be tested with several combinations of sampling rates, sample block sizes, and processed channels, only some of which may work with a given computer setup.

The testing set is run from a single batch file called LatencyAnalysis.bat. This file is located in the folder BCI2000/tools/BCI2000Certification/batch. This batch file executes additional batch files in this folder, each corresponding to a different application configuration. Each of these batch files starts the Operator module, automatically loading multiple parameter files used for a given configuration. There is a general-purpose parameter file called latencyTest.prm that all configurations use. This file configures the save location for all latency tests, as well as default window positions and sampling rates. A second parameter file is passed to the operator that contains the parameters for a unique application configuration. After starting the operator module, the batch file starts the SignalSource module, SignalProcessing module, and Application module. The loaded configuration is set automatically, and the user needs only to press the start button to start the analysis.

==Software Templates==
This describes how to implement the testing protocols for your own amplifier system and custom applications. This is useful for determining if your hardware setup and software is capable of maintaining an acceptable level of performance for real-time testing.

===Amplifier Latency===
The amplifier latency requires an output that can be recorded by the amplifier. In the case of the g.USBamp, a digital output line is used, although either analog or digital outputs could be used in a system.

In the SignalSource module code for your custom amp, find the Process function. Near the beginning of this function, before any data is acquired, set the output signal to 0, either a digital low or analog value of 0 V. This will be dependent on the particular amplifier and API used; for the g.USBamp, this function call looks like:
 <code>
GT_SetDigitalOut ( m_hdev.at(0), (UCHAR)1, (UCHAR)0);
</code> 

This sets the digital output 1 on device 0 to a value of 0.

At the end of the Process function, the output should be set to a high level. A similar function call will be used to above, only the value is 1 instead of 0; again, the function will be dependent on the system used, and whether analog or digital output is used. Here is the code for the g.USBamp:
 <code>
GT_SetDigitalOut ( m_hdev.at(0), (UCHAR)1, (UCHAR)1);
</code> 

This sets the digital output 1 on device 0 to a value of 1.

===Visual and Audio Latency===
Developing new video and optical latency tests does not necessarily require adding additional code to existing modules (beyond any customization already done).

==Supported Hardware==
A list of officially supported hardware configurations, and suggested minimum requirements is provided.

===Supported and Tested Hardware===
====Amplifiers====

*g.USBamp
*gMOBIlab (Serial RS232)
*gMOBIlab (Bluetooth)
*TDT Pentusa (RX5)

===Minimum Requirements===
This table shows the minimum requirements for running BCI2000.

{| border="1"
|+ Minimum System Requirements for BCI2000
! CPU
| 1 GHz
|-
! RAM
|512 MB (dependent on OS; 1 GB for Windows Vista)
|-
! Video Card
|32 MB VRam; Hardware OpenGL Support
|-
! Sound Card
|
|-
! Monitor
|
|-
! OS
|Windows 2000; Windows XP SP2 or Greater; Windows Vista
|}

===Voltage Divider & Amplifier Input===
Parts List:

*4 Male Mono Audio Connectors
*6 12in Safety Connector Wires (to USB amplifier input), different colors
*4 3in Wires
*Soldering Iron and Solder
*resistors for voltage dividers
This section describes how to assemble cables that connect the output of the g.TRIGbox to the amplifier input channels.

Strip the free ends of all 6 safety connector wires, about <math>\frac{1}{4}</math> in. If you are not using voltage dividers, solder 4 of the wires directly to the center signal connection on the 4 mono audio connectors. Cover the connection.

[[Image:ampPlug_1.png|frame|none|g.USBamp Amplifier Plug]]

Next, twist the two remaining safety connector wire ends together, and solder them together. Solder the 4 short wires to the ground connections on the mono plugs. Finally, solder the 4 ground wires to the two safety connector wires that were twisted together and soldered previously, as shown here.

[[Image:ampPlugs_2.png|frame|none|g.USBamp Amplifier Plugs]]

These plugs can plug directly into the g.TRIGbox outputs, and the safety connectors plug into the channels 1-4 inputs on the g.USBamp; the ground wires plug into the ground and reference on the g.USBamp.

===Digital I/O Cable===

Parts List:

*3 Colored Wires
*7-Pin Digital Connector from g.tec
*Soldering Iron and Solder
*Silicone or electrical tape for insulation
*1 Female Mono Audio Plug

In order to access the digital I/O pins on the g.USBamp, a connector needs to be assembled. The 7-pin digital I/O connector should be ordered through g.TEC, the manufacturer of the g.USBamp.

At least three wires are needed for the circuit, which connect to the digital output 1 pin, the digital input 0 pin, and the ground pin.
[[Image:DigIO.png|frame|none|g.USBamp Digital I/O Pins]]

To start, cut three 10 in wires, preferably with different colors to differentiate between the signal and ground wires. Cut back a small portion of the ground wire, and solder it to the center ground pin on the connector. Now, find the top of the connector by locating the small plastic notch, and locate pins 3 and 4 relative to the notch. Solder one wire to pin 3, and the remaining wire to pin 4. It may be helpful to insulate the wires from the casing using either a piece of black electrical tape, or an insulating gel, like silicone. If a gel is used, be sure to let it set for several hours or overnight. It is also probably a good idea to check the electrical connection with a multimeter prior to insulating.

[[Image:digConnector.png|frame|none|g.USBamp Digital I/O Pins]]

Next, attach the rubber sleeve over the end of the part with the female threads, as shown in the panel. Slide the smaller metal sleeve over the wires, then slide the larger rubber sleeve over the wires.

For the next step, attach the two metallic pieces that surround the cables, shown laying to the sides below. One of the metal pieces has a small groove in it, which should be placed over the notch on the connector; the other metal piece fits on the opposite side of the connector. Push the small metal sleeve up to the side piece with the groove, and rotate the sleeve until the notch fits in the groove.

Place the end piece over the connector, with the red dot on top and aligned with the connector notch. Finally, slide the rubber sleeve over the connector, and screw the sleeve into the end piece.

[[Image:finalDigCable.png|frame|none|g.USBamp Digital I/O Cable]]

The plug is assembled next. Solder the signal wire from Pin 3 (Digital Out 1) on the digital I/O connector to the signal connector on the female mono plug, and solder the ground wire to the outer ground connector on the plug. The below figure shows this; in this figure, the red wire is the signal wire, and the brown wire is the ground.

[[Image:digPlug.png|frame|none|g.USBamp Digital Wire Plug]]

User Reference:BCI2000Certification

2009-05-27T18:58:03Z

Awilson: /* Getting Started With the Default Tests */

==Introduction==
BCI2000 v2.0 and higher includes a certification procedure that can determine whether a computer system is capable of running all or some BCI2000 applications. Because BCI2000 does not have a standardized hardware configuration, i.e., it can run on potentially ''any'' PC, this testing procedure is capable of running on any PC with BCI2000, with the results reporting which standard BCI2000 applications meet the minimum timing requirements. Different configurations are included in the certification procedure to test a range of likely setups for a given application, in which timing characteristics such as the sampling rate, inter-stimulus intervals, and stimulus duration, and other parameters, such as the number and size of the stimuli, are changed for each configuration.

This document serves as the instruction manual for using the certification procedure, and describes how the procedure works to determine the timing characteristics of the BCI2000 system. The primary use for the certification procedure is to determine if the PC configuration used with BCI2000 is capable of running the core BCI2000 system, which is comprised of:

*Support for the the g.tec series of amplifiers, including the g.USBamp, g.MOBIlab, and the g.MOBIlab+ (bluetooth) amplifiers.
*The AR, P3, FFT, and Matlab signal processing modules.
*The CursorTask, P3Speller, and StimulusPresentation application modules.

Additionally, due to the extensibility of BCI2000, researchers who develop custom algorithms and applications, or use amplifiers not made by g.tec, can use the certification procedure to determine whether their custom modules are capable of running on a particular PC configuration.

The certification procedure works by comparing the differences in time of when BCI2000 ''expects'' an event to occur to when that event ''actually'' occurred. These events include a change in the display, an audio output through the system speakers, or an EEG sample being stored in the amplifier buffer. The times at which such events occur are recorded with the amplifier and stored in a data file. Changes in the display are found using an optical sensor in combination with the g.TRIGbox. The g.TRIGbox is a signal conditioner that generates trigger pulses for various sensors or input signals. When the sensor exceeds a threshold, the g.TRIGbox outputs a digital signal which is recorded on the amplifier. A similar procedure is used for audio detection: the sound output from the PC is input to the g.TRIGbox, and when the volume exceeds threshold, a high digital signal is output and recorded by the amplifier. This information can be used because BCI2000 stores a time-stamp for every event during an experiment. The difference between a time-stamp value and the time that the recorded event changes values are compared to find the latency for that particular event.

These latencies can be affected by many external influences, including hardware deficiencies (such as low RAM, slow CPU speed, or a video card of low quality), and other software running in the background while the experiment is being run.

==Latencies==
Briefly, the different latencies inherent in the BCI2000 system include amplifier latency, processing latency, output latency, and the sum of these, the system latency. Additionally, the block duration jitter will be measured. The figure below provides a timeline of events that occur within a single block of data, with significant time points labeled. This figure provides an accurate account of the order in which events occur within a block of data, although the time intervals are not necessarily to scale.


[[Image:timeline3.png|frame|none|Timeline of events. Time intervals are not to scale.]]

===Defining Latencies===
====Amplifier Latency====
Amplifier Latency is the minimum delay between the time that a signal is presented at the amplifier input, to when it has been acquired in the source module. Depending on configuration, this may comprise physical signal delay in the amplifier, digitization, transmission from the amplifier to the PC, and processing time inside a hardware driver. That minimum delay occurs for the last sample of a data block, which, unlike its preceding samples in the same block, will spend only a minimum time in hardware and software buffers. In [[#TimeLine|Timeline]],

Amplifier latency = <math>t_{0}-t_{-1}</math>.

For amplifiers connected via bandwidth-limited serial interfaces, transmission latency may have a measurable impact on amplifier latency, depending on the hardware. When using USB 2.0, as is the case for the g.USBamp, transmission latency may generally neglected, as illustrated by the following example: USB 2.0 has a maximum transmission rate of 480 Mbit/s. If we are acquiring 16 channels of 32-bit data, and transmitting in blocks of 16 samples, this is 8192 bits of data; at USB 2.0 speed, this should take roughly 17 <math>\mu</math>s to transfer. However, a more realistic approximation for USB 2.0 speeds is 240 Mbit/s, which increases the transfer delay to 34 <math>\mu</math>s. For sampling rates below 30 kHz, this is less than a single sample's duration.

In addition to amplifier latency, system performance will be influenced by buffering latency. Buffering latency is dependent on the sample block buffer size: When a data sample is digitized, it is not immediately transferred to the PC, but is stored in memory on the amplifier. The PC then makes the appropriate request to the amplifier, and a block of data is transferred all at once to reduce the processing load. This implies that a signal that is digitized at the start of the buffer must wait until the buffer is full to be read into the PC. For example, if the sample block size is 16 samples, the first sample must wait 15 more samples before it can be used in the application. Fortunately, this latency is always known, and can be reduced with a higher sampling rate and/or smaller block sizes, assuming the PC can handle the increased overhead. Buffering latency does not affect the acquisition-to-display latency, because processing occurs immediately after a block's last sample, which is not affected. Still, it is an important factor to keep in mind, because a large sample block size and/or a small sample rate will decrease the refresh rate for the application (e.g., at a sample rate of 256 Hz and a sample block size of 128 samples, the application will only be refreshed every 0.5 s.)

====Processing Latency====
Processing Latency is the total time it takes for the data to be processed by all BCI2000 modules (SignalSource, SignalProcessing, and Application).

Processing latency = <math>t_{2}-t_{0}</math>.

Processing latency strongly depends on CPU speed, and if this latency becomes too large, high CPU load will probably be the cause, implying decreased or unsuitable BCI2000 performance.

====Output Latency====
Output Latency is the latency from the time that the Application module issues a command to change the display or issue a sound (or another output), to the time that this output actually occurs.

Output latency = <math>t_{3}-t_{2}</math>.

====System Latency====
System Latency is the minimum time interval between a change in amplifier input, and a causally related change in application output. This is the sum of the above latencies, Amplifier, Processing, and Output.

System latency = <math>t_{3} - t_{-1}</math>.

====Block Duration, Block Duration Jitter====
Block Duration is the time interval between adjacent blocks of data, normalized to the ideal duration of a data block as determined from sampling rate and sample block size:

Block Duration = <math>\frac{t_{5}-t_{0}}{\mathrm{SampleBlockSize}/\mathrm{SamplingRate}}</math>.

When the system operates in real time, mean Block Duration will always be 1. Measuring Block Duration has the purpose of obtaining Block Duration Jitter as its standard deviation.

===Measuring Latencies===
The procedure for measuring the system latencies are below. In general, a combination of recorded events and software time-stamps recorded in BCI2000 data files to determine when important events occur, with ms or better time resolution.
[[Image:OutTimeline1.png|thumb|500px|none|Recorded events used for measuring latencies.]]

====Measuring Amplifier Latency====
In [[#TimeLine|TimeLine]], Amplifier Latency is the time interval between the sampling of a data block's last sample, and its acquisition into the source module's data buffer:
<center><math>
\mathrm{AmplifierLatency} = t_{0} - t_{-1}
</math></center>

To measure this latency, the Source module will set a digital output on the amplifier to a high value at time <math>t_0</math> immediately following data acquisition, as indicated in [[#overview|Overview]]. The digital output level is 3.3 V, so a voltage divider may required to attenuate the signal level to the range of amplifier input. This signal is then recorded on an input channel on the amplifier (time <math>t_{1}</math>).

In the recorded data, we may then identify <math>t_{-1}</math>, which is the beginning of sample block <math>n</math>, by its sample offset, which also coincides with BCI2000 state changes. <math>t_1</math> may be identified by a change in the recorded signal, occurring in the channel that was connected to the digital output during measurement.
<center><math>
\mathrm{AmplifierLatency} \approx t_{0} - t_{-1}.
</math></center>

====Measuring Processing Latency====
The processing latency is defined as the amount of time that it takes for the computer to process the data after acquiring it, to when the application module output is changed. In [[#TimeLine|TimeLine]], this is the time from <math>t_{0}</math> to <math>t_{2}</math>. Processing latency is calculated using two timestamps saved with every block of data, <math>SourceTime</math> and <math>StimulusTime</math>. <math>SourceTime</math> is saved at <math>t_0</math>, immediately following data acquisition in the Source module, and <math>StimulusTime</math> is saved at <math>t_2</math> immediately following application presentation in the Application module. Therefore, processing latency for each block of data is calculated as the difference between time stamps:

<center><math>
\mathrm{Processing Latency} = \mathrm{StimulusTime} - \mathrm{SourceTime} = t_{2} - t_{0}.
</math></center>

====Measuring Application Output Latency====

There are many possible application output types, including visual (i.e., the computer screen), audio, or mechanical (e.g., a robotic arm). The core BCI2000 system primarily uses visual and audio output, and so the default testing system will focus on these.

Both visual and audio output can be measured using the g.TRIGbox signal conditioner, which accepts inputs from optical sensors, microphones, or any other input. The user sets a threshold for the input signals, and the g.TRIGbox outputs a digital pulse whenever this threshold is exceeded. This output is then recorded back into the amplifier system, so that the analysis program can measure the response times for each output.

We identify event <math>t_0</math> by a change in the data channel connected to the amplifier's digital output, and event <math>t_3</math> by a change in the data channel connected to the g.TRIGbox, and compute their difference. Also, both events are affected by Amplifier Latency in the same way, so we may ignore Amplifier Latency, and have
<center><math>\begin{matrix}
\mathrm{Output Latency} = t_{3} - t_{2} = (t_3-t_0)-(t_2-t_0) = (t_3-t_0)-\mathrm{ProcessingLatency}.
\end{matrix}</math></center>

====Measuring System Latency====
As defined above, System Latency is the sum of Amplifier Latency, Processing Latency, and Output Latency. It is important to realize that the system latency is dependent on the output modality used, i.e., the video system latency and the audio system latency will vary on the same system due to the differences in output latencies.
The system latency may be measured
#directly, by identifying <math>t_{-1}</math> as the beginning of a data block by its sample index, and <math>t_3</math> by the signal change in the channel connected to the g.TRIGbox, and then calculating <math>\textrm{SystemLatency}=t_3-t_{-1}</math>,
#or indirectly, by using the previously measured quantities <math>\textrm{SystemLatency}=\mathrm{AmplifierLatency}+\mathrm{ProcessingLatency}+\mathrm{OutputLatency}</math>.

====Measuring Block Duration====
Block Duration is measured as the time between adjacent blocks of data, divided by the theoretical ideal value, which is the sample block duration. For the actual measurement, we use the difference between subsequent <math>\textrm{SourceTime}</math> time stamps which are recorded at <math>t_0</math> and <math>t_8</math> in [[#TimeLine|Timeline]]:

<center><math>
\mathrm{BlockDuration} = \frac{t_{5} - t_{0}}{\mathrm{SampleBlockSize}/\mathrm{SamplingRate}}
=\frac{\Delta \mathrm{SourceTime}}{\mathrm{SampleBlockSize}/\mathrm{SamplingRate}}
</math></center>

===Latency Calculation Overview===
Latencies are calculated by comparing changes in a BCI2000 state value to changes in a recorded signal. The analysis program follows these general steps in calculating the various latencies:

#Determine which threshold values to use based on the ''thresh'' definition in the BCI2000Certification.cfg file, which defines a threshold based on the amplifier used. For example, the g.USBamp has an input range of -250 mV to + 250 mV, and the g.TRIGbox outputs from 0 to 200 mV, so the threshold used is about 12.5 mV.
#Traverse the state values for a selected state and find where the state changes from 0 to a given value (or any value). The sample at which this occurs is saved for later use in <math>stateChangePos</math>.
#When this occurs, start looking through <math>Signal_{norm}</math> to find when a rising edge exceeds the determined threshold value. The sample at which this occurs is saved in <math>sigChangePos</math>.
#The latency for the <math>n</math>th state change is calculated as:
#:<center><math>\begin{matrix}
latency_n = \frac{sigChangePos_n-stateChangePos_n}{SampleRate}
\end{matrix}</math></center>
#:and is stored in an array.
#Once the entire state vector is traversed, the mean, standard deviation, minimum and maximum values for this latency are calculated and reported.

==Getting Started With the Default Tests==
This section provides step-by-step instructions on running the default certification procedure. Note that some cables must be assembled before the testing can be done; see the end of this document for information on assembling the cables.

===Starting the Procedure===
The BCI2000 certification procedure uses different combinations of BCI2000 parameter fragments to control the tests. While it is possible to edit these by hand, in most circumstances it is simpler to use the graphical user interface provided. To do so, navigate to the BCI2000/tools/BCI2000Certification folder, and start the BCI2000Certification.exe program. This program appears as:

[[image:Certificationtool.png|frame|none|The BCI2000Certification user interface.]]

This program shows a list of all of the procedures to be tested for the loaded configuration. Detailed instructions for using the interface follow.

====Load a Configuration File====
To get started, load a provided configuration file by selecting File->Open INI. The standard configurations are for 8, 16, and 32 channels, and are located in the BCI2000/tools/BCI2000Certification/ folder. These are named BCI2000Certification_32ch_100ms.ini, BCI2000Certification_16ch_100ms.ini, and BCI2000Certification_8ch_100ms.ini, respectively.

====Sampling Rate====
This is set to 512 by default. This can be changed to another value that will apply to all tests, except those that explicitly override it in their own parameter file.

====Display parameters====
These are on the lines that begin with <code>Application:Window</code>. For many labs, the default settings should work fine; the window is setup to appear in the top-left corner of the main window (<code>WindowLeft= 0</code> & <code>WindowTop= 0</code> ), and is 800 wide by 800 pixels tall (<code>WindowWidth= 800</code> & <code>WindowHeight= 800</code> ).

Users with a dual-screen configuration may wish to change this so that the BCI2000 window is on the secondary monitor; to do so, the <code>WindowLeft</code> parameter should be changed, which depends on the resolution and orientation of both monitors. For example, if the 2nd monitor is to the right of the primary monitor, and both monitors have a resolution of 1280x1024 pixels, setting <code>WindowLeft</code> to <code>1280</code> will place the window on the 2nd monitor. Similarly, if the 2nd monitor is to the left of the primary monitor, setting <code>WindowLeft</code> to <code>-1280</code> will accomplish the same thing. If the monitors have different resolutions (e.g., monitor 1 is 1600x1200 and monitor 2 is 1024x768, located to the right of the 1st monitor), the position should change accordingly. For example, in this scenario, to set the window to the right of the main window, set <code>WindowLeft</code> to <code>1600</code> . Finally, set the <code>WindowWidth</code> & <code>WindowHeight</code> to appropriate values for full-screen, if desired. To summarize, for the dual-screen case in which monitor 1 is 1600x1200 pixels, and monitor 2, to the right of 1, is 1024x768 pixels, and the BCI2000 window should be full-screen on monitor 2, the parameters should look like:

<code>Application:Window int WindowWidth= 1024 ... 
Application:Window int WindowHeight= 768 ... 
Application:Window int WindowLeft= 1600 ... 
Application:Window int WindowTop= 0 ... 
</code>
Note that nothing following the ... needs to be changed above in the parameter file.

===Connect the Amplifier to the Trigger Box, and Attach Sensors===
[[Image:connections.png|frame|none|Connections overview]]

This section describes the steps for connecting the necessary hardware. Refer to the Connections Overview figure above for additional information; each step is numbered in this figure.

#Connect the amplifier to the computer; the supported g.tec amps are connected via USB, RS232, or Bluetooth.
#Connect the Digital I/O cable (see bottom of this document) to the amplifier on the Digital I/O port.
#Connect the reference and ground wires from the assembled amplifier cables to the amplifier reference and ground connections.
#Connect the amplifier cables with the safety connectors into channels 1, 2, and 3 on the g.USBamp.
#Connect the digital output line to the channel 1 amplifier cable.
#Connect the A output from the trigger box to the channel 2 amplifier cable.
#Connect the B output from the trigger box to the channel 3 amplifier cable.
#Connect the optical sensor plug to the g.TRIGbox, using the optical sensor input channel A.
#Connect the computer audio output using a stereo cable to the g.TRIGbox, using the high-level input channel B.

===Setup Sensor Thresholds===
The audio and optical sensors each have a threshold setting on the g.TRIGbox, along with an LED indicating whether the current input is above threshold for each channel. At rest, each trigger should be off; if any is on, turn the threshold knob counter-clockwise until the LED is off.

====Audio Threshold====
To set the audio threshold, set audio volume on the computer to maximum. On Windows, to make this process easier in the future, go to the Start menu, click the Control Panel, and go to Sounds. In the Sound window, click the box that puts the volume icon in the task bar. A small speaker should now appear in the bottom-right of the screen in the task bar. Click this icon, and slide the volume up to the max; when you click on this slider, Windows emits a short beep to give an idea of the volume level, which can be used to set the threshold. To do so, make sure that the stereo audio cable is plugged into the g.TRIGbox, and click the slider to emit a sound, checking that the green LED is flashing when you click the slider. If it is not, turn the threshold knob for channel B counter-clockwise, and click the slider again. If it is still not working after several tries, unplug the audio cable from the computer, and check that you can hear the beep through the speakers. If you cannot, make sure that the sound is not muted, and that the sound drivers are properly installed. If you can hear it, plug the audio cable back into the computer audio output (NOT the microphone input), and make sure the g.TRIGbox has power; the light next to the power switch should flash momentarily if the battery levels are OK. You can also use a wall power source (see the g.TRIGbox manual for more information). The threshold is set correctly when the channel B LED is off at rest, and is on when a sound is played.

====Video Threshold====
To set the video threshold, first tape the optical sensor to the monitor in approximately the correct location, based on the information in the latencyTest.prm file for the window position and dimensions. To activate the optical trigger on the g.TRIGbox, drag a white window, such as a Notepad window, in the background under the sensor. Move the threshold knob for channel A until the LED for that channel is just on (i.e., turning it down just a little turns the trigger off). The sensor will be placed more accurately in the following step.

===Starting the Software===
[[image:Certificationtool.png]]
Navigate to BCI2000/tools/BCI2000Certification, and double-click the BCI2000Certification.exe program. The BCI2000 program should start, with the output window in the location specified in the latencyTest.prm file. If there are any errors at startup, the BCI2000 error log will report them. If there are errors, correct them, exit out of the BCI2000Certification.exe program, and restart the program.

===Setting up the Optical Sensor===
Each application has a unique display configuration, where the visual target of interest is located in a specific position on the monitor. Generally, the optical sensor will not likely have to be moved far in between tasks due to the design of the parameter files. However, it is still necessary to ensure that the sensor is in the correct position for each task, and to be able to change the position if necessary. This section describes the process to find the correct location on the monitor for the sensor. To begin, the certification procedure should be started.

====P3Speller====
The P3Speller task has an group of letters arranged into rows and columns. The analysis uses the letter in the 3rd column and 3rd row, which will contain the letter X when the program is run. This location should be very close to that specified for the CursorTask, described above. Fortunately, the arrangement of the letters is shown before the test starts, which allows the sensor to be adjusted if necessary. All of the following default tasks are setup so that the optical sensor does not need to be moved from this position.

====CursorTask====
In the default configuration, the optical sensory does not need to be moved from the position used for the P3Speller task. For custom tests, the flashing object must either be placed under the sensor, or the sensor needs to be moved to the correct position.

====StimulusPresentation====
For the StimulusPresentation tasks, a single large icon appears in the center of the screen, which will be detected by the sensor. The default location of the sensor as defined for the CursorTask should be able to capture the icon on the screen. However, if the task begins and it appears that it is outside the icon location, move the sensor to the middle of the icon. Keep in mind that it may have to be relocated for following tasks.

===Running the Tests===
Once the optical sensor is setup and calibrated for a task, begin the testing process. To start the process, press the Start button in the BCI2000 operator window. At the end of each task, the program will quit automatically, and the next one will start automatically. For each task, press the Start button to begin.

Occasionally, the optical sensor may not be in the exact correct place for a given task.You should be able to see changes in on the video channel (channel 2 by default) in the window showing the recorded channels. If the signal is not changing when it should be (e.g., during the correct visual stimulus), you may try increasing the threshold to catch the stimulus, or you may need to place the sensor in the correct location. To do this, place the sensor in the better location, then quit the current BCI2000 test, and quit the BCI2000Certification program. The procedure will need to be restarted.

When the testing is complete, the BCI2000CertAnalysis program will automatically start. It will analyze the data that have been collected, and return the results in the results.txt file. In general, a Pass or Fail will be written next to a task, and each task component, if it passed or failed the test. For more information on interpreting results, see below.

==BCI2000Certification: Additional Information==
The previous section on Getting Started provided information to quickly setup and run the default tests. This section provides detailed information about each file used, and how to modify the files for your specific system and applications.

===Overview of Important Files===
There are several important files that are used in the BCI2000 Certification procedure. These files and their contents are described in this section.

====BCI2000Certification.ini====
The BCI2000Certification.ini file contains the information that defines each task configuration. It is located in the BCI2000/tools/BCI2000Certification/ folder. It specifies the parameter file, the SignalSource, SignalProcessing, and Application modules, and the analysis definitions for each task. It contains all of the default tests, although it can easily be expanded to include additional or customized task configurations.

Each task is defined by a set of '''case-insensitive''' , space-separated fields, as described below. A * indicates an optional field. The % character indicates a comment, and everything following that character is ignored.

*'''name''' The name of the task, which should be unique. This generally describes the task. It must not contain any spaces. This value determines the path to the saved data file, and the name of the file itself. For example, the name StimulusPresentation_512 would create a file at <code>./Data/StimulusPresentation_512001/StimulusPresentation_512S001R01.dat</code> Example:
**<code>name StimulusPresentation_512</code>

*'''parm'''The BCI2000 *.prm file used for this task. It should be placed in the BCI2000/tools/BCI2000Certification/parms/ folder. Note that the CertificationMain.prm is included in ''all'' configurations by default, and does not need to be listed here. This file contains the information for this specific task configuration. See above for further information.
**<code>parm SimpleAV.prm</code>

*'''source''' The SignalSource module to be used for this test. The g.tec g.USBamp system is used in all configurations by default. If the g.MOBIlab or g.MOBIlab+ are used, the SignalSource module should be changed to the appropriate executable. All BCI2000 executables are located in BCI2000/prog/. Examples:
**<code>'source gUSBampSource.exe'''</code>
**<code>source gMOBIlabSource.exe</code>

*'''sigproc''' The SignalProcessing module that is used for this configuration. This is likely dependent on the application used as well. This program should be located in BCI2000/prog/. Example:
**<code>sigproc P3SignalProcessing.exe</code>

*'''app''' The application for this configuration. This program should be located in BCI2000/prog/. Example:
**<code>app StimulusPresentation.exe</code>

*'''*amp''' This is a single value that gives the channel that is used to compute the amplifier latency. Example:
**<code>amp 0</code>

*'''*dAmp''' This is a single value that specifies a digital input channel that is used to compute the amplifier latency. Example:
**<code>dAmp 15</code>

*'''*vid''' This field is followed by 3 values, that give the channel number that is recording the video output, and the state name and state value to use as a trigger for the comparison. See the example entry for more information. Example:
**<code>vid 1 StimulusCode 1</code>

*'''*aud''' This field is followed by 3 values, that give the channel number that is recording the audio output, and the state name and state value to use as a trigger for the comparison. See the example entry for more information. Example:
**<code>aud 1 StimulusCode 1</code>

*'''skip''' Entering '''skip''' will cause this task to not be run or analyzed. This is used to reduce the number of tasks that are run, which helps to repeat individual tasks that may have had problems in previous sessions.

*'''end''' This must come at the end of each task definition.

In addition to task-specific entries, there are several global entries that will apply to every task, unless explicitly overwritten in that task. This allows the user to quickly change settings for all tasks simultaneously, e.g., if tests will be run using a g.tec g.USBamp for one set of tests, and a g.tec g.MOBIlab for another. Global entries must be defined at the beginning of the BCI2000Certification.ini file outside of the task definitions. These entries are defined as:

*'''source''' The SourceModule to be used for all tests, unless explicitly overwritten by an individual task. Otherwise identical to the '''source''' definition in a task entry.
*'''export''' This entry does not use any other parameters on the line on which it is defined. If '''export''' is present in the BCI2000Certification.ini file, test results will be written to a comma-separated-value (CSV) text file that is located in the folder where data is saved for each task. For example, if the data folder is BCI2000/tools/BCI2000Certification/latencyData/, then the export file for the SimpleTarget task will be placed in the folder BCI2000/tools/BCI2000Certification/latencyData/SimpleTarget.

Here is a full example entry that includes two tasks.

<pre>
source gUSBampSource
export

name StimulusPresentation_512
parm StimulusPresentation_512.prm
sigproc P3SignalProcessing
app StimulusPresentation
amp 0
dAmp 15
vid 1 StimulusCode 3
aud 2 StimulusCode 3
end

name CursorTask_1200
parm CursorTask_1200.prm
source gMOBIlab
sigproc ARSignalProcessing
app CursorTask
amp 0
dAmp 15
vid 1 TargetCode 1
end
</pre>

The <code>StimulusPresentation</code> task uses the <code>gUSBampSource</code> source module, and records block-triggered digital outputs on channel 0, video output triggered off of stimulus code 3 on channel 1, and audio output triggered off of stimulus code 3 on channel 2. The <code>SimpleTarget</code> tasks overrides the global <code>source</code> entry, and uses its own <code>source</code> definition, specifying that a gMOBIlab should be used for acquisition instead of a gUSBamp. Finally, the <code>export</code> entry is set at the beginning, so test results for all files are output to a CSV file.

The BCI2000Certification.ini file contains many task definitions. Each entry is read by the BCI2000Certification.exe program, and is entered as a separate task to be run and then analyzed.

====BCI2000Certification.cfg====
The latencyTest.prm file is located in the BCI2000/tools/BCI2000Certification/ folder. It contains many default settings and definitions that determine how the results are interpreted, and should generally not be changed by the user. The timing definitions provide the absolute maximum latencies in ms for each step in the system chain, and include the Amp, ProcLat, VidOut, AudOut, VidSys, AudSys, and Jitter (see below for explanations). Timing definitions can include either one or two fields; the first field is mandatory, and is the mean value in ms, while the second field is optional, and is the standard deviation in ms.

*'''Amp''' The amplifier latency.
*'''ProcLat''' The processing latency.
*'''VidOut''' The video output latency.
*'''AudOut''' The audio output latency.
*'''VidSys''' The video system latency.
*'''AudSys''' The audio system latency.
*'''Jitter''' The system jitter. This is the difference, in ms, between the actual block duration and theoretical block duration, which is determined by the block size.
*'''Threshold Source Value''' This is the threshold defined for a specific SignalSource module. Individual amplifiers may have different input ranges, resulting in recording signals with different ranges of magnitude. The '''Source''' entry is a value in mV. For example, the threshold setting for the g.USBamp is '''Threshold gUSBampSource 12.5''' .
*'''ResultOut''' This is the file that contains the testing results.
*'''DataDir''' The default data directory. It defaults to latencyData in the BCI2000/tools/BCI2000Certification/ folder.

These values should not generally be changed by the user, although they may be updated in future BCI2000 versions.

====CertificationMain.prm====
This parameter file contains some of the default task parameters common to every test, including the save location, monitor configuration, sampling rate, and visualization settings. Note that these parameters can be overwritten in the *.prm files for each individual test configuration.

====BCI2000Certification.exe====
This file controls the execution of each task. It parses the BCI2000Certification.ini and BCI2000Certification.cfg files to determine which files and tasks to run, and controls the CPU load monitor. When all tasks are complete, this program calls the BCI2000Analysis.exe program to handle the analysis of the collected data.

====BCI2000CertAnalysis.exe====
This program analyzes the data collected, and reports results to a data file. It uses the DataDir parameter in the BCI2000Certification.cfg file to determine where the data is located. Results are output to results.txt in the BCI2000/tools/BCI2000Certification/ folder.

====Parameter Files====
Each task should have it's own parameter file that contains the unique configuration and settings for that task. For example, there may be several configurations that use the g.USBamp, ARSignalProcessing, and CursorTask, each with its own parameter file. These files end in .prm, and are placed in the BCI2000/tools/BCI2000Certification/parms/ folder.

===Interpreting Results===
Results are recorded to the BCI2000/tools/BCI2000Certification/results.txt file. The results for each task, and each applicable latency tested, are reported here. If the entire task passed, then each test performed met the minimum timing requirements specified in the BCI2000Certification.cfg file. If one or more did not pass, then the specific test that did not pass the test has Fail written next to it.

====What if a Task Did Not Pass?====
TO BE ADDED.

==Certification Protocol==
This section describes how the testing protocol is run, the various components involved in the certification analysis, and how to interpret results.

===Running the Tests===
The certification protocol consists of running several BCI2000 applications in multiple configurations to determine if each application meets the minimum requirements for BCI2000, and to determine if individual configurations of an application meet the requirements. For example, the CursorFeedback task may be tested with several combinations of sampling rates, sample block sizes, and processed channels, only some of which may work with a given computer setup.

The testing set is run from a single batch file called LatencyAnalysis.bat. This file is located in the folder BCI2000/tools/BCI2000Certification/batch. This batch file executes additional batch files in this folder, each corresponding to a different application configuration. Each of these batch files starts the Operator module, automatically loading multiple parameter files used for a given configuration. There is a general-purpose parameter file called latencyTest.prm that all configurations use. This file configures the save location for all latency tests, as well as default window positions and sampling rates. A second parameter file is passed to the operator that contains the parameters for a unique application configuration. After starting the operator module, the batch file starts the SignalSource module, SignalProcessing module, and Application module. The loaded configuration is set automatically, and the user needs only to press the start button to start the analysis.

==Software Templates==
This describes how to implement the testing protocols for your own amplifier system and custom applications. This is useful for determining if your hardware setup and software is capable of maintaining an acceptable level of performance for real-time testing.

===Amplifier Latency===
The amplifier latency requires an output that can be recorded by the amplifier. In the case of the g.USBamp, a digital output line is used, although either analog or digital outputs could be used in a system.

In the SignalSource module code for your custom amp, find the Process function. Near the beginning of this function, before any data is acquired, set the output signal to 0, either a digital low or analog value of 0 V. This will be dependent on the particular amplifier and API used; for the g.USBamp, this function call looks like:
 <code>
GT_SetDigitalOut ( m_hdev.at(0), (UCHAR)1, (UCHAR)0);
</code> 

This sets the digital output 1 on device 0 to a value of 0.

At the end of the Process function, the output should be set to a high level. A similar function call will be used to above, only the value is 1 instead of 0; again, the function will be dependent on the system used, and whether analog or digital output is used. Here is the code for the g.USBamp:
 <code>
GT_SetDigitalOut ( m_hdev.at(0), (UCHAR)1, (UCHAR)1);
</code> 

This sets the digital output 1 on device 0 to a value of 1.

===Visual and Audio Latency===
Developing new video and optical latency tests does not necessarily require adding additional code to existing modules (beyond any customization already done).

==Supported Hardware==
A list of officially supported hardware configurations, and suggested minimum requirements is provided.

===Supported and Tested Hardware===
====Amplifiers====

*g.USBamp
*gMOBIlab (Serial RS232)
*gMOBIlab (Bluetooth)
*TDT Pentusa (RX5)

===Minimum Requirements===
This table shows the minimum requirements for running BCI2000.

{| border="1"
|+ Minimum System Requirements for BCI2000
! CPU
| 1 GHz
|-
! RAM
|512 MB (dependent on OS; 1 GB for Windows Vista)
|-
! Video Card
|32 MB VRam; Hardware OpenGL Support
|-
! Sound Card
|
|-
! Monitor
|
|-
! OS
|Windows 2000; Windows XP SP2 or Greater; Windows Vista
|}

===Voltage Divider & Amplifier Input===
Parts List:

*4 Male Mono Audio Connectors
*6 12in Safety Connector Wires (to USB amplifier input), different colors
*4 3in Wires
*Soldering Iron and Solder
*resistors for voltage dividers
This section describes how to assemble cables that connect the output of the g.TRIGbox to the amplifier input channels.

Strip the free ends of all 6 safety connector wires, about <math>\frac{1}{4}</math> in. If you are not using voltage dividers, solder 4 of the wires directly to the center signal connection on the 4 mono audio connectors. Cover the connection.

[[Image:ampPlug_1.png|frame|none|g.USBamp Amplifier Plug]]

Next, twist the two remaining safety connector wire ends together, and solder them together. Solder the 4 short wires to the ground connections on the mono plugs. Finally, solder the 4 ground wires to the two safety connector wires that were twisted together and soldered previously, as shown here.

[[Image:ampPlugs_2.png|frame|none|g.USBamp Amplifier Plugs]]

These plugs can plug directly into the g.TRIGbox outputs, and the safety connectors plug into the channels 1-4 inputs on the g.USBamp; the ground wires plug into the ground and reference on the g.USBamp.

===Digital I/O Cable===

Parts List:

*3 Colored Wires
*7-Pin Digital Connector from g.tec
*Soldering Iron and Solder
*Silicone or electrical tape for insulation
*1 Female Mono Audio Plug

In order to access the digital I/O pins on the g.USBamp, a connector needs to be assembled. The 7-pin digital I/O connector should be ordered through g.TEC, the manufacturer of the g.USBamp.

At least three wires are needed for the circuit, which connect to the digital output 1 pin, the digital input 0 pin, and the ground pin.
[[Image:DigIO.png|frame|none|g.USBamp Digital I/O Pins]]

To start, cut three 10 in wires, preferably with different colors to differentiate between the signal and ground wires. Cut back a small portion of the ground wire, and solder it to the center ground pin on the connector. Now, find the top of the connector by locating the small plastic notch, and locate pins 3 and 4 relative to the notch. Solder one wire to pin 3, and the remaining wire to pin 4. It may be helpful to insulate the wires from the casing using either a piece of black electrical tape, or an insulating gel, like silicone. If a gel is used, be sure to let it set for several hours or overnight. It is also probably a good idea to check the electrical connection with a multimeter prior to insulating.

[[Image:digConnector.png|frame|none|g.USBamp Digital I/O Pins]]

Next, attach the rubber sleeve over the end of the part with the female threads, as shown in the panel. Slide the smaller metal sleeve over the wires, then slide the larger rubber sleeve over the wires.

For the next step, attach the two metallic pieces that surround the cables, shown laying to the sides below. One of the metal pieces has a small groove in it, which should be placed over the notch on the connector; the other metal piece fits on the opposite side of the connector. Push the small metal sleeve up to the side piece with the groove, and rotate the sleeve until the notch fits in the groove.

Place the end piece over the connector, with the red dot on top and aligned with the connector notch. Finally, slide the rubber sleeve over the connector, and screw the sleeve into the end piece.

[[Image:finalDigCable.png|frame|none|g.USBamp Digital I/O Cable]]

The plug is assembled next. Solder the signal wire from Pin 3 (Digital Out 1) on the digital I/O connector to the signal connector on the female mono plug, and solder the ground wire to the outer ground connector on the plug. The below figure shows this; in this figure, the red wire is the signal wire, and the brown wire is the ground.

[[Image:digPlug.png|frame|none|g.USBamp Digital Wire Plug]]

User Reference:BCI2000Certification

2009-05-27T16:40:22Z

Awilson: /* Getting Started With the Default Tests */

==Introduction==
BCI2000 v2.0 and higher includes a certification procedure that can determine whether a computer system is capable of running all or some BCI2000 applications. Because BCI2000 does not have a standardized hardware configuration, i.e., it can run on potentially ''any'' PC, this testing procedure is capable of running on any PC with BCI2000, with the results reporting which standard BCI2000 applications meet the minimum timing requirements. Different configurations are included in the certification procedure to test a range of likely setups for a given application, in which timing characteristics such as the sampling rate, inter-stimulus intervals, and stimulus duration, and other parameters, such as the number and size of the stimuli, are changed for each configuration.

This document serves as the instruction manual for using the certification procedure, and describes how the procedure works to determine the timing characteristics of the BCI2000 system. The primary use for the certification procedure is to determine if the PC configuration used with BCI2000 is capable of running the core BCI2000 system, which is comprised of:

*Support for the the g.tec series of amplifiers, including the g.USBamp, g.MOBIlab, and the g.MOBIlab+ (bluetooth) amplifiers.
*The AR, P3, FFT, and Matlab signal processing modules.
*The CursorTask, P3Speller, and StimulusPresentation application modules.

Additionally, due to the extensibility of BCI2000, researchers who develop custom algorithms and applications, or use amplifiers not made by g.tec, can use the certification procedure to determine whether their custom modules are capable of running on a particular PC configuration.

The certification procedure works by comparing the differences in time of when BCI2000 ''expects'' an event to occur to when that event ''actually'' occurred. These events include a change in the display, an audio output through the system speakers, or an EEG sample being stored in the amplifier buffer. The times at which such events occur are recorded with the amplifier and stored in a data file. Changes in the display are found using an optical sensor in combination with the g.TRIGbox. The g.TRIGbox is a signal conditioner that generates trigger pulses for various sensors or input signals. When the sensor exceeds a threshold, the g.TRIGbox outputs a digital signal which is recorded on the amplifier. A similar procedure is used for audio detection: the sound output from the PC is input to the g.TRIGbox, and when the volume exceeds threshold, a high digital signal is output and recorded by the amplifier. This information can be used because BCI2000 stores a time-stamp for every event during an experiment. The difference between a time-stamp value and the time that the recorded event changes values are compared to find the latency for that particular event.

These latencies can be affected by many external influences, including hardware deficiencies (such as low RAM, slow CPU speed, or a video card of low quality), and other software running in the background while the experiment is being run.

==Latencies==
Briefly, the different latencies inherent in the BCI2000 system include amplifier latency, processing latency, output latency, and the sum of these, the system latency. Additionally, the block duration jitter will be measured. The figure below provides a timeline of events that occur within a single block of data, with significant time points labeled. This figure provides an accurate account of the order in which events occur within a block of data, although the time intervals are not necessarily to scale.


[[Image:timeline3.png|frame|none|Timeline of events. Time intervals are not to scale.]]

===Defining Latencies===
====Amplifier Latency====
Amplifier Latency is the minimum delay between the time that a signal is presented at the amplifier input, to when it has been acquired in the source module. Depending on configuration, this may comprise physical signal delay in the amplifier, digitization, transmission from the amplifier to the PC, and processing time inside a hardware driver. That minimum delay occurs for the last sample of a data block, which, unlike its preceding samples in the same block, will spend only a minimum time in hardware and software buffers. In [[#TimeLine|Timeline]],

Amplifier latency = <math>t_{0}-t_{-1}</math>.

For amplifiers connected via bandwidth-limited serial interfaces, transmission latency may have a measurable impact on amplifier latency, depending on the hardware. When using USB 2.0, as is the case for the g.USBamp, transmission latency may generally neglected, as illustrated by the following example: USB 2.0 has a maximum transmission rate of 480 Mbit/s. If we are acquiring 16 channels of 32-bit data, and transmitting in blocks of 16 samples, this is 8192 bits of data; at USB 2.0 speed, this should take roughly 17 <math>\mu</math>s to transfer. However, a more realistic approximation for USB 2.0 speeds is 240 Mbit/s, which increases the transfer delay to 34 <math>\mu</math>s. For sampling rates below 30 kHz, this is less than a single sample's duration.

In addition to amplifier latency, system performance will be influenced by buffering latency. Buffering latency is dependent on the sample block buffer size: When a data sample is digitized, it is not immediately transferred to the PC, but is stored in memory on the amplifier. The PC then makes the appropriate request to the amplifier, and a block of data is transferred all at once to reduce the processing load. This implies that a signal that is digitized at the start of the buffer must wait until the buffer is full to be read into the PC. For example, if the sample block size is 16 samples, the first sample must wait 15 more samples before it can be used in the application. Fortunately, this latency is always known, and can be reduced with a higher sampling rate and/or smaller block sizes, assuming the PC can handle the increased overhead. Buffering latency does not affect the acquisition-to-display latency, because processing occurs immediately after a block's last sample, which is not affected. Still, it is an important factor to keep in mind, because a large sample block size and/or a small sample rate will decrease the refresh rate for the application (e.g., at a sample rate of 256 Hz and a sample block size of 128 samples, the application will only be refreshed every 0.5 s.)

====Processing Latency====
Processing Latency is the total time it takes for the data to be processed by all BCI2000 modules (SignalSource, SignalProcessing, and Application).

Processing latency = <math>t_{2}-t_{0}</math>.

Processing latency strongly depends on CPU speed, and if this latency becomes too large, high CPU load will probably be the cause, implying decreased or unsuitable BCI2000 performance.

====Output Latency====
Output Latency is the latency from the time that the Application module issues a command to change the display or issue a sound (or another output), to the time that this output actually occurs.

Output latency = <math>t_{3}-t_{2}</math>.

====System Latency====
System Latency is the minimum time interval between a change in amplifier input, and a causally related change in application output. This is the sum of the above latencies, Amplifier, Processing, and Output.

System latency = <math>t_{3} - t_{-1}</math>.

====Block Duration, Block Duration Jitter====
Block Duration is the time interval between adjacent blocks of data, normalized to the ideal duration of a data block as determined from sampling rate and sample block size:

Block Duration = <math>\frac{t_{5}-t_{0}}{\mathrm{SampleBlockSize}/\mathrm{SamplingRate}}</math>.

When the system operates in real time, mean Block Duration will always be 1. Measuring Block Duration has the purpose of obtaining Block Duration Jitter as its standard deviation.

===Measuring Latencies===
The procedure for measuring the system latencies are below. In general, a combination of recorded events and software time-stamps recorded in BCI2000 data files to determine when important events occur, with ms or better time resolution.
[[Image:OutTimeline1.png|thumb|500px|none|Recorded events used for measuring latencies.]]

====Measuring Amplifier Latency====
In [[#TimeLine|TimeLine]], Amplifier Latency is the time interval between the sampling of a data block's last sample, and its acquisition into the source module's data buffer:
<center><math>
\mathrm{AmplifierLatency} = t_{0} - t_{-1}
</math></center>

To measure this latency, the Source module will set a digital output on the amplifier to a high value at time <math>t_0</math> immediately following data acquisition, as indicated in [[#overview|Overview]]. The digital output level is 3.3 V, so a voltage divider may required to attenuate the signal level to the range of amplifier input. This signal is then recorded on an input channel on the amplifier (time <math>t_{1}</math>).

In the recorded data, we may then identify <math>t_{-1}</math>, which is the beginning of sample block <math>n</math>, by its sample offset, which also coincides with BCI2000 state changes. <math>t_1</math> may be identified by a change in the recorded signal, occurring in the channel that was connected to the digital output during measurement.
<center><math>
\mathrm{AmplifierLatency} \approx t_{0} - t_{-1}.
</math></center>

====Measuring Processing Latency====
The processing latency is defined as the amount of time that it takes for the computer to process the data after acquiring it, to when the application module output is changed. In [[#TimeLine|TimeLine]], this is the time from <math>t_{0}</math> to <math>t_{2}</math>. Processing latency is calculated using two timestamps saved with every block of data, <math>SourceTime</math> and <math>StimulusTime</math>. <math>SourceTime</math> is saved at <math>t_0</math>, immediately following data acquisition in the Source module, and <math>StimulusTime</math> is saved at <math>t_2</math> immediately following application presentation in the Application module. Therefore, processing latency for each block of data is calculated as the difference between time stamps:

<center><math>
\mathrm{Processing Latency} = \mathrm{StimulusTime} - \mathrm{SourceTime} = t_{2} - t_{0}.
</math></center>

====Measuring Application Output Latency====

There are many possible application output types, including visual (i.e., the computer screen), audio, or mechanical (e.g., a robotic arm). The core BCI2000 system primarily uses visual and audio output, and so the default testing system will focus on these.

Both visual and audio output can be measured using the g.TRIGbox signal conditioner, which accepts inputs from optical sensors, microphones, or any other input. The user sets a threshold for the input signals, and the g.TRIGbox outputs a digital pulse whenever this threshold is exceeded. This output is then recorded back into the amplifier system, so that the analysis program can measure the response times for each output.

We identify event <math>t_0</math> by a change in the data channel connected to the amplifier's digital output, and event <math>t_3</math> by a change in the data channel connected to the g.TRIGbox, and compute their difference. Also, both events are affected by Amplifier Latency in the same way, so we may ignore Amplifier Latency, and have
<center><math>\begin{matrix}
\mathrm{Output Latency} = t_{3} - t_{2} = (t_3-t_0)-(t_2-t_0) = (t_3-t_0)-\mathrm{ProcessingLatency}.
\end{matrix}</math></center>

====Measuring System Latency====
As defined above, System Latency is the sum of Amplifier Latency, Processing Latency, and Output Latency. It is important to realize that the system latency is dependent on the output modality used, i.e., the video system latency and the audio system latency will vary on the same system due to the differences in output latencies.
The system latency may be measured
#directly, by identifying <math>t_{-1}</math> as the beginning of a data block by its sample index, and <math>t_3</math> by the signal change in the channel connected to the g.TRIGbox, and then calculating <math>\textrm{SystemLatency}=t_3-t_{-1}</math>,
#or indirectly, by using the previously measured quantities <math>\textrm{SystemLatency}=\mathrm{AmplifierLatency}+\mathrm{ProcessingLatency}+\mathrm{OutputLatency}</math>.

====Measuring Block Duration====
Block Duration is measured as the time between adjacent blocks of data, divided by the theoretical ideal value, which is the sample block duration. For the actual measurement, we use the difference between subsequent <math>\textrm{SourceTime}</math> time stamps which are recorded at <math>t_0</math> and <math>t_8</math> in [[#TimeLine|Timeline]]:

<center><math>
\mathrm{BlockDuration} = \frac{t_{5} - t_{0}}{\mathrm{SampleBlockSize}/\mathrm{SamplingRate}}
=\frac{\Delta \mathrm{SourceTime}}{\mathrm{SampleBlockSize}/\mathrm{SamplingRate}}
</math></center>

===Latency Calculation Overview===
Latencies are calculated by comparing changes in a BCI2000 state value to changes in a recorded signal. The analysis program follows these general steps in calculating the various latencies:

#Determine which threshold values to use based on the ''thresh'' definition in the BCI2000Certification.cfg file, which defines a threshold based on the amplifier used. For example, the g.USBamp has an input range of -250 mV to + 250 mV, and the g.TRIGbox outputs from 0 to 200 mV, so the threshold used is about 12.5 mV.
#Traverse the state values for a selected state and find where the state changes from 0 to a given value (or any value). The sample at which this occurs is saved for later use in <math>stateChangePos</math>.
#When this occurs, start looking through <math>Signal_{norm}</math> to find when a rising edge exceeds the determined threshold value. The sample at which this occurs is saved in <math>sigChangePos</math>.
#The latency for the <math>n</math>th state change is calculated as:
#:<center><math>\begin{matrix}
latency_n = \frac{sigChangePos_n-stateChangePos_n}{SampleRate}
\end{matrix}</math></center>
#:and is stored in an array.
#Once the entire state vector is traversed, the mean, standard deviation, minimum and maximum values for this latency are calculated and reported.

==Getting Started With the Default Tests==
This section provides step-by-step instructions on running the default certification procedure. Note that some cables must be assembled before the testing can be done; see the end of this document for information on assembling the cables.

===Starting the Procedure===
The BCI2000 certification procedure uses different combinations of BCI2000 parameter fragments to control the tests. While it is possible to edit these by hand, in most circumstances it is simpler to use the graphical user interface provided. To do so, navigate to the BCI2000/tools/BCI2000Certification folder, and start the BCI2000Certification.exe program. This program appears as:

[[image:Certificationtool.png|frame|none|The BCI2000Certification user interface.]]

This program shows a list of all of the procedures to be tested for the loaded configuration. Detailed instructions for using the interface follow.

====Load a Configuration File====
To get started, load a provided configuration file. The standard

====Sampling Rate====
This is set to 512 by default. This can be changed to another value that will apply to all tests, except those that explicitly override it in their own parameter file.

====Display parameters====
These are on the lines that begin with <code>Application:Window</code>. For many labs, the default settings should work fine; the window is setup to appear in the top-left corner of the main window (<code>WindowLeft= 0</code> & <code>WindowTop= 0</code> ), and is 800 wide by 800 pixels tall (<code>WindowWidth= 800</code> & <code>WindowHeight= 800</code> ).

Users with a dual-screen configuration may wish to change this so that the BCI2000 window is on the secondary monitor; to do so, the <code>WindowLeft</code> parameter should be changed, which depends on the resolution and orientation of both monitors. For example, if the 2nd monitor is to the right of the primary monitor, and both monitors have a resolution of 1280x1024 pixels, setting <code>WindowLeft</code> to <code>1280</code> will place the window on the 2nd monitor. Similarly, if the 2nd monitor is to the left of the primary monitor, setting <code>WindowLeft</code> to <code>-1280</code> will accomplish the same thing. If the monitors have different resolutions (e.g., monitor 1 is 1600x1200 and monitor 2 is 1024x768, located to the right of the 1st monitor), the position should change accordingly. For example, in this scenario, to set the window to the right of the main window, set <code>WindowLeft</code> to <code>1600</code> . Finally, set the <code>WindowWidth</code> & <code>WindowHeight</code> to appropriate values for full-screen, if desired. To summarize, for the dual-screen case in which monitor 1 is 1600x1200 pixels, and monitor 2, to the right of 1, is 1024x768 pixels, and the BCI2000 window should be full-screen on monitor 2, the parameters should look like:

<code>Application:Window int WindowWidth= 1024 ... 
Application:Window int WindowHeight= 768 ... 
Application:Window int WindowLeft= 1600 ... 
Application:Window int WindowTop= 0 ... 
</code>
Note that nothing following the ... needs to be changed above in the parameter file.

===Connect the Amplifier to the Trigger Box, and Attach Sensors===
[[Image:connections.png|frame|none|Connections overview]]

This section describes the steps for connecting the necessary hardware. Refer to the Connections Overview figure above for additional information; each step is numbered in this figure.

#Connect the amplifier to the computer; the supported g.tec amps are connected via USB, RS232, or Bluetooth.
#Connect the Digital I/O cable (see bottom of this document) to the amplifier on the Digital I/O port.
#Connect the reference and ground wires from the assembled amplifier cables to the amplifier reference and ground connections.
#Connect the amplifier cables with the safety connectors into channels 1, 2, and 3 on the g.USBamp.
#Connect the digital output line to the channel 1 amplifier cable.
#Connect the A output from the trigger box to the channel 2 amplifier cable.
#Connect the B output from the trigger box to the channel 3 amplifier cable.
#Connect the optical sensor plug to the g.TRIGbox, using the optical sensor input channel A.
#Connect the computer audio output using a stereo cable to the g.TRIGbox, using the high-level input channel B.

===Setup Sensor Thresholds===
The audio and optical sensors each have a threshold setting on the g.TRIGbox, along with an LED indicating whether the current input is above threshold for each channel. At rest, each trigger should be off; if any is on, turn the threshold knob counter-clockwise until the LED is off.

====Audio Threshold====
To set the audio threshold, set audio volume on the computer to maximum. On Windows, to make this process easier in the future, go to the Start menu, click the Control Panel, and go to Sounds. In the Sound window, click the box that puts the volume icon in the task bar. A small speaker should now appear in the bottom-right of the screen in the task bar. Click this icon, and slide the volume up to the max; when you click on this slider, Windows emits a short beep to give an idea of the volume level, which can be used to set the threshold. To do so, make sure that the stereo audio cable is plugged into the g.TRIGbox, and click the slider to emit a sound, checking that the green LED is flashing when you click the slider. If it is not, turn the threshold knob for channel B counter-clockwise, and click the slider again. If it is still not working after several tries, unplug the audio cable from the computer, and check that you can hear the beep through the speakers. If you cannot, make sure that the sound is not muted, and that the sound drivers are properly installed. If you can hear it, plug the audio cable back into the computer audio output (NOT the microphone input), and make sure the g.TRIGbox has power; the light next to the power switch should flash momentarily if the battery levels are OK. You can also use a wall power source (see the g.TRIGbox manual for more information). The threshold is set correctly when the channel B LED is off at rest, and is on when a sound is played.

====Video Threshold====
To set the video threshold, first tape the optical sensor to the monitor in approximately the correct location, based on the information in the latencyTest.prm file for the window position and dimensions. To activate the optical trigger on the g.TRIGbox, drag a white window, such as a Notepad window, in the background under the sensor. Move the threshold knob for channel A until the LED for that channel is just on (i.e., turning it down just a little turns the trigger off). The sensor will be placed more accurately in the following step.

===Starting the Software===
[[image:Certificationtool.png]]
Navigate to BCI2000/tools/BCI2000Certification, and double-click the BCI2000Certification.exe program. The BCI2000 program should start, with the output window in the location specified in the latencyTest.prm file. If there are any errors at startup, the BCI2000 error log will report them. If there are errors, correct them, exit out of the BCI2000Certification.exe program, and restart the program.

===Setting up the Optical Sensor===
Each application has a unique display configuration, where the visual target of interest is located in a specific position on the monitor. Generally, the optical sensor will not likely have to be moved far in between tasks due to the design of the parameter files. However, it is still necessary to ensure that the sensor is in the correct position for each task, and to be able to change the position if necessary. This section describes the process to find the correct location on the monitor for the sensor. To begin, the certification procedure should be started.

====P3Speller====
The P3Speller task has an group of letters arranged into rows and columns. The analysis uses the letter in the 3rd column and 3rd row, which will contain the letter X when the program is run. This location should be very close to that specified for the CursorTask, described above. Fortunately, the arrangement of the letters is shown before the test starts, which allows the sensor to be adjusted if necessary. All of the following default tasks are setup so that the optical sensor does not need to be moved from this position.

====CursorTask====
In the default configuration, the optical sensory does not need to be moved from the position used for the P3Speller task. For custom tests, the flashing object must either be placed under the sensor, or the sensor needs to be moved to the correct position.

====StimulusPresentation====
For the StimulusPresentation tasks, a single large icon appears in the center of the screen, which will be detected by the sensor. The default location of the sensor as defined for the CursorTask should be able to capture the icon on the screen. However, if the task begins and it appears that it is outside the icon location, move the sensor to the middle of the icon. Keep in mind that it may have to be relocated for following tasks.

===Running the Tests===
Once the optical sensor is setup and calibrated for a task, begin the testing process. To start the process, press the Start button in the BCI2000 operator window. At the end of each task, the program will quit automatically, and the next one will start automatically. For each task, press the Start button to begin.

Occasionally, the optical sensor may not be in the exact correct place for a given task.You should be able to see changes in on the video channel (channel 2 by default) in the window showing the recorded channels. If the signal is not changing when it should be (e.g., during the correct visual stimulus), you may try increasing the threshold to catch the stimulus, or you may need to place the sensor in the correct location. To do this, place the sensor in the better location, then quit the current BCI2000 test, and quit the BCI2000Certification program. The procedure will need to be restarted.

When the testing is complete, the BCI2000CertAnalysis program will automatically start. It will analyze the data that have been collected, and return the results in the results.txt file. In general, a Pass or Fail will be written next to a task, and each task component, if it passed or failed the test. For more information on interpreting results, see below.

==BCI2000Certification: Additional Information==
The previous section on Getting Started provided information to quickly setup and run the default tests. This section provides detailed information about each file used, and how to modify the files for your specific system and applications.

===Overview of Important Files===
There are several important files that are used in the BCI2000 Certification procedure. These files and their contents are described in this section.

====BCI2000Certification.ini====
The BCI2000Certification.ini file contains the information that defines each task configuration. It is located in the BCI2000/tools/BCI2000Certification/ folder. It specifies the parameter file, the SignalSource, SignalProcessing, and Application modules, and the analysis definitions for each task. It contains all of the default tests, although it can easily be expanded to include additional or customized task configurations.

Each task is defined by a set of '''case-insensitive''' , space-separated fields, as described below. A * indicates an optional field. The % character indicates a comment, and everything following that character is ignored.

*'''name''' The name of the task, which should be unique. This generally describes the task. It must not contain any spaces. This value determines the path to the saved data file, and the name of the file itself. For example, the name StimulusPresentation_512 would create a file at <code>./Data/StimulusPresentation_512001/StimulusPresentation_512S001R01.dat</code> Example:
**<code>name StimulusPresentation_512</code>

*'''parm'''The BCI2000 *.prm file used for this task. It should be placed in the BCI2000/tools/BCI2000Certification/parms/ folder. Note that the CertificationMain.prm is included in ''all'' configurations by default, and does not need to be listed here. This file contains the information for this specific task configuration. See above for further information.
**<code>parm SimpleAV.prm</code>

*'''source''' The SignalSource module to be used for this test. The g.tec g.USBamp system is used in all configurations by default. If the g.MOBIlab or g.MOBIlab+ are used, the SignalSource module should be changed to the appropriate executable. All BCI2000 executables are located in BCI2000/prog/. Examples:
**<code>'source gUSBampSource.exe'''</code>
**<code>source gMOBIlabSource.exe</code>

*'''sigproc''' The SignalProcessing module that is used for this configuration. This is likely dependent on the application used as well. This program should be located in BCI2000/prog/. Example:
**<code>sigproc P3SignalProcessing.exe</code>

*'''app''' The application for this configuration. This program should be located in BCI2000/prog/. Example:
**<code>app StimulusPresentation.exe</code>

*'''*amp''' This is a single value that gives the channel that is used to compute the amplifier latency. Example:
**<code>amp 0</code>

*'''*dAmp''' This is a single value that specifies a digital input channel that is used to compute the amplifier latency. Example:
**<code>dAmp 15</code>

*'''*vid''' This field is followed by 3 values, that give the channel number that is recording the video output, and the state name and state value to use as a trigger for the comparison. See the example entry for more information. Example:
**<code>vid 1 StimulusCode 1</code>

*'''*aud''' This field is followed by 3 values, that give the channel number that is recording the audio output, and the state name and state value to use as a trigger for the comparison. See the example entry for more information. Example:
**<code>aud 1 StimulusCode 1</code>

*'''skip''' Entering '''skip''' will cause this task to not be run or analyzed. This is used to reduce the number of tasks that are run, which helps to repeat individual tasks that may have had problems in previous sessions.

*'''end''' This must come at the end of each task definition.

In addition to task-specific entries, there are several global entries that will apply to every task, unless explicitly overwritten in that task. This allows the user to quickly change settings for all tasks simultaneously, e.g., if tests will be run using a g.tec g.USBamp for one set of tests, and a g.tec g.MOBIlab for another. Global entries must be defined at the beginning of the BCI2000Certification.ini file outside of the task definitions. These entries are defined as:

*'''source''' The SourceModule to be used for all tests, unless explicitly overwritten by an individual task. Otherwise identical to the '''source''' definition in a task entry.
*'''export''' This entry does not use any other parameters on the line on which it is defined. If '''export''' is present in the BCI2000Certification.ini file, test results will be written to a comma-separated-value (CSV) text file that is located in the folder where data is saved for each task. For example, if the data folder is BCI2000/tools/BCI2000Certification/latencyData/, then the export file for the SimpleTarget task will be placed in the folder BCI2000/tools/BCI2000Certification/latencyData/SimpleTarget.

Here is a full example entry that includes two tasks.

<pre>
source gUSBampSource
export

name StimulusPresentation_512
parm StimulusPresentation_512.prm
sigproc P3SignalProcessing
app StimulusPresentation
amp 0
dAmp 15
vid 1 StimulusCode 3
aud 2 StimulusCode 3
end

name CursorTask_1200
parm CursorTask_1200.prm
source gMOBIlab
sigproc ARSignalProcessing
app CursorTask
amp 0
dAmp 15
vid 1 TargetCode 1
end
</pre>

The <code>StimulusPresentation</code> task uses the <code>gUSBampSource</code> source module, and records block-triggered digital outputs on channel 0, video output triggered off of stimulus code 3 on channel 1, and audio output triggered off of stimulus code 3 on channel 2. The <code>SimpleTarget</code> tasks overrides the global <code>source</code> entry, and uses its own <code>source</code> definition, specifying that a gMOBIlab should be used for acquisition instead of a gUSBamp. Finally, the <code>export</code> entry is set at the beginning, so test results for all files are output to a CSV file.

The BCI2000Certification.ini file contains many task definitions. Each entry is read by the BCI2000Certification.exe program, and is entered as a separate task to be run and then analyzed.

====BCI2000Certification.cfg====
The latencyTest.prm file is located in the BCI2000/tools/BCI2000Certification/ folder. It contains many default settings and definitions that determine how the results are interpreted, and should generally not be changed by the user. The timing definitions provide the absolute maximum latencies in ms for each step in the system chain, and include the Amp, ProcLat, VidOut, AudOut, VidSys, AudSys, and Jitter (see below for explanations). Timing definitions can include either one or two fields; the first field is mandatory, and is the mean value in ms, while the second field is optional, and is the standard deviation in ms.

*'''Amp''' The amplifier latency.
*'''ProcLat''' The processing latency.
*'''VidOut''' The video output latency.
*'''AudOut''' The audio output latency.
*'''VidSys''' The video system latency.
*'''AudSys''' The audio system latency.
*'''Jitter''' The system jitter. This is the difference, in ms, between the actual block duration and theoretical block duration, which is determined by the block size.
*'''Threshold Source Value''' This is the threshold defined for a specific SignalSource module. Individual amplifiers may have different input ranges, resulting in recording signals with different ranges of magnitude. The '''Source''' entry is a value in mV. For example, the threshold setting for the g.USBamp is '''Threshold gUSBampSource 12.5''' .
*'''ResultOut''' This is the file that contains the testing results.
*'''DataDir''' The default data directory. It defaults to latencyData in the BCI2000/tools/BCI2000Certification/ folder.

These values should not generally be changed by the user, although they may be updated in future BCI2000 versions.

====CertificationMain.prm====
This parameter file contains some of the default task parameters common to every test, including the save location, monitor configuration, sampling rate, and visualization settings. Note that these parameters can be overwritten in the *.prm files for each individual test configuration.

====BCI2000Certification.exe====
This file controls the execution of each task. It parses the BCI2000Certification.ini and BCI2000Certification.cfg files to determine which files and tasks to run, and controls the CPU load monitor. When all tasks are complete, this program calls the BCI2000Analysis.exe program to handle the analysis of the collected data.

====BCI2000CertAnalysis.exe====
This program analyzes the data collected, and reports results to a data file. It uses the DataDir parameter in the BCI2000Certification.cfg file to determine where the data is located. Results are output to results.txt in the BCI2000/tools/BCI2000Certification/ folder.

====Parameter Files====
Each task should have it's own parameter file that contains the unique configuration and settings for that task. For example, there may be several configurations that use the g.USBamp, ARSignalProcessing, and CursorTask, each with its own parameter file. These files end in .prm, and are placed in the BCI2000/tools/BCI2000Certification/parms/ folder.

===Interpreting Results===
Results are recorded to the BCI2000/tools/BCI2000Certification/results.txt file. The results for each task, and each applicable latency tested, are reported here. If the entire task passed, then each test performed met the minimum timing requirements specified in the BCI2000Certification.cfg file. If one or more did not pass, then the specific test that did not pass the test has Fail written next to it.

====What if a Task Did Not Pass?====
TO BE ADDED.

==Certification Protocol==
This section describes how the testing protocol is run, the various components involved in the certification analysis, and how to interpret results.

===Running the Tests===
The certification protocol consists of running several BCI2000 applications in multiple configurations to determine if each application meets the minimum requirements for BCI2000, and to determine if individual configurations of an application meet the requirements. For example, the CursorFeedback task may be tested with several combinations of sampling rates, sample block sizes, and processed channels, only some of which may work with a given computer setup.

The testing set is run from a single batch file called LatencyAnalysis.bat. This file is located in the folder BCI2000/tools/BCI2000Certification/batch. This batch file executes additional batch files in this folder, each corresponding to a different application configuration. Each of these batch files starts the Operator module, automatically loading multiple parameter files used for a given configuration. There is a general-purpose parameter file called latencyTest.prm that all configurations use. This file configures the save location for all latency tests, as well as default window positions and sampling rates. A second parameter file is passed to the operator that contains the parameters for a unique application configuration. After starting the operator module, the batch file starts the SignalSource module, SignalProcessing module, and Application module. The loaded configuration is set automatically, and the user needs only to press the start button to start the analysis.

==Software Templates==
This describes how to implement the testing protocols for your own amplifier system and custom applications. This is useful for determining if your hardware setup and software is capable of maintaining an acceptable level of performance for real-time testing.

===Amplifier Latency===
The amplifier latency requires an output that can be recorded by the amplifier. In the case of the g.USBamp, a digital output line is used, although either analog or digital outputs could be used in a system.

In the SignalSource module code for your custom amp, find the Process function. Near the beginning of this function, before any data is acquired, set the output signal to 0, either a digital low or analog value of 0 V. This will be dependent on the particular amplifier and API used; for the g.USBamp, this function call looks like:
 <code>
GT_SetDigitalOut ( m_hdev.at(0), (UCHAR)1, (UCHAR)0);
</code> 

This sets the digital output 1 on device 0 to a value of 0.

At the end of the Process function, the output should be set to a high level. A similar function call will be used to above, only the value is 1 instead of 0; again, the function will be dependent on the system used, and whether analog or digital output is used. Here is the code for the g.USBamp:
 <code>
GT_SetDigitalOut ( m_hdev.at(0), (UCHAR)1, (UCHAR)1);
</code> 

This sets the digital output 1 on device 0 to a value of 1.

===Visual and Audio Latency===
Developing new video and optical latency tests does not necessarily require adding additional code to existing modules (beyond any customization already done).

==Supported Hardware==
A list of officially supported hardware configurations, and suggested minimum requirements is provided.

===Supported and Tested Hardware===
====Amplifiers====

*g.USBamp
*gMOBIlab (Serial RS232)
*gMOBIlab (Bluetooth)
*TDT Pentusa (RX5)

===Minimum Requirements===
This table shows the minimum requirements for running BCI2000.

{| border="1"
|+ Minimum System Requirements for BCI2000
! CPU
| 1 GHz
|-
! RAM
|512 MB (dependent on OS; 1 GB for Windows Vista)
|-
! Video Card
|32 MB VRam; Hardware OpenGL Support
|-
! Sound Card
|
|-
! Monitor
|
|-
! OS
|Windows 2000; Windows XP SP2 or Greater; Windows Vista
|}

===Voltage Divider & Amplifier Input===
Parts List:

*4 Male Mono Audio Connectors
*6 12in Safety Connector Wires (to USB amplifier input), different colors
*4 3in Wires
*Soldering Iron and Solder
*resistors for voltage dividers
This section describes how to assemble cables that connect the output of the g.TRIGbox to the amplifier input channels.

Strip the free ends of all 6 safety connector wires, about <math>\frac{1}{4}</math> in. If you are not using voltage dividers, solder 4 of the wires directly to the center signal connection on the 4 mono audio connectors. Cover the connection.

[[Image:ampPlug_1.png|frame|none|g.USBamp Amplifier Plug]]

Next, twist the two remaining safety connector wire ends together, and solder them together. Solder the 4 short wires to the ground connections on the mono plugs. Finally, solder the 4 ground wires to the two safety connector wires that were twisted together and soldered previously, as shown here.

[[Image:ampPlugs_2.png|frame|none|g.USBamp Amplifier Plugs]]

These plugs can plug directly into the g.TRIGbox outputs, and the safety connectors plug into the channels 1-4 inputs on the g.USBamp; the ground wires plug into the ground and reference on the g.USBamp.

===Digital I/O Cable===

Parts List:

*3 Colored Wires
*7-Pin Digital Connector from g.tec
*Soldering Iron and Solder
*Silicone or electrical tape for insulation
*1 Female Mono Audio Plug

In order to access the digital I/O pins on the g.USBamp, a connector needs to be assembled. The 7-pin digital I/O connector should be ordered through g.TEC, the manufacturer of the g.USBamp.

At least three wires are needed for the circuit, which connect to the digital output 1 pin, the digital input 0 pin, and the ground pin.
[[Image:DigIO.png|frame|none|g.USBamp Digital I/O Pins]]

To start, cut three 10 in wires, preferably with different colors to differentiate between the signal and ground wires. Cut back a small portion of the ground wire, and solder it to the center ground pin on the connector. Now, find the top of the connector by locating the small plastic notch, and locate pins 3 and 4 relative to the notch. Solder one wire to pin 3, and the remaining wire to pin 4. It may be helpful to insulate the wires from the casing using either a piece of black electrical tape, or an insulating gel, like silicone. If a gel is used, be sure to let it set for several hours or overnight. It is also probably a good idea to check the electrical connection with a multimeter prior to insulating.

[[Image:digConnector.png|frame|none|g.USBamp Digital I/O Pins]]

Next, attach the rubber sleeve over the end of the part with the female threads, as shown in the panel. Slide the smaller metal sleeve over the wires, then slide the larger rubber sleeve over the wires.

For the next step, attach the two metallic pieces that surround the cables, shown laying to the sides below. One of the metal pieces has a small groove in it, which should be placed over the notch on the connector; the other metal piece fits on the opposite side of the connector. Push the small metal sleeve up to the side piece with the groove, and rotate the sleeve until the notch fits in the groove.

Place the end piece over the connector, with the red dot on top and aligned with the connector notch. Finally, slide the rubber sleeve over the connector, and screw the sleeve into the end piece.

[[Image:finalDigCable.png|frame|none|g.USBamp Digital I/O Cable]]

The plug is assembled next. Solder the signal wire from Pin 3 (Digital Out 1) on the digital I/O connector to the signal connector on the female mono plug, and solder the ground wire to the outer ground connector on the plug. The below figure shows this; in this figure, the red wire is the signal wire, and the brown wire is the ground.

[[Image:digPlug.png|frame|none|g.USBamp Digital Wire Plug]]

User Reference:BCI2000Certification

2009-05-27T16:24:35Z

Awilson: /* Getting Started With the Default Tests */

==Introduction==
BCI2000 v2.0 and higher includes a certification procedure that can determine whether a computer system is capable of running all or some BCI2000 applications. Because BCI2000 does not have a standardized hardware configuration, i.e., it can run on potentially ''any'' PC, this testing procedure is capable of running on any PC with BCI2000, with the results reporting which standard BCI2000 applications meet the minimum timing requirements. Different configurations are included in the certification procedure to test a range of likely setups for a given application, in which timing characteristics such as the sampling rate, inter-stimulus intervals, and stimulus duration, and other parameters, such as the number and size of the stimuli, are changed for each configuration.

This document serves as the instruction manual for using the certification procedure, and describes how the procedure works to determine the timing characteristics of the BCI2000 system. The primary use for the certification procedure is to determine if the PC configuration used with BCI2000 is capable of running the core BCI2000 system, which is comprised of:

*Support for the the g.tec series of amplifiers, including the g.USBamp, g.MOBIlab, and the g.MOBIlab+ (bluetooth) amplifiers.
*The AR, P3, FFT, and Matlab signal processing modules.
*The CursorTask, P3Speller, and StimulusPresentation application modules.

Additionally, due to the extensibility of BCI2000, researchers who develop custom algorithms and applications, or use amplifiers not made by g.tec, can use the certification procedure to determine whether their custom modules are capable of running on a particular PC configuration.

The certification procedure works by comparing the differences in time of when BCI2000 ''expects'' an event to occur to when that event ''actually'' occurred. These events include a change in the display, an audio output through the system speakers, or an EEG sample being stored in the amplifier buffer. The times at which such events occur are recorded with the amplifier and stored in a data file. Changes in the display are found using an optical sensor in combination with the g.TRIGbox. The g.TRIGbox is a signal conditioner that generates trigger pulses for various sensors or input signals. When the sensor exceeds a threshold, the g.TRIGbox outputs a digital signal which is recorded on the amplifier. A similar procedure is used for audio detection: the sound output from the PC is input to the g.TRIGbox, and when the volume exceeds threshold, a high digital signal is output and recorded by the amplifier. This information can be used because BCI2000 stores a time-stamp for every event during an experiment. The difference between a time-stamp value and the time that the recorded event changes values are compared to find the latency for that particular event.

These latencies can be affected by many external influences, including hardware deficiencies (such as low RAM, slow CPU speed, or a video card of low quality), and other software running in the background while the experiment is being run.

==Latencies==
Briefly, the different latencies inherent in the BCI2000 system include amplifier latency, processing latency, output latency, and the sum of these, the system latency. Additionally, the block duration jitter will be measured. The figure below provides a timeline of events that occur within a single block of data, with significant time points labeled. This figure provides an accurate account of the order in which events occur within a block of data, although the time intervals are not necessarily to scale.


[[Image:timeline3.png|frame|none|Timeline of events. Time intervals are not to scale.]]

===Defining Latencies===
====Amplifier Latency====
Amplifier Latency is the minimum delay between the time that a signal is presented at the amplifier input, to when it has been acquired in the source module. Depending on configuration, this may comprise physical signal delay in the amplifier, digitization, transmission from the amplifier to the PC, and processing time inside a hardware driver. That minimum delay occurs for the last sample of a data block, which, unlike its preceding samples in the same block, will spend only a minimum time in hardware and software buffers. In [[#TimeLine|Timeline]],

Amplifier latency = <math>t_{0}-t_{-1}</math>.

For amplifiers connected via bandwidth-limited serial interfaces, transmission latency may have a measurable impact on amplifier latency, depending on the hardware. When using USB 2.0, as is the case for the g.USBamp, transmission latency may generally neglected, as illustrated by the following example: USB 2.0 has a maximum transmission rate of 480 Mbit/s. If we are acquiring 16 channels of 32-bit data, and transmitting in blocks of 16 samples, this is 8192 bits of data; at USB 2.0 speed, this should take roughly 17 <math>\mu</math>s to transfer. However, a more realistic approximation for USB 2.0 speeds is 240 Mbit/s, which increases the transfer delay to 34 <math>\mu</math>s. For sampling rates below 30 kHz, this is less than a single sample's duration.

In addition to amplifier latency, system performance will be influenced by buffering latency. Buffering latency is dependent on the sample block buffer size: When a data sample is digitized, it is not immediately transferred to the PC, but is stored in memory on the amplifier. The PC then makes the appropriate request to the amplifier, and a block of data is transferred all at once to reduce the processing load. This implies that a signal that is digitized at the start of the buffer must wait until the buffer is full to be read into the PC. For example, if the sample block size is 16 samples, the first sample must wait 15 more samples before it can be used in the application. Fortunately, this latency is always known, and can be reduced with a higher sampling rate and/or smaller block sizes, assuming the PC can handle the increased overhead. Buffering latency does not affect the acquisition-to-display latency, because processing occurs immediately after a block's last sample, which is not affected. Still, it is an important factor to keep in mind, because a large sample block size and/or a small sample rate will decrease the refresh rate for the application (e.g., at a sample rate of 256 Hz and a sample block size of 128 samples, the application will only be refreshed every 0.5 s.)

====Processing Latency====
Processing Latency is the total time it takes for the data to be processed by all BCI2000 modules (SignalSource, SignalProcessing, and Application).

Processing latency = <math>t_{2}-t_{0}</math>.

Processing latency strongly depends on CPU speed, and if this latency becomes too large, high CPU load will probably be the cause, implying decreased or unsuitable BCI2000 performance.

====Output Latency====
Output Latency is the latency from the time that the Application module issues a command to change the display or issue a sound (or another output), to the time that this output actually occurs.

Output latency = <math>t_{3}-t_{2}</math>.

====System Latency====
System Latency is the minimum time interval between a change in amplifier input, and a causally related change in application output. This is the sum of the above latencies, Amplifier, Processing, and Output.

System latency = <math>t_{3} - t_{-1}</math>.

====Block Duration, Block Duration Jitter====
Block Duration is the time interval between adjacent blocks of data, normalized to the ideal duration of a data block as determined from sampling rate and sample block size:

Block Duration = <math>\frac{t_{5}-t_{0}}{\mathrm{SampleBlockSize}/\mathrm{SamplingRate}}</math>.

When the system operates in real time, mean Block Duration will always be 1. Measuring Block Duration has the purpose of obtaining Block Duration Jitter as its standard deviation.

===Measuring Latencies===
The procedure for measuring the system latencies are below. In general, a combination of recorded events and software time-stamps recorded in BCI2000 data files to determine when important events occur, with ms or better time resolution.
[[Image:OutTimeline1.png|thumb|500px|none|Recorded events used for measuring latencies.]]

====Measuring Amplifier Latency====
In [[#TimeLine|TimeLine]], Amplifier Latency is the time interval between the sampling of a data block's last sample, and its acquisition into the source module's data buffer:
<center><math>
\mathrm{AmplifierLatency} = t_{0} - t_{-1}
</math></center>

To measure this latency, the Source module will set a digital output on the amplifier to a high value at time <math>t_0</math> immediately following data acquisition, as indicated in [[#overview|Overview]]. The digital output level is 3.3 V, so a voltage divider may required to attenuate the signal level to the range of amplifier input. This signal is then recorded on an input channel on the amplifier (time <math>t_{1}</math>).

In the recorded data, we may then identify <math>t_{-1}</math>, which is the beginning of sample block <math>n</math>, by its sample offset, which also coincides with BCI2000 state changes. <math>t_1</math> may be identified by a change in the recorded signal, occurring in the channel that was connected to the digital output during measurement.
<center><math>
\mathrm{AmplifierLatency} \approx t_{0} - t_{-1}.
</math></center>

====Measuring Processing Latency====
The processing latency is defined as the amount of time that it takes for the computer to process the data after acquiring it, to when the application module output is changed. In [[#TimeLine|TimeLine]], this is the time from <math>t_{0}</math> to <math>t_{2}</math>. Processing latency is calculated using two timestamps saved with every block of data, <math>SourceTime</math> and <math>StimulusTime</math>. <math>SourceTime</math> is saved at <math>t_0</math>, immediately following data acquisition in the Source module, and <math>StimulusTime</math> is saved at <math>t_2</math> immediately following application presentation in the Application module. Therefore, processing latency for each block of data is calculated as the difference between time stamps:

<center><math>
\mathrm{Processing Latency} = \mathrm{StimulusTime} - \mathrm{SourceTime} = t_{2} - t_{0}.
</math></center>

====Measuring Application Output Latency====

There are many possible application output types, including visual (i.e., the computer screen), audio, or mechanical (e.g., a robotic arm). The core BCI2000 system primarily uses visual and audio output, and so the default testing system will focus on these.

Both visual and audio output can be measured using the g.TRIGbox signal conditioner, which accepts inputs from optical sensors, microphones, or any other input. The user sets a threshold for the input signals, and the g.TRIGbox outputs a digital pulse whenever this threshold is exceeded. This output is then recorded back into the amplifier system, so that the analysis program can measure the response times for each output.

We identify event <math>t_0</math> by a change in the data channel connected to the amplifier's digital output, and event <math>t_3</math> by a change in the data channel connected to the g.TRIGbox, and compute their difference. Also, both events are affected by Amplifier Latency in the same way, so we may ignore Amplifier Latency, and have
<center><math>\begin{matrix}
\mathrm{Output Latency} = t_{3} - t_{2} = (t_3-t_0)-(t_2-t_0) = (t_3-t_0)-\mathrm{ProcessingLatency}.
\end{matrix}</math></center>

====Measuring System Latency====
As defined above, System Latency is the sum of Amplifier Latency, Processing Latency, and Output Latency. It is important to realize that the system latency is dependent on the output modality used, i.e., the video system latency and the audio system latency will vary on the same system due to the differences in output latencies.
The system latency may be measured
#directly, by identifying <math>t_{-1}</math> as the beginning of a data block by its sample index, and <math>t_3</math> by the signal change in the channel connected to the g.TRIGbox, and then calculating <math>\textrm{SystemLatency}=t_3-t_{-1}</math>,
#or indirectly, by using the previously measured quantities <math>\textrm{SystemLatency}=\mathrm{AmplifierLatency}+\mathrm{ProcessingLatency}+\mathrm{OutputLatency}</math>.

====Measuring Block Duration====
Block Duration is measured as the time between adjacent blocks of data, divided by the theoretical ideal value, which is the sample block duration. For the actual measurement, we use the difference between subsequent <math>\textrm{SourceTime}</math> time stamps which are recorded at <math>t_0</math> and <math>t_8</math> in [[#TimeLine|Timeline]]:

<center><math>
\mathrm{BlockDuration} = \frac{t_{5} - t_{0}}{\mathrm{SampleBlockSize}/\mathrm{SamplingRate}}
=\frac{\Delta \mathrm{SourceTime}}{\mathrm{SampleBlockSize}/\mathrm{SamplingRate}}
</math></center>

===Latency Calculation Overview===
Latencies are calculated by comparing changes in a BCI2000 state value to changes in a recorded signal. The analysis program follows these general steps in calculating the various latencies:

#Determine which threshold values to use based on the ''thresh'' definition in the BCI2000Certification.cfg file, which defines a threshold based on the amplifier used. For example, the g.USBamp has an input range of -250 mV to + 250 mV, and the g.TRIGbox outputs from 0 to 200 mV, so the threshold used is about 12.5 mV.
#Traverse the state values for a selected state and find where the state changes from 0 to a given value (or any value). The sample at which this occurs is saved for later use in <math>stateChangePos</math>.
#When this occurs, start looking through <math>Signal_{norm}</math> to find when a rising edge exceeds the determined threshold value. The sample at which this occurs is saved in <math>sigChangePos</math>.
#The latency for the <math>n</math>th state change is calculated as:
#:<center><math>\begin{matrix}
latency_n = \frac{sigChangePos_n-stateChangePos_n}{SampleRate}
\end{matrix}</math></center>
#:and is stored in an array.
#Once the entire state vector is traversed, the mean, standard deviation, minimum and maximum values for this latency are calculated and reported.

==Getting Started With the Default Tests==
This section provides step-by-step instructions on running the default certification procedure. Note that some cables must be assembled before the testing can be done; see the end of this document for information on assembling the cables.

===Starting the Procedure===
The BCI2000 certification procedure uses different combinations of BCI2000 parameter fragments to control the tests. While it is possible to edit these by hand, in most circumstances it is simpler to use the graphical user interface provided. To do so, navigate to the BCI2000/tools/BCI2000Certification folder, and start the BCI2000Certification.exe program. This program appears as:

[[image:Certificationtool.png|frame|none|The BCI2000Certification user interface.]]

Using a text editor, open the CertificationMain.prm file in the BCI2000/tools/BCI2000Certification/parms/ folder. Many of the settings should be left alone, except for some of the following cases.

====Sampling Rate====
This is set to 512 by default. This can be changed to another value that will apply to all tests, except those that explicitly override it in their own parameter file.

====Display parameters====
These are on the lines that begin with <code>Application:Window</code>. For many labs, the default settings should work fine; the window is setup to appear in the top-left corner of the main window (<code>WindowLeft= 0</code> & <code>WindowTop= 0</code> ), and is 800 wide by 800 pixels tall (<code>WindowWidth= 800</code> & <code>WindowHeight= 800</code> ).

Users with a dual-screen configuration may wish to change this so that the BCI2000 window is on the secondary monitor; to do so, the <code>WindowLeft</code> parameter should be changed, which depends on the resolution and orientation of both monitors. For example, if the 2nd monitor is to the right of the primary monitor, and both monitors have a resolution of 1280x1024 pixels, setting <code>WindowLeft</code> to <code>1280</code> will place the window on the 2nd monitor. Similarly, if the 2nd monitor is to the left of the primary monitor, setting <code>WindowLeft</code> to <code>-1280</code> will accomplish the same thing. If the monitors have different resolutions (e.g., monitor 1 is 1600x1200 and monitor 2 is 1024x768, located to the right of the 1st monitor), the position should change accordingly. For example, in this scenario, to set the window to the right of the main window, set <code>WindowLeft</code> to <code>1600</code> . Finally, set the <code>WindowWidth</code> & <code>WindowHeight</code> to appropriate values for full-screen, if desired. To summarize, for the dual-screen case in which monitor 1 is 1600x1200 pixels, and monitor 2, to the right of 1, is 1024x768 pixels, and the BCI2000 window should be full-screen on monitor 2, the parameters should look like:

<code>Application:Window int WindowWidth= 1024 ... 
Application:Window int WindowHeight= 768 ... 
Application:Window int WindowLeft= 1600 ... 
Application:Window int WindowTop= 0 ... 
</code>
Note that nothing following the ... needs to be changed above in the parameter file.

===Connect the Amplifier to the Trigger Box, and Attach Sensors===
[[Image:connections.png|frame|none|Connections overview]]

This section describes the steps for connecting the necessary hardware. Refer to the Connections Overview figure above for additional information; each step is numbered in this figure.

#Connect the amplifier to the computer; the supported g.tec amps are connected via USB, RS232, or Bluetooth.
#Connect the Digital I/O cable (see bottom of this document) to the amplifier on the Digital I/O port.
#Connect the reference and ground wires from the assembled amplifier cables to the amplifier reference and ground connections.
#Connect the amplifier cables with the safety connectors into channels 1, 2, and 3 on the g.USBamp.
#Connect the digital output line to the channel 1 amplifier cable.
#Connect the A output from the trigger box to the channel 2 amplifier cable.
#Connect the B output from the trigger box to the channel 3 amplifier cable.
#Connect the optical sensor plug to the g.TRIGbox, using the optical sensor input channel A.
#Connect the computer audio output using a stereo cable to the g.TRIGbox, using the high-level input channel B.

===Setup Sensor Thresholds===
The audio and optical sensors each have a threshold setting on the g.TRIGbox, along with an LED indicating whether the current input is above threshold for each channel. At rest, each trigger should be off; if any is on, turn the threshold knob counter-clockwise until the LED is off.

====Audio Threshold====
To set the audio threshold, set audio volume on the computer to maximum. On Windows, to make this process easier in the future, go to the Start menu, click the Control Panel, and go to Sounds. In the Sound window, click the box that puts the volume icon in the task bar. A small speaker should now appear in the bottom-right of the screen in the task bar. Click this icon, and slide the volume up to the max; when you click on this slider, Windows emits a short beep to give an idea of the volume level, which can be used to set the threshold. To do so, make sure that the stereo audio cable is plugged into the g.TRIGbox, and click the slider to emit a sound, checking that the green LED is flashing when you click the slider. If it is not, turn the threshold knob for channel B counter-clockwise, and click the slider again. If it is still not working after several tries, unplug the audio cable from the computer, and check that you can hear the beep through the speakers. If you cannot, make sure that the sound is not muted, and that the sound drivers are properly installed. If you can hear it, plug the audio cable back into the computer audio output (NOT the microphone input), and make sure the g.TRIGbox has power; the light next to the power switch should flash momentarily if the battery levels are OK. You can also use a wall power source (see the g.TRIGbox manual for more information). The threshold is set correctly when the channel B LED is off at rest, and is on when a sound is played.

====Video Threshold====
To set the video threshold, first tape the optical sensor to the monitor in approximately the correct location, based on the information in the latencyTest.prm file for the window position and dimensions. To activate the optical trigger on the g.TRIGbox, drag a white window, such as a Notepad window, in the background under the sensor. Move the threshold knob for channel A until the LED for that channel is just on (i.e., turning it down just a little turns the trigger off). The sensor will be placed more accurately in the following step.

===Starting the Software===
[[image:Certificationtool.png]]
Navigate to BCI2000/tools/BCI2000Certification, and double-click the BCI2000Certification.exe program. The BCI2000 program should start, with the output window in the location specified in the latencyTest.prm file. If there are any errors at startup, the BCI2000 error log will report them. If there are errors, correct them, exit out of the BCI2000Certification.exe program, and restart the program.

===Setting up the Optical Sensor===
Each application has a unique display configuration, where the visual target of interest is located in a specific position on the monitor. Generally, the optical sensor will not likely have to be moved far in between tasks due to the design of the parameter files. However, it is still necessary to ensure that the sensor is in the correct position for each task, and to be able to change the position if necessary. This section describes the process to find the correct location on the monitor for the sensor. To begin, the certification procedure should be started.

====P3Speller====
The P3Speller task has an group of letters arranged into rows and columns. The analysis uses the letter in the 3rd column and 3rd row, which will contain the letter X when the program is run. This location should be very close to that specified for the CursorTask, described above. Fortunately, the arrangement of the letters is shown before the test starts, which allows the sensor to be adjusted if necessary. All of the following default tasks are setup so that the optical sensor does not need to be moved from this position.

====CursorTask====
In the default configuration, the optical sensory does not need to be moved from the position used for the P3Speller task. For custom tests, the flashing object must either be placed under the sensor, or the sensor needs to be moved to the correct position.

====StimulusPresentation====
For the StimulusPresentation tasks, a single large icon appears in the center of the screen, which will be detected by the sensor. The default location of the sensor as defined for the CursorTask should be able to capture the icon on the screen. However, if the task begins and it appears that it is outside the icon location, move the sensor to the middle of the icon. Keep in mind that it may have to be relocated for following tasks.

===Running the Tests===
Once the optical sensor is setup and calibrated for a task, begin the testing process. To start the process, press the Start button in the BCI2000 operator window. At the end of each task, the program will quit automatically, and the next one will start automatically. For each task, press the Start button to begin.

Occasionally, the optical sensor may not be in the exact correct place for a given task.You should be able to see changes in on the video channel (channel 2 by default) in the window showing the recorded channels. If the signal is not changing when it should be (e.g., during the correct visual stimulus), you may try increasing the threshold to catch the stimulus, or you may need to place the sensor in the correct location. To do this, place the sensor in the better location, then quit the current BCI2000 test, and quit the BCI2000Certification program. The procedure will need to be restarted.

When the testing is complete, the BCI2000CertAnalysis program will automatically start. It will analyze the data that have been collected, and return the results in the results.txt file. In general, a Pass or Fail will be written next to a task, and each task component, if it passed or failed the test. For more information on interpreting results, see below.

==BCI2000Certification: Additional Information==
The previous section on Getting Started provided information to quickly setup and run the default tests. This section provides detailed information about each file used, and how to modify the files for your specific system and applications.

===Overview of Important Files===
There are several important files that are used in the BCI2000 Certification procedure. These files and their contents are described in this section.

====BCI2000Certification.ini====
The BCI2000Certification.ini file contains the information that defines each task configuration. It is located in the BCI2000/tools/BCI2000Certification/ folder. It specifies the parameter file, the SignalSource, SignalProcessing, and Application modules, and the analysis definitions for each task. It contains all of the default tests, although it can easily be expanded to include additional or customized task configurations.

Each task is defined by a set of '''case-insensitive''' , space-separated fields, as described below. A * indicates an optional field. The % character indicates a comment, and everything following that character is ignored.

*'''name''' The name of the task, which should be unique. This generally describes the task. It must not contain any spaces. This value determines the path to the saved data file, and the name of the file itself. For example, the name StimulusPresentation_512 would create a file at <code>./Data/StimulusPresentation_512001/StimulusPresentation_512S001R01.dat</code> Example:
**<code>name StimulusPresentation_512</code>

*'''parm'''The BCI2000 *.prm file used for this task. It should be placed in the BCI2000/tools/BCI2000Certification/parms/ folder. Note that the CertificationMain.prm is included in ''all'' configurations by default, and does not need to be listed here. This file contains the information for this specific task configuration. See above for further information.
**<code>parm SimpleAV.prm</code>

*'''source''' The SignalSource module to be used for this test. The g.tec g.USBamp system is used in all configurations by default. If the g.MOBIlab or g.MOBIlab+ are used, the SignalSource module should be changed to the appropriate executable. All BCI2000 executables are located in BCI2000/prog/. Examples:
**<code>'source gUSBampSource.exe'''</code>
**<code>source gMOBIlabSource.exe</code>

*'''sigproc''' The SignalProcessing module that is used for this configuration. This is likely dependent on the application used as well. This program should be located in BCI2000/prog/. Example:
**<code>sigproc P3SignalProcessing.exe</code>

*'''app''' The application for this configuration. This program should be located in BCI2000/prog/. Example:
**<code>app StimulusPresentation.exe</code>

*'''*amp''' This is a single value that gives the channel that is used to compute the amplifier latency. Example:
**<code>amp 0</code>

*'''*dAmp''' This is a single value that specifies a digital input channel that is used to compute the amplifier latency. Example:
**<code>dAmp 15</code>

*'''*vid''' This field is followed by 3 values, that give the channel number that is recording the video output, and the state name and state value to use as a trigger for the comparison. See the example entry for more information. Example:
**<code>vid 1 StimulusCode 1</code>

*'''*aud''' This field is followed by 3 values, that give the channel number that is recording the audio output, and the state name and state value to use as a trigger for the comparison. See the example entry for more information. Example:
**<code>aud 1 StimulusCode 1</code>

*'''skip''' Entering '''skip''' will cause this task to not be run or analyzed. This is used to reduce the number of tasks that are run, which helps to repeat individual tasks that may have had problems in previous sessions.

*'''end''' This must come at the end of each task definition.

In addition to task-specific entries, there are several global entries that will apply to every task, unless explicitly overwritten in that task. This allows the user to quickly change settings for all tasks simultaneously, e.g., if tests will be run using a g.tec g.USBamp for one set of tests, and a g.tec g.MOBIlab for another. Global entries must be defined at the beginning of the BCI2000Certification.ini file outside of the task definitions. These entries are defined as:

*'''source''' The SourceModule to be used for all tests, unless explicitly overwritten by an individual task. Otherwise identical to the '''source''' definition in a task entry.
*'''export''' This entry does not use any other parameters on the line on which it is defined. If '''export''' is present in the BCI2000Certification.ini file, test results will be written to a comma-separated-value (CSV) text file that is located in the folder where data is saved for each task. For example, if the data folder is BCI2000/tools/BCI2000Certification/latencyData/, then the export file for the SimpleTarget task will be placed in the folder BCI2000/tools/BCI2000Certification/latencyData/SimpleTarget.

Here is a full example entry that includes two tasks.

<pre>
source gUSBampSource
export

name StimulusPresentation_512
parm StimulusPresentation_512.prm
sigproc P3SignalProcessing
app StimulusPresentation
amp 0
dAmp 15
vid 1 StimulusCode 3
aud 2 StimulusCode 3
end

name CursorTask_1200
parm CursorTask_1200.prm
source gMOBIlab
sigproc ARSignalProcessing
app CursorTask
amp 0
dAmp 15
vid 1 TargetCode 1
end
</pre>

The <code>StimulusPresentation</code> task uses the <code>gUSBampSource</code> source module, and records block-triggered digital outputs on channel 0, video output triggered off of stimulus code 3 on channel 1, and audio output triggered off of stimulus code 3 on channel 2. The <code>SimpleTarget</code> tasks overrides the global <code>source</code> entry, and uses its own <code>source</code> definition, specifying that a gMOBIlab should be used for acquisition instead of a gUSBamp. Finally, the <code>export</code> entry is set at the beginning, so test results for all files are output to a CSV file.

The BCI2000Certification.ini file contains many task definitions. Each entry is read by the BCI2000Certification.exe program, and is entered as a separate task to be run and then analyzed.

====BCI2000Certification.cfg====
The latencyTest.prm file is located in the BCI2000/tools/BCI2000Certification/ folder. It contains many default settings and definitions that determine how the results are interpreted, and should generally not be changed by the user. The timing definitions provide the absolute maximum latencies in ms for each step in the system chain, and include the Amp, ProcLat, VidOut, AudOut, VidSys, AudSys, and Jitter (see below for explanations). Timing definitions can include either one or two fields; the first field is mandatory, and is the mean value in ms, while the second field is optional, and is the standard deviation in ms.

*'''Amp''' The amplifier latency.
*'''ProcLat''' The processing latency.
*'''VidOut''' The video output latency.
*'''AudOut''' The audio output latency.
*'''VidSys''' The video system latency.
*'''AudSys''' The audio system latency.
*'''Jitter''' The system jitter. This is the difference, in ms, between the actual block duration and theoretical block duration, which is determined by the block size.
*'''Threshold Source Value''' This is the threshold defined for a specific SignalSource module. Individual amplifiers may have different input ranges, resulting in recording signals with different ranges of magnitude. The '''Source''' entry is a value in mV. For example, the threshold setting for the g.USBamp is '''Threshold gUSBampSource 12.5''' .
*'''ResultOut''' This is the file that contains the testing results.
*'''DataDir''' The default data directory. It defaults to latencyData in the BCI2000/tools/BCI2000Certification/ folder.

These values should not generally be changed by the user, although they may be updated in future BCI2000 versions.

====CertificationMain.prm====
This parameter file contains some of the default task parameters common to every test, including the save location, monitor configuration, sampling rate, and visualization settings. Note that these parameters can be overwritten in the *.prm files for each individual test configuration.

====BCI2000Certification.exe====
This file controls the execution of each task. It parses the BCI2000Certification.ini and BCI2000Certification.cfg files to determine which files and tasks to run, and controls the CPU load monitor. When all tasks are complete, this program calls the BCI2000Analysis.exe program to handle the analysis of the collected data.

====BCI2000CertAnalysis.exe====
This program analyzes the data collected, and reports results to a data file. It uses the DataDir parameter in the BCI2000Certification.cfg file to determine where the data is located. Results are output to results.txt in the BCI2000/tools/BCI2000Certification/ folder.

====Parameter Files====
Each task should have it's own parameter file that contains the unique configuration and settings for that task. For example, there may be several configurations that use the g.USBamp, ARSignalProcessing, and CursorTask, each with its own parameter file. These files end in .prm, and are placed in the BCI2000/tools/BCI2000Certification/parms/ folder.

===Interpreting Results===
Results are recorded to the BCI2000/tools/BCI2000Certification/results.txt file. The results for each task, and each applicable latency tested, are reported here. If the entire task passed, then each test performed met the minimum timing requirements specified in the BCI2000Certification.cfg file. If one or more did not pass, then the specific test that did not pass the test has Fail written next to it.

====What if a Task Did Not Pass?====
TO BE ADDED.

==Certification Protocol==
This section describes how the testing protocol is run, the various components involved in the certification analysis, and how to interpret results.

===Running the Tests===
The certification protocol consists of running several BCI2000 applications in multiple configurations to determine if each application meets the minimum requirements for BCI2000, and to determine if individual configurations of an application meet the requirements. For example, the CursorFeedback task may be tested with several combinations of sampling rates, sample block sizes, and processed channels, only some of which may work with a given computer setup.

The testing set is run from a single batch file called LatencyAnalysis.bat. This file is located in the folder BCI2000/tools/BCI2000Certification/batch. This batch file executes additional batch files in this folder, each corresponding to a different application configuration. Each of these batch files starts the Operator module, automatically loading multiple parameter files used for a given configuration. There is a general-purpose parameter file called latencyTest.prm that all configurations use. This file configures the save location for all latency tests, as well as default window positions and sampling rates. A second parameter file is passed to the operator that contains the parameters for a unique application configuration. After starting the operator module, the batch file starts the SignalSource module, SignalProcessing module, and Application module. The loaded configuration is set automatically, and the user needs only to press the start button to start the analysis.

==Software Templates==
This describes how to implement the testing protocols for your own amplifier system and custom applications. This is useful for determining if your hardware setup and software is capable of maintaining an acceptable level of performance for real-time testing.

===Amplifier Latency===
The amplifier latency requires an output that can be recorded by the amplifier. In the case of the g.USBamp, a digital output line is used, although either analog or digital outputs could be used in a system.

In the SignalSource module code for your custom amp, find the Process function. Near the beginning of this function, before any data is acquired, set the output signal to 0, either a digital low or analog value of 0 V. This will be dependent on the particular amplifier and API used; for the g.USBamp, this function call looks like:
 <code>
GT_SetDigitalOut ( m_hdev.at(0), (UCHAR)1, (UCHAR)0);
</code> 

This sets the digital output 1 on device 0 to a value of 0.

At the end of the Process function, the output should be set to a high level. A similar function call will be used to above, only the value is 1 instead of 0; again, the function will be dependent on the system used, and whether analog or digital output is used. Here is the code for the g.USBamp:
 <code>
GT_SetDigitalOut ( m_hdev.at(0), (UCHAR)1, (UCHAR)1);
</code> 

This sets the digital output 1 on device 0 to a value of 1.

===Visual and Audio Latency===
Developing new video and optical latency tests does not necessarily require adding additional code to existing modules (beyond any customization already done).

==Supported Hardware==
A list of officially supported hardware configurations, and suggested minimum requirements is provided.

===Supported and Tested Hardware===
====Amplifiers====

*g.USBamp
*gMOBIlab (Serial RS232)
*gMOBIlab (Bluetooth)
*TDT Pentusa (RX5)

===Minimum Requirements===
This table shows the minimum requirements for running BCI2000.

{| border="1"
|+ Minimum System Requirements for BCI2000
! CPU
| 1 GHz
|-
! RAM
|512 MB (dependent on OS; 1 GB for Windows Vista)
|-
! Video Card
|32 MB VRam; Hardware OpenGL Support
|-
! Sound Card
|
|-
! Monitor
|
|-
! OS
|Windows 2000; Windows XP SP2 or Greater; Windows Vista
|}

===Voltage Divider & Amplifier Input===
Parts List:

*4 Male Mono Audio Connectors
*6 12in Safety Connector Wires (to USB amplifier input), different colors
*4 3in Wires
*Soldering Iron and Solder
*resistors for voltage dividers
This section describes how to assemble cables that connect the output of the g.TRIGbox to the amplifier input channels.

Strip the free ends of all 6 safety connector wires, about <math>\frac{1}{4}</math> in. If you are not using voltage dividers, solder 4 of the wires directly to the center signal connection on the 4 mono audio connectors. Cover the connection.

[[Image:ampPlug_1.png|frame|none|g.USBamp Amplifier Plug]]

Next, twist the two remaining safety connector wire ends together, and solder them together. Solder the 4 short wires to the ground connections on the mono plugs. Finally, solder the 4 ground wires to the two safety connector wires that were twisted together and soldered previously, as shown here.

[[Image:ampPlugs_2.png|frame|none|g.USBamp Amplifier Plugs]]

These plugs can plug directly into the g.TRIGbox outputs, and the safety connectors plug into the channels 1-4 inputs on the g.USBamp; the ground wires plug into the ground and reference on the g.USBamp.

===Digital I/O Cable===

Parts List:

*3 Colored Wires
*7-Pin Digital Connector from g.tec
*Soldering Iron and Solder
*Silicone or electrical tape for insulation
*1 Female Mono Audio Plug

In order to access the digital I/O pins on the g.USBamp, a connector needs to be assembled. The 7-pin digital I/O connector should be ordered through g.TEC, the manufacturer of the g.USBamp.

At least three wires are needed for the circuit, which connect to the digital output 1 pin, the digital input 0 pin, and the ground pin.
[[Image:DigIO.png|frame|none|g.USBamp Digital I/O Pins]]

To start, cut three 10 in wires, preferably with different colors to differentiate between the signal and ground wires. Cut back a small portion of the ground wire, and solder it to the center ground pin on the connector. Now, find the top of the connector by locating the small plastic notch, and locate pins 3 and 4 relative to the notch. Solder one wire to pin 3, and the remaining wire to pin 4. It may be helpful to insulate the wires from the casing using either a piece of black electrical tape, or an insulating gel, like silicone. If a gel is used, be sure to let it set for several hours or overnight. It is also probably a good idea to check the electrical connection with a multimeter prior to insulating.

[[Image:digConnector.png|frame|none|g.USBamp Digital I/O Pins]]

Next, attach the rubber sleeve over the end of the part with the female threads, as shown in the panel. Slide the smaller metal sleeve over the wires, then slide the larger rubber sleeve over the wires.

For the next step, attach the two metallic pieces that surround the cables, shown laying to the sides below. One of the metal pieces has a small groove in it, which should be placed over the notch on the connector; the other metal piece fits on the opposite side of the connector. Push the small metal sleeve up to the side piece with the groove, and rotate the sleeve until the notch fits in the groove.

Place the end piece over the connector, with the red dot on top and aligned with the connector notch. Finally, slide the rubber sleeve over the connector, and screw the sleeve into the end piece.

[[Image:finalDigCable.png|frame|none|g.USBamp Digital I/O Cable]]

The plug is assembled next. Solder the signal wire from Pin 3 (Digital Out 1) on the digital I/O connector to the signal connector on the female mono plug, and solder the ground wire to the outer ground connector on the plug. The below figure shows this; in this figure, the red wire is the signal wire, and the brown wire is the ground.

[[Image:digPlug.png|frame|none|g.USBamp Digital Wire Plug]]

User Reference:BCI2000Certification

2009-05-26T14:52:34Z

Awilson: /* Starting the Software */

==Introduction==
BCI2000 v2.0 and higher includes a certification procedure that can determine whether a computer system is capable of running all or some BCI2000 applications. Because BCI2000 does not have a standardized hardware configuration, i.e., it can run on potentially ''any'' PC, this testing procedure is capable of running on any PC with BCI2000, with the results reporting which standard BCI2000 applications meet the minimum timing requirements. Different configurations are included in the certification procedure to test a range of likely setups for a given application, in which timing characteristics such as the sampling rate, inter-stimulus intervals, and stimulus duration, and other parameters, such as the number and size of the stimuli, are changed for each configuration.

This document serves as the instruction manual for using the certification procedure, and describes how the procedure works to determine the timing characteristics of the BCI2000 system. The primary use for the certification procedure is to determine if the PC configuration used with BCI2000 is capable of running the core BCI2000 system, which is comprised of:

*Support for the the g.tec series of amplifiers, including the g.USBamp, g.MOBIlab, and the g.MOBIlab+ (bluetooth) amplifiers.
*The AR, P3, FFT, and Matlab signal processing modules.
*The CursorTask, P3Speller, and StimulusPresentation application modules.

Additionally, due to the extensibility of BCI2000, researchers who develop custom algorithms and applications, or use amplifiers not made by g.tec, can use the certification procedure to determine whether their custom modules are capable of running on a particular PC configuration.

The certification procedure works by comparing the differences in time of when BCI2000 ''expects'' an event to occur to when that event ''actually'' occurred. These events include a change in the display, an audio output through the system speakers, or an EEG sample being stored in the amplifier buffer. The times at which such events occur are recorded with the amplifier and stored in a data file. Changes in the display are found using an optical sensor in combination with the g.TRIGbox. The g.TRIGbox is a signal conditioner that generates trigger pulses for various sensors or input signals. When the sensor exceeds a threshold, the g.TRIGbox outputs a digital signal which is recorded on the amplifier. A similar procedure is used for audio detection: the sound output from the PC is input to the g.TRIGbox, and when the volume exceeds threshold, a high digital signal is output and recorded by the amplifier. This information can be used because BCI2000 stores a time-stamp for every event during an experiment. The difference between a time-stamp value and the time that the recorded event changes values are compared to find the latency for that particular event.

These latencies can be affected by many external influences, including hardware deficiencies (such as low RAM, slow CPU speed, or a video card of low quality), and other software running in the background while the experiment is being run.

==Latencies==
Briefly, the different latencies inherent in the BCI2000 system include amplifier latency, processing latency, output latency, and the sum of these, the system latency. Additionally, the block duration jitter will be measured. The figure below provides a timeline of events that occur within a single block of data, with significant time points labeled. This figure provides an accurate account of the order in which events occur within a block of data, although the time intervals are not necessarily to scale.


[[Image:timeline3.png|frame|none|Timeline of events. Time intervals are not to scale.]]

===Defining Latencies===
====Amplifier Latency====
Amplifier Latency is the minimum delay between the time that a signal is presented at the amplifier input, to when it has been acquired in the source module. Depending on configuration, this may comprise physical signal delay in the amplifier, digitization, transmission from the amplifier to the PC, and processing time inside a hardware driver. That minimum delay occurs for the last sample of a data block, which, unlike its preceding samples in the same block, will spend only a minimum time in hardware and software buffers. In [[#TimeLine|Timeline]],

Amplifier latency = <math>t_{0}-t_{-1}</math>.

For amplifiers connected via bandwidth-limited serial interfaces, transmission latency may have a measurable impact on amplifier latency, depending on the hardware. When using USB 2.0, as is the case for the g.USBamp, transmission latency may generally neglected, as illustrated by the following example: USB 2.0 has a maximum transmission rate of 480 Mbit/s. If we are acquiring 16 channels of 32-bit data, and transmitting in blocks of 16 samples, this is 8192 bits of data; at USB 2.0 speed, this should take roughly 17 <math>\mu</math>s to transfer. However, a more realistic approximation for USB 2.0 speeds is 240 Mbit/s, which increases the transfer delay to 34 <math>\mu</math>s. For sampling rates below 30 kHz, this is less than a single sample's duration.

In addition to amplifier latency, system performance will be influenced by buffering latency. Buffering latency is dependent on the sample block buffer size: When a data sample is digitized, it is not immediately transferred to the PC, but is stored in memory on the amplifier. The PC then makes the appropriate request to the amplifier, and a block of data is transferred all at once to reduce the processing load. This implies that a signal that is digitized at the start of the buffer must wait until the buffer is full to be read into the PC. For example, if the sample block size is 16 samples, the first sample must wait 15 more samples before it can be used in the application. Fortunately, this latency is always known, and can be reduced with a higher sampling rate and/or smaller block sizes, assuming the PC can handle the increased overhead. Buffering latency does not affect the acquisition-to-display latency, because processing occurs immediately after a block's last sample, which is not affected. Still, it is an important factor to keep in mind, because a large sample block size and/or a small sample rate will decrease the refresh rate for the application (e.g., at a sample rate of 256 Hz and a sample block size of 128 samples, the application will only be refreshed every 0.5 s.)

====Processing Latency====
Processing Latency is the total time it takes for the data to be processed by all BCI2000 modules (SignalSource, SignalProcessing, and Application).

Processing latency = <math>t_{2}-t_{0}</math>.

Processing latency strongly depends on CPU speed, and if this latency becomes too large, high CPU load will probably be the cause, implying decreased or unsuitable BCI2000 performance.

====Output Latency====
Output Latency is the latency from the time that the Application module issues a command to change the display or issue a sound (or another output), to the time that this output actually occurs.

Output latency = <math>t_{3}-t_{2}</math>.

====System Latency====
System Latency is the minimum time interval between a change in amplifier input, and a causally related change in application output. This is the sum of the above latencies, Amplifier, Processing, and Output.

System latency = <math>t_{3} - t_{-1}</math>.

====Block Duration, Block Duration Jitter====
Block Duration is the time interval between adjacent blocks of data, normalized to the ideal duration of a data block as determined from sampling rate and sample block size:

Block Duration = <math>\frac{t_{5}-t_{0}}{\mathrm{SampleBlockSize}/\mathrm{SamplingRate}}</math>.

When the system operates in real time, mean Block Duration will always be 1. Measuring Block Duration has the purpose of obtaining Block Duration Jitter as its standard deviation.

===Measuring Latencies===
The procedure for measuring the system latencies are below. In general, a combination of recorded events and software time-stamps recorded in BCI2000 data files to determine when important events occur, with ms or better time resolution.
[[Image:OutTimeline1.png|thumb|500px|none|Recorded events used for measuring latencies.]]

====Measuring Amplifier Latency====
In [[#TimeLine|TimeLine]], Amplifier Latency is the time interval between the sampling of a data block's last sample, and its acquisition into the source module's data buffer:
<center><math>
\mathrm{AmplifierLatency} = t_{0} - t_{-1}
</math></center>

To measure this latency, the Source module will set a digital output on the amplifier to a high value at time <math>t_0</math> immediately following data acquisition, as indicated in [[#overview|Overview]]. The digital output level is 3.3 V, so a voltage divider may required to attenuate the signal level to the range of amplifier input. This signal is then recorded on an input channel on the amplifier (time <math>t_{1}</math>).

In the recorded data, we may then identify <math>t_{-1}</math>, which is the beginning of sample block <math>n</math>, by its sample offset, which also coincides with BCI2000 state changes. <math>t_1</math> may be identified by a change in the recorded signal, occurring in the channel that was connected to the digital output during measurement.
<center><math>
\mathrm{AmplifierLatency} \approx t_{0} - t_{-1}.
</math></center>

====Measuring Processing Latency====
The processing latency is defined as the amount of time that it takes for the computer to process the data after acquiring it, to when the application module output is changed. In [[#TimeLine|TimeLine]], this is the time from <math>t_{0}</math> to <math>t_{2}</math>. Processing latency is calculated using two timestamps saved with every block of data, <math>SourceTime</math> and <math>StimulusTime</math>. <math>SourceTime</math> is saved at <math>t_0</math>, immediately following data acquisition in the Source module, and <math>StimulusTime</math> is saved at <math>t_2</math> immediately following application presentation in the Application module. Therefore, processing latency for each block of data is calculated as the difference between time stamps:

<center><math>
\mathrm{Processing Latency} = \mathrm{StimulusTime} - \mathrm{SourceTime} = t_{2} - t_{0}.
</math></center>

====Measuring Application Output Latency====

There are many possible application output types, including visual (i.e., the computer screen), audio, or mechanical (e.g., a robotic arm). The core BCI2000 system primarily uses visual and audio output, and so the default testing system will focus on these.

Both visual and audio output can be measured using the g.TRIGbox signal conditioner, which accepts inputs from optical sensors, microphones, or any other input. The user sets a threshold for the input signals, and the g.TRIGbox outputs a digital pulse whenever this threshold is exceeded. This output is then recorded back into the amplifier system, so that the analysis program can measure the response times for each output.

We identify event <math>t_0</math> by a change in the data channel connected to the amplifier's digital output, and event <math>t_3</math> by a change in the data channel connected to the g.TRIGbox, and compute their difference. Also, both events are affected by Amplifier Latency in the same way, so we may ignore Amplifier Latency, and have
<center><math>\begin{matrix}
\mathrm{Output Latency} = t_{3} - t_{2} = (t_3-t_0)-(t_2-t_0) = (t_3-t_0)-\mathrm{ProcessingLatency}.
\end{matrix}</math></center>

====Measuring System Latency====
As defined above, System Latency is the sum of Amplifier Latency, Processing Latency, and Output Latency. It is important to realize that the system latency is dependent on the output modality used, i.e., the video system latency and the audio system latency will vary on the same system due to the differences in output latencies.
The system latency may be measured
#directly, by identifying <math>t_{-1}</math> as the beginning of a data block by its sample index, and <math>t_3</math> by the signal change in the channel connected to the g.TRIGbox, and then calculating <math>\textrm{SystemLatency}=t_3-t_{-1}</math>,
#or indirectly, by using the previously measured quantities <math>\textrm{SystemLatency}=\mathrm{AmplifierLatency}+\mathrm{ProcessingLatency}+\mathrm{OutputLatency}</math>.

====Measuring Block Duration====
Block Duration is measured as the time between adjacent blocks of data, divided by the theoretical ideal value, which is the sample block duration. For the actual measurement, we use the difference between subsequent <math>\textrm{SourceTime}</math> time stamps which are recorded at <math>t_0</math> and <math>t_8</math> in [[#TimeLine|Timeline]]:

<center><math>
\mathrm{BlockDuration} = \frac{t_{5} - t_{0}}{\mathrm{SampleBlockSize}/\mathrm{SamplingRate}}
=\frac{\Delta \mathrm{SourceTime}}{\mathrm{SampleBlockSize}/\mathrm{SamplingRate}}
</math></center>

===Latency Calculation Overview===
Latencies are calculated by comparing changes in a BCI2000 state value to changes in a recorded signal. The analysis program follows these general steps in calculating the various latencies:

#Determine which threshold values to use based on the ''thresh'' definition in the BCI2000Certification.cfg file, which defines a threshold based on the amplifier used. For example, the g.USBamp has an input range of -250 mV to + 250 mV, and the g.TRIGbox outputs from 0 to 200 mV, so the threshold used is about 12.5 mV.
#Traverse the state values for a selected state and find where the state changes from 0 to a given value (or any value). The sample at which this occurs is saved for later use in <math>stateChangePos</math>.
#When this occurs, start looking through <math>Signal_{norm}</math> to find when a rising edge exceeds the determined threshold value. The sample at which this occurs is saved in <math>sigChangePos</math>.
#The latency for the <math>n</math>th state change is calculated as:
#:<center><math>\begin{matrix}
latency_n = \frac{sigChangePos_n-stateChangePos_n}{SampleRate}
\end{matrix}</math></center>
#:and is stored in an array.
#Once the entire state vector is traversed, the mean, standard deviation, minimum and maximum values for this latency are calculated and reported.

==Getting Started With the Default Tests==
This section provides step-by-step instructions on running the default certification procedure. Note that some cables must be assembled before the testing can be done; see the end of this document for information on assembling the cables.

===Set Default Parameters===
Using a text editor, open the CertificationMain.prm file in the BCI2000/tools/BCI2000Certification/parms/ folder. Many of the settings should be left alone, except for some of the following cases.

====Sampling Rate====
This is set to 512 by default. This can be changed to another value that will apply to all tests, except those that explicitly override it in their own parameter file.

====Display parameters====
These are on the lines that begin with <code>Application:Window</code>. For many labs, the default settings should work fine; the window is setup to appear in the top-left corner of the main window (<code>WindowLeft= 0</code> & <code>WindowTop= 0</code> ), and is 800 wide by 800 pixels tall (<code>WindowWidth= 800</code> & <code>WindowHeight= 800</code> ).

Users with a dual-screen configuration may wish to change this so that the BCI2000 window is on the secondary monitor; to do so, the <code>WindowLeft</code> parameter should be changed, which depends on the resolution and orientation of both monitors. For example, if the 2nd monitor is to the right of the primary monitor, and both monitors have a resolution of 1280x1024 pixels, setting <code>WindowLeft</code> to <code>1280</code> will place the window on the 2nd monitor. Similarly, if the 2nd monitor is to the left of the primary monitor, setting <code>WindowLeft</code> to <code>-1280</code> will accomplish the same thing. If the monitors have different resolutions (e.g., monitor 1 is 1600x1200 and monitor 2 is 1024x768, located to the right of the 1st monitor), the position should change accordingly. For example, in this scenario, to set the window to the right of the main window, set <code>WindowLeft</code> to <code>1600</code> . Finally, set the <code>WindowWidth</code> & <code>WindowHeight</code> to appropriate values for full-screen, if desired. To summarize, for the dual-screen case in which monitor 1 is 1600x1200 pixels, and monitor 2, to the right of 1, is 1024x768 pixels, and the BCI2000 window should be full-screen on monitor 2, the parameters should look like:

<code>Application:Window int WindowWidth= 1024 ... 
Application:Window int WindowHeight= 768 ... 
Application:Window int WindowLeft= 1600 ... 
Application:Window int WindowTop= 0 ... 
</code>
Note that nothing following the ... needs to be changed above in the parameter file.

===Connect the Amplifier to the Trigger Box, and Attach Sensors===
[[Image:connections.png|frame|none|Connections overview]]

This section describes the steps for connecting the necessary hardware. Refer to the Connections Overview figure above for additional information; each step is numbered in this figure.

#Connect the amplifier to the computer; the supported g.tec amps are connected via USB, RS232, or Bluetooth.
#Connect the Digital I/O cable (see bottom of this document) to the amplifier on the Digital I/O port.
#Connect the reference and ground wires from the assembled amplifier cables to the amplifier reference and ground connections.
#Connect the amplifier cables with the safety connectors into channels 1, 2, and 3 on the g.USBamp.
#Connect the digital output line to the channel 1 amplifier cable.
#Connect the A output from the trigger box to the channel 2 amplifier cable.
#Connect the B output from the trigger box to the channel 3 amplifier cable.
#Connect the optical sensor plug to the g.TRIGbox, using the optical sensor input channel A.
#Connect the computer audio output using a stereo cable to the g.TRIGbox, using the high-level input channel B.

===Setup Sensor Thresholds===
The audio and optical sensors each have a threshold setting on the g.TRIGbox, along with an LED indicating whether the current input is above threshold for each channel. At rest, each trigger should be off; if any is on, turn the threshold knob counter-clockwise until the LED is off.

====Audio Threshold====
To set the audio threshold, set audio volume on the computer to maximum. On Windows, to make this process easier in the future, go to the Start menu, click the Control Panel, and go to Sounds. In the Sound window, click the box that puts the volume icon in the task bar. A small speaker should now appear in the bottom-right of the screen in the task bar. Click this icon, and slide the volume up to the max; when you click on this slider, Windows emits a short beep to give an idea of the volume level, which can be used to set the threshold. To do so, make sure that the stereo audio cable is plugged into the g.TRIGbox, and click the slider to emit a sound, checking that the green LED is flashing when you click the slider. If it is not, turn the threshold knob for channel B counter-clockwise, and click the slider again. If it is still not working after several tries, unplug the audio cable from the computer, and check that you can hear the beep through the speakers. If you cannot, make sure that the sound is not muted, and that the sound drivers are properly installed. If you can hear it, plug the audio cable back into the computer audio output (NOT the microphone input), and make sure the g.TRIGbox has power; the light next to the power switch should flash momentarily if the battery levels are OK. You can also use a wall power source (see the g.TRIGbox manual for more information). The threshold is set correctly when the channel B LED is off at rest, and is on when a sound is played.

====Video Threshold====
To set the video threshold, first tape the optical sensor to the monitor in approximately the correct location, based on the information in the latencyTest.prm file for the window position and dimensions. To activate the optical trigger on the g.TRIGbox, drag a white window, such as a Notepad window, in the background under the sensor. Move the threshold knob for channel A until the LED for that channel is just on (i.e., turning it down just a little turns the trigger off). The sensor will be placed more accurately in the following step.

===Starting the Software===
[[image:Certificationtool.png]]
Navigate to BCI2000/tools/BCI2000Certification, and double-click the BCI2000Certification.exe program. The BCI2000 program should start, with the output window in the location specified in the latencyTest.prm file. If there are any errors at startup, the BCI2000 error log will report them. If there are errors, correct them, exit out of the BCI2000Certification.exe program, and restart the program.

===Setting up the Optical Sensor===
Each application has a unique display configuration, where the visual target of interest is located in a specific position on the monitor. Generally, the optical sensor will not likely have to be moved far in between tasks due to the design of the parameter files. However, it is still necessary to ensure that the sensor is in the correct position for each task, and to be able to change the position if necessary. This section describes the process to find the correct location on the monitor for the sensor. To begin, the certification procedure should be started.

====P3Speller====
The P3Speller task has an group of letters arranged into rows and columns. The analysis uses the letter in the 3rd column and 3rd row, which will contain the letter X when the program is run. This location should be very close to that specified for the CursorTask, described above. Fortunately, the arrangement of the letters is shown before the test starts, which allows the sensor to be adjusted if necessary. All of the following default tasks are setup so that the optical sensor does not need to be moved from this position.

====CursorTask====
In the default configuration, the optical sensory does not need to be moved from the position used for the P3Speller task. For custom tests, the flashing object must either be placed under the sensor, or the sensor needs to be moved to the correct position.

====StimulusPresentation====
For the StimulusPresentation tasks, a single large icon appears in the center of the screen, which will be detected by the sensor. The default location of the sensor as defined for the CursorTask should be able to capture the icon on the screen. However, if the task begins and it appears that it is outside the icon location, move the sensor to the middle of the icon. Keep in mind that it may have to be relocated for following tasks.

===Running the Tests===
Once the optical sensor is setup and calibrated for a task, begin the testing process. To start the process, press the Start button in the BCI2000 operator window. At the end of each task, the program will quit automatically, and the next one will start automatically. For each task, press the Start button to begin.

Occasionally, the optical sensor may not be in the exact correct place for a given task.You should be able to see changes in on the video channel (channel 2 by default) in the window showing the recorded channels. If the signal is not changing when it should be (e.g., during the correct visual stimulus), you may try increasing the threshold to catch the stimulus, or you may need to place the sensor in the correct location. To do this, place the sensor in the better location, then quit the current BCI2000 test, and quit the BCI2000Certification program. The procedure will need to be restarted.

When the testing is complete, the BCI2000CertAnalysis program will automatically start. It will analyze the data that have been collected, and return the results in the results.txt file. In general, a Pass or Fail will be written next to a task, and each task component, if it passed or failed the test. For more information on interpreting results, see below.

==BCI2000Certification: Additional Information==
The previous section on Getting Started provided information to quickly setup and run the default tests. This section provides detailed information about each file used, and how to modify the files for your specific system and applications.

===Overview of Important Files===
There are several important files that are used in the BCI2000 Certification procedure. These files and their contents are described in this section.

====BCI2000Certification.ini====
The BCI2000Certification.ini file contains the information that defines each task configuration. It is located in the BCI2000/tools/BCI2000Certification/ folder. It specifies the parameter file, the SignalSource, SignalProcessing, and Application modules, and the analysis definitions for each task. It contains all of the default tests, although it can easily be expanded to include additional or customized task configurations.

Each task is defined by a set of '''case-insensitive''' , space-separated fields, as described below. A * indicates an optional field. The % character indicates a comment, and everything following that character is ignored.

*'''name''' The name of the task, which should be unique. This generally describes the task. It must not contain any spaces. This value determines the path to the saved data file, and the name of the file itself. For example, the name StimulusPresentation_512 would create a file at <code>./Data/StimulusPresentation_512001/StimulusPresentation_512S001R01.dat</code> Example:
**<code>name StimulusPresentation_512</code>

*'''parm'''The BCI2000 *.prm file used for this task. It should be placed in the BCI2000/tools/BCI2000Certification/parms/ folder. Note that the CertificationMain.prm is included in ''all'' configurations by default, and does not need to be listed here. This file contains the information for this specific task configuration. See above for further information.
**<code>parm SimpleAV.prm</code>

*'''source''' The SignalSource module to be used for this test. The g.tec g.USBamp system is used in all configurations by default. If the g.MOBIlab or g.MOBIlab+ are used, the SignalSource module should be changed to the appropriate executable. All BCI2000 executables are located in BCI2000/prog/. Examples:
**<code>'source gUSBampSource.exe'''</code>
**<code>source gMOBIlabSource.exe</code>

*'''sigproc''' The SignalProcessing module that is used for this configuration. This is likely dependent on the application used as well. This program should be located in BCI2000/prog/. Example:
**<code>sigproc P3SignalProcessing.exe</code>

*'''app''' The application for this configuration. This program should be located in BCI2000/prog/. Example:
**<code>app StimulusPresentation.exe</code>

*'''*amp''' This is a single value that gives the channel that is used to compute the amplifier latency. Example:
**<code>amp 0</code>

*'''*dAmp''' This is a single value that specifies a digital input channel that is used to compute the amplifier latency. Example:
**<code>dAmp 15</code>

*'''*vid''' This field is followed by 3 values, that give the channel number that is recording the video output, and the state name and state value to use as a trigger for the comparison. See the example entry for more information. Example:
**<code>vid 1 StimulusCode 1</code>

*'''*aud''' This field is followed by 3 values, that give the channel number that is recording the audio output, and the state name and state value to use as a trigger for the comparison. See the example entry for more information. Example:
**<code>aud 1 StimulusCode 1</code>

*'''skip''' Entering '''skip''' will cause this task to not be run or analyzed. This is used to reduce the number of tasks that are run, which helps to repeat individual tasks that may have had problems in previous sessions.

*'''end''' This must come at the end of each task definition.

In addition to task-specific entries, there are several global entries that will apply to every task, unless explicitly overwritten in that task. This allows the user to quickly change settings for all tasks simultaneously, e.g., if tests will be run using a g.tec g.USBamp for one set of tests, and a g.tec g.MOBIlab for another. Global entries must be defined at the beginning of the BCI2000Certification.ini file outside of the task definitions. These entries are defined as:

*'''source''' The SourceModule to be used for all tests, unless explicitly overwritten by an individual task. Otherwise identical to the '''source''' definition in a task entry.
*'''export''' This entry does not use any other parameters on the line on which it is defined. If '''export''' is present in the BCI2000Certification.ini file, test results will be written to a comma-separated-value (CSV) text file that is located in the folder where data is saved for each task. For example, if the data folder is BCI2000/tools/BCI2000Certification/latencyData/, then the export file for the SimpleTarget task will be placed in the folder BCI2000/tools/BCI2000Certification/latencyData/SimpleTarget.

Here is a full example entry that includes two tasks.

<pre>
source gUSBampSource
export

name StimulusPresentation_512
parm StimulusPresentation_512.prm
sigproc P3SignalProcessing
app StimulusPresentation
amp 0
dAmp 15
vid 1 StimulusCode 3
aud 2 StimulusCode 3
end

name CursorTask_1200
parm CursorTask_1200.prm
source gMOBIlab
sigproc ARSignalProcessing
app CursorTask
amp 0
dAmp 15
vid 1 TargetCode 1
end
</pre>

The <code>StimulusPresentation</code> task uses the <code>gUSBampSource</code> source module, and records block-triggered digital outputs on channel 0, video output triggered off of stimulus code 3 on channel 1, and audio output triggered off of stimulus code 3 on channel 2. The <code>SimpleTarget</code> tasks overrides the global <code>source</code> entry, and uses its own <code>source</code> definition, specifying that a gMOBIlab should be used for acquisition instead of a gUSBamp. Finally, the <code>export</code> entry is set at the beginning, so test results for all files are output to a CSV file.

The BCI2000Certification.ini file contains many task definitions. Each entry is read by the BCI2000Certification.exe program, and is entered as a separate task to be run and then analyzed.

====BCI2000Certification.cfg====
The latencyTest.prm file is located in the BCI2000/tools/BCI2000Certification/ folder. It contains many default settings and definitions that determine how the results are interpreted, and should generally not be changed by the user. The timing definitions provide the absolute maximum latencies in ms for each step in the system chain, and include the Amp, ProcLat, VidOut, AudOut, VidSys, AudSys, and Jitter (see below for explanations). Timing definitions can include either one or two fields; the first field is mandatory, and is the mean value in ms, while the second field is optional, and is the standard deviation in ms.

*'''Amp''' The amplifier latency.
*'''ProcLat''' The processing latency.
*'''VidOut''' The video output latency.
*'''AudOut''' The audio output latency.
*'''VidSys''' The video system latency.
*'''AudSys''' The audio system latency.
*'''Jitter''' The system jitter. This is the difference, in ms, between the actual block duration and theoretical block duration, which is determined by the block size.
*'''Threshold Source Value''' This is the threshold defined for a specific SignalSource module. Individual amplifiers may have different input ranges, resulting in recording signals with different ranges of magnitude. The '''Source''' entry is a value in mV. For example, the threshold setting for the g.USBamp is '''Threshold gUSBampSource 12.5''' .
*'''ResultOut''' This is the file that contains the testing results.
*'''DataDir''' The default data directory. It defaults to latencyData in the BCI2000/tools/BCI2000Certification/ folder.

These values should not generally be changed by the user, although they may be updated in future BCI2000 versions.

====CertificationMain.prm====
This parameter file contains some of the default task parameters common to every test, including the save location, monitor configuration, sampling rate, and visualization settings. Note that these parameters can be overwritten in the *.prm files for each individual test configuration.

====BCI2000Certification.exe====
This file controls the execution of each task. It parses the BCI2000Certification.ini and BCI2000Certification.cfg files to determine which files and tasks to run, and controls the CPU load monitor. When all tasks are complete, this program calls the BCI2000Analysis.exe program to handle the analysis of the collected data.

====BCI2000CertAnalysis.exe====
This program analyzes the data collected, and reports results to a data file. It uses the DataDir parameter in the BCI2000Certification.cfg file to determine where the data is located. Results are output to results.txt in the BCI2000/tools/BCI2000Certification/ folder.

====Parameter Files====
Each task should have it's own parameter file that contains the unique configuration and settings for that task. For example, there may be several configurations that use the g.USBamp, ARSignalProcessing, and CursorTask, each with its own parameter file. These files end in .prm, and are placed in the BCI2000/tools/BCI2000Certification/parms/ folder.

===Interpreting Results===
Results are recorded to the BCI2000/tools/BCI2000Certification/results.txt file. The results for each task, and each applicable latency tested, are reported here. If the entire task passed, then each test performed met the minimum timing requirements specified in the BCI2000Certification.cfg file. If one or more did not pass, then the specific test that did not pass the test has Fail written next to it.

====What if a Task Did Not Pass?====
TO BE ADDED.

==Certification Protocol==
This section describes how the testing protocol is run, the various components involved in the certification analysis, and how to interpret results.

===Running the Tests===
The certification protocol consists of running several BCI2000 applications in multiple configurations to determine if each application meets the minimum requirements for BCI2000, and to determine if individual configurations of an application meet the requirements. For example, the CursorFeedback task may be tested with several combinations of sampling rates, sample block sizes, and processed channels, only some of which may work with a given computer setup.

The testing set is run from a single batch file called LatencyAnalysis.bat. This file is located in the folder BCI2000/tools/BCI2000Certification/batch. This batch file executes additional batch files in this folder, each corresponding to a different application configuration. Each of these batch files starts the Operator module, automatically loading multiple parameter files used for a given configuration. There is a general-purpose parameter file called latencyTest.prm that all configurations use. This file configures the save location for all latency tests, as well as default window positions and sampling rates. A second parameter file is passed to the operator that contains the parameters for a unique application configuration. After starting the operator module, the batch file starts the SignalSource module, SignalProcessing module, and Application module. The loaded configuration is set automatically, and the user needs only to press the start button to start the analysis.

==Software Templates==
This describes how to implement the testing protocols for your own amplifier system and custom applications. This is useful for determining if your hardware setup and software is capable of maintaining an acceptable level of performance for real-time testing.

===Amplifier Latency===
The amplifier latency requires an output that can be recorded by the amplifier. In the case of the g.USBamp, a digital output line is used, although either analog or digital outputs could be used in a system.

In the SignalSource module code for your custom amp, find the Process function. Near the beginning of this function, before any data is acquired, set the output signal to 0, either a digital low or analog value of 0 V. This will be dependent on the particular amplifier and API used; for the g.USBamp, this function call looks like:
 <code>
GT_SetDigitalOut ( m_hdev.at(0), (UCHAR)1, (UCHAR)0);
</code> 

This sets the digital output 1 on device 0 to a value of 0.

At the end of the Process function, the output should be set to a high level. A similar function call will be used to above, only the value is 1 instead of 0; again, the function will be dependent on the system used, and whether analog or digital output is used. Here is the code for the g.USBamp:
 <code>
GT_SetDigitalOut ( m_hdev.at(0), (UCHAR)1, (UCHAR)1);
</code> 

This sets the digital output 1 on device 0 to a value of 1.

===Visual and Audio Latency===
Developing new video and optical latency tests does not necessarily require adding additional code to existing modules (beyond any customization already done).

==Supported Hardware==
A list of officially supported hardware configurations, and suggested minimum requirements is provided.

===Supported and Tested Hardware===
====Amplifiers====

*g.USBamp
*gMOBIlab (Serial RS232)
*gMOBIlab (Bluetooth)
*TDT Pentusa (RX5)

===Minimum Requirements===
This table shows the minimum requirements for running BCI2000.

{| border="1"
|+ Minimum System Requirements for BCI2000
! CPU
| 1 GHz
|-
! RAM
|512 MB (dependent on OS; 1 GB for Windows Vista)
|-
! Video Card
|32 MB VRam; Hardware OpenGL Support
|-
! Sound Card
|
|-
! Monitor
|
|-
! OS
|Windows 2000; Windows XP SP2 or Greater; Windows Vista
|}

===Voltage Divider & Amplifier Input===
Parts List:

*4 Male Mono Audio Connectors
*6 12in Safety Connector Wires (to USB amplifier input), different colors
*4 3in Wires
*Soldering Iron and Solder
*resistors for voltage dividers
This section describes how to assemble cables that connect the output of the g.TRIGbox to the amplifier input channels.

Strip the free ends of all 6 safety connector wires, about <math>\frac{1}{4}</math> in. If you are not using voltage dividers, solder 4 of the wires directly to the center signal connection on the 4 mono audio connectors. Cover the connection.

[[Image:ampPlug_1.png|frame|none|g.USBamp Amplifier Plug]]

Next, twist the two remaining safety connector wire ends together, and solder them together. Solder the 4 short wires to the ground connections on the mono plugs. Finally, solder the 4 ground wires to the two safety connector wires that were twisted together and soldered previously, as shown here.

[[Image:ampPlugs_2.png|frame|none|g.USBamp Amplifier Plugs]]

These plugs can plug directly into the g.TRIGbox outputs, and the safety connectors plug into the channels 1-4 inputs on the g.USBamp; the ground wires plug into the ground and reference on the g.USBamp.

===Digital I/O Cable===

Parts List:

*3 Colored Wires
*7-Pin Digital Connector from g.tec
*Soldering Iron and Solder
*Silicone or electrical tape for insulation
*1 Female Mono Audio Plug

In order to access the digital I/O pins on the g.USBamp, a connector needs to be assembled. The 7-pin digital I/O connector should be ordered through g.TEC, the manufacturer of the g.USBamp.

At least three wires are needed for the circuit, which connect to the digital output 1 pin, the digital input 0 pin, and the ground pin.
[[Image:DigIO.png|frame|none|g.USBamp Digital I/O Pins]]

To start, cut three 10 in wires, preferably with different colors to differentiate between the signal and ground wires. Cut back a small portion of the ground wire, and solder it to the center ground pin on the connector. Now, find the top of the connector by locating the small plastic notch, and locate pins 3 and 4 relative to the notch. Solder one wire to pin 3, and the remaining wire to pin 4. It may be helpful to insulate the wires from the casing using either a piece of black electrical tape, or an insulating gel, like silicone. If a gel is used, be sure to let it set for several hours or overnight. It is also probably a good idea to check the electrical connection with a multimeter prior to insulating.

[[Image:digConnector.png|frame|none|g.USBamp Digital I/O Pins]]

Next, attach the rubber sleeve over the end of the part with the female threads, as shown in the panel. Slide the smaller metal sleeve over the wires, then slide the larger rubber sleeve over the wires.

For the next step, attach the two metallic pieces that surround the cables, shown laying to the sides below. One of the metal pieces has a small groove in it, which should be placed over the notch on the connector; the other metal piece fits on the opposite side of the connector. Push the small metal sleeve up to the side piece with the groove, and rotate the sleeve until the notch fits in the groove.

Place the end piece over the connector, with the red dot on top and aligned with the connector notch. Finally, slide the rubber sleeve over the connector, and screw the sleeve into the end piece.

[[Image:finalDigCable.png|frame|none|g.USBamp Digital I/O Cable]]

The plug is assembled next. Solder the signal wire from Pin 3 (Digital Out 1) on the digital I/O connector to the signal connector on the female mono plug, and solder the ground wire to the outer ground connector on the plug. The below figure shows this; in this figure, the red wire is the signal wire, and the brown wire is the ground.

[[Image:digPlug.png|frame|none|g.USBamp Digital Wire Plug]]