BCI2000 Wiki - User contributions [en]

User Tutorial:BCI2000Remote

2025-05-14T23:13:48Z

Swiftj: /* Python Tutorial */

==Description==
BCI2000Remote is a proxy interface class to the BCI2000 Operator module, and allows to start up, configure, and control BCI2000 from other applications. Internally, it maintains a telnet connection to the Operator module, and sends Operator Scripting commands to control it. However, no knowledge of these scripting commands is required in order to use the BCI2000Remote class from your own application.

BCI2000Remote is most useful when writing applications in C++, or in another language for which bindings to the BCI2000RemoteLib library exist, such as Python, or MATLAB.
==Note==
BCI2000Remote is a means of interfacing with the BCI2000 Operator module meaning that there are potentially hundreds of ways we leverage this tool to have a meaningful interface with BCI2000. Because of this we will illustrate a few different integrations using different languages. This "How-to" will be separated into three separate sections: Python, C++, and Matlab.
==Python Tutorial==
<ol>
<li>Find your Python folder. If you have an existing Python environment with your code find it using the Sys Library like this:

<syntaxhighlight lang="python">
import sys

locate_python = sys.exec_prefix
print(locate_python)
</syntaxhighlight>

</li>
<li>
Locate your BCI2000Remote.py file which should have compiled into your prog folder.
Find where in your Python code you wish to integrate BCI2000. In this example I will show the minimum requirements for integration with BCI2000:

<syntaxhighlight lang="python">
# Set BCI2000 path
import sys, time
sys.path.append('C:\\BCI2000.x64\\prog')

# BCI2000 setup
import BCI2000Remote
bci = BCI2000Remote.BCI2000Remote()
bci.WindowVisible = True
bci.WindowTitle = 'BCI2000 Remote Python'
bci.Connect()
bci.Execute('cd ${BCI2000LAUNCHDIR}')
bci.Execute('ADD EVENT Square 2 0')
bci.StartupModules(('SignalGenerator', 'DummySignalprocessing', 'DummyApplication'))

bci.Execute('Wait for Connected')
bci.LoadParametersRemote('..\\parms\\fragments\\amplifiers\\SignalGenerator.prm')
bci.Execute('Wait for Running')
bci.Execute('Set event Square 1')
</syntaxhighlight>

Here is how you import BCI2000Remote:
 

<gallery mode="packed" widths=300px heights=300px>
File:BCIRemote1.png
</gallery>

 
Here is how you instantiate the operator object:
 

<gallery mode="packed" widths=300px heights=300px>
File:BCIRemote 2.png
</gallery>

 
Here is how to customize the operator and connect to it:
 

<gallery mode="packed" widths=300px heights=300px>
File:BCI2000Remote2.png
</gallery>

 
Here is how you add your states:
 

<gallery mode="packed" widths=300px heights=300px>
File:BCIRemote_4.png
</gallery>

 
How to specify your signal source, signal processing, and application modules:
 

<gallery mode="packed" widths=300px heights=300px>
File:BCIRemote_5.png
</gallery>

 
How to load a parameter file(you can learn more about parameters [[Technical_Reference:Parameter_File|here]]):
 

<gallery mode="packed" widths=300px heights=300px>
File:BCIRemote_6.png
</gallery>

 
How to connect and issue commands to BCI2000:
 

<gallery mode="packed" widths=300px heights=300px>
File:BCIRemote_666.png
</gallery>

</li>
<li>
And finally, how to tell BCI2000 to set states to a value during runtime:
 

<gallery mode="packed" widths=300px heights=300px>
File:BCIRemote_8.png
</gallery>

 
Now that you've added those components to your code all you have to do is run your code. You should see the BCI2000 operator along with the system log, source watcher, and the timing window.

<gallery mode="packed" widths=500px heights=500px>
File:BCIRemote_7.png
</gallery>

 
</ol>

==C++ Tutorial==
<ol>
<li>
<li>
Open the C++ file or solution you would like to integrate with BCI2000 in Visual Studio, and find where it is located on your computer.
</li>
<li>
Navigate to the program's properties, and make the following changes:
<ul>
<li>
Under Configuration Properties -> C++ -> General, add the following folders from BCI2000 (64-bit)'s src folder: \core\Operator\BCI2000Remote, \shared\utils\Lib, \shared\config. 
</li>
<li>
Navigate to Configuration Properties -> Linker -> Input, and add ws2_32.lib to Additional Dependencies.
</li>
<li>
Under Configuration Properties -> C++ -> Advanced, add 4996 to the Disable Specific Warnings section.
</li>
</ul>
<li>
Add your Operator executable and the BCI2000RemoteLib dynamic library to the same directory as the program you intend to integrate. This can be found in the prog folder.
</li>
<li> Also, add the following files to the directory with your program and Operator.exe:

<ul>
<li>
BCI2000Connection.cpp
</li>
<li>
BCI2000Connection.h
</li>
<li>
BCI2000Remote.cpp
</li>
<li>
BCI2000Remote.h
</li>
<li>
BCI2000RemoteLib.cpp
</li>
<li>
BCI2000RemoteLib.h
</li>
<li>
SelfPipe.cpp
</li>
<li>
SelfPipe.h
</li>
<li>
sockstream.cpp
</li>
<li>
sockstream.h
</li>
</ul>

<li>
Make sure that you include all of your dependencies including BCI2000Remote.h

<syntaxhighlight lang="cpp">
#include "BCI2000Remote.h"
#include <string>
#include <vector>
#include <iostream>
</syntaxhighlight>

</li>
<li>
Next, instantiate the BCI2000Remote object

<syntaxhighlight lang="cpp">
int main( int argc, char* argv[] )
{
// Instantiate a BCI2000Remote object
BCI2000Remote bci;
// Assume that Operator executable resides in the same directory as this program.
std::string path = ( argc > 0 ) ? argv[0] : "";
size_t pos = path.find_last_of( "\\/" );
path = ( pos != std::string::npos ) ? path.substr( 0, pos + 1 ) : "";
// Start the Operator module, and connect
bci.OperatorPath( path + "Operator" );
if( !bci.Connect() )
{
std::cerr << bci.Result();
return -1;
}
</syntaxhighlight>

</li>
<li>
Specify your startup modules and any flags you wish to start them with

<syntaxhighlight lang="cpp">
// Startup modules
std::vector<std::string> modules{ "SignalGenerator --LogMouse=1", "ARSignalProcessing", "CursorTask" };
if( !bci.StartupModules( modules ) )
{
std::cerr << bci.Result();
return -1;
}
</syntaxhighlight>
</li>
<li>
Load any parameter files and set subject information

<syntaxhighlight lang="cpp">
bci.LoadParametersRemote( "../parms/examples/CursorTask_SignalGenerator.prm" );
bci.SubjectID( "SUB" );
// Start a run
if( !bci.Start() )
{
std::cerr << bci.Result();
return -1;
}
</syntaxhighlight>
</li>
</li>
<li>
And here we just have BCI2000 send us back a feedback signal:
<syntaxhighlight lang="cpp">
std::string state;
while( bci.GetSystemState( state ) && state == "Running" )
{
double value = 0;
bci.GetControlSignal( 1, 1, value );
std::cout << "Control signal: " << value << ", press Enter to proceed" << std::flush;
std::string line;
std::getline( std::cin, line );
}
return 0;
}
</syntaxhighlight>
</li>
<li>
Now that you've added those components to your code all you have to do is compile and run it. You should see the BCI2000 operator along with the system log, source watcher, and the timing window.
Note: Be sure to compile this in your prog folder. This can be done by navigating again to Configuration Properties -> General, and changing the Output Directory to the path of the BCI2000 prog folder.
</li>
</ol>
<syntaxhighlight lang="cpp">
#include "BCI2000Remote.h"
#include <string>
#include <vector>
#include <iostream>

int main( int argc, char* argv[] )
{
// Instantiate a BCI2000Remote object
BCI2000Remote bci;
// Assume that Operator executable resides in the same directory as this program.
std::string path = ( argc > 0 ) ? argv[0] : "";
size_t pos = path.find_last_of( "\\/" );
path = ( pos != std::string::npos ) ? path.substr( 0, pos + 1 ) : "";
// Start the Operator module, and connect
bci.OperatorPath( path + "Operator" );
if( !bci.Connect() )
{
std::cerr << bci.Result();
return -1;
}
// Startup modules
std::vector<std::string> modules{ "SignalGenerator --LogMouse=1", "ARSignalProcessing", "CursorTask" };
if( !bci.StartupModules( modules ) )
{
std::cerr << bci.Result();
return -1;
}
// Load a parameter file, and set subject information
bci.LoadParametersRemote( "../parms/examples/CursorTask_SignalGenerator.prm" );
bci.SubjectID( "SUB" );
// Start a run
if( !bci.Start() )
{
std::cerr << bci.Result();
return -1;
}
// Print feedback signal
std::string state;
while( bci.GetSystemState( state ) && state == "Running" )
{
double value = 0;
bci.GetControlSignal( 1, 1, value );
std::cout << "Control signal: " << value << ", press Enter to proceed" << std::flush;
std::string line;
std::getline( std::cin, line );
}
return 0;
}
</syntaxhighlight>

==MatlabTutorial==
<ol>
<li>Open the Matlab file you would like to integrate with BCI2000.</li>
<li>Locate the BCI2000RemoteLib file in the BCI2000 prog folder, and BCI2000RemoteLib.h in src\core\Operator\BCI2000Remote, and load these into the Matlab file. Modify the file paths in loadlibrary(...) as needed.
Note that BCI2000RemoteLib's file name has a "64" appended when it was built in 64 bit mode, and a "32" if built iin 32 bit mode.
In this tutorial, we will be using the 64 bit version.
<syntaxhighlight lang="matlab">
%% c library load, initial part
BCI2000root = 'C:\bci2000.x64';
if not(libisloaded('bci'))
loadlibrary(fullfile(BCI2000root,'prog','BCI2000RemoteLib64'),...
fullfile(BCI2000root,'src','core','Operator','BCI2000Remote','BCI2000RemoteLib.h'), 'alias', 'bci')
end
libfunctions('bci')
</syntaxhighlight>
</li>
<li> Locate Operator.exe in the prog folder. Recover the memory, change the directory, and make the window visible in BCI2000. Again, modify the file path if it differs.

<syntaxhighlight lang="matlab">
%need to call BCI2000Remote_Delete to recover the memory
bciHandle = calllib('bci', 'BCI2000Remote_New');
calllib('bci', 'BCI2000Remote_SetOperatorPath', bciHandle, fullfile(BCI2000root,'prog','Operator'));

% if we fail cto establish a connection to BCI2000Remote
if calllib('bci', 'BCI2000Remote_Connect', bciHandle) ~= 1
fprintf('bci connect fail!')
calllib('bci', 'BCI2000Remote_Delete', bciHandle); % call BCI2000Remote_Delete to recovery the memory
return
end

% Startup BCI2000
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Change directory $BCI2000LAUNCHDIR', 0);
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Show window; Set title ${Extract file base $0}', 0);
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Reset system', 0);
</syntaxhighlight>
</li>
<li> Add new states, events, or parameters before starting up the system. Note that it is greatly preferred to use events instead of states because of timing precision.
<syntaxhighlight lang="matlab">
% Create new parameter (must be done before startup)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Add Parameter Application:TestParameterField string TestParameter= FirstNewParameter % % %', 0);

% Define events
% Define new event with 1 bit of information (2 colors)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'add event Square 1 0', 0);
</syntaxhighlight>
</li>
<li>Add in the proper modules (Signal Generator, Signal Processor, and Application). Refer to the documentation [[Technical_Reference:BCI2000Remote_Library]] for more information on BCI2000 remote functions. Also refer to the example Matlab code under [[Programming_Reference:BCI2000Remote_Class#Matlab_Example]].</li>
<syntaxhighlight lang="matlab">
% Startup system localhost
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Startup system localhost', 0);

% Establish connection to three modules
SourceModule = 'SignalGenerator';
modules = libpointer('stringPtrPtr', {[SourceModule ' --local --LogKeyboard=1'], 'DummySignalProcessing', 'DummyApplication'});
calllib('bci', 'BCI2000Remote_StartupModules2', bciHandle, modules, 3);

% Wait for connected before loading parameters!
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Wait for Connected', 0);
</syntaxhighlight>
<li> Load parameter files, modify parameters directly, and add watches after BCI2000 is connected. It can also be helpful to wait for bci2000 to start running (collecting data) before proceeding.
<syntaxhighlight lang="matlab">
% Load parameter files
calllib('bci', 'BCI2000Remote_LoadParametersRemote', bciHandle, fullfile(BCI2000root,'parms','fragments','amplifiers','SignalGenerator.prm'));

% Set parameter values
calllib('bci', 'BCI2000Remote_SetDataDirectory', bciHandle, fullfile(BCI2000root,'data','BJH'));

%Set watches to appear automatically
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'visualize watch Square', 0);

% Wait for the user to click SetConfig and Start
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Wait for Running', 0);
</syntaxhighlight>
</li>
<li> While BCI2000 is running you can also get and set event and state values, and also get parameter values. Note that you cannot modify parameter values while BCI2000 is running.
<syntaxhighlight lang="matlab">
% Get parameter value
SamplingRate = calllib('bci', 'BCI2000Remote_GetParameter', bciHandle, 'SamplingRate');
fprintf(['\nSamplingRate: ' num2str(SamplingRate) 'Hz\n'])

% Get event value
[~,~,~,Square]=calllib('bci', 'BCI2000Remote_GetEventVariable', bciHandle, 'Square', 0.0);

% BCI2000 set white rectangle to 1 (true)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Set event Square 1', 0);

% Get state value
% Immediately after data block has been acquired from hardware, the
% DataIOFilter writes a 16-bit millisecond-resolution time stamp into the
% SourceTime state. Block duration is measured as the difference between
% two consecutive time stamps.
[~,~,~,SourceTime]=calllib('bci', 'BCI2000Remote_GetStateVariable', bciHandle, 'SourceTime', 0.0);
fprintf(['\nSourceTime: ', num2str(SourceTime), '\n'])

% Stop running BCI2000
calllib('bci', 'BCI2000Remote_SetStateVariable', bciHandle, 'Running', 0);
</syntaxhighlight>
</li>
</ol>

==Video==
<youtube alignment="center">https://www.youtube.com/watch?v=ZwLcovHZabw</youtube>

Also see the [https://bci2000.org/mediawiki/index.php/PsychoPy PsychoPy] page for more details on the installation process, APIs, and hooks.

==See also==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Tutorial]][[Category:Video]]

PsychoPy

2025-05-13T00:29:02Z

Swiftj: /* Using Use Expression Option */

PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. [1] This wiki page first describes the two components that remotely start BCI2000 from PsychoPy. The next section describes the steps to add the new components in the PsychoPy application. The final section goes over two tutorial examples.
==Video Overview==
<youtube alignment="center">https://youtu.be/yPacLewE3Xo</youtube>
==Prerequisites==
For this project, you will need two things: [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Building_and_Customizing_BCI2000 BCI2000] compiled for your system and the newest version of [https://www.psychopy.org/download.html PsychoPy].

== Components ==

=== BCI2000Start ===
This component starts up the BCI2000 modules remotely. The component takes two parameters:
; Path : Path to the BCI2000 ''prog'' directory, which contains the ''BCI2000Remote.py'' file.
; States : List of new states to add to BCI2000. The states in the list are defined as follows: 'StateName defaultValue maxValue.' Eg: lastKey 0 255, correctKey 0 1.
'''NOTE:''' You can specify the modules with which you want to run the experiment with the ''BCI.StartupModules'' command in the Init.py file previously copied into your PsychoPy environment. You can also specify which parameters to use for the experiment and specify other command-line arguments with the ''BCI.LoadParameterRemote'' command.

[[File:BCI2000Start.png|500px|alt="BCI2000 start component image showing its parameters"|BCIStart Component]]

=== BCI2000UpdateEvent ===
Note: It is highly recommended to use EVENTS instead of STATES when recording experimental values using BCI2000. This is because the timing of events is on a per-sample basis, while states are recorded on a per-block basis. The time of recorded states can be delayed by up to a full block (often up to 100ms).

This component defines which event to update and when. It takes the following parameters:
; Event Name : The name of the event in BCI2000 to update.
; Response Component Variable : The variable to which the event is to be set OR the variable which contains the new value of the event. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the event.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the event is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET EVENT'' to update the event in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCIUpdateEvent.PNG|500px|alt="BCI2000 update event component image showing its parameters"|BCIUpdateEvent Component]]

=== BCI2000UpdateState ===
This component defines which state to update and when. It takes the following parameters:
; State Name : The name of the state in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the state. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the state.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the state is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET STATE'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCI2000UpdateState.png|alt="BCI2000 update state component image showing its parameters"|BCIUpdateState Component]]

== Integrating BCI2000 into PyschoPy ==
Clone PsychoPy from the [https://github.com/psychopy/psychopy PyschoPy] repository. You can also download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 
Below is a picture of PsychoPy before integrating BCI2000. Notice that in the rightmost column, under '''Custom''' Components, there is no BCI2000 component.

<gallery mode="packed" widths=500px heights=500px>
File:PsychoPyWithoutBCI.png|alt="PsychoPy Homepage without BCI2000 Components"|PsychoPy Homepage without BCI2000 Components
</gallery>

=== Standalone version ===
For Windows, Copy the folders '''BCIStart''', '''BCIUpdateEvent''', and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components folder.

=== Developer version ===
Copy the folders '''BCIStart''', '''BCIUpdateEvent''', and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\psychopy\experiment\components.
Open the terminal and navigate to the PsychoPy home directory where ''setup.py'' resides.
Run the following command in the terminal: 
<code>pip install -e .</code> 
 
Start PsychoPy application by running "python \psychopy\app\psychopyApp.py" from wherever you cloned your PsychoPy repository. If you downloaded the standalone version installer, you can simply press the Windows key and search for PsychoPy. Once you're under the '''Custom''' Components (in the rightmost column), you should see the three new components - ''BCI2000Start'', ''BCIUpdateEvent'', and ''BCI2000UpdateState'' as shown in the figure below.

<gallery mode="packed" widths=550px heights=550px>
File:PsychoPy_Start.png|alt="PsychoPy Homepage with BCI2000 Components"|PsychoPy Homepage with BCI2000 Components
</gallery>

'''Note:''' Make sure you don't run the experiments in full screen if you are using a single screen.

== Tutorial ==
In this section, two examples are presented to help the user understand the use of BCI2000 within PsychoPy. The examples modify the demo stroopExtended (already provided by PsychoPy once you have unpacked the demos) and integrates BCI2000 within it. The stroopExtended demo asks user to press certain keys depending on the color shown on the screen and records the response time.

=== Using Response Component Variable Option ===
In this tutorial, we will add a new event called '''correctKey''' in BCI2000 using PsychoPy. This event will be changed to 1 if the key pressed by user is correct, otherwise 0.
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like this. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>

 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>correctKey 0 1</code> in the ''Events'' field as shown in the image. '''correctKey''' is the name we want the new event to have in BCI2000, '''0''' is the default value the event should have and '''1''' is the maximum value the event can take in any case. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart1.png|alt="PsychoPy - Add Event into BCI2000"|PsychoPy - Add Event into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 Event - Navigate to the '''trial''' tab and click on '''BCI2000UpdateEvent'''. Fill in the fields ''Event Name'' with '''$correctKey''' (the BCI2000 event we want to update; '$' is used to indicate to PsychoPy to treat it as a variable) and ''Response Component Variable'' with '''$resp.corr''' ('resp' is the name of the keyboard that takes the input and 'corr' is its property that stores whether the key pressed is correct or not. you can see this variable being used in the program when you compile it to script) as shown in the image. This will essentially update the event 'correctKey' with the value of 'resp.corr'. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateEvent1.png|alt="PsychoPy - Update Event in BCI2000"|PsychoPy - Update Event in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created event to watch (in the BCI2000 operator, click on View -> States and Events.., right click on correctKey and add to watch, then click Ok on States and Events screen) and proceed as with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy10.png|alt="PsychoPy Stroop Extended Demo Run 1"|PsychoPy Stroop Extended Demo Run 1
</gallery>

</li>
 
</ol>

=== Using Use Expression Option ===
In this tutorial, we will add a new state called '''responseTime''' in BCI2000 using PsychoPy. This state will represent the time the user takes to press the correct key in seconds (with no decimals).
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like the image below. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>
 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>responseTime 0 600</code> in the ''Events'' field as shown in the image. '''responseTime''' is the name we want the new event to have in BCI2000, '''0''' is the default value the event should have and '''600''' is the maximum value the event can take in any case, i.e, the maximum response time could be 10 minutes. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart2.png|alt="PsychoPy- Add Event into BCI2000"|PsychoPy - Add Event into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 Event - Navigate to the '''trial''' tab and click on '''BCI2000UpdateEvent'''. Check on the '''Use Expression''' option to run the expression that is written in the '''Expression''' field. Write the lines of python code in the '''Expression''' field as shown in the image. These lines first set the 'RUNNING' state of BCI2000 to 1 to make sure that BCI2000 is running. It then checks if the type of the 'resp.rt' is float. If yes, that means 'resp.rt' stores the response time and sets the event 'responseTime' to the rounded value of 'resp.rt' ('resp' is the name of the keyboard which takes the input and 'rt' is its property that stores the time it took user to press the key; you can see this variable being used in the program when you compile it to script) using the bci.Execute and SET EVENT commands. 
<code>bci.Execute('SET STATE RUNNING 1') 
if(type(resp.rt) == float): 
    bci.Execute('SET EVENT responseTime %d' % round(resp.rt))
</code> 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState2.png|alt="PsychoPy - Update Event in BCI2000"|PsychoPy - Update Event in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created event to watch (in the BCI2000 operator, click on View -> States and Events.., right click on responseTime and add to watch. Click Ok on the States and Events screen) and proceed with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun2.png|alt="PsychoPy Stroop Extended Demo Run 2"|PsychoPy Stroop Extended Demo Run 2
</gallery>

</li>
 
</ol>

== References ==
1. [https://www.psychopy.org/ PsychoPy site]

== See Also ==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Video]]

File:PsychoPyBciStart2.png

2025-05-13T00:26:44Z

Swiftj: Swiftj uploaded a new version of File:PsychoPyBciStart2.png

PsychoPy-Bci Stroop Extended Start with Use Expression Option

PsychoPy

2025-05-12T22:24:35Z

Swiftj: /* Using Response Component Variable Option */

PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. [1] This wiki page first describes the two components that remotely start BCI2000 from PsychoPy. The next section describes the steps to add the new components in the PsychoPy application. The final section goes over two tutorial examples.
==Video Overview==
<youtube alignment="center">https://youtu.be/yPacLewE3Xo</youtube>
==Prerequisites==
For this project, you will need two things: [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Building_and_Customizing_BCI2000 BCI2000] compiled for your system and the newest version of [https://www.psychopy.org/download.html PsychoPy].

== Components ==

=== BCI2000Start ===
This component starts up the BCI2000 modules remotely. The component takes two parameters:
; Path : Path to the BCI2000 ''prog'' directory, which contains the ''BCI2000Remote.py'' file.
; States : List of new states to add to BCI2000. The states in the list are defined as follows: 'StateName defaultValue maxValue.' Eg: lastKey 0 255, correctKey 0 1.
'''NOTE:''' You can specify the modules with which you want to run the experiment with the ''BCI.StartupModules'' command in the Init.py file previously copied into your PsychoPy environment. You can also specify which parameters to use for the experiment and specify other command-line arguments with the ''BCI.LoadParameterRemote'' command.

[[File:BCI2000Start.png|500px|alt="BCI2000 start component image showing its parameters"|BCIStart Component]]

=== BCI2000UpdateEvent ===
Note: It is highly recommended to use EVENTS instead of STATES when recording experimental values using BCI2000. This is because the timing of events is on a per-sample basis, while states are recorded on a per-block basis. The time of recorded states can be delayed by up to a full block (often up to 100ms).

This component defines which event to update and when. It takes the following parameters:
; Event Name : The name of the event in BCI2000 to update.
; Response Component Variable : The variable to which the event is to be set OR the variable which contains the new value of the event. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the event.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the event is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET EVENT'' to update the event in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCIUpdateEvent.PNG|500px|alt="BCI2000 update event component image showing its parameters"|BCIUpdateEvent Component]]

=== BCI2000UpdateState ===
This component defines which state to update and when. It takes the following parameters:
; State Name : The name of the state in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the state. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the state.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the state is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET STATE'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCI2000UpdateState.png|alt="BCI2000 update state component image showing its parameters"|BCIUpdateState Component]]

== Integrating BCI2000 into PyschoPy ==
Clone PsychoPy from the [https://github.com/psychopy/psychopy PyschoPy] repository. You can also download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 
Below is a picture of PsychoPy before integrating BCI2000. Notice that in the rightmost column, under '''Custom''' Components, there is no BCI2000 component.

<gallery mode="packed" widths=500px heights=500px>
File:PsychoPyWithoutBCI.png|alt="PsychoPy Homepage without BCI2000 Components"|PsychoPy Homepage without BCI2000 Components
</gallery>

=== Standalone version ===
For Windows, Copy the folders '''BCIStart''', '''BCIUpdateEvent''', and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components folder.

=== Developer version ===
Copy the folders '''BCIStart''', '''BCIUpdateEvent''', and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\psychopy\experiment\components.
Open the terminal and navigate to the PsychoPy home directory where ''setup.py'' resides.
Run the following command in the terminal: 
<code>pip install -e .</code> 
 
Start PsychoPy application by running "python \psychopy\app\psychopyApp.py" from wherever you cloned your PsychoPy repository. If you downloaded the standalone version installer, you can simply press the Windows key and search for PsychoPy. Once you're under the '''Custom''' Components (in the rightmost column), you should see the three new components - ''BCI2000Start'', ''BCIUpdateEvent'', and ''BCI2000UpdateState'' as shown in the figure below.

<gallery mode="packed" widths=550px heights=550px>
File:PsychoPy_Start.png|alt="PsychoPy Homepage with BCI2000 Components"|PsychoPy Homepage with BCI2000 Components
</gallery>

'''Note:''' Make sure you don't run the experiments in full screen if you are using a single screen.

== Tutorial ==
In this section, two examples are presented to help the user understand the use of BCI2000 within PsychoPy. The examples modify the demo stroopExtended (already provided by PsychoPy once you have unpacked the demos) and integrates BCI2000 within it. The stroopExtended demo asks user to press certain keys depending on the color shown on the screen and records the response time.

=== Using Response Component Variable Option ===
In this tutorial, we will add a new event called '''correctKey''' in BCI2000 using PsychoPy. This event will be changed to 1 if the key pressed by user is correct, otherwise 0.
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like this. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>

 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>correctKey 0 1</code> in the ''Events'' field as shown in the image. '''correctKey''' is the name we want the new event to have in BCI2000, '''0''' is the default value the event should have and '''1''' is the maximum value the event can take in any case. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart1.png|alt="PsychoPy - Add Event into BCI2000"|PsychoPy - Add Event into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 Event - Navigate to the '''trial''' tab and click on '''BCI2000UpdateEvent'''. Fill in the fields ''Event Name'' with '''$correctKey''' (the BCI2000 event we want to update; '$' is used to indicate to PsychoPy to treat it as a variable) and ''Response Component Variable'' with '''$resp.corr''' ('resp' is the name of the keyboard that takes the input and 'corr' is its property that stores whether the key pressed is correct or not. you can see this variable being used in the program when you compile it to script) as shown in the image. This will essentially update the event 'correctKey' with the value of 'resp.corr'. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateEvent1.png|alt="PsychoPy - Update Event in BCI2000"|PsychoPy - Update Event in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created event to watch (in the BCI2000 operator, click on View -> States and Events.., right click on correctKey and add to watch, then click Ok on States and Events screen) and proceed as with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy10.png|alt="PsychoPy Stroop Extended Demo Run 1"|PsychoPy Stroop Extended Demo Run 1
</gallery>

</li>
 
</ol>

=== Using Use Expression Option ===
In this tutorial, we will add a new state called '''responseTime''' in BCI2000 using PsychoPy. This state will represent the time the user takes to press the correct key in seconds (with no decimals).
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like the image below. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>
 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>responseTime 0 600</code> in the ''States'' field as shown in the image. '''responseTime''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''600''' is the maximum value the state can take in any case, i.e, the maximum response time could be 10 minutes. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart2.png|alt="PsychoPy- Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Check on the '''Use Expression''' option to run the expression that is written in the '''Expression''' field. Write the lines of python code in the '''Expression''' field as shown in the image. These lines first set the 'RUNNING' state of BCI2000 to 1 to make sure that BCI2000 is running. It then checks if the type of the 'resp.rt' is float. If yes, that means 'resp.rt' stores the response time and sets the state 'responseTime' to the rounded value of 'resp.rt' ('resp' is the name of the keyboard which takes the input and 'rt' is its property that stores the time it took user to press the key; you can see this variable being used in the program when you compile it to script) using the bci.Execute and SET STATE commands. 
<code>bci.Execute('SET STATE RUNNING 1') 
if(type(resp.rt) == float): 
    bci.Execute('SET STATE responseTime %d' % round(resp.rt))
</code> 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState2.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on responseTime and add to watch. Click Ok on the States and Events screen) and proceed with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun2.png|alt="PsychoPy Stroop Extended Demo Run 2"|PsychoPy Stroop Extended Demo Run 2
</gallery>

</li>
 
</ol>

== References ==
1. [https://www.psychopy.org/ PsychoPy site]

== See Also ==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Video]]

File:PsychoPyBciUpdateEvent1.png

2025-05-12T22:21:18Z

Swiftj:

File:PsychoPyBciStart1.png

2025-05-12T22:19:37Z

Swiftj: Swiftj uploaded a new version of File:PsychoPyBciStart1.png

PsychoPy-Bci Stroop Extended Start with Response Component Variable Option

PsychoPy

2025-05-12T22:17:39Z

Swiftj: /* Using Response Component Variable Option */

PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. [1] This wiki page first describes the two components that remotely start BCI2000 from PsychoPy. The next section describes the steps to add the new components in the PsychoPy application. The final section goes over two tutorial examples.
==Video Overview==
<youtube alignment="center">https://youtu.be/yPacLewE3Xo</youtube>
==Prerequisites==
For this project, you will need two things: [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Building_and_Customizing_BCI2000 BCI2000] compiled for your system and the newest version of [https://www.psychopy.org/download.html PsychoPy].

== Components ==

=== BCI2000Start ===
This component starts up the BCI2000 modules remotely. The component takes two parameters:
; Path : Path to the BCI2000 ''prog'' directory, which contains the ''BCI2000Remote.py'' file.
; States : List of new states to add to BCI2000. The states in the list are defined as follows: 'StateName defaultValue maxValue.' Eg: lastKey 0 255, correctKey 0 1.
'''NOTE:''' You can specify the modules with which you want to run the experiment with the ''BCI.StartupModules'' command in the Init.py file previously copied into your PsychoPy environment. You can also specify which parameters to use for the experiment and specify other command-line arguments with the ''BCI.LoadParameterRemote'' command.

[[File:BCI2000Start.png|500px|alt="BCI2000 start component image showing its parameters"|BCIStart Component]]

=== BCI2000UpdateEvent ===
Note: It is highly recommended to use EVENTS instead of STATES when recording experimental values using BCI2000. This is because the timing of events is on a per-sample basis, while states are recorded on a per-block basis. The time of recorded states can be delayed by up to a full block (often up to 100ms).

This component defines which event to update and when. It takes the following parameters:
; Event Name : The name of the event in BCI2000 to update.
; Response Component Variable : The variable to which the event is to be set OR the variable which contains the new value of the event. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the event.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the event is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET EVENT'' to update the event in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCIUpdateEvent.PNG|500px|alt="BCI2000 update event component image showing its parameters"|BCIUpdateEvent Component]]

=== BCI2000UpdateState ===
This component defines which state to update and when. It takes the following parameters:
; State Name : The name of the state in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the state. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the state.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the state is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET STATE'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCI2000UpdateState.png|alt="BCI2000 update state component image showing its parameters"|BCIUpdateState Component]]

== Integrating BCI2000 into PyschoPy ==
Clone PsychoPy from the [https://github.com/psychopy/psychopy PyschoPy] repository. You can also download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 
Below is a picture of PsychoPy before integrating BCI2000. Notice that in the rightmost column, under '''Custom''' Components, there is no BCI2000 component.

<gallery mode="packed" widths=500px heights=500px>
File:PsychoPyWithoutBCI.png|alt="PsychoPy Homepage without BCI2000 Components"|PsychoPy Homepage without BCI2000 Components
</gallery>

=== Standalone version ===
For Windows, Copy the folders '''BCIStart''', '''BCIUpdateEvent''', and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components folder.

=== Developer version ===
Copy the folders '''BCIStart''', '''BCIUpdateEvent''', and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\psychopy\experiment\components.
Open the terminal and navigate to the PsychoPy home directory where ''setup.py'' resides.
Run the following command in the terminal: 
<code>pip install -e .</code> 
 
Start PsychoPy application by running "python \psychopy\app\psychopyApp.py" from wherever you cloned your PsychoPy repository. If you downloaded the standalone version installer, you can simply press the Windows key and search for PsychoPy. Once you're under the '''Custom''' Components (in the rightmost column), you should see the three new components - ''BCI2000Start'', ''BCIUpdateEvent'', and ''BCI2000UpdateState'' as shown in the figure below.

<gallery mode="packed" widths=550px heights=550px>
File:PsychoPy_Start.png|alt="PsychoPy Homepage with BCI2000 Components"|PsychoPy Homepage with BCI2000 Components
</gallery>

'''Note:''' Make sure you don't run the experiments in full screen if you are using a single screen.

== Tutorial ==
In this section, two examples are presented to help the user understand the use of BCI2000 within PsychoPy. The examples modify the demo stroopExtended (already provided by PsychoPy once you have unpacked the demos) and integrates BCI2000 within it. The stroopExtended demo asks user to press certain keys depending on the color shown on the screen and records the response time.

=== Using Response Component Variable Option ===
In this tutorial, we will add a new event called '''correctKey''' in BCI2000 using PsychoPy. This event will be changed to 1 if the key pressed by user is correct, otherwise 0.
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like this. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>

 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>correctKey 0 1</code> in the ''Events'' field as shown in the image. '''correctKey''' is the name we want the new event to have in BCI2000, '''0''' is the default value the event should have and '''1''' is the maximum value the event can take in any case. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart1.png|alt="PsychoPy - Add Event into BCI2000"|PsychoPy - Add Event into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 Event - Navigate to the '''trial''' tab and click on '''BCI2000UpdateEvent'''. Fill in the fields ''Event Name'' with '''$correctKey''' (the BCI2000 event we want to update; '$' is used to indicate to PsychoPy to treat it as a variable) and ''Response Component Variable'' with '''$resp.corr''' ('resp' is the name of the keyboard that takes the input and 'corr' is its property that stores whether the key pressed is correct or not. you can see this variable being used in the program when you compile it to script) as shown in the image. This will essentially update the event 'correctKey' with the value of 'resp.corr'. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateEvent1.png|alt="PsychoPy - Update Event in BCI2000"|PsychoPy - Update Event in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created event to watch (in the BCI2000 operator, click on View -> States and Events.., right click on correctKey and add to watch, then click Ok on States and Events screen) and proceed as with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun1.png|alt="PsychoPy Stroop Extended Demo Run 1"|PsychoPy Stroop Extended Demo Run 1
</gallery>

</li>
 
</ol>

=== Using Use Expression Option ===
In this tutorial, we will add a new state called '''responseTime''' in BCI2000 using PsychoPy. This state will represent the time the user takes to press the correct key in seconds (with no decimals).
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like the image below. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>
 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>responseTime 0 600</code> in the ''States'' field as shown in the image. '''responseTime''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''600''' is the maximum value the state can take in any case, i.e, the maximum response time could be 10 minutes. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart2.png|alt="PsychoPy- Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Check on the '''Use Expression''' option to run the expression that is written in the '''Expression''' field. Write the lines of python code in the '''Expression''' field as shown in the image. These lines first set the 'RUNNING' state of BCI2000 to 1 to make sure that BCI2000 is running. It then checks if the type of the 'resp.rt' is float. If yes, that means 'resp.rt' stores the response time and sets the state 'responseTime' to the rounded value of 'resp.rt' ('resp' is the name of the keyboard which takes the input and 'rt' is its property that stores the time it took user to press the key; you can see this variable being used in the program when you compile it to script) using the bci.Execute and SET STATE commands. 
<code>bci.Execute('SET STATE RUNNING 1') 
if(type(resp.rt) == float): 
    bci.Execute('SET STATE responseTime %d' % round(resp.rt))
</code> 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState2.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on responseTime and add to watch. Click Ok on the States and Events screen) and proceed with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun2.png|alt="PsychoPy Stroop Extended Demo Run 2"|PsychoPy Stroop Extended Demo Run 2
</gallery>

</li>
 
</ol>

== References ==
1. [https://www.psychopy.org/ PsychoPy site]

== See Also ==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Video]]

File:PsychoPyDemoStart.png

2025-05-12T22:14:56Z

Swiftj: Swiftj uploaded a new version of File:PsychoPyDemoStart.png

PsychoPy Stroop Extended Demo Start

PsychoPy

2025-05-12T22:12:20Z

Swiftj: /* Integrating BCI2000 into PyschoPy */

PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. [1] This wiki page first describes the two components that remotely start BCI2000 from PsychoPy. The next section describes the steps to add the new components in the PsychoPy application. The final section goes over two tutorial examples.
==Video Overview==
<youtube alignment="center">https://youtu.be/yPacLewE3Xo</youtube>
==Prerequisites==
For this project, you will need two things: [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Building_and_Customizing_BCI2000 BCI2000] compiled for your system and the newest version of [https://www.psychopy.org/download.html PsychoPy].

== Components ==

=== BCI2000Start ===
This component starts up the BCI2000 modules remotely. The component takes two parameters:
; Path : Path to the BCI2000 ''prog'' directory, which contains the ''BCI2000Remote.py'' file.
; States : List of new states to add to BCI2000. The states in the list are defined as follows: 'StateName defaultValue maxValue.' Eg: lastKey 0 255, correctKey 0 1.
'''NOTE:''' You can specify the modules with which you want to run the experiment with the ''BCI.StartupModules'' command in the Init.py file previously copied into your PsychoPy environment. You can also specify which parameters to use for the experiment and specify other command-line arguments with the ''BCI.LoadParameterRemote'' command.

[[File:BCI2000Start.png|500px|alt="BCI2000 start component image showing its parameters"|BCIStart Component]]

=== BCI2000UpdateEvent ===
Note: It is highly recommended to use EVENTS instead of STATES when recording experimental values using BCI2000. This is because the timing of events is on a per-sample basis, while states are recorded on a per-block basis. The time of recorded states can be delayed by up to a full block (often up to 100ms).

This component defines which event to update and when. It takes the following parameters:
; Event Name : The name of the event in BCI2000 to update.
; Response Component Variable : The variable to which the event is to be set OR the variable which contains the new value of the event. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the event.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the event is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET EVENT'' to update the event in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCIUpdateEvent.PNG|500px|alt="BCI2000 update event component image showing its parameters"|BCIUpdateEvent Component]]

=== BCI2000UpdateState ===
This component defines which state to update and when. It takes the following parameters:
; State Name : The name of the state in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the state. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the state.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the state is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET STATE'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCI2000UpdateState.png|alt="BCI2000 update state component image showing its parameters"|BCIUpdateState Component]]

== Integrating BCI2000 into PyschoPy ==
Clone PsychoPy from the [https://github.com/psychopy/psychopy PyschoPy] repository. You can also download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 
Below is a picture of PsychoPy before integrating BCI2000. Notice that in the rightmost column, under '''Custom''' Components, there is no BCI2000 component.

<gallery mode="packed" widths=500px heights=500px>
File:PsychoPyWithoutBCI.png|alt="PsychoPy Homepage without BCI2000 Components"|PsychoPy Homepage without BCI2000 Components
</gallery>

=== Standalone version ===
For Windows, Copy the folders '''BCIStart''', '''BCIUpdateEvent''', and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components folder.

=== Developer version ===
Copy the folders '''BCIStart''', '''BCIUpdateEvent''', and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\psychopy\experiment\components.
Open the terminal and navigate to the PsychoPy home directory where ''setup.py'' resides.
Run the following command in the terminal: 
<code>pip install -e .</code> 
 
Start PsychoPy application by running "python \psychopy\app\psychopyApp.py" from wherever you cloned your PsychoPy repository. If you downloaded the standalone version installer, you can simply press the Windows key and search for PsychoPy. Once you're under the '''Custom''' Components (in the rightmost column), you should see the three new components - ''BCI2000Start'', ''BCIUpdateEvent'', and ''BCI2000UpdateState'' as shown in the figure below.

<gallery mode="packed" widths=550px heights=550px>
File:PsychoPy_Start.png|alt="PsychoPy Homepage with BCI2000 Components"|PsychoPy Homepage with BCI2000 Components
</gallery>

'''Note:''' Make sure you don't run the experiments in full screen if you are using a single screen.

== Tutorial ==
In this section, two examples are presented to help the user understand the use of BCI2000 within PsychoPy. The examples modify the demo stroopExtended (already provided by PsychoPy once you have unpacked the demos) and integrates BCI2000 within it. The stroopExtended demo asks user to press certain keys depending on the color shown on the screen and records the response time.

=== Using Response Component Variable Option ===
In this tutorial, we will add a new state called '''correctKey''' in BCI2000 using PsychoPy. This state will be changed to 1 if the key pressed by user is correct, otherwise 0.
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like this. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>

 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>correctKey 0 1</code> in the ''States'' field as shown in the image. '''correctKey''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''1''' is the maximum value the state can take in any case. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart1.png|alt="PsychoPy - Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Fill in the fields ''State Name'' with '''$correctKey''' (the BCI2000 state we want to update; '$' is used to indicate to PsychoPy to treat it as a variable) and ''Response Component Variable'' with '''$resp.corr''' ('resp' is the name of the keyboard that takes the input and 'corr' is its property that stores whether the key pressed is correct or not. you can see this variable being used in the program when you compile it to script) as shown in the image. This will essentially update the state 'correctKey' with the value of 'resp.corr'. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState1.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on correctKey and add to watch, then click Ok on States and Events screen) and proceed as with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun1.png|alt="PsychoPy Stroop Extended Demo Run 1"|PsychoPy Stroop Extended Demo Run 1
</gallery>

</li>
 
</ol>

=== Using Use Expression Option ===
In this tutorial, we will add a new state called '''responseTime''' in BCI2000 using PsychoPy. This state will represent the time the user takes to press the correct key in seconds (with no decimals).
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like the image below. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>
 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>responseTime 0 600</code> in the ''States'' field as shown in the image. '''responseTime''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''600''' is the maximum value the state can take in any case, i.e, the maximum response time could be 10 minutes. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart2.png|alt="PsychoPy- Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Check on the '''Use Expression''' option to run the expression that is written in the '''Expression''' field. Write the lines of python code in the '''Expression''' field as shown in the image. These lines first set the 'RUNNING' state of BCI2000 to 1 to make sure that BCI2000 is running. It then checks if the type of the 'resp.rt' is float. If yes, that means 'resp.rt' stores the response time and sets the state 'responseTime' to the rounded value of 'resp.rt' ('resp' is the name of the keyboard which takes the input and 'rt' is its property that stores the time it took user to press the key; you can see this variable being used in the program when you compile it to script) using the bci.Execute and SET STATE commands. 
<code>bci.Execute('SET STATE RUNNING 1') 
if(type(resp.rt) == float): 
    bci.Execute('SET STATE responseTime %d' % round(resp.rt))
</code> 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState2.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on responseTime and add to watch. Click Ok on the States and Events screen) and proceed with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun2.png|alt="PsychoPy Stroop Extended Demo Run 2"|PsychoPy Stroop Extended Demo Run 2
</gallery>

</li>
 
</ol>

== References ==
1. [https://www.psychopy.org/ PsychoPy site]

== See Also ==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Video]]

File:PsychoPy Start.png

2025-05-12T22:11:13Z

Swiftj: Swiftj uploaded a new version of File:PsychoPy Start.png

PsychoPy

2025-05-12T22:06:20Z

Swiftj: /* Developer version */

PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. [1] This wiki page first describes the two components that remotely start BCI2000 from PsychoPy. The next section describes the steps to add the new components in the PsychoPy application. The final section goes over two tutorial examples.
==Video Overview==
<youtube alignment="center">https://youtu.be/yPacLewE3Xo</youtube>
==Prerequisites==
For this project, you will need two things: [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Building_and_Customizing_BCI2000 BCI2000] compiled for your system and the newest version of [https://www.psychopy.org/download.html PsychoPy].

== Components ==

=== BCI2000Start ===
This component starts up the BCI2000 modules remotely. The component takes two parameters:
; Path : Path to the BCI2000 ''prog'' directory, which contains the ''BCI2000Remote.py'' file.
; States : List of new states to add to BCI2000. The states in the list are defined as follows: 'StateName defaultValue maxValue.' Eg: lastKey 0 255, correctKey 0 1.
'''NOTE:''' You can specify the modules with which you want to run the experiment with the ''BCI.StartupModules'' command in the Init.py file previously copied into your PsychoPy environment. You can also specify which parameters to use for the experiment and specify other command-line arguments with the ''BCI.LoadParameterRemote'' command.

[[File:BCI2000Start.png|500px|alt="BCI2000 start component image showing its parameters"|BCIStart Component]]

=== BCI2000UpdateEvent ===
Note: It is highly recommended to use EVENTS instead of STATES when recording experimental values using BCI2000. This is because the timing of events is on a per-sample basis, while states are recorded on a per-block basis. The time of recorded states can be delayed by up to a full block (often up to 100ms).

This component defines which event to update and when. It takes the following parameters:
; Event Name : The name of the event in BCI2000 to update.
; Response Component Variable : The variable to which the event is to be set OR the variable which contains the new value of the event. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the event.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the event is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET EVENT'' to update the event in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCIUpdateEvent.PNG|500px|alt="BCI2000 update event component image showing its parameters"|BCIUpdateEvent Component]]

=== BCI2000UpdateState ===
This component defines which state to update and when. It takes the following parameters:
; State Name : The name of the state in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the state. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the state.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the state is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET STATE'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCI2000UpdateState.png|alt="BCI2000 update state component image showing its parameters"|BCIUpdateState Component]]

== Integrating BCI2000 into PyschoPy ==
Clone PsychoPy from the [https://github.com/psychopy/psychopy PyschoPy] repository. You can also download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 
Below is a picture of PsychoPy before integrating BCI2000. Notice that in the rightmost column, under '''Custom''' Components, there is no BCI2000 component.

<gallery mode="packed" widths=500px heights=500px>
File:PsychoPyWithoutBCI.png|alt="PsychoPy Homepage without BCI2000 Components"|PsychoPy Homepage without BCI2000 Components
</gallery>

=== Standalone version ===
For Windows, Copy the folders '''BCIStart''', '''BCIUpdateEvent''', and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components folder.

=== Developer version ===
Copy the folders '''BCIStart''', '''BCIUpdateEvent''', and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\psychopy\experiment\components.
Open the terminal and navigate to the PsychoPy home directory where ''setup.py'' resides.
Run the following command in the terminal: 
<code>pip install -e .</code> 
 
Start PsychoPy application by running "python \psychopy\app\psychopyApp.py" from wherever you cloned your PsychoPy repository. If you downloaded the standalone version installer, you can simply press the Windows key and search for PsychoPy. Once you're under the '''Custom''' Components (in the rightmost column), you should see the three new components - ''BCI2000Start'', ''BCIUpdateEvent'', and ''BCI2000UpdateState'' as shown in the figure below.

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPy_Start.png|alt="PsychoPy Homepage with BCI2000 Components"|PsychoPy Homepage with BCI2000 Components
</gallery>

'''Note:''' Make sure you don't run the experiments in full screen if you are using a single screen.

== Tutorial ==
In this section, two examples are presented to help the user understand the use of BCI2000 within PsychoPy. The examples modify the demo stroopExtended (already provided by PsychoPy once you have unpacked the demos) and integrates BCI2000 within it. The stroopExtended demo asks user to press certain keys depending on the color shown on the screen and records the response time.

=== Using Response Component Variable Option ===
In this tutorial, we will add a new state called '''correctKey''' in BCI2000 using PsychoPy. This state will be changed to 1 if the key pressed by user is correct, otherwise 0.
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like this. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>

 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>correctKey 0 1</code> in the ''States'' field as shown in the image. '''correctKey''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''1''' is the maximum value the state can take in any case. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart1.png|alt="PsychoPy - Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Fill in the fields ''State Name'' with '''$correctKey''' (the BCI2000 state we want to update; '$' is used to indicate to PsychoPy to treat it as a variable) and ''Response Component Variable'' with '''$resp.corr''' ('resp' is the name of the keyboard that takes the input and 'corr' is its property that stores whether the key pressed is correct or not. you can see this variable being used in the program when you compile it to script) as shown in the image. This will essentially update the state 'correctKey' with the value of 'resp.corr'. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState1.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on correctKey and add to watch, then click Ok on States and Events screen) and proceed as with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun1.png|alt="PsychoPy Stroop Extended Demo Run 1"|PsychoPy Stroop Extended Demo Run 1
</gallery>

</li>
 
</ol>

=== Using Use Expression Option ===
In this tutorial, we will add a new state called '''responseTime''' in BCI2000 using PsychoPy. This state will represent the time the user takes to press the correct key in seconds (with no decimals).
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like the image below. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>
 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>responseTime 0 600</code> in the ''States'' field as shown in the image. '''responseTime''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''600''' is the maximum value the state can take in any case, i.e, the maximum response time could be 10 minutes. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart2.png|alt="PsychoPy- Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Check on the '''Use Expression''' option to run the expression that is written in the '''Expression''' field. Write the lines of python code in the '''Expression''' field as shown in the image. These lines first set the 'RUNNING' state of BCI2000 to 1 to make sure that BCI2000 is running. It then checks if the type of the 'resp.rt' is float. If yes, that means 'resp.rt' stores the response time and sets the state 'responseTime' to the rounded value of 'resp.rt' ('resp' is the name of the keyboard which takes the input and 'rt' is its property that stores the time it took user to press the key; you can see this variable being used in the program when you compile it to script) using the bci.Execute and SET STATE commands. 
<code>bci.Execute('SET STATE RUNNING 1') 
if(type(resp.rt) == float): 
    bci.Execute('SET STATE responseTime %d' % round(resp.rt))
</code> 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState2.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on responseTime and add to watch. Click Ok on the States and Events screen) and proceed with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun2.png|alt="PsychoPy Stroop Extended Demo Run 2"|PsychoPy Stroop Extended Demo Run 2
</gallery>

</li>
 
</ol>

== References ==
1. [https://www.psychopy.org/ PsychoPy site]

== See Also ==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Video]]

PsychoPy

2025-05-12T21:59:51Z

Swiftj: /* BCI2000Start */

PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. [1] This wiki page first describes the two components that remotely start BCI2000 from PsychoPy. The next section describes the steps to add the new components in the PsychoPy application. The final section goes over two tutorial examples.
==Video Overview==
<youtube alignment="center">https://youtu.be/yPacLewE3Xo</youtube>
==Prerequisites==
For this project, you will need two things: [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Building_and_Customizing_BCI2000 BCI2000] compiled for your system and the newest version of [https://www.psychopy.org/download.html PsychoPy].

== Components ==

=== BCI2000Start ===
This component starts up the BCI2000 modules remotely. The component takes two parameters:
; Path : Path to the BCI2000 ''prog'' directory, which contains the ''BCI2000Remote.py'' file.
; States : List of new states to add to BCI2000. The states in the list are defined as follows: 'StateName defaultValue maxValue.' Eg: lastKey 0 255, correctKey 0 1.
'''NOTE:''' You can specify the modules with which you want to run the experiment with the ''BCI.StartupModules'' command in the Init.py file previously copied into your PsychoPy environment. You can also specify which parameters to use for the experiment and specify other command-line arguments with the ''BCI.LoadParameterRemote'' command.

[[File:BCI2000Start.png|500px|alt="BCI2000 start component image showing its parameters"|BCIStart Component]]

=== BCI2000UpdateEvent ===
Note: It is highly recommended to use EVENTS instead of STATES when recording experimental values using BCI2000. This is because the timing of events is on a per-sample basis, while states are recorded on a per-block basis. The time of recorded states can be delayed by up to a full block (often up to 100ms).

This component defines which event to update and when. It takes the following parameters:
; Event Name : The name of the event in BCI2000 to update.
; Response Component Variable : The variable to which the event is to be set OR the variable which contains the new value of the event. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the event.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the event is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET EVENT'' to update the event in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCIUpdateEvent.PNG|500px|alt="BCI2000 update event component image showing its parameters"|BCIUpdateEvent Component]]

=== BCI2000UpdateState ===
This component defines which state to update and when. It takes the following parameters:
; State Name : The name of the state in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the state. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the state.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the state is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET STATE'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCI2000UpdateState.png|alt="BCI2000 update state component image showing its parameters"|BCIUpdateState Component]]

== Integrating BCI2000 into PyschoPy ==
Clone PsychoPy from the [https://github.com/psychopy/psychopy PyschoPy] repository. You can also download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 
Below is a picture of PsychoPy before integrating BCI2000. Notice that in the rightmost column, under '''Custom''' Components, there is no BCI2000 component.

<gallery mode="packed" widths=500px heights=500px>
File:PsychoPyWithoutBCI.png|alt="PsychoPy Homepage without BCI2000 Components"|PsychoPy Homepage without BCI2000 Components
</gallery>

=== Standalone version ===
For Windows, Copy the folders '''BCIStart''', '''BCIUpdateEvent''', and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components folder.

=== Developer version ===
Copy the folders '''BCIStart''', '''BCIUpdateEvent''', and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\psychopy\experiment\components.
Open the terminal and navigate to the PsychoPy home directory where ''setup.py'' resides.
Run the following command in the terminal: 
<code>pip install -e .</code> 
 
Start PsychoPy application by running "python \psychopy\app\psychopyApp.py" from wherever you cloned your PsychoPy repository. If you downloaded the standalone version installer, you can simply press the Windows key and search for PsychoPy. Once you're under the '''Custom''' Components (in the rightmost column), you should see the two new components - ''BCI2000Start'', ''BCIUpdateEvent'', and ''BCI2000UpdateState'' as shown in the figure below.

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPy_Start.png|alt="PsychoPy Homepage with BCI2000 Components"|PsychoPy Homepage with BCI2000 Components
</gallery>

'''Note:''' Make sure you don't run the experiments in full screen if you are using a single screen.

== Tutorial ==
In this section, two examples are presented to help the user understand the use of BCI2000 within PsychoPy. The examples modify the demo stroopExtended (already provided by PsychoPy once you have unpacked the demos) and integrates BCI2000 within it. The stroopExtended demo asks user to press certain keys depending on the color shown on the screen and records the response time.

=== Using Response Component Variable Option ===
In this tutorial, we will add a new state called '''correctKey''' in BCI2000 using PsychoPy. This state will be changed to 1 if the key pressed by user is correct, otherwise 0.
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like this. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>

 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>correctKey 0 1</code> in the ''States'' field as shown in the image. '''correctKey''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''1''' is the maximum value the state can take in any case. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart1.png|alt="PsychoPy - Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Fill in the fields ''State Name'' with '''$correctKey''' (the BCI2000 state we want to update; '$' is used to indicate to PsychoPy to treat it as a variable) and ''Response Component Variable'' with '''$resp.corr''' ('resp' is the name of the keyboard that takes the input and 'corr' is its property that stores whether the key pressed is correct or not. you can see this variable being used in the program when you compile it to script) as shown in the image. This will essentially update the state 'correctKey' with the value of 'resp.corr'. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState1.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on correctKey and add to watch, then click Ok on States and Events screen) and proceed as with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun1.png|alt="PsychoPy Stroop Extended Demo Run 1"|PsychoPy Stroop Extended Demo Run 1
</gallery>

</li>
 
</ol>

=== Using Use Expression Option ===
In this tutorial, we will add a new state called '''responseTime''' in BCI2000 using PsychoPy. This state will represent the time the user takes to press the correct key in seconds (with no decimals).
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like the image below. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>
 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>responseTime 0 600</code> in the ''States'' field as shown in the image. '''responseTime''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''600''' is the maximum value the state can take in any case, i.e, the maximum response time could be 10 minutes. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart2.png|alt="PsychoPy- Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Check on the '''Use Expression''' option to run the expression that is written in the '''Expression''' field. Write the lines of python code in the '''Expression''' field as shown in the image. These lines first set the 'RUNNING' state of BCI2000 to 1 to make sure that BCI2000 is running. It then checks if the type of the 'resp.rt' is float. If yes, that means 'resp.rt' stores the response time and sets the state 'responseTime' to the rounded value of 'resp.rt' ('resp' is the name of the keyboard which takes the input and 'rt' is its property that stores the time it took user to press the key; you can see this variable being used in the program when you compile it to script) using the bci.Execute and SET STATE commands. 
<code>bci.Execute('SET STATE RUNNING 1') 
if(type(resp.rt) == float): 
    bci.Execute('SET STATE responseTime %d' % round(resp.rt))
</code> 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState2.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on responseTime and add to watch. Click Ok on the States and Events screen) and proceed with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun2.png|alt="PsychoPy Stroop Extended Demo Run 2"|PsychoPy Stroop Extended Demo Run 2
</gallery>

</li>
 
</ol>

== References ==
1. [https://www.psychopy.org/ PsychoPy site]

== See Also ==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Video]]

File:BCI2000Start.png

2025-05-12T21:59:17Z

Swiftj: Swiftj uploaded a new version of File:BCI2000Start.png

File:PsychoPyWithoutBCI.png

2025-05-12T21:56:59Z

Swiftj: Swiftj uploaded a new version of File:PsychoPyWithoutBCI.png

PsychoPy without BCI

PsychoPy

2025-05-12T21:56:15Z

Swiftj: /* Integrating BCI2000 into PyschoPy */

PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. [1] This wiki page first describes the two components that remotely start BCI2000 from PsychoPy. The next section describes the steps to add the new components in the PsychoPy application. The final section goes over two tutorial examples.
==Video Overview==
<youtube alignment="center">https://youtu.be/yPacLewE3Xo</youtube>
==Prerequisites==
For this project, you will need two things: [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Building_and_Customizing_BCI2000 BCI2000] compiled for your system and the newest version of [https://www.psychopy.org/download.html PsychoPy].

== Components ==

=== BCI2000Start ===
This component starts up the BCI2000 modules remotely. The component takes two parameters:
; Path : Path to the BCI2000 ''prog'' directory, which contains the ''BCI2000Remote.py'' file.
; States : List of new states to add to BCI2000. The states in the list are defined as follows: 'StateName defaultValue maxValue.' Eg: lastKey 0 255, correctKey 0 1.
'''NOTE:''' You can specify the modules with which you want to run the experiment with the ''BCI.StartupModules'' command in the Init.py file previously copied into your PsychoPy environment. You can also specify which parameters to use for the experiment and specify other command-line arguments with the ''BCI.LoadParameterRemote'' command.

[[File:BCI2000Start.png|alt="BCI2000 start component image showing its parameters"|BCIStart Component]]

=== BCI2000UpdateEvent ===
Note: It is highly recommended to use EVENTS instead of STATES when recording experimental values using BCI2000. This is because the timing of events is on a per-sample basis, while states are recorded on a per-block basis. The time of recorded states can be delayed by up to a full block (often up to 100ms).

This component defines which event to update and when. It takes the following parameters:
; Event Name : The name of the event in BCI2000 to update.
; Response Component Variable : The variable to which the event is to be set OR the variable which contains the new value of the event. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the event.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the event is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET EVENT'' to update the event in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCIUpdateEvent.PNG|500px|alt="BCI2000 update event component image showing its parameters"|BCIUpdateEvent Component]]

=== BCI2000UpdateState ===
This component defines which state to update and when. It takes the following parameters:
; State Name : The name of the state in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the state. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the state.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the state is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET STATE'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCI2000UpdateState.png|alt="BCI2000 update state component image showing its parameters"|BCIUpdateState Component]]

== Integrating BCI2000 into PyschoPy ==
Clone PsychoPy from the [https://github.com/psychopy/psychopy PyschoPy] repository. You can also download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 
Below is a picture of PsychoPy before integrating BCI2000. Notice that in the rightmost column, under '''Custom''' Components, there is no BCI2000 component.

<gallery mode="packed" widths=500px heights=500px>
File:PsychoPyWithoutBCI.png|alt="PsychoPy Homepage without BCI2000 Components"|PsychoPy Homepage without BCI2000 Components
</gallery>

=== Standalone version ===
For Windows, Copy the folders '''BCIStart''', '''BCIUpdateEvent''', and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components folder.

=== Developer version ===
Copy the folders '''BCIStart''', '''BCIUpdateEvent''', and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\psychopy\experiment\components.
Open the terminal and navigate to the PsychoPy home directory where ''setup.py'' resides.
Run the following command in the terminal: 
<code>pip install -e .</code> 
 
Start PsychoPy application by running "python \psychopy\app\psychopyApp.py" from wherever you cloned your PsychoPy repository. If you downloaded the standalone version installer, you can simply press the Windows key and search for PsychoPy. Once you're under the '''Custom''' Components (in the rightmost column), you should see the two new components - ''BCI2000Start'', ''BCIUpdateEvent'', and ''BCI2000UpdateState'' as shown in the figure below.

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPy_Start.png|alt="PsychoPy Homepage with BCI2000 Components"|PsychoPy Homepage with BCI2000 Components
</gallery>

'''Note:''' Make sure you don't run the experiments in full screen if you are using a single screen.

== Tutorial ==
In this section, two examples are presented to help the user understand the use of BCI2000 within PsychoPy. The examples modify the demo stroopExtended (already provided by PsychoPy once you have unpacked the demos) and integrates BCI2000 within it. The stroopExtended demo asks user to press certain keys depending on the color shown on the screen and records the response time.

=== Using Response Component Variable Option ===
In this tutorial, we will add a new state called '''correctKey''' in BCI2000 using PsychoPy. This state will be changed to 1 if the key pressed by user is correct, otherwise 0.
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like this. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>

 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>correctKey 0 1</code> in the ''States'' field as shown in the image. '''correctKey''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''1''' is the maximum value the state can take in any case. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart1.png|alt="PsychoPy - Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Fill in the fields ''State Name'' with '''$correctKey''' (the BCI2000 state we want to update; '$' is used to indicate to PsychoPy to treat it as a variable) and ''Response Component Variable'' with '''$resp.corr''' ('resp' is the name of the keyboard that takes the input and 'corr' is its property that stores whether the key pressed is correct or not. you can see this variable being used in the program when you compile it to script) as shown in the image. This will essentially update the state 'correctKey' with the value of 'resp.corr'. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState1.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on correctKey and add to watch, then click Ok on States and Events screen) and proceed as with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun1.png|alt="PsychoPy Stroop Extended Demo Run 1"|PsychoPy Stroop Extended Demo Run 1
</gallery>

</li>
 
</ol>

=== Using Use Expression Option ===
In this tutorial, we will add a new state called '''responseTime''' in BCI2000 using PsychoPy. This state will represent the time the user takes to press the correct key in seconds (with no decimals).
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like the image below. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>
 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>responseTime 0 600</code> in the ''States'' field as shown in the image. '''responseTime''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''600''' is the maximum value the state can take in any case, i.e, the maximum response time could be 10 minutes. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart2.png|alt="PsychoPy- Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Check on the '''Use Expression''' option to run the expression that is written in the '''Expression''' field. Write the lines of python code in the '''Expression''' field as shown in the image. These lines first set the 'RUNNING' state of BCI2000 to 1 to make sure that BCI2000 is running. It then checks if the type of the 'resp.rt' is float. If yes, that means 'resp.rt' stores the response time and sets the state 'responseTime' to the rounded value of 'resp.rt' ('resp' is the name of the keyboard which takes the input and 'rt' is its property that stores the time it took user to press the key; you can see this variable being used in the program when you compile it to script) using the bci.Execute and SET STATE commands. 
<code>bci.Execute('SET STATE RUNNING 1') 
if(type(resp.rt) == float): 
    bci.Execute('SET STATE responseTime %d' % round(resp.rt))
</code> 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState2.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on responseTime and add to watch. Click Ok on the States and Events screen) and proceed with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun2.png|alt="PsychoPy Stroop Extended Demo Run 2"|PsychoPy Stroop Extended Demo Run 2
</gallery>

</li>
 
</ol>

== References ==
1. [https://www.psychopy.org/ PsychoPy site]

== See Also ==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Video]]

User Tutorial:Psychopy

2025-05-12T18:50:05Z

Swiftj:

==Description==
PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. The video first describes the three components that are developed to remotely start BCI2000 from PsychoPy, then lists the steps to follow to add the new components in the PsychoPy application and finally goes on to an example.

==Tutorial==
<ol>
<li>Download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy1.png
</gallery>
</li>

<li>Copy the folders '''BCIStart''', '''BCIUpdateEvent''', and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components

<gallery mode="packed" widths=300px heights=300px>
File:Psychopy2.png
</gallery>
</li>

<li>
Open PsychoPy and then open your experiment file (StroopExtended is what we use in the demo)
<gallery mode="packed" widths=400px heights=400px>
File:Psychopy3.png
</gallery>
</li>

<li>
Open the part of the experiment where you want to start BCI2000 (in this case the ''instruct'' tab) and look under the custom section of the components for the '''BCI Connect''' and '''BCI Update Event''' components

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy4.png
</gallery>
</li>

<li>
Add the BCI2000 Start Component by clicking on it.
</li>

<li>
Enter the path to the prog folder in the BCI2000 directory where your BCI2000Remote.py file exists

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy5.png
</gallery>
</li>

<li>
Add the events that you want to record separated by commas (the first value will always be the default value and the second value will always be the maximum value). It is strongly recommended to use events instead of states, as events are recorded on a per-sample basis, while states are recorded on a pre-block basis.

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy6.png
</gallery>
</li>

<li>
Add the BCIUpdateEvent component to where you want to update event values. You can either choose to simply pass a variable through BCIUpdateEvent, or you can specify that it execute a specific Python script by choosing the "Use Expression" ticker

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy7.png
</gallery>

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy8.png
</gallery>
</li>

<li>
Run the experiment

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy9.png
</gallery>

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy10.png
</gallery>
</li>

</ol>

==Video==
<youtube alignment="center">https://www.youtube.com/watch?v=yPacLewE3Xo&list=PL6LrR5Nj3cAxOxKHNsnqyKfLDGikpi8Qi&index=4</youtube>

Also see the [https://bci2000.org/mediawiki/index.php/PsychoPy PsychoPy] page for more details on the installation process, APIs, and hooks.

==See also==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Tutorial]][[Category:Video]]

File:Psychopy10.png

2025-05-12T18:34:43Z

Swiftj: Swiftj uploaded a new version of File:Psychopy10.png

File:Psychopy9.png

2025-05-12T18:34:33Z

Swiftj: Swiftj uploaded a new version of File:Psychopy9.png

File:Psychopy8.png

2025-05-12T18:34:25Z

Swiftj: Swiftj uploaded a new version of File:Psychopy8.png

File:Psychopy7.png

2025-05-12T18:34:14Z

Swiftj: Swiftj uploaded a new version of File:Psychopy7.png

File:Psychopy6.png

2025-05-12T18:34:01Z

Swiftj: Swiftj uploaded a new version of File:Psychopy6.png

File:Psychopy5.png

2025-05-12T18:33:50Z

Swiftj: Swiftj uploaded a new version of File:Psychopy5.png

File:Psychopy4.png

2025-05-12T18:33:38Z

Swiftj: Swiftj uploaded a new version of File:Psychopy4.png

File:Psychopy2.png

2025-05-12T18:33:26Z

Swiftj: Swiftj uploaded a new version of File:Psychopy2.png

PsychoPy

2025-05-12T16:41:58Z

Swiftj: /* BCI2000UpdateEvent */

PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. [1] This wiki page first describes the two components that remotely start BCI2000 from PsychoPy. The next section describes the steps to add the new components in the PsychoPy application. The final section goes over two tutorial examples.
==Video Overview==
<youtube alignment="center">https://youtu.be/yPacLewE3Xo</youtube>
==Prerequisites==
For this project, you will need two things: [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Building_and_Customizing_BCI2000 BCI2000] compiled for your system and the newest version of [https://www.psychopy.org/download.html PsychoPy].

== Components ==

=== BCI2000Start ===
This component starts up the BCI2000 modules remotely. The component takes two parameters:
; Path : Path to the BCI2000 ''prog'' directory, which contains the ''BCI2000Remote.py'' file.
; States : List of new states to add to BCI2000. The states in the list are defined as follows: 'StateName defaultValue maxValue.' Eg: lastKey 0 255, correctKey 0 1.
'''NOTE:''' You can specify the modules with which you want to run the experiment with the ''BCI.StartupModules'' command in the Init.py file previously copied into your PsychoPy environment. You can also specify which parameters to use for the experiment and specify other command-line arguments with the ''BCI.LoadParameterRemote'' command.

[[File:BCI2000Start.png|alt="BCI2000 start component image showing its parameters"|BCIStart Component]]

=== BCI2000UpdateEvent ===
Note: It is highly recommended to use EVENTS instead of STATES when recording experimental values using BCI2000. This is because the timing of events is on a per-sample basis, while states are recorded on a per-block basis. The time of recorded states can be delayed by up to a full block (often up to 100ms).

This component defines which event to update and when. It takes the following parameters:
; Event Name : The name of the event in BCI2000 to update.
; Response Component Variable : The variable to which the event is to be set OR the variable which contains the new value of the event. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the event.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the event is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET EVENT'' to update the event in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCIUpdateEvent.PNG|500px|alt="BCI2000 update event component image showing its parameters"|BCIUpdateEvent Component]]

=== BCI2000UpdateState ===
This component defines which state to update and when. It takes the following parameters:
; State Name : The name of the state in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the state. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the state.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the state is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET STATE'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCI2000UpdateState.png|alt="BCI2000 update state component image showing its parameters"|BCIUpdateState Component]]

== Integrating BCI2000 into PyschoPy ==
Clone PsychoPy from the [https://github.com/psychopy/psychopy PyschoPy] repository. You can also download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 
Below is a picture of PsychoPy before integrating BCI2000. Notice that in the rightmost column, under '''Custom''' Components, there is no BCI2000 component.

<gallery mode="packed" widths=500px heights=500px>
File:PsychoPyWithoutBCI.png|alt="PsychoPy Homepage without BCI2000 Components"|PsychoPy Homepage without BCI2000 Components
</gallery>

=== Standalone version ===
For Windows, Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components folder.

=== Developer version ===
Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\psychopy\experiment\components.
Open the terminal and navigate to the PsychoPy home directory where ''setup.py'' resides.
Run the following command in the terminal: 
<code>pip install -e .</code> 
 
Start PsychoPy application by running "python \psychopy\app\psychopyApp.py" from wherever you cloned your PsychoPy repository. If you downloaded the standalone version installer, you can simply press the Windows key and search for PsychoPy. Once you're under the '''Custom''' Components (in the rightmost column), you should see the two new components - ''BCI2000Start'' and ''BCI2000UpdateState'' as shown in the figure below.

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPy_Start.png|alt="PsychoPy Homepage with BCI2000 Components"|PsychoPy Homepage with BCI2000 Components
</gallery>

'''Note:''' Make sure you don't run the experiments in full screen if you are using a single screen.

== Tutorial ==
In this section, two examples are presented to help the user understand the use of BCI2000 within PsychoPy. The examples modify the demo stroopExtended (already provided by PsychoPy once you have unpacked the demos) and integrates BCI2000 within it. The stroopExtended demo asks user to press certain keys depending on the color shown on the screen and records the response time.

=== Using Response Component Variable Option ===
In this tutorial, we will add a new state called '''correctKey''' in BCI2000 using PsychoPy. This state will be changed to 1 if the key pressed by user is correct, otherwise 0.
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like this. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>

 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>correctKey 0 1</code> in the ''States'' field as shown in the image. '''correctKey''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''1''' is the maximum value the state can take in any case. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart1.png|alt="PsychoPy - Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Fill in the fields ''State Name'' with '''$correctKey''' (the BCI2000 state we want to update; '$' is used to indicate to PsychoPy to treat it as a variable) and ''Response Component Variable'' with '''$resp.corr''' ('resp' is the name of the keyboard that takes the input and 'corr' is its property that stores whether the key pressed is correct or not. you can see this variable being used in the program when you compile it to script) as shown in the image. This will essentially update the state 'correctKey' with the value of 'resp.corr'. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState1.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on correctKey and add to watch, then click Ok on States and Events screen) and proceed as with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun1.png|alt="PsychoPy Stroop Extended Demo Run 1"|PsychoPy Stroop Extended Demo Run 1
</gallery>

</li>
 
</ol>

=== Using Use Expression Option ===
In this tutorial, we will add a new state called '''responseTime''' in BCI2000 using PsychoPy. This state will represent the time the user takes to press the correct key in seconds (with no decimals).
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like the image below. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>
 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>responseTime 0 600</code> in the ''States'' field as shown in the image. '''responseTime''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''600''' is the maximum value the state can take in any case, i.e, the maximum response time could be 10 minutes. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart2.png|alt="PsychoPy- Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Check on the '''Use Expression''' option to run the expression that is written in the '''Expression''' field. Write the lines of python code in the '''Expression''' field as shown in the image. These lines first set the 'RUNNING' state of BCI2000 to 1 to make sure that BCI2000 is running. It then checks if the type of the 'resp.rt' is float. If yes, that means 'resp.rt' stores the response time and sets the state 'responseTime' to the rounded value of 'resp.rt' ('resp' is the name of the keyboard which takes the input and 'rt' is its property that stores the time it took user to press the key; you can see this variable being used in the program when you compile it to script) using the bci.Execute and SET STATE commands. 
<code>bci.Execute('SET STATE RUNNING 1') 
if(type(resp.rt) == float): 
    bci.Execute('SET STATE responseTime %d' % round(resp.rt))
</code> 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState2.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on responseTime and add to watch. Click Ok on the States and Events screen) and proceed with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun2.png|alt="PsychoPy Stroop Extended Demo Run 2"|PsychoPy Stroop Extended Demo Run 2
</gallery>

</li>
 
</ol>

== References ==
1. [https://www.psychopy.org/ PsychoPy site]

== See Also ==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Video]]

PsychoPy

2025-05-12T16:40:28Z

Swiftj: /* BCI2000UpdateEvent */

PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. [1] This wiki page first describes the two components that remotely start BCI2000 from PsychoPy. The next section describes the steps to add the new components in the PsychoPy application. The final section goes over two tutorial examples.
==Video Overview==
<youtube alignment="center">https://youtu.be/yPacLewE3Xo</youtube>
==Prerequisites==
For this project, you will need two things: [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Building_and_Customizing_BCI2000 BCI2000] compiled for your system and the newest version of [https://www.psychopy.org/download.html PsychoPy].

== Components ==

=== BCI2000Start ===
This component starts up the BCI2000 modules remotely. The component takes two parameters:
; Path : Path to the BCI2000 ''prog'' directory, which contains the ''BCI2000Remote.py'' file.
; States : List of new states to add to BCI2000. The states in the list are defined as follows: 'StateName defaultValue maxValue.' Eg: lastKey 0 255, correctKey 0 1.
'''NOTE:''' You can specify the modules with which you want to run the experiment with the ''BCI.StartupModules'' command in the Init.py file previously copied into your PsychoPy environment. You can also specify which parameters to use for the experiment and specify other command-line arguments with the ''BCI.LoadParameterRemote'' command.

[[File:BCI2000Start.png|alt="BCI2000 start component image showing its parameters"|BCIStart Component]]

=== BCI2000UpdateEvent ===
Note: It is highly recommended to use EVENTS instead of STATES when recording experimental values using BCI2000. This is because the timing of events is on a per-sample basis, while states are recorded on a per-block basis. The time of recorded states can be delayed by up to a full block (often up to 100ms).

This component defines which event to update and when. It takes the following parameters:
; Event Name : The name of the event in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the event. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the event.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the event is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET EVENT'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCIUpdateEvent.PNG|500px|alt="BCI2000 update event component image showing its parameters"|BCIUpdateEvent Component]]

=== BCI2000UpdateState ===
This component defines which state to update and when. It takes the following parameters:
; State Name : The name of the state in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the state. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the state.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the state is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET STATE'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCI2000UpdateState.png|alt="BCI2000 update state component image showing its parameters"|BCIUpdateState Component]]

== Integrating BCI2000 into PyschoPy ==
Clone PsychoPy from the [https://github.com/psychopy/psychopy PyschoPy] repository. You can also download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 
Below is a picture of PsychoPy before integrating BCI2000. Notice that in the rightmost column, under '''Custom''' Components, there is no BCI2000 component.

<gallery mode="packed" widths=500px heights=500px>
File:PsychoPyWithoutBCI.png|alt="PsychoPy Homepage without BCI2000 Components"|PsychoPy Homepage without BCI2000 Components
</gallery>

=== Standalone version ===
For Windows, Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components folder.

=== Developer version ===
Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\psychopy\experiment\components.
Open the terminal and navigate to the PsychoPy home directory where ''setup.py'' resides.
Run the following command in the terminal: 
<code>pip install -e .</code> 
 
Start PsychoPy application by running "python \psychopy\app\psychopyApp.py" from wherever you cloned your PsychoPy repository. If you downloaded the standalone version installer, you can simply press the Windows key and search for PsychoPy. Once you're under the '''Custom''' Components (in the rightmost column), you should see the two new components - ''BCI2000Start'' and ''BCI2000UpdateState'' as shown in the figure below.

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPy_Start.png|alt="PsychoPy Homepage with BCI2000 Components"|PsychoPy Homepage with BCI2000 Components
</gallery>

'''Note:''' Make sure you don't run the experiments in full screen if you are using a single screen.

== Tutorial ==
In this section, two examples are presented to help the user understand the use of BCI2000 within PsychoPy. The examples modify the demo stroopExtended (already provided by PsychoPy once you have unpacked the demos) and integrates BCI2000 within it. The stroopExtended demo asks user to press certain keys depending on the color shown on the screen and records the response time.

=== Using Response Component Variable Option ===
In this tutorial, we will add a new state called '''correctKey''' in BCI2000 using PsychoPy. This state will be changed to 1 if the key pressed by user is correct, otherwise 0.
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like this. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>

 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>correctKey 0 1</code> in the ''States'' field as shown in the image. '''correctKey''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''1''' is the maximum value the state can take in any case. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart1.png|alt="PsychoPy - Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Fill in the fields ''State Name'' with '''$correctKey''' (the BCI2000 state we want to update; '$' is used to indicate to PsychoPy to treat it as a variable) and ''Response Component Variable'' with '''$resp.corr''' ('resp' is the name of the keyboard that takes the input and 'corr' is its property that stores whether the key pressed is correct or not. you can see this variable being used in the program when you compile it to script) as shown in the image. This will essentially update the state 'correctKey' with the value of 'resp.corr'. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState1.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on correctKey and add to watch, then click Ok on States and Events screen) and proceed as with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun1.png|alt="PsychoPy Stroop Extended Demo Run 1"|PsychoPy Stroop Extended Demo Run 1
</gallery>

</li>
 
</ol>

=== Using Use Expression Option ===
In this tutorial, we will add a new state called '''responseTime''' in BCI2000 using PsychoPy. This state will represent the time the user takes to press the correct key in seconds (with no decimals).
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like the image below. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>
 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>responseTime 0 600</code> in the ''States'' field as shown in the image. '''responseTime''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''600''' is the maximum value the state can take in any case, i.e, the maximum response time could be 10 minutes. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart2.png|alt="PsychoPy- Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Check on the '''Use Expression''' option to run the expression that is written in the '''Expression''' field. Write the lines of python code in the '''Expression''' field as shown in the image. These lines first set the 'RUNNING' state of BCI2000 to 1 to make sure that BCI2000 is running. It then checks if the type of the 'resp.rt' is float. If yes, that means 'resp.rt' stores the response time and sets the state 'responseTime' to the rounded value of 'resp.rt' ('resp' is the name of the keyboard which takes the input and 'rt' is its property that stores the time it took user to press the key; you can see this variable being used in the program when you compile it to script) using the bci.Execute and SET STATE commands. 
<code>bci.Execute('SET STATE RUNNING 1') 
if(type(resp.rt) == float): 
    bci.Execute('SET STATE responseTime %d' % round(resp.rt))
</code> 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState2.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on responseTime and add to watch. Click Ok on the States and Events screen) and proceed with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun2.png|alt="PsychoPy Stroop Extended Demo Run 2"|PsychoPy Stroop Extended Demo Run 2
</gallery>

</li>
 
</ol>

== References ==
1. [https://www.psychopy.org/ PsychoPy site]

== See Also ==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Video]]

PsychoPy

2025-05-12T16:22:42Z

Swiftj: /* BCI2000UpdateEvent */

PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. [1] This wiki page first describes the two components that remotely start BCI2000 from PsychoPy. The next section describes the steps to add the new components in the PsychoPy application. The final section goes over two tutorial examples.
==Video Overview==
<youtube alignment="center">https://youtu.be/yPacLewE3Xo</youtube>
==Prerequisites==
For this project, you will need two things: [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Building_and_Customizing_BCI2000 BCI2000] compiled for your system and the newest version of [https://www.psychopy.org/download.html PsychoPy].

== Components ==

=== BCI2000Start ===
This component starts up the BCI2000 modules remotely. The component takes two parameters:
; Path : Path to the BCI2000 ''prog'' directory, which contains the ''BCI2000Remote.py'' file.
; States : List of new states to add to BCI2000. The states in the list are defined as follows: 'StateName defaultValue maxValue.' Eg: lastKey 0 255, correctKey 0 1.
'''NOTE:''' You can specify the modules with which you want to run the experiment with the ''BCI.StartupModules'' command in the Init.py file previously copied into your PsychoPy environment. You can also specify which parameters to use for the experiment and specify other command-line arguments with the ''BCI.LoadParameterRemote'' command.

[[File:BCI2000Start.png|alt="BCI2000 start component image showing its parameters"|BCIStart Component]]

=== BCI2000UpdateEvent ===
Note: It is highly recommended to use EVENTS instead of STATES when recording experimental values using BCI2000. This is because the timing of events is on a per-sample basis, while states are recorded on a per-block basis. The time of recorded states can be delayed by up to a full block (often up to 100ms).

This component defines which event to update and when. It takes the following parameters:
; Event Name : The name of the event in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the event. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the event.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the event is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET EVENT'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCIUpdateEvent.PNG|alt="BCI2000 update event component image showing its parameters"|BCIUpdateEvent Component]]

=== BCI2000UpdateState ===
This component defines which state to update and when. It takes the following parameters:
; State Name : The name of the state in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the state. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the state.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the state is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET STATE'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCI2000UpdateState.png|alt="BCI2000 update state component image showing its parameters"|BCIUpdateState Component]]

== Integrating BCI2000 into PyschoPy ==
Clone PsychoPy from the [https://github.com/psychopy/psychopy PyschoPy] repository. You can also download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 
Below is a picture of PsychoPy before integrating BCI2000. Notice that in the rightmost column, under '''Custom''' Components, there is no BCI2000 component.

<gallery mode="packed" widths=500px heights=500px>
File:PsychoPyWithoutBCI.png|alt="PsychoPy Homepage without BCI2000 Components"|PsychoPy Homepage without BCI2000 Components
</gallery>

=== Standalone version ===
For Windows, Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components folder.

=== Developer version ===
Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\psychopy\experiment\components.
Open the terminal and navigate to the PsychoPy home directory where ''setup.py'' resides.
Run the following command in the terminal: 
<code>pip install -e .</code> 
 
Start PsychoPy application by running "python \psychopy\app\psychopyApp.py" from wherever you cloned your PsychoPy repository. If you downloaded the standalone version installer, you can simply press the Windows key and search for PsychoPy. Once you're under the '''Custom''' Components (in the rightmost column), you should see the two new components - ''BCI2000Start'' and ''BCI2000UpdateState'' as shown in the figure below.

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPy_Start.png|alt="PsychoPy Homepage with BCI2000 Components"|PsychoPy Homepage with BCI2000 Components
</gallery>

'''Note:''' Make sure you don't run the experiments in full screen if you are using a single screen.

== Tutorial ==
In this section, two examples are presented to help the user understand the use of BCI2000 within PsychoPy. The examples modify the demo stroopExtended (already provided by PsychoPy once you have unpacked the demos) and integrates BCI2000 within it. The stroopExtended demo asks user to press certain keys depending on the color shown on the screen and records the response time.

=== Using Response Component Variable Option ===
In this tutorial, we will add a new state called '''correctKey''' in BCI2000 using PsychoPy. This state will be changed to 1 if the key pressed by user is correct, otherwise 0.
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like this. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>

 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>correctKey 0 1</code> in the ''States'' field as shown in the image. '''correctKey''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''1''' is the maximum value the state can take in any case. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart1.png|alt="PsychoPy - Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Fill in the fields ''State Name'' with '''$correctKey''' (the BCI2000 state we want to update; '$' is used to indicate to PsychoPy to treat it as a variable) and ''Response Component Variable'' with '''$resp.corr''' ('resp' is the name of the keyboard that takes the input and 'corr' is its property that stores whether the key pressed is correct or not. you can see this variable being used in the program when you compile it to script) as shown in the image. This will essentially update the state 'correctKey' with the value of 'resp.corr'. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState1.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on correctKey and add to watch, then click Ok on States and Events screen) and proceed as with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun1.png|alt="PsychoPy Stroop Extended Demo Run 1"|PsychoPy Stroop Extended Demo Run 1
</gallery>

</li>
 
</ol>

=== Using Use Expression Option ===
In this tutorial, we will add a new state called '''responseTime''' in BCI2000 using PsychoPy. This state will represent the time the user takes to press the correct key in seconds (with no decimals).
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like the image below. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>
 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>responseTime 0 600</code> in the ''States'' field as shown in the image. '''responseTime''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''600''' is the maximum value the state can take in any case, i.e, the maximum response time could be 10 minutes. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart2.png|alt="PsychoPy- Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Check on the '''Use Expression''' option to run the expression that is written in the '''Expression''' field. Write the lines of python code in the '''Expression''' field as shown in the image. These lines first set the 'RUNNING' state of BCI2000 to 1 to make sure that BCI2000 is running. It then checks if the type of the 'resp.rt' is float. If yes, that means 'resp.rt' stores the response time and sets the state 'responseTime' to the rounded value of 'resp.rt' ('resp' is the name of the keyboard which takes the input and 'rt' is its property that stores the time it took user to press the key; you can see this variable being used in the program when you compile it to script) using the bci.Execute and SET STATE commands. 
<code>bci.Execute('SET STATE RUNNING 1') 
if(type(resp.rt) == float): 
    bci.Execute('SET STATE responseTime %d' % round(resp.rt))
</code> 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState2.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on responseTime and add to watch. Click Ok on the States and Events screen) and proceed with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun2.png|alt="PsychoPy Stroop Extended Demo Run 2"|PsychoPy Stroop Extended Demo Run 2
</gallery>

</li>
 
</ol>

== References ==
1. [https://www.psychopy.org/ PsychoPy site]

== See Also ==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Video]]

PsychoPy

2025-05-12T16:21:06Z

Swiftj: /* Components */

PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. [1] This wiki page first describes the two components that remotely start BCI2000 from PsychoPy. The next section describes the steps to add the new components in the PsychoPy application. The final section goes over two tutorial examples.
==Video Overview==
<youtube alignment="center">https://youtu.be/yPacLewE3Xo</youtube>
==Prerequisites==
For this project, you will need two things: [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Building_and_Customizing_BCI2000 BCI2000] compiled for your system and the newest version of [https://www.psychopy.org/download.html PsychoPy].

== Components ==

=== BCI2000Start ===
This component starts up the BCI2000 modules remotely. The component takes two parameters:
; Path : Path to the BCI2000 ''prog'' directory, which contains the ''BCI2000Remote.py'' file.
; States : List of new states to add to BCI2000. The states in the list are defined as follows: 'StateName defaultValue maxValue.' Eg: lastKey 0 255, correctKey 0 1.
'''NOTE:''' You can specify the modules with which you want to run the experiment with the ''BCI.StartupModules'' command in the Init.py file previously copied into your PsychoPy environment. You can also specify which parameters to use for the experiment and specify other command-line arguments with the ''BCI.LoadParameterRemote'' command.

[[File:BCI2000Start.png|alt="BCI2000 start component image showing its parameters"|BCIStart Component]]

=== BCI2000UpdateEvent ===
Note: It is highly recommended to use EVENTS instead of STATES when recording experimental values using BCI2000. This is because the timing of events is on a per-sample basis, while states are recorded on a per-block basis. The time of recorded states can be delayed by up to a full block (often up to 100ms).

This component defines which event to update and when. It takes the following parameters:
; Event Name : The name of the event in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the event. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the event.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the event is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET EVENT'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCIUpdateEvent.png|alt="BCI2000 update event component image showing its parameters"|BCIUpdateEvent Component]]

=== BCI2000UpdateState ===
This component defines which state to update and when. It takes the following parameters:
; State Name : The name of the state in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the state. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the state.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the state is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET STATE'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCI2000UpdateState.png|alt="BCI2000 update state component image showing its parameters"|BCIUpdateState Component]]

== Integrating BCI2000 into PyschoPy ==
Clone PsychoPy from the [https://github.com/psychopy/psychopy PyschoPy] repository. You can also download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 
Below is a picture of PsychoPy before integrating BCI2000. Notice that in the rightmost column, under '''Custom''' Components, there is no BCI2000 component.

<gallery mode="packed" widths=500px heights=500px>
File:PsychoPyWithoutBCI.png|alt="PsychoPy Homepage without BCI2000 Components"|PsychoPy Homepage without BCI2000 Components
</gallery>

=== Standalone version ===
For Windows, Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components folder.

=== Developer version ===
Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\psychopy\experiment\components.
Open the terminal and navigate to the PsychoPy home directory where ''setup.py'' resides.
Run the following command in the terminal: 
<code>pip install -e .</code> 
 
Start PsychoPy application by running "python \psychopy\app\psychopyApp.py" from wherever you cloned your PsychoPy repository. If you downloaded the standalone version installer, you can simply press the Windows key and search for PsychoPy. Once you're under the '''Custom''' Components (in the rightmost column), you should see the two new components - ''BCI2000Start'' and ''BCI2000UpdateState'' as shown in the figure below.

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPy_Start.png|alt="PsychoPy Homepage with BCI2000 Components"|PsychoPy Homepage with BCI2000 Components
</gallery>

'''Note:''' Make sure you don't run the experiments in full screen if you are using a single screen.

== Tutorial ==
In this section, two examples are presented to help the user understand the use of BCI2000 within PsychoPy. The examples modify the demo stroopExtended (already provided by PsychoPy once you have unpacked the demos) and integrates BCI2000 within it. The stroopExtended demo asks user to press certain keys depending on the color shown on the screen and records the response time.

=== Using Response Component Variable Option ===
In this tutorial, we will add a new state called '''correctKey''' in BCI2000 using PsychoPy. This state will be changed to 1 if the key pressed by user is correct, otherwise 0.
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like this. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>

 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>correctKey 0 1</code> in the ''States'' field as shown in the image. '''correctKey''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''1''' is the maximum value the state can take in any case. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart1.png|alt="PsychoPy - Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Fill in the fields ''State Name'' with '''$correctKey''' (the BCI2000 state we want to update; '$' is used to indicate to PsychoPy to treat it as a variable) and ''Response Component Variable'' with '''$resp.corr''' ('resp' is the name of the keyboard that takes the input and 'corr' is its property that stores whether the key pressed is correct or not. you can see this variable being used in the program when you compile it to script) as shown in the image. This will essentially update the state 'correctKey' with the value of 'resp.corr'. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState1.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on correctKey and add to watch, then click Ok on States and Events screen) and proceed as with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun1.png|alt="PsychoPy Stroop Extended Demo Run 1"|PsychoPy Stroop Extended Demo Run 1
</gallery>

</li>
 
</ol>

=== Using Use Expression Option ===
In this tutorial, we will add a new state called '''responseTime''' in BCI2000 using PsychoPy. This state will represent the time the user takes to press the correct key in seconds (with no decimals).
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like the image below. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>
 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>responseTime 0 600</code> in the ''States'' field as shown in the image. '''responseTime''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''600''' is the maximum value the state can take in any case, i.e, the maximum response time could be 10 minutes. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart2.png|alt="PsychoPy- Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Check on the '''Use Expression''' option to run the expression that is written in the '''Expression''' field. Write the lines of python code in the '''Expression''' field as shown in the image. These lines first set the 'RUNNING' state of BCI2000 to 1 to make sure that BCI2000 is running. It then checks if the type of the 'resp.rt' is float. If yes, that means 'resp.rt' stores the response time and sets the state 'responseTime' to the rounded value of 'resp.rt' ('resp' is the name of the keyboard which takes the input and 'rt' is its property that stores the time it took user to press the key; you can see this variable being used in the program when you compile it to script) using the bci.Execute and SET STATE commands. 
<code>bci.Execute('SET STATE RUNNING 1') 
if(type(resp.rt) == float): 
    bci.Execute('SET STATE responseTime %d' % round(resp.rt))
</code> 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState2.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on responseTime and add to watch. Click Ok on the States and Events screen) and proceed with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun2.png|alt="PsychoPy Stroop Extended Demo Run 2"|PsychoPy Stroop Extended Demo Run 2
</gallery>

</li>
 
</ol>

== References ==
1. [https://www.psychopy.org/ PsychoPy site]

== See Also ==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Video]]

File:BCIUpdateEvent.PNG

2025-05-12T16:20:38Z

Swiftj:

PsychoPy

2025-05-12T16:17:53Z

Swiftj: /* Components */

PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. [1] This wiki page first describes the two components that remotely start BCI2000 from PsychoPy. The next section describes the steps to add the new components in the PsychoPy application. The final section goes over two tutorial examples.
==Video Overview==
<youtube alignment="center">https://youtu.be/yPacLewE3Xo</youtube>
==Prerequisites==
For this project, you will need two things: [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Building_and_Customizing_BCI2000 BCI2000] compiled for your system and the newest version of [https://www.psychopy.org/download.html PsychoPy].

== Components ==

=== BCI2000Start ===
This component starts up the BCI2000 modules remotely. The component takes two parameters:
; Path : Path to the BCI2000 ''prog'' directory, which contains the ''BCI2000Remote.py'' file.
; States : List of new states to add to BCI2000. The states in the list are defined as follows: 'StateName defaultValue maxValue.' Eg: lastKey 0 255, correctKey 0 1.
'''NOTE:''' You can specify the modules with which you want to run the experiment with the ''BCI.StartupModules'' command in the Init.py file previously copied into your PsychoPy environment. You can also specify which parameters to use for the experiment and specify other command-line arguments with the ''BCI.LoadParameterRemote'' command.

[[File:BCI2000Start.png|alt="BCI2000 start component image showing its parameters"|BCIStart Component]]

=== BCI2000UpdateEvent ===
Note: It is highly recommended to use EVENTS instead of STATES when recording experimental values using BCI2000. This is because the timing of events is on a per-sample basis, while states are recorded on a per-block basis. The time of recorded states can be delayed by up to a full block (often up to 100ms).

This component defines which event to update and when. It takes the following parameters:
; Event Name : The name of the event in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the event. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the event.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the event is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET EVENT'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCI2000UpdateEvent.png|alt="BCI2000 update event component image showing its parameters"|BCIUpdateEvent Component]]

=== BCI2000UpdateState ===
This component defines which state to update and when. It takes the following parameters:
; State Name : The name of the state in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the state. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the state.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the state is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET STATE'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCI2000UpdateState.png|alt="BCI2000 update state component image showing its parameters"|BCIUpdateState Component]]

== Integrating BCI2000 into PyschoPy ==
Clone PsychoPy from the [https://github.com/psychopy/psychopy PyschoPy] repository. You can also download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 
Below is a picture of PsychoPy before integrating BCI2000. Notice that in the rightmost column, under '''Custom''' Components, there is no BCI2000 component.

<gallery mode="packed" widths=500px heights=500px>
File:PsychoPyWithoutBCI.png|alt="PsychoPy Homepage without BCI2000 Components"|PsychoPy Homepage without BCI2000 Components
</gallery>

=== Standalone version ===
For Windows, Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components folder.

=== Developer version ===
Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\psychopy\experiment\components.
Open the terminal and navigate to the PsychoPy home directory where ''setup.py'' resides.
Run the following command in the terminal: 
<code>pip install -e .</code> 
 
Start PsychoPy application by running "python \psychopy\app\psychopyApp.py" from wherever you cloned your PsychoPy repository. If you downloaded the standalone version installer, you can simply press the Windows key and search for PsychoPy. Once you're under the '''Custom''' Components (in the rightmost column), you should see the two new components - ''BCI2000Start'' and ''BCI2000UpdateState'' as shown in the figure below.

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPy_Start.png|alt="PsychoPy Homepage with BCI2000 Components"|PsychoPy Homepage with BCI2000 Components
</gallery>

'''Note:''' Make sure you don't run the experiments in full screen if you are using a single screen.

== Tutorial ==
In this section, two examples are presented to help the user understand the use of BCI2000 within PsychoPy. The examples modify the demo stroopExtended (already provided by PsychoPy once you have unpacked the demos) and integrates BCI2000 within it. The stroopExtended demo asks user to press certain keys depending on the color shown on the screen and records the response time.

=== Using Response Component Variable Option ===
In this tutorial, we will add a new state called '''correctKey''' in BCI2000 using PsychoPy. This state will be changed to 1 if the key pressed by user is correct, otherwise 0.
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like this. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>

 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>correctKey 0 1</code> in the ''States'' field as shown in the image. '''correctKey''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''1''' is the maximum value the state can take in any case. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart1.png|alt="PsychoPy - Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Fill in the fields ''State Name'' with '''$correctKey''' (the BCI2000 state we want to update; '$' is used to indicate to PsychoPy to treat it as a variable) and ''Response Component Variable'' with '''$resp.corr''' ('resp' is the name of the keyboard that takes the input and 'corr' is its property that stores whether the key pressed is correct or not. you can see this variable being used in the program when you compile it to script) as shown in the image. This will essentially update the state 'correctKey' with the value of 'resp.corr'. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState1.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on correctKey and add to watch, then click Ok on States and Events screen) and proceed as with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun1.png|alt="PsychoPy Stroop Extended Demo Run 1"|PsychoPy Stroop Extended Demo Run 1
</gallery>

</li>
 
</ol>

=== Using Use Expression Option ===
In this tutorial, we will add a new state called '''responseTime''' in BCI2000 using PsychoPy. This state will represent the time the user takes to press the correct key in seconds (with no decimals).
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like the image below. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>
 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>responseTime 0 600</code> in the ''States'' field as shown in the image. '''responseTime''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''600''' is the maximum value the state can take in any case, i.e, the maximum response time could be 10 minutes. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart2.png|alt="PsychoPy- Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Check on the '''Use Expression''' option to run the expression that is written in the '''Expression''' field. Write the lines of python code in the '''Expression''' field as shown in the image. These lines first set the 'RUNNING' state of BCI2000 to 1 to make sure that BCI2000 is running. It then checks if the type of the 'resp.rt' is float. If yes, that means 'resp.rt' stores the response time and sets the state 'responseTime' to the rounded value of 'resp.rt' ('resp' is the name of the keyboard which takes the input and 'rt' is its property that stores the time it took user to press the key; you can see this variable being used in the program when you compile it to script) using the bci.Execute and SET STATE commands. 
<code>bci.Execute('SET STATE RUNNING 1') 
if(type(resp.rt) == float): 
    bci.Execute('SET STATE responseTime %d' % round(resp.rt))
</code> 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState2.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on responseTime and add to watch. Click Ok on the States and Events screen) and proceed with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun2.png|alt="PsychoPy Stroop Extended Demo Run 2"|PsychoPy Stroop Extended Demo Run 2
</gallery>

</li>
 
</ol>

== References ==
1. [https://www.psychopy.org/ PsychoPy site]

== See Also ==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Video]]

Programming Howto:Building and Customizing BCI2000

2025-02-05T17:46:27Z

Swiftj: /* Video Overview */

This tutorial walks you through the process of obtaining the [[Programming_Reference:BCI2000_Source_Code|BCI2000 source distribution]], and using it to build and test your own custom [[BCI2000_Glossary#Filter|filters]], implemented in C++ inside your own custom [[BCI2000_Glossary#Core_Module|core module]]. It assumes that you have a good working knowledge of the C++ language, and basic familiarity with the compiler/IDE that you are going to use.

This tutorial is a simplified version of the previous [[Programming Howto:Quickstart Guide]], which is slightly outdated but kept in the wiki as it contains valuable suggestions and exercises.

==Howto steps==
*[[Programming Howto:Install Prerequisites|Install Prerequisites]]
:shows you how to install TortoiseSVN, CMake, VisualStudio, and Qt.
*[[Programming Howto:Register with BCI2000 Project|Register with the BCI2000 Project]]
:explains how to obtain a BCI2000 user account.
*[[Programming Howto:Download the BCI2000 Sourcecode|Download the BCI2000 Sourcecode]]
:details the steps how to use TortoiseSVN to download the BCI2000 sourcecode.
*[[Programming Howto:Configure BCI2000 for Compilation|Configure BCI2000 for Compilation]]
:demonstrates how to use CMake to create a BCI2000 solution file.
*[[Programming Howto:Compile BCI2000|Compile BCI2000]]
:illustrates how to compile BCI2000 using VisualStudio.
*[[Programming Howto:Create a custom Signal Processing Module|Create a custom Signal Processing Module]]
:shows how to create a new BCI2000 module from a template.
*[[Programming Howto:Attach the Debugger to a BCI2000 Module|Attach the Debugger to a BCI2000 Module]]
:explains how to attach the VisualStudio debugger to a running module.
*[[Programming Howto:Programmatically wait for the Debugger in a BCI2000 Module|Programmatically wait for the Debugger in a BCI2000 Module]]
:explains how to halt execution of a BCI2000 module, and wait for the user to attach a debugger.
*[[Programming Howto:Deploy a Release version of a BCI2000 Module|Deploy a Release version of a BCI2000 Module]]
:demonstrates how to build a self-contained version of your new module.

==Video Overview==
Note that this video is quite out of date - please install the currently released versions of TortoiseSVN, CMake, Qt, and Visual Studio instead of those recommended in the video.

<youtube alignment="center">https://youtu.be/3Jz527f2n5o</youtube>

[[Category:Howto]][[Category:Video]]

User Reference:StimulusPresentationTask

2025-01-14T21:44:21Z

Swiftj: /* Result */

==Synopsis==
The main purpose of this task is to present a sequential series of auditory and/or visual stimuli to the user of the BCI system.

The StimulusPresentationTask is suited to implement evoked response (ERP) paradigms, as well as to display tasks for selective activation experiments, such as SMR screening sessions.

The sequence and nature of the stimuli can be defined by the investigator. In addition to stimulus delivery, the task can optionally be used in conjunction with BCI2000's P300 Signal Processing module ([[User_Reference:P3TemporalFilter|P3TemporalFilter]]) to provide feedback to a selected stimulus in either a copy or a free mode.

==Functional Description==

===Stimulus Definition===

Stimuli are set up through a parameter defined by the application module. This implicitly defines the total number of stimuli as well as the details of each stimulus.

Each stimulus is defined by the following properties:

#Caption
#Icon file
#Audio file

In addition to stimuli that are part of the actual stimulation sequence, the [[#FocusOn|FocusOn]]
and [[#Result|Result]] parameters contain definitions for a stimulus that indicates what to focus on,
and a stimulus that presents the result. These stimuli are only used when the task is set to copy or free mode.

The following table contains an example definition of two stimuli:

{|border="1"
| ||stimulus1 ||stimulus2
|-
|caption ||Donkey ||  
|-
|icon ||images\donkey.bmp ||images\elephant.bmp
|-
|audio || sounds\snicker.wav ||sounds\trumpet.wav
|}

A blank entry for caption/icon/audio file is accepted, and defines that no presentation of the respective element takes place (e.g., see caption in stimulus2). The stimulus definition parameter does ''not'' contain a description on how the stimuli are presented.
For further details, see the [[#Stimuli|Stimuli]] parameter description.

====Stimulus Codes====
When defining a stimulus sequence, stimuli are referred to an integer ID called ''stimulus code''.
The stimulus code associated with a stimulus corresponds to the column in which that stimulus is defined in the [[#Stimuli|Stimuli]] matrix parameter.

In the recorded data file, stimulus presentation is indicated by the [[#StimulusCode|StimulusCode]] state.
During presentation of a stimulus, this state is set to the associated stimulus code.

===Stimulus Sequence===

Stimuli are presented in a certain sequence. This sequence can either be deterministic, i.e., defined by the investigator, or pseudo-random.

====Deterministic Sequence:====

The investigator defines the order by
entering a list of stimulus IDs to be presented. As an example:

1 5 3 4 2

defines a sequence in which stimulus 1 is presented first, followed by stimulus 5, etc.

====Random Sequence:====

The investigator defines absolute stimulus frequencies for each stimulus, with the sum <math>N</math> of those values equaling the total number of stimulus presentations in the final sequence. The resulting random sequence is obtained by applying a random permutation to an arbitrary sequence that reproduces the given frequencies, with all <math>N!</math> index permutations being equally probable (Block Randomization).

As an example:

6 2 3

defines a sequence of 11 stimulus presentations with stimulus 1 being presented 6 times, stimulus 2, 2 times, and stimulus 3, 3 times. The resulting sequence <math>S_1</math> will be a permutation of <math>S_0 = [1, 1, 1, 1, 1, 1, 2, 2, 3, 3, 3]</math>, and the probability for <math>S_1</math> to equal <math>S_0</math> will be <math>\frac{6!\times2!\times3!}{(6+2+3)!}=1/4620</math>.

Multiple sequences can be generated from the given frequencies. The investigator can define how many sequences are generated and presented.

====P3Speller Compatible====
Sequences are random, with each stimulus being presented ''NumberOfSequences'' times, in a block-randomized fashion. When in copy mode, each entry in the ''ToBeCopied'' parameter corresponds to a ''NumberOfSequences''-times repetition of all stimulus codes. In other ''InterpretMode''s, stimulus presentation is repeated indefinitely. This mode is intended as a compatibility mode for transitioning experiments from or to the [[User Reference:P3SpellerTask|P3SpellerTask]].

===Stimulus Delivery===

For any stimulus, delivery occurs simultaneously for caption, icon, and audio.
When both caption and icon are defined, the caption appears overlaying the icon.

An investigator can specify:

*[[#WindowWidth|Size and position]] of the target window.

*[[#StimulusWidth|Width and height]] of caption and icon in percent of screen width/height, or that the icon should appear in its original pixel size.

*Whether captions, icons, or audio files will be presented (i.e., a [[#IconSwitch|global switch]]). There are no individual switches for each stimulus. However, individual captions/icons/wave files are not presented if they are not defined (i.e., their respective entries are blank).

*The [[#AudioVolume|volume for audio playback]] as a percentage of maximum volume.

*[[#BackgroundColor|Window background color]] in RGB. (For convenience, RGB values may be entered in hexadecimal notation, e.g. <tt>0xff0000</tt> for red.)

*[[#CaptionColor|Caption color]] in RGB.

*The [[#StimulusDuration|duration]] of stimulus presentation. (Playback of audio extending above the specified duration will be muted.)

*The duration of an [[#ISIMinDuration|inter-stimulus interval]] following stimulus presentation. (During the inter-stimulus interval, the screen is blank and audio is turned off.)

*Variance in inter-stimulus intervals, with probability distributed uniformly over the interval between minimum and maximum inter-stimulus interval.

*For documentation purposes, a user can enter a [[#UserComment|comment]] to the specific run in a string parameter.

==Processing of Classification Results==

The task can be configured to interpret results communicated to it by the [[User Reference:P3TemporalFilter|P3 Signal Processing]] module. These results represent a judgment of which of the stimuli was most likely selected. Handling of these results is identical to the [[User Reference:P3SpellerTask|P3 Spelling Task]].

When it transmits a classification result, Signal Processing sets the state ''StimulusCodeRes'' to the stimulus code that was originally transmitted to it by the user application. For example, when Signal Processing sets ''StimulusCodeRes'' to 3, it transmits classification results for stimulus 3. In addition, it sets ''StimulusTypeRes'' to reflect the type of stimulus
(0=non-target, 1=target) when the system is in copy mode. Signal Processing transmits the classification result as one number (i.e., the first control signal).

===Free Mode===

The task can be configured to operate in free mode. In this case, the sequence of stimulus deliveries is followed by a time period, in which the Signal Processing classification result is presented. The final classification result is the stimulus with the highest classification result.

In order to present this result, the system uses the stimulus defined in the <tt>result</tt> column of the stimuli parameter. This presentation is followed by delivery of the determined stimulus. In other words, after a sequence of stimulus deliveries, the system might play a .wav file that says: "the result is," followed by a .wav file that says "yes." (assuming "yes" represents
the stimulus that produced the highest classification result).

Finally, the task sends this result to the operator module as an ASCII text message so that it appears in a log window.

Free mode does not terminate until the investigator suspends operation.

===Copy Mode===

Copy mode is similar to free mode. In copy mode, the investigator can define a list of stimuli to be copied (e.g., "3 5 4"). In this example, the user has to attend to stimulus 3 for the first sequence, 5 for the second sequence, etc.

In addition to presenting the result, the delivery of stimuli is preceded by a presentation that describes the stimulus to which the user must attend. This presentation uses the stimulus that is defined in the [[#FocusOn|FocusOn]] parameter. This presentation is followed by delivery of the desired target stimulus. As an example, the system might say "Please focus on" ... "yes," before it starts with the sequence of stimulus deliveries.

Copy mode terminates (i.e., suspends the task) when the user has finished copying all stimuli specified by the investigator.

==Parameters==
{{ApplicationWindowParams}}
{{StimulusTaskParams}}

====SequenceType====
Enumerated value selecting between
*0 deterministic sequence mode: the sequence is explicitly defined in the ''Sequence'' parameter;
*1 random sequence mode: the sequence is random, with pre-defined stimulus frequencies.
*2 P3Speller compatible mode: the sequence is random, with each stimulus being presented exactly ''NumberOfSequences'' times, in a block-randomized fashion. In copy spelling mode, one such sequence is presented for each entry in the ''ToBeCopied'' parameter. In other ''InterpretMode''s, such sequences are repeated indefinitely; the current run must be stopped manually.

====Sequence====
In deterministic mode, a list of stimulus codes defining the sequence of presentations.
In random mode, a list of integer stimulus frequencies.
In P3Speller compatible mode, this parameter is ignored.

====NumberOfSequences====
The number of sequence repetitions in a run (a run corresponds to a single data file).

====ToBeCopied====
A list of stimulus codes defining a sequence of attended stimuli.
At the beginning of each presentation sequence, another entry from this list is announced as the attended stimulus (see [[#FocusOn|FocusOn]]).

This parameter is only used in [[#InterpretMode|copy mode]].

====UserComment====
An arbitrary string intended for documentation purposes.

====Stimuli====
A matrix defining the properties of stimuli to be presented.
Columns of the ''Stimuli'' matrix correspond to individual stimuli and their stimulus codes.
For each stimulus, the following properties are defined by its row entries:
*Caption: a text string, with its size and color depending on the ''CaptionHeight'' and ''CaptionColor'' parameters;
*Icon: a graphic file (a number of formats are supported through libav), with its size depending on the ''StimulusWidth'' parameter;
*AV: an AV file (video with or without audio, or an audio file), with playback starting at the onset of the visual stimuli.
For backward compatibility reasons, each of these three rows must be present.
A blank entry for caption/icon/AV is accepted, and defines that no presentation of the respective element takes place.
Note that for Windows .bmp files, the top left pixel is taken to be the transparent background color, so results may not be as expected. Try a different format, or add a 1-pixel frame in a different color to the image.

Additionally, a number of global stimulus parameters may be overridden with specific values for individual stimuli.
To do this, for each parameter to be individualized, add an additional row to the Stimuli matrix. The row label indicates the parameter to be changed, and has to be one of:
*StimulusDuration,
*EarlyOffsetExpression,
*ISIMinDuration, ISIMaxDuration,
*StimulusWidth, CaptionHeight, CaptionColor, AudioVolume.

Whenever one of these rows is present, the corresponding global parameter will be ignored.

====FocusOn====
In copy mode (see [[#InterpretMode|InterpretMode]]), the attended stimulus is presented prior to the stimulus sequence ([[#PreSequenceTime|PreSequenceTime]]),
preceded with a special announcement stimulus.
This stimulus' properties are defined by the ''FocusOn'' parameter, which is a matrix in the same format as the ''Stimuli'' parameter.
Usually, this matrix has a single column; when multiple columns are present, all stimuli are presented concurrently.
To control the duration of the "FocusOn" announcement and the attended stimulus independently of the global [[#StimulusDuration|StimulusDuration]] parameter, a ''StimulusDuration'' row may be added in the ''FocusOn'' matrix.

====Result====
In copy and free modes (see [[#InterpretMode|InterpretMode]]), the classification result is presented following the sequence ([[#PostSequenceTime|PostSequenceTime]]). Presentation of the predicted stimulus is preceded with an announcement stimulus.
This stimulus' properties are defined by the ''Result'' parameter, which is a matrix in the same format as the ''Stimuli'' and ''FocusOn'' parameters.
As for the "FocusOn" parameter, to control the duration of the "Result" announcement and the predicted stimulus independently of the global [[#StimulusDuration|StimulusDuration]] parameter, a ''StimulusDuration'' row may be added in the ''Result'' matrix.

====StimulusWidth====
For icon stimuli, stimulus width in percent of screen width.
Stimulus height is deduced from the stimulus' aspect ratio, which is always conserved.
If this parameter is zero, all stimuli will be displayed unscaled, i.e. at their original pixel size.
{{StimulusParamOverride}}

====CaptionHeight====
For text stimuli, the height of the stimulus' caption in percent of screen height.
{{StimulusParamOverride}}

====CaptionColor====
For text stimuli, the color of the stimulus' caption, given as an RGB value.
{{StimulusParamOverride}}

====BackgroundColor====
The background color of the stimulus rectangle, given as an RGB value. The height of the rectangle is defined by the CaptionHeight parameter, and its width depends on the caption's text width.

====CaptionSwitch====
A boolean parameter to globally switch presentation of stimulus captions on or off.
To present captions for individual stimuli only, remove captions for other stimuli from the [[#Stimuli|Stimuli]] matrix.

====IconSwitch====
A boolean parameter to globally switch presentation of icon stimuli on or off.
To present icons for individual stimuli only, leave icon entries for other stimuli blank in the [[#Stimuli|Stimuli]] matrix.

====AudioSwitch====
A boolean parameter to globally switch presentation of audio stimuli on or off.
To present audio for individual stimuli only, remove audio entries for other stimuli from the [[#Stimuli|Stimuli]] matrix.
====AVSwitch====
A boolean parameter to globally switch presentation of AV stimuli on or off.
To present audio for individual stimuli only, remove AV entries for other stimuli from the [[#Stimuli|Stimuli]] matrix.

====AudioVolume====
The volume for audio playback, in percent of maximum volume.
{{StimulusParamOverride}}

====AVPlayToEnd====
If yes, AV stimuli will be played as long as they last; if no, AV stimuli will be aborted after the specified stimulus duration has expired.

==States==
{{ApplicationBaseStates}}

{{StimulusTaskStates}}

===SelectedStimulus===
When classification is performed, this state contains the stimulus code of the stimulus classified as the "selected" one.

==Timeline==
{{StimulusTaskTimeline}}

==See also==
[[User Reference:P3TemporalFilter]], [[User Reference:P3SpellerTask]], [[Programming Reference:StimulusTask Class]]

[[Category:Filters]][[Category:User Application]][[Category:Specification]]

User Reference:StimulusPresentationTask

2025-01-14T21:44:02Z

Swiftj: /* FocusOn */

==Synopsis==
The main purpose of this task is to present a sequential series of auditory and/or visual stimuli to the user of the BCI system.

The StimulusPresentationTask is suited to implement evoked response (ERP) paradigms, as well as to display tasks for selective activation experiments, such as SMR screening sessions.

The sequence and nature of the stimuli can be defined by the investigator. In addition to stimulus delivery, the task can optionally be used in conjunction with BCI2000's P300 Signal Processing module ([[User_Reference:P3TemporalFilter|P3TemporalFilter]]) to provide feedback to a selected stimulus in either a copy or a free mode.

==Functional Description==

===Stimulus Definition===

Stimuli are set up through a parameter defined by the application module. This implicitly defines the total number of stimuli as well as the details of each stimulus.

Each stimulus is defined by the following properties:

#Caption
#Icon file
#Audio file

In addition to stimuli that are part of the actual stimulation sequence, the [[#FocusOn|FocusOn]]
and [[#Result|Result]] parameters contain definitions for a stimulus that indicates what to focus on,
and a stimulus that presents the result. These stimuli are only used when the task is set to copy or free mode.

The following table contains an example definition of two stimuli:

{|border="1"
| ||stimulus1 ||stimulus2
|-
|caption ||Donkey ||  
|-
|icon ||images\donkey.bmp ||images\elephant.bmp
|-
|audio || sounds\snicker.wav ||sounds\trumpet.wav
|}

A blank entry for caption/icon/audio file is accepted, and defines that no presentation of the respective element takes place (e.g., see caption in stimulus2). The stimulus definition parameter does ''not'' contain a description on how the stimuli are presented.
For further details, see the [[#Stimuli|Stimuli]] parameter description.

====Stimulus Codes====
When defining a stimulus sequence, stimuli are referred to an integer ID called ''stimulus code''.
The stimulus code associated with a stimulus corresponds to the column in which that stimulus is defined in the [[#Stimuli|Stimuli]] matrix parameter.

In the recorded data file, stimulus presentation is indicated by the [[#StimulusCode|StimulusCode]] state.
During presentation of a stimulus, this state is set to the associated stimulus code.

===Stimulus Sequence===

Stimuli are presented in a certain sequence. This sequence can either be deterministic, i.e., defined by the investigator, or pseudo-random.

====Deterministic Sequence:====

The investigator defines the order by
entering a list of stimulus IDs to be presented. As an example:

1 5 3 4 2

defines a sequence in which stimulus 1 is presented first, followed by stimulus 5, etc.

====Random Sequence:====

The investigator defines absolute stimulus frequencies for each stimulus, with the sum <math>N</math> of those values equaling the total number of stimulus presentations in the final sequence. The resulting random sequence is obtained by applying a random permutation to an arbitrary sequence that reproduces the given frequencies, with all <math>N!</math> index permutations being equally probable (Block Randomization).

As an example:

6 2 3

defines a sequence of 11 stimulus presentations with stimulus 1 being presented 6 times, stimulus 2, 2 times, and stimulus 3, 3 times. The resulting sequence <math>S_1</math> will be a permutation of <math>S_0 = [1, 1, 1, 1, 1, 1, 2, 2, 3, 3, 3]</math>, and the probability for <math>S_1</math> to equal <math>S_0</math> will be <math>\frac{6!\times2!\times3!}{(6+2+3)!}=1/4620</math>.

Multiple sequences can be generated from the given frequencies. The investigator can define how many sequences are generated and presented.

====P3Speller Compatible====
Sequences are random, with each stimulus being presented ''NumberOfSequences'' times, in a block-randomized fashion. When in copy mode, each entry in the ''ToBeCopied'' parameter corresponds to a ''NumberOfSequences''-times repetition of all stimulus codes. In other ''InterpretMode''s, stimulus presentation is repeated indefinitely. This mode is intended as a compatibility mode for transitioning experiments from or to the [[User Reference:P3SpellerTask|P3SpellerTask]].

===Stimulus Delivery===

For any stimulus, delivery occurs simultaneously for caption, icon, and audio.
When both caption and icon are defined, the caption appears overlaying the icon.

An investigator can specify:

*[[#WindowWidth|Size and position]] of the target window.

*[[#StimulusWidth|Width and height]] of caption and icon in percent of screen width/height, or that the icon should appear in its original pixel size.

*Whether captions, icons, or audio files will be presented (i.e., a [[#IconSwitch|global switch]]). There are no individual switches for each stimulus. However, individual captions/icons/wave files are not presented if they are not defined (i.e., their respective entries are blank).

*The [[#AudioVolume|volume for audio playback]] as a percentage of maximum volume.

*[[#BackgroundColor|Window background color]] in RGB. (For convenience, RGB values may be entered in hexadecimal notation, e.g. <tt>0xff0000</tt> for red.)

*[[#CaptionColor|Caption color]] in RGB.

*The [[#StimulusDuration|duration]] of stimulus presentation. (Playback of audio extending above the specified duration will be muted.)

*The duration of an [[#ISIMinDuration|inter-stimulus interval]] following stimulus presentation. (During the inter-stimulus interval, the screen is blank and audio is turned off.)

*Variance in inter-stimulus intervals, with probability distributed uniformly over the interval between minimum and maximum inter-stimulus interval.

*For documentation purposes, a user can enter a [[#UserComment|comment]] to the specific run in a string parameter.

==Processing of Classification Results==

The task can be configured to interpret results communicated to it by the [[User Reference:P3TemporalFilter|P3 Signal Processing]] module. These results represent a judgment of which of the stimuli was most likely selected. Handling of these results is identical to the [[User Reference:P3SpellerTask|P3 Spelling Task]].

When it transmits a classification result, Signal Processing sets the state ''StimulusCodeRes'' to the stimulus code that was originally transmitted to it by the user application. For example, when Signal Processing sets ''StimulusCodeRes'' to 3, it transmits classification results for stimulus 3. In addition, it sets ''StimulusTypeRes'' to reflect the type of stimulus
(0=non-target, 1=target) when the system is in copy mode. Signal Processing transmits the classification result as one number (i.e., the first control signal).

===Free Mode===

The task can be configured to operate in free mode. In this case, the sequence of stimulus deliveries is followed by a time period, in which the Signal Processing classification result is presented. The final classification result is the stimulus with the highest classification result.

In order to present this result, the system uses the stimulus defined in the <tt>result</tt> column of the stimuli parameter. This presentation is followed by delivery of the determined stimulus. In other words, after a sequence of stimulus deliveries, the system might play a .wav file that says: "the result is," followed by a .wav file that says "yes." (assuming "yes" represents
the stimulus that produced the highest classification result).

Finally, the task sends this result to the operator module as an ASCII text message so that it appears in a log window.

Free mode does not terminate until the investigator suspends operation.

===Copy Mode===

Copy mode is similar to free mode. In copy mode, the investigator can define a list of stimuli to be copied (e.g., "3 5 4"). In this example, the user has to attend to stimulus 3 for the first sequence, 5 for the second sequence, etc.

In addition to presenting the result, the delivery of stimuli is preceded by a presentation that describes the stimulus to which the user must attend. This presentation uses the stimulus that is defined in the [[#FocusOn|FocusOn]] parameter. This presentation is followed by delivery of the desired target stimulus. As an example, the system might say "Please focus on" ... "yes," before it starts with the sequence of stimulus deliveries.

Copy mode terminates (i.e., suspends the task) when the user has finished copying all stimuli specified by the investigator.

==Parameters==
{{ApplicationWindowParams}}
{{StimulusTaskParams}}

====SequenceType====
Enumerated value selecting between
*0 deterministic sequence mode: the sequence is explicitly defined in the ''Sequence'' parameter;
*1 random sequence mode: the sequence is random, with pre-defined stimulus frequencies.
*2 P3Speller compatible mode: the sequence is random, with each stimulus being presented exactly ''NumberOfSequences'' times, in a block-randomized fashion. In copy spelling mode, one such sequence is presented for each entry in the ''ToBeCopied'' parameter. In other ''InterpretMode''s, such sequences are repeated indefinitely; the current run must be stopped manually.

====Sequence====
In deterministic mode, a list of stimulus codes defining the sequence of presentations.
In random mode, a list of integer stimulus frequencies.
In P3Speller compatible mode, this parameter is ignored.

====NumberOfSequences====
The number of sequence repetitions in a run (a run corresponds to a single data file).

====ToBeCopied====
A list of stimulus codes defining a sequence of attended stimuli.
At the beginning of each presentation sequence, another entry from this list is announced as the attended stimulus (see [[#FocusOn|FocusOn]]).

This parameter is only used in [[#InterpretMode|copy mode]].

====UserComment====
An arbitrary string intended for documentation purposes.

====Stimuli====
A matrix defining the properties of stimuli to be presented.
Columns of the ''Stimuli'' matrix correspond to individual stimuli and their stimulus codes.
For each stimulus, the following properties are defined by its row entries:
*Caption: a text string, with its size and color depending on the ''CaptionHeight'' and ''CaptionColor'' parameters;
*Icon: a graphic file (a number of formats are supported through libav), with its size depending on the ''StimulusWidth'' parameter;
*AV: an AV file (video with or without audio, or an audio file), with playback starting at the onset of the visual stimuli.
For backward compatibility reasons, each of these three rows must be present.
A blank entry for caption/icon/AV is accepted, and defines that no presentation of the respective element takes place.
Note that for Windows .bmp files, the top left pixel is taken to be the transparent background color, so results may not be as expected. Try a different format, or add a 1-pixel frame in a different color to the image.

Additionally, a number of global stimulus parameters may be overridden with specific values for individual stimuli.
To do this, for each parameter to be individualized, add an additional row to the Stimuli matrix. The row label indicates the parameter to be changed, and has to be one of:
*StimulusDuration,
*EarlyOffsetExpression,
*ISIMinDuration, ISIMaxDuration,
*StimulusWidth, CaptionHeight, CaptionColor, AudioVolume.

Whenever one of these rows is present, the corresponding global parameter will be ignored.

====FocusOn====
In copy mode (see [[#InterpretMode|InterpretMode]]), the attended stimulus is presented prior to the stimulus sequence ([[#PreSequenceTime|PreSequenceTime]]),
preceded with a special announcement stimulus.
This stimulus' properties are defined by the ''FocusOn'' parameter, which is a matrix in the same format as the ''Stimuli'' parameter.
Usually, this matrix has a single column; when multiple columns are present, all stimuli are presented concurrently.
To control the duration of the "FocusOn" announcement and the attended stimulus independently of the global [[#StimulusDuration|StimulusDuration]] parameter, a ''StimulusDuration'' row may be added in the ''FocusOn'' matrix.

====Result====
In copy and free modes (see [[#InterpretMode|InterpretMode]]), the classification result is presented following the sequence ([[#PostSequenceTime|PostSequenceTime]]). Presentation of the predicted stimulus is preceded with an announcement stimulus.
This stimulus' properties are defined by the ''Result'' parameter, which is a matrix in the same format as the ''Stimuli'' and ''FocusOn'' parameters.
As for the "FocusOn" parameter, to control the duration of the "Result" announcement and the predicted stimulus independently of the global [[#StimulusDuration|StimulusDuration]] parameter, a ''StimulusDuration'' column may be present in the ''Result'' matrix.

====StimulusWidth====
For icon stimuli, stimulus width in percent of screen width.
Stimulus height is deduced from the stimulus' aspect ratio, which is always conserved.
If this parameter is zero, all stimuli will be displayed unscaled, i.e. at their original pixel size.
{{StimulusParamOverride}}

====CaptionHeight====
For text stimuli, the height of the stimulus' caption in percent of screen height.
{{StimulusParamOverride}}

====CaptionColor====
For text stimuli, the color of the stimulus' caption, given as an RGB value.
{{StimulusParamOverride}}

====BackgroundColor====
The background color of the stimulus rectangle, given as an RGB value. The height of the rectangle is defined by the CaptionHeight parameter, and its width depends on the caption's text width.

====CaptionSwitch====
A boolean parameter to globally switch presentation of stimulus captions on or off.
To present captions for individual stimuli only, remove captions for other stimuli from the [[#Stimuli|Stimuli]] matrix.

====IconSwitch====
A boolean parameter to globally switch presentation of icon stimuli on or off.
To present icons for individual stimuli only, leave icon entries for other stimuli blank in the [[#Stimuli|Stimuli]] matrix.

====AudioSwitch====
A boolean parameter to globally switch presentation of audio stimuli on or off.
To present audio for individual stimuli only, remove audio entries for other stimuli from the [[#Stimuli|Stimuli]] matrix.
====AVSwitch====
A boolean parameter to globally switch presentation of AV stimuli on or off.
To present audio for individual stimuli only, remove AV entries for other stimuli from the [[#Stimuli|Stimuli]] matrix.

====AudioVolume====
The volume for audio playback, in percent of maximum volume.
{{StimulusParamOverride}}

====AVPlayToEnd====
If yes, AV stimuli will be played as long as they last; if no, AV stimuli will be aborted after the specified stimulus duration has expired.

==States==
{{ApplicationBaseStates}}

{{StimulusTaskStates}}

===SelectedStimulus===
When classification is performed, this state contains the stimulus code of the stimulus classified as the "selected" one.

==Timeline==
{{StimulusTaskTimeline}}

==See also==
[[User Reference:P3TemporalFilter]], [[User Reference:P3SpellerTask]], [[Programming Reference:StimulusTask Class]]

[[Category:Filters]][[Category:User Application]][[Category:Specification]]

Contributions:NatusADC

2024-11-25T23:51:30Z

Swiftj: /* On the Natus Computer */

[[Image:NatusClinicalSystem.webp|thumb|400px|Example set-up for a Natus NeuroWorks clinical system]]

== Function ==
The NatusADC filter acquires raw data in real-time from Natus Headboxes over UDP connection for signal processing and visualizations. The overview of the NatusADC working is shown in the image below.
[[File:Prog_Ref_NatusADC_NatusWorking.png|center|800px|Overview of NatusADC working]]

NatusDataServer processes and sends signal from the device to the client application. A project named XLDataExportClient reads signals from the device and calls the NatusDataServer's functions to send the signal to the client. NatusClient is the client application within the BCI2000 that receives the signals and does the initial processing. NatusPackageInterface contains the implementation of data transfer protocol between server/device and client and is used by NatusClient and NatusDataServer to communicate with each other over TCP and UDP. NatusDataServer and NatusPackageInterface are independent of BCI2000, whereas NatusClient relies on BCI2000.

The below image explains the context in which packet, blocks, samples and channels are used in this project. A packet may have one or block, a block may have one or more samples and a sample contains values for all the channels.
[[File:NatusPacketImage.png|center|600px|Packet, block and samples relationship]]

''For more information about the Natus connection and specific commands, refer to the [[Programming Reference:NatusADC|Natus programming page]]

===Version History===

===Source Code Revisions===
*Initial development: 5900
*Tested under: 7381
*Known to compile under:7381
*Broken since: --
*Natus software version: 9.2.1 Build 6524
*Natus Data Export Version: 9.4

== Prerequisites ==
* The NatusADC source module requires a proprietary SDK protected by an NDA with Natus. Please contact Natus for this NDA and for access to the XLDataExportClient SDK before attempting to use the NatusADC source module.
* It is also helpful to have an ethernet port available for the Natus computer. If your system does not have an ethernet port, consider using a USB ethernet dongle.

=== Hardware ===
In theory, the module should work fine with all of the following Natus Headboxes.
# EEG32
# EEG128, EEG128FS
# Mobee32, Mobee32-02
# Mobee-24
# Connex/ Brain Monitor
# Trex
# EMU40
# EEG32u
# Quantum
# NeuroLink IP
# Bio-logic NetLink
# Bio-logic Traveler

==== Drivers ====

== Connecting Natus to BCI2000 ==
The figure below should serve as a supplement to the instructions for connecting the Natus computer to the BCI2000 computer
[[File:NW_SDK_for_BCI2000.png|center|1000px|Neuroworks SDK for BCI2000]]

=== On the Natus Computer ===
# Connect the BCI2000 computer to the Natus computer via ethernet (this may require a usb-to-ethernet adapter)
# Change the IP address of this port on the Natus computer to something on its own subnet, like 192.168.10.10. ***This must be a static IP address.*** You can follow a tutorial like [https://nordvpn.com/blog/how-to-change-your-ip-address/ this one] to change the IP address. The easiest way to confirm that you are changing the IP address of the correct port is to unplug the ethernet cable. The unplugged option will disappear.
# When starting a new study, set the sampling rate of the acquisition system by opening "Wave" and going to edit -> settings -> acquisition while a study is NOT running
#* Be sure that the Natus computer is set to acquire data over Ethernet and not USB if you intend to acquire data over 4kHz [[File:Natus1_StudySettings.jpg|center|600px|Set Natus Sampling Rate]]
# Start an EEG study in Neuroworks using the New EEG button. [[File:Natus2_StartStudy.jpg|center|1000px|Start a new Natus study]] You will need to enter the study information. [[File:Natus3_StudyInformation.jpg|center|600px|Enter the study information]] Note that you do not need to start the recording for the signal to stream to BCI2000. [[File:Natus4_StudyRunning.jpg|center|1000px|Study is running]]

=== On the BCI2000 Computer ===
# Compile the NatusSignalSource source module after you have gotten access to the Natus data export service on the BCI2000 svn
# Change the IP address of the BCI2000 computer ethernet port to something on the same subnet, like 192.168.10.9, following the same steps as above.
# Open the command line on the BCI2000 computer and type "ping 192.168.10.10" to ensure you have a connection.
#* Note that if this does not work you may need to turn off firewalls on one or both machines
# Locate the included registry editing tool found in bci2000/src/private/SignalSource/NatusSignalSource/
# Edit the _SetSdkAcquisitionStationIp.reg registry editing tool (right-click, edit) to add the IP of the Natus computer to the BCI2000 computer's registry (i.e., 192.168.10.10)
# Run RegXLDataExportService.bat found in bci2000/src/private/SignalSource/NatusSignalSource/DataExport_9.4/XLDataExportService to register the DLL of the data export service. (This may not be necessary with the newest version?)
# Start the data export service executable XLDataExportSrv.exe found in bci2000/src/private/SignalSource/NatusSignalSource/DataExport_9.4/XLDataExportService
#* Note that this can be started before an EEG study has been started, or after an EEG study is already running
#* A small horizontal window should appear, indicating study data is streaming
# Create a BCI2000 batch file to start up the NatusSignalSource source module (An example batch file should be in the same NatusSignalSource folder after BCI2000 has been compiled)
# Launch BCI2000 using this batch file
# Open the config window and navigate to the source tab. Source parameters will vary according to your needs, but some recommended settings can be found below
#* SampleBlockSize: 100 (at a sampling rate of 2048, this yields a sample block size of 48.83ms. Note that the ratio of SampleBlockSize/ServerBlockSize needs to be a whole number for best performance. SampleBlockSize less than 48.83ms is not recommended.)
#* SamplingRate: auto (inherited from the Natus system)
#* ServerBlockSize: 1 (server buffer size. Larger ServerBlockSize can lead to performance issues.)
#* DecimationFactor: 1 (you can decimate the incoming sampled data by the DecimationFactor. The BCI2000 sampling rate will reflect the decimated rate.)
#* ServerIP: Set the IP address to localhost or 127.0.0.1
# Press “Set Config.” Data should begin streaming. Open the System Log from the BCI2000 Operator window to confirm that the sampling rate and channel count were inherited correctly from the Natus stream

== Legacy Instructions for Connecting Natus to BCI2000 ==
=== On the Natus Computer ===
# If you have previously registered the XLDataExportClient.dll for an older version of the data export tool, you must first deregister this dll. Launch a command window as an administrator and type regsvr /u XLDataExportClient.dll
# Connect to the network via ethernet cable. Alternately, it is preferable to connect directly to the BCI2000 computer via ethernet.
# Copy the Export Service folder found in src\private\SignalSource\NatusSignalSource\DataExport_9.4\XLDataExportService to the hard drive of the computer running Natus Neuroworks or to a USB drive
# Note the IP address of the Natus computer (run “ipconfig” in the Command Prompt on the Natus computer). If the computers are directly connected with an ethernet cable, the IP address should be under "ethernet adapter ethernet" [[File:Natus7_IPaddress.jpg|center|600px|Run ipconfig on the Natus computer and note the IP address]]
# When starting a new study, set the sampling rate of the acquisition system by opening "Wave" and going to edit -> settings -> acquisition while a study is NOT running
#* Be sure that the Natus computer is set to acquire data over Ethernet and not USB if you intend to acquire data over 4kHz [[File:Natus1_StudySettings.jpg|center|600px|Set Natus Sampling Rate]]
# Start an EEG study in Neuroworks using the New EEG button. [[File:Natus2_StartStudy.jpg|center|1000px|Start a new Natus study]] You will need to enter the study information. [[File:Natus3_StudyInformation.jpg|center|600px|Enter the study information]] Note that you do not need to start the recording for the signal to stream to BCI2000. [[File:Natus4_StudyRunning.jpg|center|1000px|Study is running]]
# Run the executable XLDataExportSrv.exe found in the XLDataExportService folder that was copied to the Natus computer [[File:Natus5_DataExportServiceFolder.jpg|center|600px|Run the executable XLDataExportSrv.exe from the XLDataExportService folder]]
#* Note that this can be started before an EEG study has been started, or after an EEG study is already running
#* A small horizontal window should appear, indicating study data is streaming [[File:Natus6_DataExportServiceRunning.jpg|center|1000px|Natus Data Export Service Running]]

=== On the BCI2000 Computer ===
# Connect to the same network that the Natus computer is connected via ethernet cable. Alternately, it is preferable to connect directly to the Natus computer via ethernet.
# Run a BCI2000 batch file that loads the NatusSignalSource
# Open the config window and navigate to the source tab. Source parameters will vary according to your needs, but some recommended settings can be found below
#* SampleBlockSize: 100 (at a sampling rate of 2048, this yields a sample block size of 48.83ms. Note that the ratio of SampleBlockSize/ServerBlockSize needs to be a whole number for best performance. SampleBlockSize less than 48.83ms is not recommended.)
#* SamplingRate: auto (inherited from the Natus system)
#* ServerBlockSize: 1 (server buffer size. Larger ServerBlockSize can lead to performance issues.)
#* DecimationFactor: 1 (you can decimate the incoming sampled data by the DecimationFactor. The BCI2000 sampling rate will reflect the decimated rate.)
#* ServerIP: Set the IP address to that of the Natus computer [[File:Natus8_BCI2000Parameters.jpg|center|600px|Natus BCI2000 parameters]]
# Press “Set Config.” Data should begin streaming. Open the System Log from the BCI2000 Operator window to confirm that the sampling rate and channel count were inherited correctly from the Natus stream

== Parameters ==
Parameters common to all source modules are described under [[User Reference:DataIOFilter]]. In addition, the following parameters are supported:

=== SamplingRate ===
The rate at which the device samples the data. The default value is the device's default sampling rate.

=== SampleBlockSize ===
The number of samples per block the output signal, created by the client application(NatusADC), should have. The default value is 20. Note that the ratio of SampleBlockSize/ServerBlockSize needs to be a whole number for best performance. SampleBlockSize less than 48.83ms is not recommended.

=== ServerBlockSize ===
The number of samples sent by the server/device in a single UDP Packet. The default value is 1.

=== DecimationFactor ===
The decimation factor. The factor by which to decimate/downsize the signal. The default value is 1. ''The SamplingRate is updated by dividing it by the DecimationFactor.''
'''Note:''' The SamplingRate should be an integral multiple of DecimationFactor.

=== ServerIP ===
The IPv4 address of the server/device.

=== Port ===
The port number of the server/device which on which TCP runs. UDP port number is assumed to be 1 + TCP port number.

=== SourceCh ===
The number of channels to be acquired from the device. If this is set to auto, all the available channels from the device will be acquired.

=== SourceChGain ===
SourceChGain should be left to auto. The default value is 0 for every channel.

=== SourceChOffset ===
SourceChOffset should be left to auto. The default value is 1 microVolt for every channel.

=== SourceChList ===
The list of channel numbers to be acquired from the device. The order of the numbers doesn't matter, i.e., '1 2 3 4' is same as '3 2 4 1'. Entering duplicate channels, eg. in '1 2 3 2' will result in an error. Entering an invalid channel number, i.e., a number greater than the maximum number of the channels will result in an error. If set to auto, all the device channels will be streamed.

=== ChannelNames ===
The user-preferred channel names. If set to auto, the channel names will be retrieved from the device. If the device doesn't have any specific channel names, the channel names will be set to 0 to SourceCh - 1. If set manually, names should be given for each channel in SourceChList

== States ==

=== Interpolated ===
Interpolated is represented by 1 bit. The device sends data in packets over UDP connection which is not a reliable connection and hence may result in loss of some packets. The lost packets between two packets received from the device are linearly interpolated from the aforementioned two packets. The Interpolated state value is 1 if the packet is interpolated or 0 if the packet is received from the device.

== Events ==

=== NatusPackageCount ===
This event variable will be increased by 1 whenever a UDP packet is received by the signal source. Thus, longer periods of missing packets may be detected by observing the time course of the <tt>NatusPackageCount</tt> event.

== Additional Info ==
The module also contains a function called GetDecimationFactor to query the current Decimation Factor from the server/device. 
More details from a programmer's perspective can be found here [[Programming_Reference:NatusADC]]

== Troubleshooting ==
If there is a problem streaming the data, try force quitting the Natus export service by opening the task manager on the Natus computer, then right clicking on the XLDataExportSrv and choosing 'end task.' Then start the data export service again.

== See also ==
[[User Reference:DataIOFilter]], [[Programming Reference:GenericADC Class]]
[[Category:Filters]][[Category:Data Acquisition]]

Main Page

2024-10-23T19:36:07Z

Swiftj:

__NOTOC__ __NOEDITSECTION__
<table cellspacing="10" class="noprint" style="float:right; margin-top:-2em;margin-bottom:-2.4em; text-align:right">
<tr>
<td style="border-radius: 4px; background-color:#efefef;padding: 0.4em 1em 0.4em 1em;word-spacing:1em;">
<htmltag tagname="form" name="sitesearch" action="https://www.google.com/search">
<htmltag tagname="input" name="q" type="text" size="40" />
<htmltag tagname="input" type="submit" value="Google site search of bci2000.org" />
<htmltag tagname="input" type="hidden" name="sitesearch" value="bci2000.org" />
<htmltag tagname="input" type="hidden" name="ie" value="utf-8" />
<htmltag tagname="input" type="hidden" name="oe" value="utf-8" />
</htmltag>
</td>
</tr>
</table>

<table cellspacing="10" style="width:100%;margin-top:-10px">
<td style="margin:0; margin-top:-10px; margin-right:10px; background-color:#ededed; padding:0 1em 1em 1em; align:right; border-radius: 10px; vertical-align:top;">
=Download BCI2000=
1. [https://www.bci2000.org/useradmin/ Create a free user account!!] (Required to download BCI2000)
 
2. Download the [https://bci2000.org/downloads/bin/BCI2000Setup.exe latest release], or download the source code ([[Programming Howto:Building and Customizing BCI2000 |Windows]], [[Programming Howto:Non:Building and Customizing BCI2000 on Non-Windows Platforms |Non-windows]])
</td>
</table>

<table cellspacing="10" style="width:100%;margin-top:-10px">
<tr> <td style="margin:0; margin-right:10px; border-radius: 10px; border:0.5px solid #a2a2a2; padding:0 1em 1em 1em; align:right;vertical-align:top;">
=What is BCI2000?=
BCI2000 is an open-source, general-purpose software system for brain-computer interface (BCI) research that is free for non-commercial use.
BCI2000 includes software tools that can acquire and process data, present stimuli and feedback, and manage interaction with outside devices such as robotic arms. BCI2000 is a real-time system that can synchronize EEG and other signals with a wide variety of biosignals and input devices such as mice or eye-trackers. It has several modules to manage data importing and exporting in common file formats. BCI2000 operates on most Windows systems, and the source code can be compiled on most Windows machines.

[[File:BCI2000 New Schematic Extra Large.gif|center|800px|BCI2000 Schematic]]

Above shows the main framework of BCI2000, with examples for each section. Navigate to the [[User Reference:Filters|Filters page]] to learn more about the framework, or view links below for tutorials and more reference pages.
</td> </tr>

<table cellspacing="10" style="width:100%;margin-top:-10px">
<tr>
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#fff8dc; align:right;vertical-align:top;">
==BCI2000 for Users==

* [//{{SERVERNAME}}/useradmin Create or modify a User Account]
* [[DownloadBCI2000|Download BCI2000]]
* Take the introductory [[User Tutorial:BCI2000 Tour|BCI2000 Tour]]
* Learn more through an [[Introduction_to_Adaptive_Neurotechnologies|Introduction to Adaptive Neurotechnologies]]
* Review the terminology in the [[BCI2000 Glossary]]
</td>

<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#e3f5fc; align:right;vertical-align:top;">
==BCI2000 for Developers==
* [//{{SERVERNAME}}/useradmin Create or modify a User Account]
* Download [[BCI2000 Binaries]]
* Download, build, and customize the BCI2000 toolchain for windows using [[Programming_Howto:Building and Customizing BCI2000|Building and Customizing Howto]]
* Download, build, and customize the BCI2000 toolchain for non-windows platforms using [[ Programming_Howto:Non:Building_and_Customizing_BCI2000_on_Non-Windows_Platforms|Building and Customizing Howto for Non-Windows]]
* Access to the [[Programming Howto:Building and Customizing BCI2000|BCI2000 Source Code]]
</td>
</tr>

<tr>
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; background-color:#e3f5fc; padding:0 1em 1em 1em; align:right;vertical-align:top;">
==BCI2000 References==
===BCI2000 Overview and Tools===
* The [[User Reference:Contents|User Reference Manual]] describes all details of system configuration and usage
===Technical References===
* The [[Technical Reference:Contents|Technical Reference Manual]] contains a discussion of its basic concepts, and a detailed specification of the BCI2000 standard.
===Programming References===
* The [[Programming Reference:Contents|Programming Reference]] provides background information which you need in order to understand, modify, or create code that depends on the BCI2000 framework.
===Contributions===
* [[Contributions:Contents|User-Contributed BCI2000 Components and Patches]]
===Categories===
*[[:Category:Data Acquisition | Data Acquisition]]
*[[:Category:Signal Processing | Signal Processing]]
*[[:Category:User Application | User Application]]
*[[:Category:External Interfaces | External Interfaces]]
*[[:Category:User Interface | User Interface]]
*[[:Category:Video | Video Tutorials]]

</td>

<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; background-color:#fff8dc; padding:0 1em 1em 1em; align:right;vertical-align:top;">
==BCI2000 Tutorials==
===Setup Tutorials===
*[[Programming Howto:Install Prerequisites|Install Prerequisites]]
*[[Programming Howto:Register with BCI2000 Project|Register with the BCI2000 Project]]
*[[Programming Howto:Download the BCI2000 Sourcecode|Download the BCI2000 Sourcecode]]
*[[Programming Howto:Configure BCI2000 for Compilation|Configure BCI2000 for Compilation]]
*[[Programming Howto:Compile BCI2000|Compile BCI2000]]
===Experimental Tutorials===
*[[User Tutorial:Mu Rhythm BCI Tutorial|Mu Rhythm BCI Tutorial]]
*[[User Tutorial:P300 BCI Tutorial|P300 BCI Tutorial]]
===Programming Tutorials===
*[[Programming Tutorial:Implementing a Source Module|Implementing a Source Module]]
*[[Programming Howto:Create a custom Signal Processing Module|Implementing a Signal Processing Module]]
*[[Programming Tutorial:Implementing a Matlab-based Filter|Implementing a Matlab-based Filter]]
*[[Programming Tutorial:Implementing an Input Logger|Implementing an Input Logger]]
===Data Analysis Tutorials===
*[[User Tutorial:Data Analysis|Data Analysis with BCI2000]]
* Converting and Analyzing BCI2000 Data with [[User Reference:Matlab MEX Files|Matlab MEX Files]]
* Analyze BCI2000 Data in Python with [https://github.com/neurotechcenter/BCI2kReader BCI2k Reader]
===All Tutorials: See a complete list of [[User Tutorial|BCI2000 tutorials]] here===
*
</td>
</tr>

<tr>
<td style="margin:0; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#fff8dc; align:right;vertical-align:top;">
==Supported Frameworks==
===BCI2000 Core Frameworks===
* [[User Reference:P3SpellerTask|P3 Speller]]
* [[User Reference:StimulusPresentationTask|Stimulus Presentation]]
* [[User Reference:CursorTask|Cursor Task]]
===[[Supported Frameworks|External Frameworks]]===
* [[User Tutorial:BCI2000Remote|BCI2000 Remote]] - includes Matlab, C++, and Python
* [[PsychoPy]]
* [[BCPy2000]]
</td>

<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#e3f5fc; align:right;vertical-align:top;">

==Additional Information==
* [[System Features|Features supported by BCI2000]]
* [https://github.com/neurotechcenter NCAN Github]
* [//{{SERVERNAME}}/phpbb BCI2000 Community Forum]
* [//{{SERVERNAME}}/tracproj/newticket Submit a Bug Report] (make sure you log in)
* [[User FAQ|BCI2000 Frequently Asked Questions]]
* [[BCI2000 Glossary]] of terms specific to BCI2000
* [[BCI2000 Licensing|Licensing Information]]
</td>
</tr>
</table>

<table cellspacing="10" style="width:100%;">
<tr>
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; border:0.5px solid #a2a2a2; padding:0 1em 1em 1em; background-color:white; align:right;vertical-align:top;">
==BCI2000 Publications==
* [https://{{SERVERNAME}}/downloads/doc/paper.pdf G. Schalk, D.J. McFarland, T. Hinterberger, N. Birbaumer, and J.R. Wolpaw: ''BCI2000: A General-Purpose Brain-Computer Interface (BCI) System'', IEEE Trans Biomed Eng, 51(6), June 2004.]
* J. Mellinger, G. Schalk: ''BCI2000: A General-Purpose Software Platform for BCI Research,'' In: G. Dornhege, J. del R. Millán, T. Hinterberger, D.J. McFarland, K.-R. Müller (eds.), ''Toward Brain-Computer Interfacing,'' MIT Press, 2007.
* [http://www.amazon.com/Practical-Guide-BrainComputer-Interfacing-BCI2000/dp/1849960917/ G. Schalk, J. Mellinger: "A Practical Guide to Brain-Computer Interfacing with BCI2000", Springer, 2010.]
* J. Mellinger, G. Schalk: "Using BCI2000 in BCI Research," In: B. Graimann, B. Allison, G. Pfurtscheller (eds.), "Brain-Computer Interfaces: Revolutionizing Human-Computer Interaction", Springer, 2010.
</td>
</tr>
</table>

Main Page

2024-10-23T19:03:44Z

Swiftj:

__NOTOC__ __NOEDITSECTION__
<table cellspacing="10" class="noprint" style="float:right; margin-top:-2em;margin-bottom:-2.4em; text-align:right">
<tr>
<td style="border-radius: 4px; background-color:#efefef;padding: 0.4em 1em 0.4em 1em;word-spacing:1em;">
<htmltag tagname="form" name="sitesearch" action="https://www.google.com/search">
<htmltag tagname="input" name="q" type="text" size="40" />
<htmltag tagname="input" type="submit" value="Google site search of bci2000.org" />
<htmltag tagname="input" type="hidden" name="sitesearch" value="bci2000.org" />
<htmltag tagname="input" type="hidden" name="ie" value="utf-8" />
<htmltag tagname="input" type="hidden" name="oe" value="utf-8" />
</htmltag>
</td>
</tr>
</table>

<table cellspacing="10" style="width:100%;margin-top:-10px">
<td style="margin:0; margin-top:-10px; margin-right:10px; background-color:#ededed; padding:0 1em 1em 1em; align:right; border-radius: 10px; vertical-align:top;">
=Download BCI2000=
1. [https://www.bci2000.org/useradmin/ Create a free user account!!] (Required to download BCI2000)
 
2. Download the [https://bci2000.org/downloads/bin/BCI2000Setup.exe latest release], or download the source code ([[Programming Howto:Building and Customizing BCI2000 |Windows]], [[Programming Howto:Non:Building and Customizing BCI2000 on Non-Windows Platforms |Non-windows]])
</td>
</table>

<table cellspacing="10" style="width:100%;margin-top:-10px">
<tr> <td style="margin:0; margin-right:10px; border-radius: 10px; border:0.5px solid #a2a2a2; padding:0 1em 1em 1em; align:right;vertical-align:top;">
=What is BCI2000?=
BCI2000 is an open-source, general-purpose software system for brain-computer interface (BCI) research that is free for non-commercial use.
BCI2000 includes software tools that can acquire and process data, present stimuli and feedback, and manage interaction with outside devices such as robotic arms. BCI2000 is a real-time system that can synchronize EEG and other signals with a wide variety of biosignals and input devices such as mice or eye-trackers. It has several modules to manage data importing and exporting in common file formats. BCI2000 operates on most Windows systems, and the source code can be compiled on most Windows machines.

[[File:BCI2000 New Schematic Extra Large.gif|center|BCI2000 Schematic]]

Above shows the main framework of BCI2000, with examples for each section. Navigate to the [[User Reference:Filters|Filters page]] to learn more about the framework, or view links below for tutorials and more reference pages.
</td> </tr>

<table cellspacing="10" style="width:100%;margin-top:-10px">
<tr>
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#fff8dc; align:right;vertical-align:top;">
==BCI2000 for Users==

* [//{{SERVERNAME}}/useradmin Create or modify a User Account]
* [[DownloadBCI2000|Download BCI2000]]
* Take the introductory [[User Tutorial:BCI2000 Tour|BCI2000 Tour]]
* Learn more through an [[Introduction_to_Adaptive_Neurotechnologies|Introduction to Adaptive Neurotechnologies]]
* Review the terminology in the [[BCI2000 Glossary]]
</td>

<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#e3f5fc; align:right;vertical-align:top;">
==BCI2000 for Developers==
* [//{{SERVERNAME}}/useradmin Create or modify a User Account]
* Download [[BCI2000 Binaries]]
* Download, build, and customize the BCI2000 toolchain for windows using [[Programming_Howto:Building and Customizing BCI2000|Building and Customizing Howto]]
* Download, build, and customize the BCI2000 toolchain for non-windows platforms using [[ Programming_Howto:Non:Building_and_Customizing_BCI2000_on_Non-Windows_Platforms|Building and Customizing Howto for Non-Windows]]
* Access to the [[Programming Howto:Building and Customizing BCI2000|BCI2000 Source Code]]
</td>
</tr>

<tr>
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; background-color:#e3f5fc; padding:0 1em 1em 1em; align:right;vertical-align:top;">
==BCI2000 References==
===BCI2000 Overview and Tools===
* The [[User Reference:Contents|User Reference Manual]] describes all details of system configuration and usage
===Technical References===
* The [[Technical Reference:Contents|Technical Reference Manual]] contains a discussion of its basic concepts, and a detailed specification of the BCI2000 standard.
===Programming References===
* The [[Programming Reference:Contents|Programming Reference]] provides background information which you need in order to understand, modify, or create code that depends on the BCI2000 framework.
===Contributions===
* [[Contributions:Contents|User-Contributed BCI2000 Components and Patches]]
===Categories===
*[[:Category:Data Acquisition | Data Acquisition]]
*[[:Category:Signal Processing | Signal Processing]]
*[[:Category:User Application | User Application]]
*[[:Category:External Interfaces | External Interfaces]]
*[[:Category:User Interface | User Interface]]
*[[:Category:Video | Video Tutorials]]

</td>

<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; background-color:#fff8dc; padding:0 1em 1em 1em; align:right;vertical-align:top;">
==BCI2000 Tutorials==
===Setup Tutorials===
*[[Programming Howto:Install Prerequisites|Install Prerequisites]]
*[[Programming Howto:Register with BCI2000 Project|Register with the BCI2000 Project]]
*[[Programming Howto:Download the BCI2000 Sourcecode|Download the BCI2000 Sourcecode]]
*[[Programming Howto:Configure BCI2000 for Compilation|Configure BCI2000 for Compilation]]
*[[Programming Howto:Compile BCI2000|Compile BCI2000]]
===Experimental Tutorials===
*[[User Tutorial:Mu Rhythm BCI Tutorial|Mu Rhythm BCI Tutorial]]
*[[User Tutorial:P300 BCI Tutorial|P300 BCI Tutorial]]
===Programming Tutorials===
*[[Programming Tutorial:Implementing a Source Module|Implementing a Source Module]]
*[[Programming Howto:Create a custom Signal Processing Module|Implementing a Signal Processing Module]]
*[[Programming Tutorial:Implementing a Matlab-based Filter|Implementing a Matlab-based Filter]]
*[[Programming Tutorial:Implementing an Input Logger|Implementing an Input Logger]]
===Data Analysis Tutorials===
*[[User Tutorial:Data Analysis|Data Analysis with BCI2000]]
* Converting and Analyzing BCI2000 Data with [[User Reference:Matlab MEX Files|Matlab MEX Files]]
* Analyze BCI2000 Data in Python with [https://github.com/neurotechcenter/BCI2kReader BCI2k Reader]
===All Tutorials: See a complete list of [[User Tutorial|BCI2000 tutorials]] here===
*
</td>
</tr>

<tr>
<td style="margin:0; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#fff8dc; align:right;vertical-align:top;">
==Supported Frameworks==
===BCI2000 Core Frameworks===
* [[User Reference:P3SpellerTask|P3 Speller]]
* [[User Reference:StimulusPresentationTask|Stimulus Presentation]]
* [[User Reference:CursorTask|Cursor Task]]
===[[Supported Frameworks|External Frameworks]]===
* [[User Tutorial:BCI2000Remote|BCI2000 Remote]] - includes Matlab, C++, and Python
* [[PsychoPy]]
* [[BCPy2000]]
</td>

<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#e3f5fc; align:right;vertical-align:top;">

==Additional Information==
* [[System Features|Features supported by BCI2000]]
* [https://github.com/neurotechcenter NCAN Github]
* [//{{SERVERNAME}}/phpbb BCI2000 Community Forum]
* [//{{SERVERNAME}}/tracproj/newticket Submit a Bug Report] (make sure you log in)
* [[User FAQ|BCI2000 Frequently Asked Questions]]
* [[BCI2000 Glossary]] of terms specific to BCI2000
* [[BCI2000 Licensing|Licensing Information]]
</td>
</tr>
</table>

<table cellspacing="10" style="width:100%;">
<tr>
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; border:0.5px solid #a2a2a2; padding:0 1em 1em 1em; background-color:white; align:right;vertical-align:top;">
==BCI2000 Publications==
* [https://{{SERVERNAME}}/downloads/doc/paper.pdf G. Schalk, D.J. McFarland, T. Hinterberger, N. Birbaumer, and J.R. Wolpaw: ''BCI2000: A General-Purpose Brain-Computer Interface (BCI) System'', IEEE Trans Biomed Eng, 51(6), June 2004.]
* J. Mellinger, G. Schalk: ''BCI2000: A General-Purpose Software Platform for BCI Research,'' In: G. Dornhege, J. del R. Millán, T. Hinterberger, D.J. McFarland, K.-R. Müller (eds.), ''Toward Brain-Computer Interfacing,'' MIT Press, 2007.
* [http://www.amazon.com/Practical-Guide-BrainComputer-Interfacing-BCI2000/dp/1849960917/ G. Schalk, J. Mellinger: "A Practical Guide to Brain-Computer Interfacing with BCI2000", Springer, 2010.]
* J. Mellinger, G. Schalk: "Using BCI2000 in BCI Research," In: B. Graimann, B. Allison, G. Pfurtscheller (eds.), "Brain-Computer Interfaces: Revolutionizing Human-Computer Interaction", Springer, 2010.
</td>
</tr>
</table>

Main Page

2024-10-23T19:03:28Z

Swiftj:

Main Page

2024-10-23T18:59:52Z

Swiftj:

__NOTOC__ __NOEDITSECTION__
<table cellspacing="10" class="noprint" style="float:right; margin-top:-2em;margin-bottom:-2.4em; text-align:right">
<tr>
<td style="border-radius: 4px; background-color:#efefef;padding: 0.4em 1em 0.4em 1em;word-spacing:1em;">
<htmltag tagname="form" name="sitesearch" action="https://www.google.com/search">
<htmltag tagname="input" name="q" type="text" size="40" />
<htmltag tagname="input" type="submit" value="Google site search of bci2000.org" />
<htmltag tagname="input" type="hidden" name="sitesearch" value="bci2000.org" />
<htmltag tagname="input" type="hidden" name="ie" value="utf-8" />
<htmltag tagname="input" type="hidden" name="oe" value="utf-8" />
</htmltag>
</td>
</tr>
</table>

<table cellspacing="10" style="width:100%;margin-top:-10px">
<td style="margin:0; margin-top:-10px; margin-right:10px; background-color:#ededed; padding:0 1em 1em 1em; align:right; border-radius: 10px; vertical-align:top;">
=Download BCI2000=
1. [https://www.bci2000.org/useradmin/ Create a free user account!!] (Required to download BCI2000)
 
2. Download the [https://bci2000.org/downloads/bin/BCI2000Setup.exe latest release], or download the source code ([[Programming Howto:Building and Customizing BCI2000 |Windows]], [[Programming Howto:Non:Building and Customizing BCI2000 on Non-Windows Platforms |Non-windows]])
</td>
</table>

<table cellspacing="10" style="width:100%;margin-top:-10px">
<tr> <td style="margin:0; margin-right:10px; border-radius: 10px; border:0.5px solid #a2a2a2; padding:0 1em 1em 1em; align:right;vertical-align:top;">
=What is BCI2000?=
BCI2000 is an open-source, general-purpose software system for brain-computer interface (BCI) research that is free for non-commercial use.
BCI2000 includes software tools that can acquire and process data, present stimuli and feedback, and manage interaction with outside devices such as robotic arms. BCI2000 is a real-time system that can synchronize EEG and other signals with a wide variety of biosignals and input devices such as mice or eye-trackers. It has several modules to manage data importing and exporting in common file formats. BCI2000 operates on most Windows systems, and the source code can be compiled on most Windows machines.

[[File:BCI2000 New Schematic Extra Large.gif|center|BCI2000 Schematic]]

Above shows the main framework of BCI2000, with examples for each section. Navigate to the [[User Reference:Filters|Filters page]] to learn more about the framework, or view links below for tutorials and more reference pages.
</td> </tr>

<table cellspacing="10" style="width:100%;margin-top:-10px">
<tr>
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#fff8dc; align:right;vertical-align:top;">
==BCI2000 for Users==

* [//{{SERVERNAME}}/useradmin Create or modify a User Account]
* [[DownloadBCI2000|Download BCI2000]]
* Take the introductory [[User Tutorial:BCI2000 Tour|BCI2000 Tour]]
* Learn more through an [[Introduction_to_Adaptive_Neurotechnologies|Introduction to Adaptive Neurotechnologies]]
* Review the terminology in the [[BCI2000 Glossary]]
</td>

<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#e3f5fc; align:right;vertical-align:top;">
==BCI2000 for Developers==
* [//{{SERVERNAME}}/useradmin Create or modify a User Account]
* Download [[BCI2000 Binaries]]
* Download, build, and customize the BCI2000 toolchain for windows using [[Programming_Howto:Building and Customizing BCI2000|Building and Customizing Howto]]
* Download, build, and customize the BCI2000 toolchain for non-windows platforms using [[ Programming_Howto:Non:Building_and_Customizing_BCI2000_on_Non-Windows_Platforms|Building and Customizing Howto for Non-Windows]]
* Access to the [[Programming Howto:Building and Customizing BCI2000|BCI2000 Source Code]]
</td>
</tr>

<tr>
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; background-color:#e3f5fc; padding:0 1em 1em 1em; align:right;vertical-align:top;">
==BCI2000 References==
===BCI2000 Overview and Tools===
* The [[User Reference:Contents|User Reference Manual]] describes all details of system configuration and usage
===Technical References===
* The [[Technical Reference:Contents|Technical Reference Manual]] contains a discussion of its basic concepts, and a detailed specification of the BCI2000 standard.
===Programming References===
* The [[Programming Reference:Contents|Programming Reference]] provides background information which you need in order to understand, modify, or create code that depends on the BCI2000 framework.
===Contributions===
* [[Contributions:Contents|User-Contributed BCI2000 Components and Patches]]
===Categories===
*[[:Category:Data Acquisition | Data Acquisition]]
*[[:Category:Signal Processing | Signal Processing]]
*[[:Category:User Application | User Application]]
*[[:Category:External Interfaces | External Interfaces]]
*[[:Category:User Interface | User Interface]]
*[[:Category:Video | Video Tutorials]]

</td>

<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; background-color:#fff8dc; padding:0 1em 1em 1em; align:right;vertical-align:top;">
==BCI2000 Tutorials==
===Setup Tutorials===
*[[Programming Howto:Install Prerequisites|Install Prerequisites]]
*[[Programming Howto:Register with BCI2000 Project|Register with the BCI2000 Project]]
*[[Programming Howto:Download the BCI2000 Sourcecode|Download the BCI2000 Sourcecode]]
*[[Programming Howto:Configure BCI2000 for Compilation|Configure BCI2000 for Compilation]]
*[[Programming Howto:Compile BCI2000|Compile BCI2000]]
===Experimental Tutorials===
*[[User Tutorial:Mu Rhythm BCI Tutorial|Mu Rhythm BCI Tutorial]]
*[[User Tutorial:P300 BCI Tutorial|P300 BCI Tutorial]]
===Programming Tutorials===
*[[Programming Tutorial:Implementing a Source Module|Implementing a Source Module]]
*[[Programming Howto:Create a custom Signal Processing Module|Implementing a Signal Processing Module]]
*[[Programming Tutorial:Implementing a Matlab-based Filter|Implementing a Matlab-based Filter]]
*[[Programming Tutorial:Implementing an Input Logger|Implementing an Input Logger]]
===Data Analysis Tutorials===
*[[User Tutorial:Data Analysis|Data Analysis with BCI2000]]
* Converting and Analyzing BCI2000 Data with [[User Reference:Matlab MEX Files|Matlab MEX Files]]
* Analyze BCI2000 Data in Python with [https://github.com/neurotechcenter/BCI2kReader BCI2k Reader]
===All Tutorials: See a complete list of [[User Tutorial|BCI2000 tutorials]] here===
*
</td>
</tr>

<tr>
<td style="margin:0; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#fff8dc; align:right;vertical-align:top;">
==Supported Frameworks==
===BCI2000 Core Frameworks===
* [[User Reference:P3SpellerTask|P3 Speller]]
* [[User Reference:StimulusPresentationTask|Stimulus Presentation]]
* [[User Reference:CursorTask|Cursor Task]]
===[[Supported Frameworks|External Frameworks]]===
* [[User Tutorial:BCI2000Remote|BCI2000 Remote]] - includes Matlab, C++, and Python
* [[PsychoPy]]
* [[BCPy2000]]
</td>

<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; padding:0 1em 1em 1em; background-color:#e3f5fc; align:right;vertical-align:top;">

==Additional Information==
* [[System Features|Features supported by BCI2000]]
* [https://github.com/neurotechcenter NCAN Github]
* [//{{SERVERNAME}}/phpbb BCI2000 Community Forum]
* [//{{SERVERNAME}}/tracproj/newticket Submit a Bug Report] (make sure you log in)
* [[User FAQ|BCI2000 Frequently Asked Questions]]
* [[BCI2000 Glossary]] of terms specific to BCI2000
* [[BCI2000 Licensing|Licensing Information]]
</td>
</tr>
</table>

<table cellspacing="10" style="width:100%;">
<tr>
<td style="margin:0; margin-top:10px; margin-right:10px; border-radius: 10px; border:0.5px solid #a2a2a2; padding:0 1em 1em 1em; background-color:white; align:right;vertical-align:top;">
==BCI2000 Publications==
* [https://{{SERVERNAME}}/downloads/doc/paper.pdf G. Schalk, D.J. McFarland, T. Hinterberger, N. Birbaumer, and J.R. Wolpaw: ''BCI2000: A General-Purpose Brain-Computer Interface (BCI) System'', IEEE Trans Biomed Eng, 51(6), June 2004.]
* J. Mellinger, G. Schalk: ''BCI2000: A General-Purpose Software Platform for BCI Research,'' In: G. Dornhege, J. del R. Millán, T. Hinterberger, D.J. McFarland, K.-R. Müller (eds.), ''Toward Brain-Computer Interfacing,'' MIT Press, 2007.
* [http://www.amazon.com/Practical-Guide-BrainComputer-Interfacing-BCI2000/dp/1849960917/ G. Schalk, J. Mellinger: "A Practical Guide to Brain-Computer Interfacing with BCI2000", Springer, 2010.]
* J. Mellinger, G. Schalk: "Using BCI2000 in BCI Research," In: B. Graimann, B. Allison, G. Pfurtscheller (eds.), "Brain-Computer Interfaces: Revolutionizing Human-Computer Interaction", Springer, 2010.
</td>
</tr>
</table>

Main Page

2024-10-23T18:56:06Z

Swiftj:

User Tutorial:BCI2000Remote

2024-09-05T18:44:16Z

Swiftj: /* Python Tutorial */

==Description==
BCI2000Remote is a proxy interface class to the BCI2000 Operator module, and allows to start up, configure, and control BCI2000 from other applications. Internally, it maintains a telnet connection to the Operator module, and sends Operator Scripting commands to control it. However, no knowledge of these scripting commands is required in order to use the BCI2000Remote class from your own application.

BCI2000Remote is most useful when writing applications in C++, or in another language for which bindings to the BCI2000RemoteLib library exist, such as Python, or MATLAB.
==Note==
BCI2000Remote is a means of interfacing with the BCI2000 Operator module meaning that there are potentially hundreds of ways we leverage this tool to have a meaningful interface with BCI2000. Because of this we will illustrate a few different integrations using different languages. This "How-to" will be separated into three separate sections: Python, C++, and Matlab.
==Python Tutorial==
<ol>
<li>Find your Python folder. If you have an existing Python environment with your code find it using the Sys Library like this:
<pre>
import sys

locate_python = sys.exec_prefix
print(locate_python)
</pre>
</li>
<li>
Locate your BCI2000Remote.py file which should have compiled into your prog folder.
Find where in your Python code you wish to integrate BCI2000. In this example I will show the minimum requirements for integration with BCI2000:
<pre>
import sys
sys.path.append('C:\\BCI2000.x64\\prog')
import BCI2000Remote
bci = BCI2000Remote.BCI2000Remote()
print('Operator path:', bci.OperatorPath)
bci.WindowVisible = True
bci.WindowTitle = 'Python controlled'
bci.SubjectID = 'pysub'
bci.Connect()
bci.Execute('cd ${BCI2000LAUNCHDIR}')
bci.Execute('ADD EVENT score 16 0')
bci.StartupModules(('SignalGenerator', 'DummySignalprocessing', 'DummyApplication'))
bci.Execute('Wait for Connected')
bci.LoadParametersRemote('../parms/fragments/amplifiers/SignalGenerator.prm')
bci.SetConfig()
</pre>
Here is how you import BCI2000Remote:
 

<gallery mode="packed" widths=300px heights=300px>
File:BCIRemote1.png
</gallery>

 
Here is how you instantiate the operator object:
 

<gallery mode="packed" widths=300px heights=300px>
File:BCIRemote 2.png
</gallery>

 
Here is how to customize the operator and connect to it:
 

<gallery mode="packed" widths=300px heights=300px>
File:BCI2000Remote2.png
</gallery>

 
Here is how you add your states:
 

<gallery mode="packed" widths=300px heights=300px>
File:BCIRemote_4.png
</gallery>

 
How to specify your signal source, signal processing, and application modules:
 

<gallery mode="packed" widths=300px heights=300px>
File:BCIRemote_5.png
</gallery>

 
How to load a parameter file(you can learn more about parameters [[Technical_Reference:Parameter_File|here]]):
 

<gallery mode="packed" widths=300px heights=300px>
File:BCIRemote_55.png
</gallery>

 
How to connect and issue commands to BCI2000:
 

<gallery mode="packed" widths=300px heights=300px>
File:BCIRemote_6.png
</gallery>

</li>
<li>
And finally, how to tell BCI2000 to set states to a value during runtime:
 

<gallery mode="packed" widths=300px heights=300px>
File:BCIRemote_6.png
</gallery>

 
Now that you've added those components to your code all you have to do is run your code. You should see the BCI2000 operator along with the system log, source watcher, and the timing window.

<gallery mode="packed" widths=500px heights=500px>
File:BCIRemote_7.png
</gallery>

 
</ol>

==C++ Tutorial==
<ol>
<li>
<li>
Open the C++ file or solution you would like to integrate with BCI2000 in Visual Studio, and find where it is located on your computer.
</li>
<li>
Navigate to the program's properties, and make the following changes:
<ul>
<li>
Under Configuration Properties -> C++ -> General, add the following folders from BCI2000 (64-bit)'s src folder: \core\Operator\BCI2000Remote, \shared\utils\Lib, \shared\config. 
</li>
<li>
Navigate to Configuration Properties -> Linker -> Input, and add ws2_32.lib to Additional Dependencies.
</li>
<li>
Under Configuration Properties -> C++ -> Advanced, add 4996 to the Disable Specific Warnings section.
</li>
</ul>
<li>
Add your Operator executable and the BCI2000RemoteLib dynamic library to the same directory as the program you intend to integrate. This can be found in the prog folder.
</li>
<li> Also, add the following files to the directory with your program and Operator.exe:

<ul>
<li>
BCI2000Connection.cpp
</li>
<li>
BCI2000Connection.h
</li>
<li>
BCI2000Remote.cpp
</li>
<li>
BCI2000Remote.h
</li>
<li>
BCI2000RemoteLib.cpp
</li>
<li>
BCI2000RemoteLib.h
</li>
<li>
SelfPipe.cpp
</li>
<li>
SelfPipe.h
</li>
<li>
sockstream.cpp
</li>
<li>
sockstream.h
</li>
</ul>

<li>
Make sure that you include all of your dependencies including BCI2000Remote.h
<pre>
#include "BCI2000Remote.h"
#include <string>
#include <vector>
#include <iostream>
</pre>
</li>
<li>
Next, instantiate the BCI2000Remote object
<pre>
int main( int argc, char* argv[] )
{
// Instantiate a BCI2000Remote object
BCI2000Remote bci;
// Assume that Operator executable resides in the same directory as this program.
std::string path = ( argc > 0 ) ? argv[0] : "";
size_t pos = path.find_last_of( "\\/" );
path = ( pos != std::string::npos ) ? path.substr( 0, pos + 1 ) : "";
// Start the Operator module, and connect
bci.OperatorPath( path + "Operator" );
if( !bci.Connect() )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
<li>
Specify your startup modules and any flags you wish to start them with
<pre>
// Startup modules
const char* modules[] = { "SignalGenerator --LogMouse=1", "ARSignalProcessing", "CursorTask" };
std::vector<std::string> vModules( &modules[0], &modules[0] + sizeof( modules ) / sizeof( *modules ) );
if( !bci.StartupModules( vModules ) )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
<li>
Load any parameter files and set subject information
<pre>
bci.LoadParametersRemote( "../parms/examples/CursorTask_SignalGenerator.prm" );
bci.SubjectID( "SUB" );
// Start a run
if( !bci.Start() )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
</li>
<li>
And here we just have BCI2000 send us back a feedback signal:
<pre>
std::string state;
while( bci.GetSystemState( state ) && state == "Running" )
{
double value = 0;
bci.GetControlSignal( 1, 1, value );
std::cout << "Control signal: " << value << ", press Enter to proceed" << std::flush;
std::string line;
std::getline( std::cin, line );
}
return 0;
}
</pre>
</li>
<li>
Now that you've added those components to your code all you have to do is compile and run it. You should see the BCI2000 operator along with the system log, source watcher, and the timing window.
Note: Be sure to compile this in your prog folder. This can be done by navigating again to Configuration Properties -> General, and changing the Output Directory to the path of the BCI2000 prog folder.
[[File:BCIRemote_7.jpg]]
</li>
</ol>
<pre>
#include "BCI2000Remote.h"
#include <string>
#include <vector>
#include <iostream>

int main( int argc, char* argv[] )
{
// Instantiate a BCI2000Remote object
BCI2000Remote bci;
// Assume that Operator executable resides in the same directory as this program.
std::string path = ( argc > 0 ) ? argv[0] : "";
size_t pos = path.find_last_of( "\\/" );
path = ( pos != std::string::npos ) ? path.substr( 0, pos + 1 ) : "";
// Start the Operator module, and connect
bci.OperatorPath( path + "Operator" );
if( !bci.Connect() )
{
std::cerr << bci.Result();
return -1;
}
// Startup modules
const char* modules[] = { "SignalGenerator --LogMouse=1", "ARSignalProcessing", "CursorTask" };
std::vector<std::string> vModules( &modules[0], &modules[0] + sizeof( modules ) / sizeof( *modules ) );
if( !bci.StartupModules( vModules ) )
{
std::cerr << bci.Result();
return -1;
}
// Load a parameter file, and set subject information
bci.LoadParametersRemote( "../parms/examples/CursorTask_SignalGenerator.prm" );
bci.SubjectID( "SUB" );
// Start a run
if( !bci.Start() )
{
std::cerr << bci.Result();
return -1;
}
// Print feedback signal
std::string state;
while( bci.GetSystemState( state ) && state == "Running" )
{
double value = 0;
bci.GetControlSignal( 1, 1, value );
std::cout << "Control signal: " << value << ", press Enter to proceed" << std::flush;
std::string line;
std::getline( std::cin, line );
}
return 0;
}
</pre>

==MatlabTutorial==
<ol>
<li>Open the Matlab file you would like to integrate with BCI2000.</li>
<li>Locate the BCI2000RemoteLib file in the BCI2000 prog folder, and BCI2000RemoteLib.h in src\core\Operator\BCI2000Remote, and load these into the Matlab file. Modify the file paths in loadlibrary(...) as needed.
Note that BCI2000RemoteLib's file name has a "64" appended when it was built in 64 bit mode, and a "32" if built iin 32 bit mode.
In this tutorial, we will be using the 64 bit version.
<pre>
%% c library load, initial part
BCI2000root = 'C:\bci2000.x64';
if not(libisloaded('bci'))
loadlibrary(fullfile(BCI2000root,'prog','BCI2000RemoteLib64'),...
fullfile(BCI2000root,'src','core','Operator','BCI2000Remote','BCI2000RemoteLib.h'), 'alias', 'bci')
end
libfunctions('bci')
</pre>
</li>
<li> Locate Operator.exe in the prog folder. Recover the memory, change the directory, and make the window visible in BCI2000. Again, modify the file path if it differs.
<pre>%need to call BCI2000Remote_Delete to recover the memory
bciHandle = calllib('bci', 'BCI2000Remote_New');
calllib('bci', 'BCI2000Remote_SetOperatorPath', bciHandle, fullfile(BCI2000root,'prog','Operator'));

% if we fail cto establish a connection to BCI2000Remote
if calllib('bci', 'BCI2000Remote_Connect', bciHandle) ~= 1
fprintf('bci connect fail!')
calllib('bci', 'BCI2000Remote_Delete', bciHandle); % call BCI2000Remote_Delete to recovery the memory
return
end

% Startup BCI2000
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Change directory $BCI2000LAUNCHDIR', 0);
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Show window; Set title ${Extract file base $0}', 0);
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Reset system', 0);
</pre>
</li>
<li> Add new states, events, or parameters before starting up the system. Note that it is greatly preferred to use events instead of states because of timing precision.
<pre>
% Create new parameter (must be done before startup)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Add Parameter Application:TestParameterField string TestParameter= FirstNewParameter % % %', 0);

% Define events
% Define new event with 2 bytes of information (2 colors)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'add event Square 1 0', 0);
</pre>
</li>
<li>Add in the proper modules (Signal Generator, Signal Processor, and Application). Refer to the documentation [[Technical_Reference:BCI2000Remote_Library]] for more information on BCI2000 remote functions. Also refer to the example Matlab code under [[Programming_Reference:BCI2000Remote_Class#Matlab_Example]].</li>
<pre>
% Startup system localhost
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Startup system localhost', 0);

% Establish connection to three modules
SourceModule = 'SignalGenerator';
modules = libpointer('stringPtrPtr', {[SourceModule ' --local --LogKeyboard=1'], 'DummySignalProcessing', 'DummyApplication'});
calllib('bci', 'BCI2000Remote_StartupModules2', bciHandle, modules, 3);

% Wait for connected before loading parameters!
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Wait for Connected', 0);
</pre>
<li> Load parameter files, modify parameters directly, and add watches after BCI2000 is connected. It can also be helpful to wait for bci2000 to start running (collecting data) before proceeding.
<pre>
% Load parameter files
calllib('bci', 'BCI2000Remote_LoadParametersRemote', bciHandle, fullfile(BCI2000root,'parms','fragments','amplifiers','SignalGenerator.prm'));

% Set parameter values
calllib('bci', 'BCI2000Remote_SetDataDirectory', bciHandle, fullfile(BCI2000root,'data','BJH'));

%Set watches to appear automatically
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'visualize watch Square', 0);

% Wait for BCI2000 to start running before starting application
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Wait for Running', 0);
</pre>
</li>
<li> While BCI2000 is running you can also get and set event and state values, and also get parameter values. Note that you cannot modify parameter values while BCI2000 is running.
<pre>
% Get parameter value
SamplingRate = calllib('bci', 'BCI2000Remote_GetParameter', bciHandle, 'SamplingRate');
fprintf(['\nSamplingRate: ' num2str(SamplingRate) 'Hz\n'])

% Get event value
[~,~,~,Square]=calllib('bci', 'BCI2000Remote_GetEventVariable', bciHandle, 'Square', 0.0);

% BCI2000 set white rectangle to 1 (true)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Set event Square 1', 0);

% Get state value
% Immediately after data block has been acquired from hardware, the
% DataIOFilter writes a 16-bit millisecond-resolution time stamp into the
% SourceTime state. Block duration is measured as the difference between
% two consecutive time stamps.
[~,~,~,SourceTime]=calllib('bci', 'BCI2000Remote_GetStateVariable', bciHandle, 'SourceTime', 0.0);
fprintf(['\nSourceTime: ', num2str(SourceTime), '\n'])

% Stop running BCI2000
calllib('bci', 'BCI2000Remote_SetStateVariable', bciHandle, 'Running', 0);
</pre>
</li>
</ol>

==Video==
<youtube alignment="center">https://www.youtube.com/watch?v=ZwLcovHZabw</youtube>

Also see the [https://bci2000.org/mediawiki/index.php/PsychoPy PsychoPy] page for more details on the installation process, APIs, and hooks.

==See also==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Tutorial]][[Category:Video]]

User Tutorial:Psychopy

2024-09-05T18:38:00Z

Swiftj: /* Tutorial */

==Description==
PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. The video first describes the two components that are developed to remotely start BCI2000 from PsychoPy, then lists the steps to follow to add the new components in the PsychoPy application and finally goes on to an example.

==Tutorial==
<ol>
<li>Download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy1.png
</gallery>
</li>

<li>Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components

<gallery mode="packed" widths=300px heights=300px>
File:Psychopy2.png
</gallery>
</li>

<li>
Open PsychoPy and then open your experiment file (StroopExtended is what we use in the demo)
<gallery mode="packed" widths=400px heights=400px>
File:Psychopy3.png
</gallery>
</li>

<li>
Open the part of the experiment where you want to start BCI2000 (in this case the ''instruct'' tab) and look under the custom section of the components for the '''BCI Connect''' and '''BCI Update State''' components

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy4.png
</gallery>
</li>

<li>
Add the BCI2000 Start Component by clicking on it.
</li>

<li>
Enter the path to the prog folder in the BCI2000 directory where your BCI2000Remote.py file exists

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy5.png
</gallery>
</li>

<li>
Add the states that you want to record separated by commas (the first value will always be the default value and the second value will always be the maximum value)

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy6.png
</gallery>
</li>

<li>
Add the BCIUpdateState component to where you want to update state values. You can either choose to simply pass a variable through BCIUpdateState, or you can specify that it execute a specific Python script by choosing the "Use Expression" ticker

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy7.png
</gallery>

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy8.png
</gallery>
</li>

<li>
Run the experiment

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy9.png
</gallery>

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy10.png
</gallery>
</li>

</ol>

==Video==
<youtube alignment="center">https://www.youtube.com/watch?v=yPacLewE3Xo&list=PL6LrR5Nj3cAxOxKHNsnqyKfLDGikpi8Qi&index=4</youtube>

Also see the [https://bci2000.org/mediawiki/index.php/PsychoPy PsychoPy] page for more details on the installation process, APIs, and hooks.

==See also==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Tutorial]][[Category:Video]]

PsychoPy

2024-09-05T18:37:20Z

Swiftj: /* Tutorial */

PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. [1] This wiki page first describes the two components that remotely start BCI2000 from PsychoPy. The next section describes the steps to add the new components in the PsychoPy application. The final section goes over two tutorial examples.
==Video Overview==
<youtube alignment="center">https://youtu.be/yPacLewE3Xo</youtube>
==Prerequisites==
For this project, you will need two things: [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Building_and_Customizing_BCI2000 BCI2000] compiled for your system and the newest version of [https://www.psychopy.org/download.html PsychoPy].

== Components ==

=== BCI2000Start ===
This component starts up the BCI2000 modules remotely. The component takes two parameters:
; Path : Path to the BCI2000 ''prog'' directory, which contains the ''BCI2000Remote.py'' file.
; States : List of new states to add to BCI2000. The states in the list are defined as follows: 'StateName defaultValue maxValue.' Eg: lastKey 0 255, correctKey 0 1.
'''NOTE:''' You can specify the modules with which you want to run the experiment with the ''BCI.StartupModules'' command in the Init.py file previously copied into your PsychoPy environment. You can also specify which parameters to use for the experiment and specify other command-line arguments with the ''BCI.LoadParameterRemote'' command.

[[File:BCI2000Start.png|alt="BCI2000 start component image showing its parameters"|BCIStart Component]]

=== BCI2000UpdateState ===
This component defines which state to update and when. It takes the following parameters:
; State Name : The name of the state in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the state. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the state.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the state is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET STATE'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCI2000UpdateState.png|alt="BCI2000 update state component image showing its parameters"|BCIUpdateStart Component]]

== Integrating BCI2000 into PyschoPy ==
Clone PsychoPy from the [https://github.com/psychopy/psychopy PyschoPy] repository. You can also download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 
Below is a picture of PsychoPy before integrating BCI2000. Notice that in the rightmost column, under '''Custom''' Components, there is no BCI2000 component.

<gallery mode="packed" widths=500px heights=500px>
File:PsychoPyWithoutBCI.png|alt="PsychoPy Homepage without BCI2000 Components"|PsychoPy Homepage without BCI2000 Components
</gallery>

=== Standalone version ===
For Windows, Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components folder.

=== Developer version ===
Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\psychopy\experiment\components.
Open the terminal and navigate to the PsychoPy home directory where ''setup.py'' resides.
Run the following command in the terminal: 
<code>pip install -e .</code> 
 
Start PsychoPy application by running "python \psychopy\app\psychopyApp.py" from wherever you cloned your PsychoPy repository. If you downloaded the standalone version installer, you can simply press the Windows key and search for PsychoPy. Once you're under the '''Custom''' Components (in the rightmost column), you should see the two new components - ''BCI2000Start'' and ''BCI2000UpdateState'' as shown in the figure below.

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPy_Start.png|alt="PsychoPy Homepage with BCI2000 Components"|PsychoPy Homepage with BCI2000 Components
</gallery>

'''Note:''' Make sure you don't run the experiments in full screen if you are using a single screen.

== Tutorial ==
In this section, two examples are presented to help the user understand the use of BCI2000 within PsychoPy. The examples modify the demo stroopExtended (already provided by PsychoPy once you have unpacked the demos) and integrates BCI2000 within it. The stroopExtended demo asks user to press certain keys depending on the color shown on the screen and records the response time.

=== Using Response Component Variable Option ===
In this tutorial, we will add a new state called '''correctKey''' in BCI2000 using PsychoPy. This state will be changed to 1 if the key pressed by user is correct, otherwise 0.
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like this. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>

 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>correctKey 0 1</code> in the ''States'' field as shown in the image. '''correctKey''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''1''' is the maximum value the state can take in any case. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart1.png|alt="PsychoPy - Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Fill in the fields ''State Name'' with '''$correctKey''' (the BCI2000 state we want to update; '$' is used to indicate to PsychoPy to treat it as a variable) and ''Response Component Variable'' with '''$resp.corr''' ('resp' is the name of the keyboard that takes the input and 'corr' is its property that stores whether the key pressed is correct or not. you can see this variable being used in the program when you compile it to script) as shown in the image. This will essentially update the state 'correctKey' with the value of 'resp.corr'. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState1.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on correctKey and add to watch, then click Ok on States and Events screen) and proceed as with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun1.png|alt="PsychoPy Stroop Extended Demo Run 1"|PsychoPy Stroop Extended Demo Run 1
</gallery>

</li>
 
</ol>

=== Using Use Expression Option ===
In this tutorial, we will add a new state called '''responseTime''' in BCI2000 using PsychoPy. This state will represent the time the user takes to press the correct key in seconds (with no decimals).
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like the image below. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo
</gallery>

</li>
 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>responseTime 0 600</code> in the ''States'' field as shown in the image. '''responseTime''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''600''' is the maximum value the state can take in any case, i.e, the maximum response time could be 10 minutes. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciStart2.png|alt="PsychoPy- Add State into BCI2000"|PsychoPy - Add State into BCI2000
</gallery>

</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Check on the '''Use Expression''' option to run the expression that is written in the '''Expression''' field. Write the lines of python code in the '''Expression''' field as shown in the image. These lines first set the 'RUNNING' state of BCI2000 to 1 to make sure that BCI2000 is running. It then checks if the type of the 'resp.rt' is float. If yes, that means 'resp.rt' stores the response time and sets the state 'responseTime' to the rounded value of 'resp.rt' ('resp' is the name of the keyboard which takes the input and 'rt' is its property that stores the time it took user to press the key; you can see this variable being used in the program when you compile it to script) using the bci.Execute and SET STATE commands. 
<code>bci.Execute('SET STATE RUNNING 1') 
if(type(resp.rt) == float): 
    bci.Execute('SET STATE responseTime %d' % round(resp.rt))
</code> 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciUpdateState2.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000
</gallery>

</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on responseTime and add to watch. Click Ok on the States and Events screen) and proceed with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPyBciDemoRun2.png|alt="PsychoPy Stroop Extended Demo Run 2"|PsychoPy Stroop Extended Demo Run 2
</gallery>

</li>
 
</ol>

== References ==
1. [https://www.psychopy.org/ PsychoPy site]

== See Also ==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Video]]

PsychoPy

2024-09-05T18:00:32Z

Swiftj: /* Integrating BCI2000 into PyschoPy */

PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. [1] This wiki page first describes the two components that remotely start BCI2000 from PsychoPy. The next section describes the steps to add the new components in the PsychoPy application. The final section goes over two tutorial examples.
==Video Overview==
<youtube alignment="center">https://youtu.be/yPacLewE3Xo</youtube>
==Prerequisites==
For this project, you will need two things: [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Building_and_Customizing_BCI2000 BCI2000] compiled for your system and the newest version of [https://www.psychopy.org/download.html PsychoPy].

== Components ==

=== BCI2000Start ===
This component starts up the BCI2000 modules remotely. The component takes two parameters:
; Path : Path to the BCI2000 ''prog'' directory, which contains the ''BCI2000Remote.py'' file.
; States : List of new states to add to BCI2000. The states in the list are defined as follows: 'StateName defaultValue maxValue.' Eg: lastKey 0 255, correctKey 0 1.
'''NOTE:''' You can specify the modules with which you want to run the experiment with the ''BCI.StartupModules'' command in the Init.py file previously copied into your PsychoPy environment. You can also specify which parameters to use for the experiment and specify other command-line arguments with the ''BCI.LoadParameterRemote'' command.

[[File:BCI2000Start.png|alt="BCI2000 start component image showing its parameters"|BCIStart Component]]

=== BCI2000UpdateState ===
This component defines which state to update and when. It takes the following parameters:
; State Name : The name of the state in BCI2000 to update.
; Response Component Variable : The variable to which the state is to be set OR the variable which contains the new value of the state. '''Note-''' the variable is written as ''$VariableName''.
; Use Expression : If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the state.
; Expression : The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the state is updated. '''Note-''' the user would have to use commands such as ''bci.Execute'' and ''SET STATE'' to update the state in such cases. See [[Programming Reference:BCI2000Remote Class]] and [[User Reference:Operator Module Scripting]] for more details.

[[File:BCI2000UpdateState.png|alt="BCI2000 update state component image showing its parameters"|BCIUpdateStart Component]]

== Integrating BCI2000 into PyschoPy ==
Clone PsychoPy from the [https://github.com/psychopy/psychopy PyschoPy] repository. You can also download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 
Below is a picture of PsychoPy before integrating BCI2000. Notice that in the rightmost column, under '''Custom''' Components, there is no BCI2000 component.

<gallery mode="packed" widths=500px heights=500px>
File:PsychoPyWithoutBCI.png|alt="PsychoPy Homepage without BCI2000 Components"|PsychoPy Homepage without BCI2000 Components
</gallery>

=== Standalone version ===
For Windows, Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components folder.

=== Developer version ===
Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\psychopy\experiment\components.
Open the terminal and navigate to the PsychoPy home directory where ''setup.py'' resides.
Run the following command in the terminal: 
<code>pip install -e .</code> 
 
Start PsychoPy application by running "python \psychopy\app\psychopyApp.py" from wherever you cloned your PsychoPy repository. If you downloaded the standalone version installer, you can simply press the Windows key and search for PsychoPy. Once you're under the '''Custom''' Components (in the rightmost column), you should see the two new components - ''BCI2000Start'' and ''BCI2000UpdateState'' as shown in the figure below.

<gallery mode="packed" widths=400px heights=400px>
File:PsychoPy_Start.png|alt="PsychoPy Homepage with BCI2000 Components"|PsychoPy Homepage with BCI2000 Components
</gallery>

'''Note:''' Make sure you don't run the experiments in full screen if you are using a single screen.

== Tutorial ==
In this section, two examples are presented to help the user understand the use of BCI2000 within PsychoPy. The examples modify the demo stroopExtended (already provided by PsychoPy once you have unpacked the demos) and integrates BCI2000 within it. The stroopExtended demo asks user to press certain keys depending on the color shown on the screen and records the response time.

=== Using Response Component Variable Option ===
In this tutorial, we will add a new state called '''correctKey''' in BCI2000 using PsychoPy. This state will be changed to 1 if the key pressed by user is correct, otherwise 0.
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like this. 
[[File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo]]
</li>

 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>correctKey 0 1</code> in the ''States'' field as shown in the image. '''correctKey''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''1''' is the maximum value the state can take in any case. 

[[File:PsychoPyBciStart1.png|alt="PsychoPy - Add State into BCI2000"|PsychoPy - Add State into BCI2000]]
</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Fill in the fields ''State Name'' with '''$correctKey''' (the BCI2000 state we want to update; '$' is used to indicate to PsychoPy to treat it as a variable) and ''Response Component Variable'' with '''$resp.corr''' ('resp' is the name of the keyboard that takes the input and 'corr' is its property that stores whether the key pressed is correct or not. you can see this variable being used in the program when you compile it to script) as shown in the image. This will essentially update the state 'correctKey' with the value of 'resp.corr'. 
[[File:PsychoPyBciUpdateState1.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000]]
</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on correctKey and add to watch, then click Ok on States and Events screen) and proceed as with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 
[[File:PsychoPyBciDemoRun1.png|alt="PsychoPy Stroop Extended Demo Run 1"|PsychoPy Stroop Extended Demo Run 1]]
</li>
 
</ol>

=== Using Use Expression Option ===
In this tutorial, we will add a new state called '''responseTime''' in BCI2000 using PsychoPy. This state will represent the time the user takes to press the correct key in seconds (with no decimals).
<ol>
<li>
Open the stroopExtended demo in PsychoPy. It should look like the image below. 
[[File:PsychoPyDemoStart.png|alt="PsychoPy Stroop Extended Demo"|PsychoPy Stroop Extended Demo]]
</li>
 
<li>
Start BCI2000 - Navigate to the '''instruct''' tab and click on '''BCI2000Start'''. Enter the path to the '''prog''' directory of BCI2000 (within which BCI2000Remote.py exists) in the ''Path'' field and <code>responseTime 0 600</code> in the ''States'' field as shown in the image. '''responseTime''' is the name we want the new state to have in BCI2000, '''0''' is the default value the state should have and '''600''' is the maximum value the state can take in any case, i.e, the maximum response time could be 10 minutes. 

[[File:PsychoPyBciStart2.png|alt="PsychoPy- Add State into BCI2000"|PsychoPy - Add State into BCI2000]]
</li>
 
<li>
Update BCI2000 State - Navigate to the '''trial''' tab and click on '''BCI2000UpdateState'''. Check on the '''Use Expression''' option to run the expression that is written in the '''Expression''' field. Write the lines of python code in the '''Expression''' field as shown in the image. These lines first set the 'RUNNING' state of BCI2000 to 1 to make sure that BCI2000 is running. It then checks if the type of the 'resp.rt' is float. If yes, that means 'resp.rt' stores the response time and sets the state 'responseTime' to the rounded value of 'resp.rt' ('resp' is the name of the keyboard which takes the input and 'rt' is its property that stores the time it took user to press the key; you can see this variable being used in the program when you compile it to script) using the bci.Execute and SET STATE commands. 
<code>bci.Execute('SET STATE RUNNING 1') 
if(type(resp.rt) == float): 
    bci.Execute('SET STATE responseTime %d' % round(resp.rt))
</code> 
[[File:PsychoPyBciUpdateState2.png|alt="PsychoPy - Update State in BCI2000"|PsychoPy - Update State in BCI2000]]
</li>
 
<li>
Run the experiment. BCI2000 will start. Add the newly created state to watch (in the BCI2000 operator, click on View -> States and Events.., right click on responseTime and add to watch. Click Ok on the States and Events screen) and proceed with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. '''Note:''' Make sure you don't run the experiments in full screen mode if you are using a single screen. 
[[File:PsychoPyBciDemoRun2.png|alt="PsychoPy Stroop Extended Demo Run 2"|PsychoPy Stroop Extended Demo Run 2]]
</li>
 
</ol>

== References ==
1. [https://www.psychopy.org/ PsychoPy site]

== See Also ==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Video]]

User Tutorial:Psychopy

2024-09-05T17:57:29Z

Swiftj:

==Description==
PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. The video first describes the two components that are developed to remotely start BCI2000 from PsychoPy, then lists the steps to follow to add the new components in the PsychoPy application and finally goes on to an example.

==Tutorial==
<ol>
<li>Download the PsychoPy standalone version from the PsychoPy [https://www.psychopy.org/download.html downloads page]. 

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy1.png
</gallery>
</li>

<li>Copy the folders '''BCIStart''' and '''BCIUpdateState''' from the ''src/contrib/PsychoPy Components'' directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy2.png
</gallery>
</li>

<li>
Open PsychoPy and then open your experiment file (StroopExtended is what we use in the demo)
<gallery mode="packed" widths=400px heights=400px>
File:Psychopy3.png
</gallery>
</li>

<li>
Open the part of the experiment where you want to start BCI2000 (in this case the ''instruct'' tab) and look under the custom section of the components for the '''BCI Connect''' and '''BCI Update State''' components

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy4.png
</gallery>
</li>

<li>
Add the BCI2000 Start Component by clicking on it.
</li>

<li>
Enter the path to the prog folder in the BCI2000 directory where your BCI2000Remote.py file exists

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy5.png
</gallery>
</li>

<li>
Add the states that you want to record separated by commas (the first value will always be the default value and the second value will always be the maximum value)

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy6.png
</gallery>
</li>

<li>
Add the BCIUpdateState component to where you want to update state values. You can either choose to simply pass a variable through BCIUpdateState, or you can specify that it execute a specific Python script by choosing the "Use Expression" ticker

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy7.png
</gallery>

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy8.png
</gallery>
</li>

<li>
Run the experiment

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy9.png
</gallery>

<gallery mode="packed" widths=400px heights=400px>
File:Psychopy10.png
</gallery>
</li>

</ol>

==Video==
<youtube alignment="center">https://www.youtube.com/watch?v=yPacLewE3Xo&list=PL6LrR5Nj3cAxOxKHNsnqyKfLDGikpi8Qi&index=4</youtube>

Also see the [https://bci2000.org/mediawiki/index.php/PsychoPy PsychoPy] page for more details on the installation process, APIs, and hooks.

==See also==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Tutorial]][[Category:Video]]

User Tutorial:BCI2000Remote

2024-08-15T22:28:45Z

Swiftj: /* Python Tutorial */

==Description==
BCI2000Remote is a proxy interface class to the BCI2000 Operator module, and allows to start up, configure, and control BCI2000 from other applications. Internally, it maintains a telnet connection to the Operator module, and sends Operator Scripting commands to control it. However, no knowledge of these scripting commands is required in order to use the BCI2000Remote class from your own application.

BCI2000Remote is most useful when writing applications in C++, or in another language for which bindings to the BCI2000RemoteLib library exist, such as Python, or MATLAB.
==Note==
BCI2000Remote is a means of interfacing with the BCI2000 Operator module meaning that there are potentially hundreds of ways we leverage this tool to have a meaningful interface with BCI2000. Because of this we will illustrate a few different integrations using different languages. This "How-to" will be separated into three separate sections: Python, C++, and Matlab.
==Python Tutorial==
<ol>
<li>Find your Python folder. If you have an existing Python environment with your code find it using the Sys Library like this:
<pre>
import sys

locate_python = sys.exec_prefix
print(locate_python)
</pre>
</li>
<li>
Locate your BCI2000Remote.py file which should have compiled into your prog folder.
Find where in your Python code you wish to integrate BCI2000. In this example I will show the minimum requirements for integration with BCI2000:
<pre>
import sys
sys.path.append('C:\\BCI2000.x64\\prog')
import BCI2000Remote
bci = BCI2000Remote.BCI2000Remote()
print('Operator path:', bci.OperatorPath)
bci.WindowVisible = True
bci.WindowTitle = 'Python controlled'
bci.SubjectID = 'pysub'
bci.Connect()
bci.Execute('cd ${BCI2000LAUNCHDIR}')
bci.Execute('ADD EVENT score 16 0')
bci.StartupModules(('SignalGenerator', 'DummySignalprocessing', 'DummyApplication'))
bci.Execute('Wait for Connected')
bci.LoadParametersRemote('../parms/fragments/amplifiers/SignalGenerator.prm')
bci.SetConfig()
</pre>
Here is how you import BCI2000Remote:
 
[[File:BCIRemote1.png]]
 
Here is how you instantiate the operator object:
 
[[File:BCIRemote 2.png]]
 
Here is how to customize the operator and connect to it:
 
[[File:BCI2000Remote2.png]]
 
Here is how you add your states:
 
[[File:BCIRemote_4.png]]
 
How to specify your signal source, signal processing, and application modules:
 
[[File:BCIRemote_5.png]]
 
How to load a parameter file(you can learn more about parameters [[Technical_Reference:Parameter_File|here]]):
 
[[File:BCIRemote_55.png]]
 
How to connect and issue commands to BCI2000:
 
[[File:BCIRemote_6.png]]
</li>
<li>
And finally, how to tell BCI2000 to set states to a value during runtime:
 
[[File:BCIRemote_6.png]]
 
Now that you've added those components to your code all you have to do is run your code. You should see the BCI2000 operator along with the system log, source watcher, and the timing window.
[[File:BCIRemote_7.png]]
 
</ol>

==C++ Tutorial==
<ol>
<li>
<li>
Open the C++ file or solution you would like to integrate with BCI2000 in Visual Studio, and find where it is located on your computer.
</li>
<li>
Navigate to the program's properties, and make the following changes:
<ul>
<li>
Under Configuration Properties -> C++ -> General, add the following folders from BCI2000 (64-bit)'s src folder: \core\Operator\BCI2000Remote, \shared\utils\Lib, \shared\config. 
</li>
<li>
Navigate to Configuration Properties -> Linker -> Input, and add ws2_32.lib to Additional Dependencies.
</li>
<li>
Under Configuration Properties -> C++ -> Advanced, add 4996 to the Disable Specific Warnings section.
</li>
</ul>
<li>
Add your Operator executable and the BCI2000RemoteLib dynamic library to the same directory as the program you intend to integrate. This can be found in the prog folder.
</li>
<li> Also, add the following files to the directory with your program and Operator.exe:

<ul>
<li>
BCI2000Connection.cpp
</li>
<li>
BCI2000Connection.h
</li>
<li>
BCI2000Remote.cpp
</li>
<li>
BCI2000Remote.h
</li>
<li>
BCI2000RemoteLib.cpp
</li>
<li>
BCI2000RemoteLib.h
</li>
<li>
SelfPipe.cpp
</li>
<li>
SelfPipe.h
</li>
<li>
sockstream.cpp
</li>
<li>
sockstream.h
</li>
</ul>

<li>
Make sure that you include all of your dependencies including BCI2000Remote.h
<pre>
#include "BCI2000Remote.h"
#include <string>
#include <vector>
#include <iostream>
</pre>
</li>
<li>
Next, instantiate the BCI2000Remote object
<pre>
int main( int argc, char* argv[] )
{
// Instantiate a BCI2000Remote object
BCI2000Remote bci;
// Assume that Operator executable resides in the same directory as this program.
std::string path = ( argc > 0 ) ? argv[0] : "";
size_t pos = path.find_last_of( "\\/" );
path = ( pos != std::string::npos ) ? path.substr( 0, pos + 1 ) : "";
// Start the Operator module, and connect
bci.OperatorPath( path + "Operator" );
if( !bci.Connect() )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
<li>
Specify your startup modules and any flags you wish to start them with
<pre>
// Startup modules
const char* modules[] = { "SignalGenerator --LogMouse=1", "ARSignalProcessing", "CursorTask" };
std::vector<std::string> vModules( &modules[0], &modules[0] + sizeof( modules ) / sizeof( *modules ) );
if( !bci.StartupModules( vModules ) )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
<li>
Load any parameter files and set subject information
<pre>
bci.LoadParametersRemote( "../parms/examples/CursorTask_SignalGenerator.prm" );
bci.SubjectID( "SUB" );
// Start a run
if( !bci.Start() )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
</li>
<li>
And here we just have BCI2000 send us back a feedback signal:
<pre>
std::string state;
while( bci.GetSystemState( state ) && state == "Running" )
{
double value = 0;
bci.GetControlSignal( 1, 1, value );
std::cout << "Control signal: " << value << ", press Enter to proceed" << std::flush;
std::string line;
std::getline( std::cin, line );
}
return 0;
}
</pre>
</li>
<li>
Now that you've added those components to your code all you have to do is compile and run it. You should see the BCI2000 operator along with the system log, source watcher, and the timing window.
Note: Be sure to compile this in your prog folder. This can be done by navigating again to Configuration Properties -> General, and changing the Output Directory to the path of the BCI2000 prog folder.
[[File:BCIRemote_7.jpg]]
</li>
</ol>
<pre>
#include "BCI2000Remote.h"
#include <string>
#include <vector>
#include <iostream>

int main( int argc, char* argv[] )
{
// Instantiate a BCI2000Remote object
BCI2000Remote bci;
// Assume that Operator executable resides in the same directory as this program.
std::string path = ( argc > 0 ) ? argv[0] : "";
size_t pos = path.find_last_of( "\\/" );
path = ( pos != std::string::npos ) ? path.substr( 0, pos + 1 ) : "";
// Start the Operator module, and connect
bci.OperatorPath( path + "Operator" );
if( !bci.Connect() )
{
std::cerr << bci.Result();
return -1;
}
// Startup modules
const char* modules[] = { "SignalGenerator --LogMouse=1", "ARSignalProcessing", "CursorTask" };
std::vector<std::string> vModules( &modules[0], &modules[0] + sizeof( modules ) / sizeof( *modules ) );
if( !bci.StartupModules( vModules ) )
{
std::cerr << bci.Result();
return -1;
}
// Load a parameter file, and set subject information
bci.LoadParametersRemote( "../parms/examples/CursorTask_SignalGenerator.prm" );
bci.SubjectID( "SUB" );
// Start a run
if( !bci.Start() )
{
std::cerr << bci.Result();
return -1;
}
// Print feedback signal
std::string state;
while( bci.GetSystemState( state ) && state == "Running" )
{
double value = 0;
bci.GetControlSignal( 1, 1, value );
std::cout << "Control signal: " << value << ", press Enter to proceed" << std::flush;
std::string line;
std::getline( std::cin, line );
}
return 0;
}
</pre>

==MatlabTutorial==
<ol>
<li>Open the Matlab file you would like to integrate with BCI2000.</li>
<li>Locate the BCI2000RemoteLib file in the BCI2000 prog folder, and BCI2000RemoteLib.h in src\core\Operator\BCI2000Remote, and load these into the Matlab file. Modify the file paths in loadlibrary(...) as needed.
Note that BCI2000RemoteLib's file name has a "64" appended when it was built in 64 bit mode, and a "32" if built iin 32 bit mode.
In this tutorial, we will be using the 64 bit version.
<pre>
%% c library load, initial part
BCI2000root = 'C:\bci2000.x64';
if not(libisloaded('bci'))
loadlibrary(fullfile(BCI2000root,'prog','BCI2000RemoteLib64'),...
fullfile(BCI2000root,'src','core','Operator','BCI2000Remote','BCI2000RemoteLib.h'), 'alias', 'bci')
end
libfunctions('bci')
</pre>
</li>
<li> Locate Operator.exe in the prog folder. Recover the memory, change the directory, and make the window visible in BCI2000. Again, modify the file path if it differs.
<pre>%need to call BCI2000Remote_Delete to recover the memory
bciHandle = calllib('bci', 'BCI2000Remote_New');
calllib('bci', 'BCI2000Remote_SetOperatorPath', bciHandle, fullfile(BCI2000root,'prog','Operator'));

% if we fail cto establish a connection to BCI2000Remote
if calllib('bci', 'BCI2000Remote_Connect', bciHandle) ~= 1
fprintf('bci connect fail!')
calllib('bci', 'BCI2000Remote_Delete', bciHandle); % call BCI2000Remote_Delete to recovery the memory
return
end

% Startup BCI2000
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Change directory $BCI2000LAUNCHDIR', 0);
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Show window; Set title ${Extract file base $0}', 0);
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Reset system', 0);
</pre>
</li>
<li> Add new states, events, or parameters before starting up the system. Note that it is greatly preferred to use events instead of states because of timing precision.
<pre>
% Create new parameter (must be done before startup)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Add Parameter Application:TestParameterField string TestParameter= FirstNewParameter % % %', 0);

% Define events
% Define new event with 2 bytes of information (2 colors)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'add event Square 1 0', 0);
</pre>
</li>
<li>Add in the proper modules (Signal Generator, Signal Processor, and Application). Refer to the documentation [[Technical_Reference:BCI2000Remote_Library]] for more information on BCI2000 remote functions. Also refer to the example Matlab code under [[Programming_Reference:BCI2000Remote_Class#Matlab_Example]].</li>
<pre>
% Startup system localhost
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Startup system localhost', 0);

% Establish connection to three modules
SourceModule = 'SignalGenerator';
modules = libpointer('stringPtrPtr', {[SourceModule ' --local --LogKeyboard=1'], 'DummySignalProcessing', 'DummyApplication'});
calllib('bci', 'BCI2000Remote_StartupModules2', bciHandle, modules, 3);

% Wait for connected before loading parameters!
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Wait for Connected', 0);
</pre>
<li> Load parameter files, modify parameters directly, and add watches after BCI2000 is connected. It can also be helpful to wait for bci2000 to start running (collecting data) before proceeding.
<pre>
% Load parameter files
calllib('bci', 'BCI2000Remote_LoadParametersRemote', bciHandle, fullfile(BCI2000root,'parms','fragments','amplifiers','SignalGenerator.prm'));

% Set parameter values
calllib('bci', 'BCI2000Remote_SetDataDirectory', bciHandle, fullfile(BCI2000root,'data','BJH'));

%Set watches to appear automatically
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'visualize watch Square', 0);

% Wait for BCI2000 to start running before starting application
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Wait for Running', 0);
</pre>
</li>
<li> While BCI2000 is running you can also get and set event and state values, and also get parameter values. Note that you cannot modify parameter values while BCI2000 is running.
<pre>
% Get parameter value
SamplingRate = calllib('bci', 'BCI2000Remote_GetParameter', bciHandle, 'SamplingRate');
fprintf(['\nSamplingRate: ' num2str(SamplingRate) 'Hz\n'])

% Get event value
[~,~,~,Square]=calllib('bci', 'BCI2000Remote_GetEventVariable', bciHandle, 'Square', 0.0);

% BCI2000 set white rectangle to 1 (true)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Set event Square 1', 0);

% Get state value
% Immediately after data block has been acquired from hardware, the
% DataIOFilter writes a 16-bit millisecond-resolution time stamp into the
% SourceTime state. Block duration is measured as the difference between
% two consecutive time stamps.
[~,~,~,SourceTime]=calllib('bci', 'BCI2000Remote_GetStateVariable', bciHandle, 'SourceTime', 0.0);
fprintf(['\nSourceTime: ', num2str(SourceTime), '\n'])

% Stop running BCI2000
calllib('bci', 'BCI2000Remote_SetStateVariable', bciHandle, 'Running', 0);
</pre>
</li>
</ol>

==Video==
<youtube alignment="center">https://www.youtube.com/watch?v=ZwLcovHZabw</youtube>

Also see the [https://bci2000.org/mediawiki/index.php/PsychoPy PsychoPy] page for more details on the installation process, APIs, and hooks.

==See also==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Tutorial]]

User Tutorial:BCI2000Remote

2024-08-15T22:12:16Z

Swiftj: /* MatlabTutorial */

==Description==
BCI2000Remote is a proxy interface class to the BCI2000 Operator module, and allows to start up, configure, and control BCI2000 from other applications. Internally, it maintains a telnet connection to the Operator module, and sends Operator Scripting commands to control it. However, no knowledge of these scripting commands is required in order to use the BCI2000Remote class from your own application.

BCI2000Remote is most useful when writing applications in C++, or in another language for which bindings to the BCI2000RemoteLib library exist, such as Python, or MATLAB.
==Note==
BCI2000Remote is a means of interfacing with the BCI2000 Operator module meaning that there are potentially hundreds of ways we leverage this tool to have a meaningful interface with BCI2000. Because of this we will illustrate a few different integrations using different languages. This "How-to" will be separated into three separate sections: Python, C++, and Matlab.
==Python Tutorial==
<ol>
<li>Find your Python folder. If you have an existing Python environment with your code find it using the Sys Library like this:
<pre>
import sys

locate_python = sys.exec_prefix
print(locate_python)
</pre>
</li>
<li>
Locate your BCI2000Remote.py file which should have compiled into your prog folder.
Find where in your Python code you wish to integrate BCI2000. In this example I will show the minimum requirements for integration with BCI2000:
<pre>
import sys
sys.path.append('C:\\BCI2000.x64\\prog')
import BCI2000Remote
bci = BCI2000Remote.BCI2000Remote()
print('Operator path:', bci.OperatorPath)
bci.WindowVisible = True
bci.WindowTitle = 'Python controlled'
bci.SubjectID = 'pysub'
bci.Connect()
bci.Execute('cd ${BCI2000LAUNCHDIR}')
bci.Execute('ADD STATE score 16 0')
bci.StartupModules(('SignalGenerator', 'DummySignalprocessing', 'DummyApplication'))
bci.Execute('Wait for Connected')
bci.LoadParametersRemote('../parms/fragments/amplifiers/amplifier.prm')
bci.SetConfig()
</pre>
Here is how you import BCI2000Remote:
 
[[File:BCIRemote1.png]]
 
Here is how you instantiate the operator object:
 
[[File:BCIRemote 2.png]]
 
Here is how to customize the operator and connect to it:
 
[[File:BCI2000Remote2.png]]
 
Here is how you add your states:
 
[[File:BCIRemote_4.png]]
 
How to specify your signal source, signal processing, and application modules:
 
[[File:BCIRemote_5.png]]
 
How to load a parameter file(you can learn more about parameters [[Technical_Reference:Parameter_File|here]]):
 
[[File:BCIRemote_55.png]]
 
How to connect and issue commands to BCI2000:
 
[[File:BCIRemote_6.png]]
</li>
<li>
And finally, how to tell BCI2000 to set states to a value during runtime:
 
[[File:BCIRemote_6.png]]
 
Now that you've added those components to your code all you have to do is run your code. You should see the BCI2000 operator along with the system log, source watcher, and the timing window.
[[File:BCIRemote_7.png]]
 
</ol>

==C++ Tutorial==
<ol>
<li>
<li>
Open the C++ file or solution you would like to integrate with BCI2000 in Visual Studio, and find where it is located on your computer.
</li>
<li>
Navigate to the program's properties, and make the following changes:
<ul>
<li>
Under Configuration Properties -> C++ -> General, add the following folders from BCI2000 (64-bit)'s src folder: \core\Operator\BCI2000Remote, \shared\utils\Lib, \shared\config. 
</li>
<li>
Navigate to Configuration Properties -> Linker -> Input, and add ws2_32.lib to Additional Dependencies.
</li>
<li>
Under Configuration Properties -> C++ -> Advanced, add 4996 to the Disable Specific Warnings section.
</li>
</ul>
<li>
Add your Operator executable and the BCI2000RemoteLib dynamic library to the same directory as the program you intend to integrate. This can be found in the prog folder.
</li>
<li> Also, add the following files to the directory with your program and Operator.exe:

<ul>
<li>
BCI2000Connection.cpp
</li>
<li>
BCI2000Connection.h
</li>
<li>
BCI2000Remote.cpp
</li>
<li>
BCI2000Remote.h
</li>
<li>
BCI2000RemoteLib.cpp
</li>
<li>
BCI2000RemoteLib.h
</li>
<li>
SelfPipe.cpp
</li>
<li>
SelfPipe.h
</li>
<li>
sockstream.cpp
</li>
<li>
sockstream.h
</li>
</ul>

<li>
Make sure that you include all of your dependencies including BCI2000Remote.h
<pre>
#include "BCI2000Remote.h"
#include <string>
#include <vector>
#include <iostream>
</pre>
</li>
<li>
Next, instantiate the BCI2000Remote object
<pre>
int main( int argc, char* argv[] )
{
// Instantiate a BCI2000Remote object
BCI2000Remote bci;
// Assume that Operator executable resides in the same directory as this program.
std::string path = ( argc > 0 ) ? argv[0] : "";
size_t pos = path.find_last_of( "\\/" );
path = ( pos != std::string::npos ) ? path.substr( 0, pos + 1 ) : "";
// Start the Operator module, and connect
bci.OperatorPath( path + "Operator" );
if( !bci.Connect() )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
<li>
Specify your startup modules and any flags you wish to start them with
<pre>
// Startup modules
const char* modules[] = { "SignalGenerator --LogMouse=1", "ARSignalProcessing", "CursorTask" };
std::vector<std::string> vModules( &modules[0], &modules[0] + sizeof( modules ) / sizeof( *modules ) );
if( !bci.StartupModules( vModules ) )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
<li>
Load any parameter files and set subject information
<pre>
bci.LoadParametersRemote( "../parms/examples/CursorTask_SignalGenerator.prm" );
bci.SubjectID( "SUB" );
// Start a run
if( !bci.Start() )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
</li>
<li>
And here we just have BCI2000 send us back a feedback signal:
<pre>
std::string state;
while( bci.GetSystemState( state ) && state == "Running" )
{
double value = 0;
bci.GetControlSignal( 1, 1, value );
std::cout << "Control signal: " << value << ", press Enter to proceed" << std::flush;
std::string line;
std::getline( std::cin, line );
}
return 0;
}
</pre>
</li>
<li>
Now that you've added those components to your code all you have to do is compile and run it. You should see the BCI2000 operator along with the system log, source watcher, and the timing window.
Note: Be sure to compile this in your prog folder. This can be done by navigating again to Configuration Properties -> General, and changing the Output Directory to the path of the BCI2000 prog folder.
[[File:BCIRemote_7.jpg]]
</li>
</ol>
<pre>
#include "BCI2000Remote.h"
#include <string>
#include <vector>
#include <iostream>

int main( int argc, char* argv[] )
{
// Instantiate a BCI2000Remote object
BCI2000Remote bci;
// Assume that Operator executable resides in the same directory as this program.
std::string path = ( argc > 0 ) ? argv[0] : "";
size_t pos = path.find_last_of( "\\/" );
path = ( pos != std::string::npos ) ? path.substr( 0, pos + 1 ) : "";
// Start the Operator module, and connect
bci.OperatorPath( path + "Operator" );
if( !bci.Connect() )
{
std::cerr << bci.Result();
return -1;
}
// Startup modules
const char* modules[] = { "SignalGenerator --LogMouse=1", "ARSignalProcessing", "CursorTask" };
std::vector<std::string> vModules( &modules[0], &modules[0] + sizeof( modules ) / sizeof( *modules ) );
if( !bci.StartupModules( vModules ) )
{
std::cerr << bci.Result();
return -1;
}
// Load a parameter file, and set subject information
bci.LoadParametersRemote( "../parms/examples/CursorTask_SignalGenerator.prm" );
bci.SubjectID( "SUB" );
// Start a run
if( !bci.Start() )
{
std::cerr << bci.Result();
return -1;
}
// Print feedback signal
std::string state;
while( bci.GetSystemState( state ) && state == "Running" )
{
double value = 0;
bci.GetControlSignal( 1, 1, value );
std::cout << "Control signal: " << value << ", press Enter to proceed" << std::flush;
std::string line;
std::getline( std::cin, line );
}
return 0;
}
</pre>

==MatlabTutorial==
<ol>
<li>Open the Matlab file you would like to integrate with BCI2000.</li>
<li>Locate the BCI2000RemoteLib file in the BCI2000 prog folder, and BCI2000RemoteLib.h in src\core\Operator\BCI2000Remote, and load these into the Matlab file. Modify the file paths in loadlibrary(...) as needed.
Note that BCI2000RemoteLib's file name has a "64" appended when it was built in 64 bit mode, and a "32" if built iin 32 bit mode.
In this tutorial, we will be using the 64 bit version.
<pre>
%% c library load, initial part
BCI2000root = 'C:\bci2000.x64';
if not(libisloaded('bci'))
loadlibrary(fullfile(BCI2000root,'prog','BCI2000RemoteLib64'),...
fullfile(BCI2000root,'src','core','Operator','BCI2000Remote','BCI2000RemoteLib.h'), 'alias', 'bci')
end
libfunctions('bci')
</pre>
</li>
<li> Locate Operator.exe in the prog folder. Recover the memory, change the directory, and make the window visible in BCI2000. Again, modify the file path if it differs.
<pre>%need to call BCI2000Remote_Delete to recover the memory
bciHandle = calllib('bci', 'BCI2000Remote_New');
calllib('bci', 'BCI2000Remote_SetOperatorPath', bciHandle, fullfile(BCI2000root,'prog','Operator'));

% if we fail cto establish a connection to BCI2000Remote
if calllib('bci', 'BCI2000Remote_Connect', bciHandle) ~= 1
fprintf('bci connect fail!')
calllib('bci', 'BCI2000Remote_Delete', bciHandle); % call BCI2000Remote_Delete to recovery the memory
return
end

% Startup BCI2000
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Change directory $BCI2000LAUNCHDIR', 0);
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Show window; Set title ${Extract file base $0}', 0);
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Reset system', 0);
</pre>
</li>
<li> Add new states, events, or parameters before starting up the system. Note that it is greatly preferred to use events instead of states because of timing precision.
<pre>
% Create new parameter (must be done before startup)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Add Parameter Application:TestParameterField string TestParameter= FirstNewParameter % % %', 0);

% Define events
% Define new event with 2 bytes of information (2 colors)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'add event Square 1 0', 0);
</pre>
</li>
<li>Add in the proper modules (Signal Generator, Signal Processor, and Application). Refer to the documentation [[Technical_Reference:BCI2000Remote_Library]] for more information on BCI2000 remote functions. Also refer to the example Matlab code under [[Programming_Reference:BCI2000Remote_Class#Matlab_Example]].</li>
<pre>
% Startup system localhost
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Startup system localhost', 0);

% Establish connection to three modules
SourceModule = 'SignalGenerator';
modules = libpointer('stringPtrPtr', {[SourceModule ' --local --LogKeyboard=1'], 'DummySignalProcessing', 'DummyApplication'});
calllib('bci', 'BCI2000Remote_StartupModules2', bciHandle, modules, 3);

% Wait for connected before loading parameters!
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Wait for Connected', 0);
</pre>
<li> Load parameter files, modify parameters directly, and add watches after BCI2000 is connected. It can also be helpful to wait for bci2000 to start running (collecting data) before proceeding.
<pre>
% Load parameter files
calllib('bci', 'BCI2000Remote_LoadParametersRemote', bciHandle, fullfile(BCI2000root,'parms','fragments','amplifiers','SignalGenerator.prm'));

% Set parameter values
calllib('bci', 'BCI2000Remote_SetDataDirectory', bciHandle, fullfile(BCI2000root,'data','BJH'));

%Set watches to appear automatically
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'visualize watch Square', 0);

% Wait for BCI2000 to start running before starting application
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Wait for Running', 0);
</pre>
</li>
<li> While BCI2000 is running you can also get and set event and state values, and also get parameter values. Note that you cannot modify parameter values while BCI2000 is running.
<pre>
% Get parameter value
SamplingRate = calllib('bci', 'BCI2000Remote_GetParameter', bciHandle, 'SamplingRate');
fprintf(['\nSamplingRate: ' num2str(SamplingRate) 'Hz\n'])

% Get event value
[~,~,~,Square]=calllib('bci', 'BCI2000Remote_GetEventVariable', bciHandle, 'Square', 0.0);

% BCI2000 set white rectangle to 1 (true)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Set event Square 1', 0);

% Get state value
% Immediately after data block has been acquired from hardware, the
% DataIOFilter writes a 16-bit millisecond-resolution time stamp into the
% SourceTime state. Block duration is measured as the difference between
% two consecutive time stamps.
[~,~,~,SourceTime]=calllib('bci', 'BCI2000Remote_GetStateVariable', bciHandle, 'SourceTime', 0.0);
fprintf(['\nSourceTime: ', num2str(SourceTime), '\n'])

% Stop running BCI2000
calllib('bci', 'BCI2000Remote_SetStateVariable', bciHandle, 'Running', 0);
</pre>
</li>
</ol>

==Video==
<youtube alignment="center">https://www.youtube.com/watch?v=ZwLcovHZabw</youtube>

Also see the [https://bci2000.org/mediawiki/index.php/PsychoPy PsychoPy] page for more details on the installation process, APIs, and hooks.

==See also==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Tutorial]]

User Tutorial:BCI2000Remote

2024-08-15T22:05:46Z

Swiftj: /* MatlabTutorial */

==Description==
BCI2000Remote is a proxy interface class to the BCI2000 Operator module, and allows to start up, configure, and control BCI2000 from other applications. Internally, it maintains a telnet connection to the Operator module, and sends Operator Scripting commands to control it. However, no knowledge of these scripting commands is required in order to use the BCI2000Remote class from your own application.

BCI2000Remote is most useful when writing applications in C++, or in another language for which bindings to the BCI2000RemoteLib library exist, such as Python, or MATLAB.
==Note==
BCI2000Remote is a means of interfacing with the BCI2000 Operator module meaning that there are potentially hundreds of ways we leverage this tool to have a meaningful interface with BCI2000. Because of this we will illustrate a few different integrations using different languages. This "How-to" will be separated into three separate sections: Python, C++, and Matlab.
==Python Tutorial==
<ol>
<li>Find your Python folder. If you have an existing Python environment with your code find it using the Sys Library like this:
<pre>
import sys

locate_python = sys.exec_prefix
print(locate_python)
</pre>
</li>
<li>
Locate your BCI2000Remote.py file which should have compiled into your prog folder.
Find where in your Python code you wish to integrate BCI2000. In this example I will show the minimum requirements for integration with BCI2000:
<pre>
import sys
sys.path.append('C:\\BCI2000.x64\\prog')
import BCI2000Remote
bci = BCI2000Remote.BCI2000Remote()
print('Operator path:', bci.OperatorPath)
bci.WindowVisible = True
bci.WindowTitle = 'Python controlled'
bci.SubjectID = 'pysub'
bci.Connect()
bci.Execute('cd ${BCI2000LAUNCHDIR}')
bci.Execute('ADD STATE score 16 0')
bci.StartupModules(('SignalGenerator', 'DummySignalprocessing', 'DummyApplication'))
bci.Execute('Wait for Connected')
bci.LoadParametersRemote('../parms/fragments/amplifiers/amplifier.prm')
bci.SetConfig()
</pre>
Here is how you import BCI2000Remote:
 
[[File:BCIRemote1.png]]
 
Here is how you instantiate the operator object:
 
[[File:BCIRemote 2.png]]
 
Here is how to customize the operator and connect to it:
 
[[File:BCI2000Remote2.png]]
 
Here is how you add your states:
 
[[File:BCIRemote_4.png]]
 
How to specify your signal source, signal processing, and application modules:
 
[[File:BCIRemote_5.png]]
 
How to load a parameter file(you can learn more about parameters [[Technical_Reference:Parameter_File|here]]):
 
[[File:BCIRemote_55.png]]
 
How to connect and issue commands to BCI2000:
 
[[File:BCIRemote_6.png]]
</li>
<li>
And finally, how to tell BCI2000 to set states to a value during runtime:
 
[[File:BCIRemote_6.png]]
 
Now that you've added those components to your code all you have to do is run your code. You should see the BCI2000 operator along with the system log, source watcher, and the timing window.
[[File:BCIRemote_7.png]]
 
</ol>

==C++ Tutorial==
<ol>
<li>
<li>
Open the C++ file or solution you would like to integrate with BCI2000 in Visual Studio, and find where it is located on your computer.
</li>
<li>
Navigate to the program's properties, and make the following changes:
<ul>
<li>
Under Configuration Properties -> C++ -> General, add the following folders from BCI2000 (64-bit)'s src folder: \core\Operator\BCI2000Remote, \shared\utils\Lib, \shared\config. 
</li>
<li>
Navigate to Configuration Properties -> Linker -> Input, and add ws2_32.lib to Additional Dependencies.
</li>
<li>
Under Configuration Properties -> C++ -> Advanced, add 4996 to the Disable Specific Warnings section.
</li>
</ul>
<li>
Add your Operator executable and the BCI2000RemoteLib dynamic library to the same directory as the program you intend to integrate. This can be found in the prog folder.
</li>
<li> Also, add the following files to the directory with your program and Operator.exe:

<ul>
<li>
BCI2000Connection.cpp
</li>
<li>
BCI2000Connection.h
</li>
<li>
BCI2000Remote.cpp
</li>
<li>
BCI2000Remote.h
</li>
<li>
BCI2000RemoteLib.cpp
</li>
<li>
BCI2000RemoteLib.h
</li>
<li>
SelfPipe.cpp
</li>
<li>
SelfPipe.h
</li>
<li>
sockstream.cpp
</li>
<li>
sockstream.h
</li>
</ul>

<li>
Make sure that you include all of your dependencies including BCI2000Remote.h
<pre>
#include "BCI2000Remote.h"
#include <string>
#include <vector>
#include <iostream>
</pre>
</li>
<li>
Next, instantiate the BCI2000Remote object
<pre>
int main( int argc, char* argv[] )
{
// Instantiate a BCI2000Remote object
BCI2000Remote bci;
// Assume that Operator executable resides in the same directory as this program.
std::string path = ( argc > 0 ) ? argv[0] : "";
size_t pos = path.find_last_of( "\\/" );
path = ( pos != std::string::npos ) ? path.substr( 0, pos + 1 ) : "";
// Start the Operator module, and connect
bci.OperatorPath( path + "Operator" );
if( !bci.Connect() )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
<li>
Specify your startup modules and any flags you wish to start them with
<pre>
// Startup modules
const char* modules[] = { "SignalGenerator --LogMouse=1", "ARSignalProcessing", "CursorTask" };
std::vector<std::string> vModules( &modules[0], &modules[0] + sizeof( modules ) / sizeof( *modules ) );
if( !bci.StartupModules( vModules ) )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
<li>
Load any parameter files and set subject information
<pre>
bci.LoadParametersRemote( "../parms/examples/CursorTask_SignalGenerator.prm" );
bci.SubjectID( "SUB" );
// Start a run
if( !bci.Start() )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
</li>
<li>
And here we just have BCI2000 send us back a feedback signal:
<pre>
std::string state;
while( bci.GetSystemState( state ) && state == "Running" )
{
double value = 0;
bci.GetControlSignal( 1, 1, value );
std::cout << "Control signal: " << value << ", press Enter to proceed" << std::flush;
std::string line;
std::getline( std::cin, line );
}
return 0;
}
</pre>
</li>
<li>
Now that you've added those components to your code all you have to do is compile and run it. You should see the BCI2000 operator along with the system log, source watcher, and the timing window.
Note: Be sure to compile this in your prog folder. This can be done by navigating again to Configuration Properties -> General, and changing the Output Directory to the path of the BCI2000 prog folder.
[[File:BCIRemote_7.jpg]]
</li>
</ol>
<pre>
#include "BCI2000Remote.h"
#include <string>
#include <vector>
#include <iostream>

int main( int argc, char* argv[] )
{
// Instantiate a BCI2000Remote object
BCI2000Remote bci;
// Assume that Operator executable resides in the same directory as this program.
std::string path = ( argc > 0 ) ? argv[0] : "";
size_t pos = path.find_last_of( "\\/" );
path = ( pos != std::string::npos ) ? path.substr( 0, pos + 1 ) : "";
// Start the Operator module, and connect
bci.OperatorPath( path + "Operator" );
if( !bci.Connect() )
{
std::cerr << bci.Result();
return -1;
}
// Startup modules
const char* modules[] = { "SignalGenerator --LogMouse=1", "ARSignalProcessing", "CursorTask" };
std::vector<std::string> vModules( &modules[0], &modules[0] + sizeof( modules ) / sizeof( *modules ) );
if( !bci.StartupModules( vModules ) )
{
std::cerr << bci.Result();
return -1;
}
// Load a parameter file, and set subject information
bci.LoadParametersRemote( "../parms/examples/CursorTask_SignalGenerator.prm" );
bci.SubjectID( "SUB" );
// Start a run
if( !bci.Start() )
{
std::cerr << bci.Result();
return -1;
}
// Print feedback signal
std::string state;
while( bci.GetSystemState( state ) && state == "Running" )
{
double value = 0;
bci.GetControlSignal( 1, 1, value );
std::cout << "Control signal: " << value << ", press Enter to proceed" << std::flush;
std::string line;
std::getline( std::cin, line );
}
return 0;
}
</pre>

==MatlabTutorial==
<ol>
<li>Open the Matlab file you would like to integrate with BCI2000.</li>
<li>Locate the BCI2000RemoteLib file in the BCI2000 prog folder, and BCI2000RemoteLib.h in src\core\Operator\BCI2000Remote, and load these into the Matlab file. Modify the file paths in loadlibrary(...) as needed.
Note that BCI2000RemoteLib's file name has a "64" appended when it was built in 64 bit mode, and a "32" if built iin 32 bit mode.
In this tutorial, we will be using the 64 bit version.
<pre>
%% c library load, initial part
BCI2000root = 'C:\bci2000.x64';
if not(libisloaded('bci'))
loadlibrary(fullfile(BCI2000root,'prog','BCI2000RemoteLib64'),...
fullfile(BCI2000root,'src','core','Operator','BCI2000Remote','BCI2000RemoteLib.h'), 'alias', 'bci')
end
libfunctions('bci')
</pre>
</li>
<li> Locate Operator.exe in the prog folder. Recover the memory, change the directory, and make the window visible in BCI2000. Again, modify the file path if it differs.
<pre>%need to call BCI2000Remote_Delete to recover the memory
bciHandle = calllib('bci', 'BCI2000Remote_New');
calllib('bci', 'BCI2000Remote_SetOperatorPath', bciHandle, fullfile(BCI2000root,'prog','Operator'));

% if we fail cto establish a connection to BCI2000Remote
if calllib('bci', 'BCI2000Remote_Connect', bciHandle) ~= 1
fprintf('bci connect fail!')
calllib('bci', 'BCI2000Remote_Delete', bciHandle); % call BCI2000Remote_Delete to recovery the memory
return
end

% Startup BCI2000
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Change directory $BCI2000LAUNCHDIR', 0);
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Show window; Set title ${Extract file base $0}', 0);
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Reset system', 0);
</pre>
</li>
<li> Add new states, events, or parameters before starting up the system. Note that it is greatly preferred to use events instead of states because of timing precision.
<pre>
% Create new parameter (must be done before startup)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Add Parameter Application:TestParameterField string TestParameter= FirstNewParameter % % %', 0);

% Define events
% Define new event with 2 bytes of information (2 colors)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'add event Square 1 0', 0);
</pre>
</li>
<li>Add in the proper modules (Signal Generator, Signal Processor, and Application). Refer to the documentation [[Technical_Reference:BCI2000Remote_Library]] for more information on BCI2000 remote functions. Also refer to the example Matlab code under [[Programming_Reference:BCI2000Remote_Class#Matlab_Example]].</li>
<pre>
% Startup system localhost
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Startup system localhost', 0);

% Establish connection to three modules
SourceModule = 'SignalGenerator';
modules = libpointer('stringPtrPtr', {[SourceModule ' --local --LogKeyboard=1'], 'DummySignalProcessing', 'DummyApplication'});
calllib('bci', 'BCI2000Remote_StartupModules2', bciHandle, modules, 3);

% Wait for connected before loading parameters!
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Wait for Connected', 0);
</pre>
<li> Load parameter files, modify parameters directly, and add watches after BCI2000 is connected. It can also be helpful to wait for bci2000 to start running (collecting data) before proceeding.
<pre>
% Load parameter files
calllib('bci', 'BCI2000Remote_LoadParametersRemote', bciHandle, fullfile(BCI2000root,'parms','fragments','amplifiers','SignalGenerator.prm'));

% Set parameter values
calllib('bci', 'BCI2000Remote_SetDataDirectory', bciHandle, fullfile(BCI2000root,'data','BJH'));

%Set watches to appear automatically
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'visualize watch Square', 0);

% Wait for BCI2000 to start running before starting application
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Wait for Running', 0);
</pre>
</li>
<li> While BCI2000 is running you can also get and set event and state values, and also get parameter values. Note that you cannot modify parameter values while BCI2000 is running.
<pre>
% Get parameter value
SamplingRate = calllib('bci', 'BCI2000Remote_GetParameter', bciHandle, 'SamplingRate');
fprintf(['\nSamplingRate: ' num2str(SamplingRate) 'Hz\n'])

% Get event value
[~,~,~,KeyDown]=calllib('bci', 'BCI2000Remote_GetEventVariable', bciHandle, 'KeyDown', passKeyDown);

% BCI2000 set white rectangle to 1 (true)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Set event Square 1', 0);

% Get state value
% Immediately after data block has been acquired from hardware, the
% DataIOFilter writes a 16-bit millisecond-resolution time stamp into the
% SourceTime state. Block duration is measured as the difference between
% two consecutive time stamps.
[~,~,~,SourceTime]=calllib('bci', 'BCI2000Remote_GetStateVariable', bciHandle, 'SourceTime', passSourceTime);
fprintf(['\nSourceTime: ', num2str(SourceTime), '\n'])

% Stop running BCI2000
calllib('bci', 'BCI2000Remote_SetStateVariable', bciHandle, 'Running', 0);
</pre>
</li>
</ol>

==Video==
<youtube alignment="center">https://www.youtube.com/watch?v=ZwLcovHZabw</youtube>

Also see the [https://bci2000.org/mediawiki/index.php/PsychoPy PsychoPy] page for more details on the installation process, APIs, and hooks.

==See also==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Tutorial]]

User Tutorial:BCI2000Remote

2024-08-15T21:58:55Z

Swiftj: /* MatlabTutorial */

==Description==
BCI2000Remote is a proxy interface class to the BCI2000 Operator module, and allows to start up, configure, and control BCI2000 from other applications. Internally, it maintains a telnet connection to the Operator module, and sends Operator Scripting commands to control it. However, no knowledge of these scripting commands is required in order to use the BCI2000Remote class from your own application.

BCI2000Remote is most useful when writing applications in C++, or in another language for which bindings to the BCI2000RemoteLib library exist, such as Python, or MATLAB.
==Note==
BCI2000Remote is a means of interfacing with the BCI2000 Operator module meaning that there are potentially hundreds of ways we leverage this tool to have a meaningful interface with BCI2000. Because of this we will illustrate a few different integrations using different languages. This "How-to" will be separated into three separate sections: Python, C++, and Matlab.
==Python Tutorial==
<ol>
<li>Find your Python folder. If you have an existing Python environment with your code find it using the Sys Library like this:
<pre>
import sys

locate_python = sys.exec_prefix
print(locate_python)
</pre>
</li>
<li>
Locate your BCI2000Remote.py file which should have compiled into your prog folder.
Find where in your Python code you wish to integrate BCI2000. In this example I will show the minimum requirements for integration with BCI2000:
<pre>
import sys
sys.path.append('C:\\BCI2000.x64\\prog')
import BCI2000Remote
bci = BCI2000Remote.BCI2000Remote()
print('Operator path:', bci.OperatorPath)
bci.WindowVisible = True
bci.WindowTitle = 'Python controlled'
bci.SubjectID = 'pysub'
bci.Connect()
bci.Execute('cd ${BCI2000LAUNCHDIR}')
bci.Execute('ADD STATE score 16 0')
bci.StartupModules(('SignalGenerator', 'DummySignalprocessing', 'DummyApplication'))
bci.Execute('Wait for Connected')
bci.LoadParametersRemote('../parms/fragments/amplifiers/amplifier.prm')
bci.SetConfig()
</pre>
Here is how you import BCI2000Remote:
 
[[File:BCIRemote1.png]]
 
Here is how you instantiate the operator object:
 
[[File:BCIRemote 2.png]]
 
Here is how to customize the operator and connect to it:
 
[[File:BCI2000Remote2.png]]
 
Here is how you add your states:
 
[[File:BCIRemote_4.png]]
 
How to specify your signal source, signal processing, and application modules:
 
[[File:BCIRemote_5.png]]
 
How to load a parameter file(you can learn more about parameters [[Technical_Reference:Parameter_File|here]]):
 
[[File:BCIRemote_55.png]]
 
How to connect and issue commands to BCI2000:
 
[[File:BCIRemote_6.png]]
</li>
<li>
And finally, how to tell BCI2000 to set states to a value during runtime:
 
[[File:BCIRemote_6.png]]
 
Now that you've added those components to your code all you have to do is run your code. You should see the BCI2000 operator along with the system log, source watcher, and the timing window.
[[File:BCIRemote_7.png]]
 
</ol>

==C++ Tutorial==
<ol>
<li>
<li>
Open the C++ file or solution you would like to integrate with BCI2000 in Visual Studio, and find where it is located on your computer.
</li>
<li>
Navigate to the program's properties, and make the following changes:
<ul>
<li>
Under Configuration Properties -> C++ -> General, add the following folders from BCI2000 (64-bit)'s src folder: \core\Operator\BCI2000Remote, \shared\utils\Lib, \shared\config. 
</li>
<li>
Navigate to Configuration Properties -> Linker -> Input, and add ws2_32.lib to Additional Dependencies.
</li>
<li>
Under Configuration Properties -> C++ -> Advanced, add 4996 to the Disable Specific Warnings section.
</li>
</ul>
<li>
Add your Operator executable and the BCI2000RemoteLib dynamic library to the same directory as the program you intend to integrate. This can be found in the prog folder.
</li>
<li> Also, add the following files to the directory with your program and Operator.exe:

<ul>
<li>
BCI2000Connection.cpp
</li>
<li>
BCI2000Connection.h
</li>
<li>
BCI2000Remote.cpp
</li>
<li>
BCI2000Remote.h
</li>
<li>
BCI2000RemoteLib.cpp
</li>
<li>
BCI2000RemoteLib.h
</li>
<li>
SelfPipe.cpp
</li>
<li>
SelfPipe.h
</li>
<li>
sockstream.cpp
</li>
<li>
sockstream.h
</li>
</ul>

<li>
Make sure that you include all of your dependencies including BCI2000Remote.h
<pre>
#include "BCI2000Remote.h"
#include <string>
#include <vector>
#include <iostream>
</pre>
</li>
<li>
Next, instantiate the BCI2000Remote object
<pre>
int main( int argc, char* argv[] )
{
// Instantiate a BCI2000Remote object
BCI2000Remote bci;
// Assume that Operator executable resides in the same directory as this program.
std::string path = ( argc > 0 ) ? argv[0] : "";
size_t pos = path.find_last_of( "\\/" );
path = ( pos != std::string::npos ) ? path.substr( 0, pos + 1 ) : "";
// Start the Operator module, and connect
bci.OperatorPath( path + "Operator" );
if( !bci.Connect() )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
<li>
Specify your startup modules and any flags you wish to start them with
<pre>
// Startup modules
const char* modules[] = { "SignalGenerator --LogMouse=1", "ARSignalProcessing", "CursorTask" };
std::vector<std::string> vModules( &modules[0], &modules[0] + sizeof( modules ) / sizeof( *modules ) );
if( !bci.StartupModules( vModules ) )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
<li>
Load any parameter files and set subject information
<pre>
bci.LoadParametersRemote( "../parms/examples/CursorTask_SignalGenerator.prm" );
bci.SubjectID( "SUB" );
// Start a run
if( !bci.Start() )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
</li>
<li>
And here we just have BCI2000 send us back a feedback signal:
<pre>
std::string state;
while( bci.GetSystemState( state ) && state == "Running" )
{
double value = 0;
bci.GetControlSignal( 1, 1, value );
std::cout << "Control signal: " << value << ", press Enter to proceed" << std::flush;
std::string line;
std::getline( std::cin, line );
}
return 0;
}
</pre>
</li>
<li>
Now that you've added those components to your code all you have to do is compile and run it. You should see the BCI2000 operator along with the system log, source watcher, and the timing window.
Note: Be sure to compile this in your prog folder. This can be done by navigating again to Configuration Properties -> General, and changing the Output Directory to the path of the BCI2000 prog folder.
[[File:BCIRemote_7.jpg]]
</li>
</ol>
<pre>
#include "BCI2000Remote.h"
#include <string>
#include <vector>
#include <iostream>

int main( int argc, char* argv[] )
{
// Instantiate a BCI2000Remote object
BCI2000Remote bci;
// Assume that Operator executable resides in the same directory as this program.
std::string path = ( argc > 0 ) ? argv[0] : "";
size_t pos = path.find_last_of( "\\/" );
path = ( pos != std::string::npos ) ? path.substr( 0, pos + 1 ) : "";
// Start the Operator module, and connect
bci.OperatorPath( path + "Operator" );
if( !bci.Connect() )
{
std::cerr << bci.Result();
return -1;
}
// Startup modules
const char* modules[] = { "SignalGenerator --LogMouse=1", "ARSignalProcessing", "CursorTask" };
std::vector<std::string> vModules( &modules[0], &modules[0] + sizeof( modules ) / sizeof( *modules ) );
if( !bci.StartupModules( vModules ) )
{
std::cerr << bci.Result();
return -1;
}
// Load a parameter file, and set subject information
bci.LoadParametersRemote( "../parms/examples/CursorTask_SignalGenerator.prm" );
bci.SubjectID( "SUB" );
// Start a run
if( !bci.Start() )
{
std::cerr << bci.Result();
return -1;
}
// Print feedback signal
std::string state;
while( bci.GetSystemState( state ) && state == "Running" )
{
double value = 0;
bci.GetControlSignal( 1, 1, value );
std::cout << "Control signal: " << value << ", press Enter to proceed" << std::flush;
std::string line;
std::getline( std::cin, line );
}
return 0;
}
</pre>

==MatlabTutorial==
<ol>
<li>Open the Matlab file you would like to integrate with BCI2000.</li>
<li>Locate the BCI2000RemoteLib file in the BCI2000 prog folder, and BCI2000RemoteLib.h in src\core\Operator\BCI2000Remote, and load these into the Matlab file. Modify the file paths in loadlibrary(...) as needed.
Note that BCI2000RemoteLib's file name has a "64" appended when it was built in 64 bit mode, and a "32" if built iin 32 bit mode.
In this tutorial, we will be using the 64 bit version.
<pre>
%% c library load, initial part
BCI2000root = 'C:\bci2000.x64';
if not(libisloaded('bci'))
loadlibrary(fullfile(BCI2000root,'prog','BCI2000RemoteLib64'),...
fullfile(BCI2000root,'src','core','Operator','BCI2000Remote','BCI2000RemoteLib.h'), 'alias', 'bci')
end
libfunctions('bci')
</pre>
</li>
<li> Locate Operator.exe in the prog folder. Recover the memory, change the directory, and make the window visible in BCI2000. Again, modify the file path if it differs.
<pre>%need to call BCI2000Remote_Delete to recover the memory
bciHandle = calllib('bci', 'BCI2000Remote_New');
calllib('bci', 'BCI2000Remote_SetOperatorPath', bciHandle, fullfile(BCI2000root,'prog','Operator'));

% if we fail cto establish a connection to BCI2000Remote
if calllib('bci', 'BCI2000Remote_Connect', bciHandle) ~= 1
fprintf('bci connect fail!')
calllib('bci', 'BCI2000Remote_Delete', bciHandle); % call BCI2000Remote_Delete to recovery the memory
return
end

% Startup BCI2000
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Change directory $BCI2000LAUNCHDIR', 0);
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Show window; Set title ${Extract file base $0}', 0);
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Reset system', 0);
</pre>
</li>
<li> Add new states, events, or parameters before starting up the system. Note that it is greatly preferred to use events instead of states because of timing precision.
<pre>
% Create new parameter (must be done before startup)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Add Parameter Application:TestParameterField string TestParameter= FirstNewParameter % % %', 0);

% Define events
% Define new event with 2 bytes of information (2 colors)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'add event Square 1 0', 0);
</pre>
</li>
<li>Add in the proper modules (Signal Generator, Signal Processor, and Application). Refer to the documentation [[Technical_Reference:BCI2000Remote_Library]] for more information on BCI2000 remote functions. Also refer to the example Matlab code under [[Programming_Reference:BCI2000Remote_Class#Matlab_Example]].</li>
<pre>
% Startup system localhost
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Startup system localhost', 0);

% Establish connection to three modules
SourceModule = 'SignalGenerator';
modules = libpointer('stringPtrPtr', {[SourceModule ' --local --LogKeyboard=1'], 'DummySignalProcessing', 'DummyApplication'});
calllib('bci', 'BCI2000Remote_StartupModules2', bciHandle, modules, 3);

% Wait for connected before loading parameters!
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Wait for Connected', 0);
</pre>
<li> Load parameter files, modify parameters directly, and add watches after BCI2000 is connected. It can also be helpful to wait for bci2000 to start running (collecting data) before proceeding.
<pre>
% Load parameter files
calllib('bci', 'BCI2000Remote_LoadParametersRemote', bciHandle, fullfile(BCI2000root,'parms','fragments','amplifiers','SignalGenerator.prm'));

% Set parameter values
calllib('bci', 'BCI2000Remote_SetDataDirectory', bciHandle, fullfile(BCI2000root,'data','BJH'));

%Set watches to appear automatically
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'visualize watch Square', 0);

% Wait for BCI2000 to start running before starting application
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Wait for Running', 0);
</pre>
</li>
<li> While BCI2000 is running you can also get and set event and state values, and also get parameter values. Note that you cannot modify parameter values while BCI2000 is running.
<pre>
% Get parameter value
SamplingRate = calllib('bci', 'BCI2000Remote_GetParameter', bciHandle, 'SamplingRate');
fprintf(['\nSamplingRate: ' num2str(SamplingRate) 'Hz\n'])

% Get event value

% BCI2000 set white rectangle to 1 (true)
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Set event Square 1', 0);

% Get state value
% Immediately after data block has been acquired from hardware, the
% DataIOFilter writes a 16-bit millisecond-resolution time stamp into the
% SourceTime state. Block duration is measured as the difference between
% two consecutive time stamps.
[~,~,~,SourceTime]=calllib('bci', 'BCI2000Remote_GetStateVariable', bciHandle, 'SourceTime', passSourceTime);
fprintf(['\nSourceTime: ', num2str(SourceTime), '\n'])

% Stop running BCI2000
calllib('bci', 'BCI2000Remote_SetStateVariable', bciHandle, 'Running', 0);
</pre>
</li>
</ol>

==Video==
<youtube alignment="center">https://www.youtube.com/watch?v=ZwLcovHZabw</youtube>

Also see the [https://bci2000.org/mediawiki/index.php/PsychoPy PsychoPy] page for more details on the installation process, APIs, and hooks.

==See also==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Tutorial]]

User Tutorial:BCI2000Remote

2024-08-15T21:44:46Z

Swiftj: /* MatlabTutorial */

==Description==
BCI2000Remote is a proxy interface class to the BCI2000 Operator module, and allows to start up, configure, and control BCI2000 from other applications. Internally, it maintains a telnet connection to the Operator module, and sends Operator Scripting commands to control it. However, no knowledge of these scripting commands is required in order to use the BCI2000Remote class from your own application.

BCI2000Remote is most useful when writing applications in C++, or in another language for which bindings to the BCI2000RemoteLib library exist, such as Python, or MATLAB.
==Note==
BCI2000Remote is a means of interfacing with the BCI2000 Operator module meaning that there are potentially hundreds of ways we leverage this tool to have a meaningful interface with BCI2000. Because of this we will illustrate a few different integrations using different languages. This "How-to" will be separated into three separate sections: Python, C++, and Matlab.
==Python Tutorial==
<ol>
<li>Find your Python folder. If you have an existing Python environment with your code find it using the Sys Library like this:
<pre>
import sys

locate_python = sys.exec_prefix
print(locate_python)
</pre>
</li>
<li>
Locate your BCI2000Remote.py file which should have compiled into your prog folder.
Find where in your Python code you wish to integrate BCI2000. In this example I will show the minimum requirements for integration with BCI2000:
<pre>
import sys
sys.path.append('C:\\BCI2000.x64\\prog')
import BCI2000Remote
bci = BCI2000Remote.BCI2000Remote()
print('Operator path:', bci.OperatorPath)
bci.WindowVisible = True
bci.WindowTitle = 'Python controlled'
bci.SubjectID = 'pysub'
bci.Connect()
bci.Execute('cd ${BCI2000LAUNCHDIR}')
bci.Execute('ADD STATE score 16 0')
bci.StartupModules(('SignalGenerator', 'DummySignalprocessing', 'DummyApplication'))
bci.Execute('Wait for Connected')
bci.LoadParametersRemote('../parms/fragments/amplifiers/amplifier.prm')
bci.SetConfig()
</pre>
Here is how you import BCI2000Remote:
 
[[File:BCIRemote1.png]]
 
Here is how you instantiate the operator object:
 
[[File:BCIRemote 2.png]]
 
Here is how to customize the operator and connect to it:
 
[[File:BCI2000Remote2.png]]
 
Here is how you add your states:
 
[[File:BCIRemote_4.png]]
 
How to specify your signal source, signal processing, and application modules:
 
[[File:BCIRemote_5.png]]
 
How to load a parameter file(you can learn more about parameters [[Technical_Reference:Parameter_File|here]]):
 
[[File:BCIRemote_55.png]]
 
How to connect and issue commands to BCI2000:
 
[[File:BCIRemote_6.png]]
</li>
<li>
And finally, how to tell BCI2000 to set states to a value during runtime:
 
[[File:BCIRemote_6.png]]
 
Now that you've added those components to your code all you have to do is run your code. You should see the BCI2000 operator along with the system log, source watcher, and the timing window.
[[File:BCIRemote_7.png]]
 
</ol>

==C++ Tutorial==
<ol>
<li>
<li>
Open the C++ file or solution you would like to integrate with BCI2000 in Visual Studio, and find where it is located on your computer.
</li>
<li>
Navigate to the program's properties, and make the following changes:
<ul>
<li>
Under Configuration Properties -> C++ -> General, add the following folders from BCI2000 (64-bit)'s src folder: \core\Operator\BCI2000Remote, \shared\utils\Lib, \shared\config. 
</li>
<li>
Navigate to Configuration Properties -> Linker -> Input, and add ws2_32.lib to Additional Dependencies.
</li>
<li>
Under Configuration Properties -> C++ -> Advanced, add 4996 to the Disable Specific Warnings section.
</li>
</ul>
<li>
Add your Operator executable and the BCI2000RemoteLib dynamic library to the same directory as the program you intend to integrate. This can be found in the prog folder.
</li>
<li> Also, add the following files to the directory with your program and Operator.exe:

<ul>
<li>
BCI2000Connection.cpp
</li>
<li>
BCI2000Connection.h
</li>
<li>
BCI2000Remote.cpp
</li>
<li>
BCI2000Remote.h
</li>
<li>
BCI2000RemoteLib.cpp
</li>
<li>
BCI2000RemoteLib.h
</li>
<li>
SelfPipe.cpp
</li>
<li>
SelfPipe.h
</li>
<li>
sockstream.cpp
</li>
<li>
sockstream.h
</li>
</ul>

<li>
Make sure that you include all of your dependencies including BCI2000Remote.h
<pre>
#include "BCI2000Remote.h"
#include <string>
#include <vector>
#include <iostream>
</pre>
</li>
<li>
Next, instantiate the BCI2000Remote object
<pre>
int main( int argc, char* argv[] )
{
// Instantiate a BCI2000Remote object
BCI2000Remote bci;
// Assume that Operator executable resides in the same directory as this program.
std::string path = ( argc > 0 ) ? argv[0] : "";
size_t pos = path.find_last_of( "\\/" );
path = ( pos != std::string::npos ) ? path.substr( 0, pos + 1 ) : "";
// Start the Operator module, and connect
bci.OperatorPath( path + "Operator" );
if( !bci.Connect() )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
<li>
Specify your startup modules and any flags you wish to start them with
<pre>
// Startup modules
const char* modules[] = { "SignalGenerator --LogMouse=1", "ARSignalProcessing", "CursorTask" };
std::vector<std::string> vModules( &modules[0], &modules[0] + sizeof( modules ) / sizeof( *modules ) );
if( !bci.StartupModules( vModules ) )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
<li>
Load any parameter files and set subject information
<pre>
bci.LoadParametersRemote( "../parms/examples/CursorTask_SignalGenerator.prm" );
bci.SubjectID( "SUB" );
// Start a run
if( !bci.Start() )
{
std::cerr << bci.Result();
return -1;
}
</pre>
</li>
</li>
<li>
And here we just have BCI2000 send us back a feedback signal:
<pre>
std::string state;
while( bci.GetSystemState( state ) && state == "Running" )
{
double value = 0;
bci.GetControlSignal( 1, 1, value );
std::cout << "Control signal: " << value << ", press Enter to proceed" << std::flush;
std::string line;
std::getline( std::cin, line );
}
return 0;
}
</pre>
</li>
<li>
Now that you've added those components to your code all you have to do is compile and run it. You should see the BCI2000 operator along with the system log, source watcher, and the timing window.
Note: Be sure to compile this in your prog folder. This can be done by navigating again to Configuration Properties -> General, and changing the Output Directory to the path of the BCI2000 prog folder.
[[File:BCIRemote_7.jpg]]
</li>
</ol>
<pre>
#include "BCI2000Remote.h"
#include <string>
#include <vector>
#include <iostream>

int main( int argc, char* argv[] )
{
// Instantiate a BCI2000Remote object
BCI2000Remote bci;
// Assume that Operator executable resides in the same directory as this program.
std::string path = ( argc > 0 ) ? argv[0] : "";
size_t pos = path.find_last_of( "\\/" );
path = ( pos != std::string::npos ) ? path.substr( 0, pos + 1 ) : "";
// Start the Operator module, and connect
bci.OperatorPath( path + "Operator" );
if( !bci.Connect() )
{
std::cerr << bci.Result();
return -1;
}
// Startup modules
const char* modules[] = { "SignalGenerator --LogMouse=1", "ARSignalProcessing", "CursorTask" };
std::vector<std::string> vModules( &modules[0], &modules[0] + sizeof( modules ) / sizeof( *modules ) );
if( !bci.StartupModules( vModules ) )
{
std::cerr << bci.Result();
return -1;
}
// Load a parameter file, and set subject information
bci.LoadParametersRemote( "../parms/examples/CursorTask_SignalGenerator.prm" );
bci.SubjectID( "SUB" );
// Start a run
if( !bci.Start() )
{
std::cerr << bci.Result();
return -1;
}
// Print feedback signal
std::string state;
while( bci.GetSystemState( state ) && state == "Running" )
{
double value = 0;
bci.GetControlSignal( 1, 1, value );
std::cout << "Control signal: " << value << ", press Enter to proceed" << std::flush;
std::string line;
std::getline( std::cin, line );
}
return 0;
}
</pre>

==MatlabTutorial==
<ol>
<li>Open the Matlab file you would like to integrate with BCI2000.</li>
<li>Locate the BCI2000RemoteLib file in the BCI2000 prog folder, and BCI2000RemoteLib.h in src\core\Operator\BCI2000Remote, and load these into the Matlab file. Modify the file paths in loadlibrary(...) as needed.
Note that BCI2000RemoteLib's file name has a "64" appended when it was built in 64 bit mode, and a "32" if built iin 32 bit mode.
In this tutorial, we will be using the 64 bit version.
<pre>
%% c library load, initial part
BCI2000root = 'C:\bci2000.x64';
if not(libisloaded('bci'))
loadlibrary(fullfile(BCI2000root,'prog','BCI2000RemoteLib64'),...
fullfile(BCI2000root,'src','core','Operator','BCI2000Remote','BCI2000RemoteLib.h'), 'alias', 'bci')
end
libfunctions('bci')
</pre>
</li>
<li> Locate Operator.exe in the prog folder. Recover the memory, change the directory, and make the window visible in BCI2000. Again, modify the file path if it differs.
<pre>%need to call BCI2000Remote_Delete to recover the memory
bciHandle = calllib('bci', 'BCI2000Remote_New');
calllib('bci', 'BCI2000Remote_SetOperatorPath', bciHandle, fullfile(BCI2000root,'prog','Operator'));

% if we fail cto establish a connection to BCI2000Remote
if calllib('bci', 'BCI2000Remote_Connect', bciHandle) ~= 1
fprintf('bci connect fail!')
calllib('bci', 'BCI2000Remote_Delete', bciHandle); % call BCI2000Remote_Delete to recovery the memory
return
end

% Startup BCI2000
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Change directory $BCI2000LAUNCHDIR', 0);
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Show window; Set title ${Extract file base $0}', 0);
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Reset system', 0);
</pre>
</li>
<li>Add in the proper modules (Signal Generator, Signal Processor, and Application). Also, load in BCI2000 parameters, add/set state variables, and include any desired functionality. Refer to the documentation [[Technical_Reference:BCI2000Remote_Library]] for more information on BCI2000 remote functions. Also refer to the example Matlab code under [[Programming_Reference:BCI2000Remote_Class#Matlab_Example]].</li>
<pre>
% Startup system localhost
calllib('bci', 'BCI2000Remote_Execute', bciHandle,'Startup system localhost', 0);

% Establish connection to three modules
SourceModule = 'SignalGenerator';
modules = libpointer('stringPtrPtr', {[SourceModule ' --local --LogKeyboard=1'], 'DummySignalProcessing', 'DummyApplication'});
calllib('bci', 'BCI2000Remote_StartupModules2', bciHandle, modules, 3);

% Wait for connected before loading parameters!
calllib('bci', 'BCI2000Remote_Execute', bciHandle, 'Wait for Connected', 0);
</pre>
</ol>

==Video==
<youtube alignment="center">https://www.youtube.com/watch?v=ZwLcovHZabw</youtube>

Also see the [https://bci2000.org/mediawiki/index.php/PsychoPy PsychoPy] page for more details on the installation process, APIs, and hooks.

==See also==
* [[Programming Reference:BCI2000Remote Class]]
* [[User Reference:Operator Module Scripting]]

[[Category:Tutorial]]

Contributions:NatusADC

2024-05-10T17:31:35Z

Swiftj: /* On the BCI2000 Computer */

== Function ==
The NatusADC filter acquires raw data in real-time from Natus Headboxes over UDP connection for signal processing and visualizations. The overview of the NatusADC working is shown in the image below.
[[File:Prog_Ref_NatusADC_NatusWorking.png|center|800px|Overview of NatusADC working]]

NatusDataServer processes and sends signal from the device to the client application. A project named XLDataExportClient reads signals from the device and calls the NatusDataServer's functions to send the signal to the client. NatusClient is the client application within the BCI2000 that receives the signals and does the initial processing. NatusPackageInterface contains the implementation of data transfer protocol between server/device and client and is used by NatusClient and NatusDataServer to communicate with each other over TCP and UDP. NatusDataServer and NatusPackageInterface are independent of BCI2000, whereas NatusClient relies on BCI2000.

The below image explains the context in which packet, blocks, samples and channels are used in this project. A packet may have one or block, a block may have one or more samples and a sample contains values for all the channels.
[[File:NatusPacketImage.png|center|600px|Packet, block and samples relationship]]

===Version History===

===Source Code Revisions===
*Initial development: 5900
*Tested under: 7381
*Known to compile under:7381
*Broken since: --
*Natus software version: 9.2.1 Build 6524
*Natus Data Export Version: 9.4

== Prerequisites ==
* The NatusADC source module requires a proprietary SDK protected by an NDA with Natus. Please contact Natus for this NDA and for access to the XLDataExportClient SDK before attempting to use the NatusADC source module.
* It is also helpful to have an ethernet port available for the Natus computer. If your system does not have an ethernet port, consider using a USB ethernet dongle.

=== Hardware ===
In theory, the module should work fine with all of the following Natus Headboxes.
# EEG32
# EEG128, EEG128FS
# Mobee32, Mobee32-02
# Mobee-24
# Connex/ Brain Monitor
# Trex
# EMU40
# EEG32u
# Quantum
# NeuroLink IP
# Bio-logic NetLink
# Bio-logic Traveler

==== Drivers ====

== Connecting Natus to BCI2000 ==
The figure below should serve as a supplement to the instructions for connecting the Natus computer to the BCI2000 computer
[[File:NW_SDK_for_BCI2000.png|center|1000px|Neuroworks SDK for BCI2000]]

=== On the Natus Computer ===
# Connect the BCI2000 computer to the Natus computer via ethernet (this may require a usb-to-ethernet adapter)
# Change the IP address of this port on the Natus computer to something on its own subnet, like 192.168.10.10. You can follow a tutorial like [https://nordvpn.com/blog/how-to-change-your-ip-address/ this one] to change the IP address. The easiest way to confirm that you are changing the IP address of the correct port is to unplug the ethernet cable. The unplugged option will disappear.
# When starting a new study, set the sampling rate of the acquisition system by opening "Wave" and going to edit -> settings -> acquisition while a study is NOT running
#* Be sure that the Natus computer is set to acquire data over Ethernet and not USB if you intend to acquire data over 4kHz [[File:Natus1_StudySettings.jpg|center|600px|Set Natus Sampling Rate]]
# Start an EEG study in Neuroworks using the New EEG button. [[File:Natus2_StartStudy.jpg|center|1000px|Start a new Natus study]] You will need to enter the study information. [[File:Natus3_StudyInformation.jpg|center|600px|Enter the study information]] Note that you do not need to start the recording for the signal to stream to BCI2000. [[File:Natus4_StudyRunning.jpg|center|1000px|Study is running]]

=== On the BCI2000 Computer ===
# Compile the NatusSignalSource source module after you have gotten access to the Natus data export service on the BCI2000 svn
# Change the IP address of the BCI2000 computer ethernet port to something on the same subnet, like 192.168.10.9, following the same steps as above.
# Open the command line on the BCI2000 computer and type "ping 192.168.10.10" to ensure you have a connection.
#* Note that if this does not work you may need to turn off firewalls on one or both machines
# Locate the included registry editing tool found in bci2000/src/private/SignalSource/NatusSignalSource/
# Edit the _SetSdkAcquisitionStationIp.reg registry editing tool (right-click, edit) to add the IP of the Natus computer to the BCI2000 computer's registry (i.e., 192.168.10.10)
# Run RegXLDataExportService.bat found in bci2000/src/private/SignalSource/NatusSignalSource/DataExport_9.4/XLDataExportService to register the DLL of the data export service. (This may not be necessary with the newest version?)
# Start the data export service executable XLDataExportSrv.exe found in bci2000/src/private/SignalSource/NatusSignalSource/DataExport_9.4/XLDataExportService
#* Note that this can be started before an EEG study has been started, or after an EEG study is already running
#* A small horizontal window should appear, indicating study data is streaming
# Create a BCI2000 batch file to start up the NatusSignalSource source module (An example batch file should be in the same NatusSignalSource folder after BCI2000 has been compiled)
# Launch BCI2000 using this batch file
# Open the config window and navigate to the source tab. Source parameters will vary according to your needs, but some recommended settings can be found below
#* SampleBlockSize: 100 (at a sampling rate of 2048, this yields a sample block size of 48.83ms. Note that the ratio of SampleBlockSize/ServerBlockSize needs to be a whole number for best performance. SampleBlockSize less than 48.83ms is not recommended.)
#* SamplingRate: auto (inherited from the Natus system)
#* ServerBlockSize: 1 (server buffer size. Larger ServerBlockSize can lead to performance issues.)
#* DecimationFactor: 1 (you can decimate the incoming sampled data by the DecimationFactor. The BCI2000 sampling rate will reflect the decimated rate.)
#* ServerIP: Set the IP address to localhost or 127.0.0.1
# Press “Set Config.” Data should begin streaming. Open the System Log from the BCI2000 Operator window to confirm that the sampling rate and channel count were inherited correctly from the Natus stream

== Legacy Instructions for Connecting Natus to BCI2000 ==
=== On the Natus Computer ===
# If you have previously registered the XLDataExportClient.dll for an older version of the data export tool, you must first deregister this dll. Launch a command window as an administrator and type regsvr /u XLDataExportClient.dll
# Connect to the network via ethernet cable. Alternately, it is preferable to connect directly to the BCI2000 computer via ethernet.
# Copy the Export Service folder found in src\private\SignalSource\NatusSignalSource\DataExport_9.4\XLDataExportService to the hard drive of the computer running Natus Neuroworks or to a USB drive
# Note the IP address of the Natus computer (run “ipconfig” in the Command Prompt on the Natus computer). If the computers are directly connected with an ethernet cable, the IP address should be under "ethernet adapter ethernet" [[File:Natus7_IPaddress.jpg|center|600px|Run ipconfig on the Natus computer and note the IP address]]
# When starting a new study, set the sampling rate of the acquisition system by opening "Wave" and going to edit -> settings -> acquisition while a study is NOT running
#* Be sure that the Natus computer is set to acquire data over Ethernet and not USB if you intend to acquire data over 4kHz [[File:Natus1_StudySettings.jpg|center|600px|Set Natus Sampling Rate]]
# Start an EEG study in Neuroworks using the New EEG button. [[File:Natus2_StartStudy.jpg|center|1000px|Start a new Natus study]] You will need to enter the study information. [[File:Natus3_StudyInformation.jpg|center|600px|Enter the study information]] Note that you do not need to start the recording for the signal to stream to BCI2000. [[File:Natus4_StudyRunning.jpg|center|1000px|Study is running]]
# Run the executable XLDataExportSrv.exe found in the XLDataExportService folder that was copied to the Natus computer [[File:Natus5_DataExportServiceFolder.jpg|center|600px|Run the executable XLDataExportSrv.exe from the XLDataExportService folder]]
#* Note that this can be started before an EEG study has been started, or after an EEG study is already running
#* A small horizontal window should appear, indicating study data is streaming [[File:Natus6_DataExportServiceRunning.jpg|center|1000px|Natus Data Export Service Running]]

=== On the BCI2000 Computer ===
# Connect to the same network that the Natus computer is connected via ethernet cable. Alternately, it is preferable to connect directly to the Natus computer via ethernet.
# Run a BCI2000 batch file that loads the NatusSignalSource
# Open the config window and navigate to the source tab. Source parameters will vary according to your needs, but some recommended settings can be found below
#* SampleBlockSize: 100 (at a sampling rate of 2048, this yields a sample block size of 48.83ms. Note that the ratio of SampleBlockSize/ServerBlockSize needs to be a whole number for best performance. SampleBlockSize less than 48.83ms is not recommended.)
#* SamplingRate: auto (inherited from the Natus system)
#* ServerBlockSize: 1 (server buffer size. Larger ServerBlockSize can lead to performance issues.)
#* DecimationFactor: 1 (you can decimate the incoming sampled data by the DecimationFactor. The BCI2000 sampling rate will reflect the decimated rate.)
#* ServerIP: Set the IP address to that of the Natus computer [[File:Natus8_BCI2000Parameters.jpg|center|600px|Natus BCI2000 parameters]]
# Press “Set Config.” Data should begin streaming. Open the System Log from the BCI2000 Operator window to confirm that the sampling rate and channel count were inherited correctly from the Natus stream

== Parameters ==
Parameters common to all source modules are described under [[User Reference:DataIOFilter]]. In addition, the following parameters are supported:

=== SamplingRate ===
The rate at which the device samples the data. The default value is the device's default sampling rate.

=== SampleBlockSize ===
The number of samples per block the output signal, created by the client application(NatusADC), should have. The default value is 20. Note that the ratio of SampleBlockSize/ServerBlockSize needs to be a whole number for best performance. SampleBlockSize less than 48.83ms is not recommended.

=== ServerBlockSize ===
The number of samples sent by the server/device in a single UDP Packet. The default value is 1.

=== DecimationFactor ===
The decimation factor. The factor by which to decimate/downsize the signal. The default value is 1. ''The SamplingRate is updated by dividing it by the DecimationFactor.''
'''Note:''' The SamplingRate should be an integral multiple of DecimationFactor.

=== ServerIP ===
The IPv4 address of the server/device.

=== Port ===
The port number of the server/device which on which TCP runs. UDP port number is assumed to be 1 + TCP port number.

=== SourceCh ===
The number of channels to be acquired from the device. If this is set to auto, all the available channels from the device will be acquired.

=== SourceChGain ===
SourceChGain should be left to auto. The default value is 0 for every channel.

=== SourceChOffset ===
SourceChOffset should be left to auto. The default value is 1 microVolt for every channel.

=== SourceChList ===
The list of channel numbers to be acquired from the device. The order of the numbers doesn't matter, i.e., '1 2 3 4' is same as '3 2 4 1'. Entering duplicate channels, eg. in '1 2 3 2' will result in an error. Entering an invalid channel number, i.e., a number greater than the maximum number of the channels will result in an error. If set to auto, all the device channels will be streamed.

=== ChannelNames ===
The user-preferred channel names. If set to auto, the channel names will be retrieved from the device. If the device doesn't have any specific channel names, the channel names will be set to 0 to SourceCh - 1. If set manually, names should be given for each channel in SourceChList

== States ==

=== Interpolated ===
Interpolated is represented by 1 bit. The device sends data in packets over UDP connection which is not a reliable connection and hence may result in loss of some packets. The lost packets between two packets received from the device are linearly interpolated from the aforementioned two packets. The Interpolated state value is 1 if the packet is interpolated or 0 if the packet is received from the device.

== Additional Info ==
The module also contains a function called GetDecimationFactor to query the current Decimation Factor from the server/device. 
More details from a programmer's perspective can be found here [[Programming_Reference:NatusADC]]

== Troubleshooting ==
If there is a problem streaming the data, try force quitting the Natus export service by opening the task manager on the Natus computer, then right clicking on the XLDataExportSrv and choosing 'end task.' Then start the data export service again.

== See also ==
[[User Reference:DataIOFilter]], [[Programming Reference:GenericADC Class]]
[[Category:Filters]][[Category:Data Acquisition]]