BCI2000 Wiki - User contributions [en]

Contributions:CommunicationTask

2025-10-10T16:20:59Z

Lingling: /* States */

==Synopsis==
The hyperscanning task is a turn-based communication game between two clients. This game aims to guess what the subject is in Sender's computer without talking. For each trial, the two players will alternate between the roles of Sender and Receiver. The Sender will describe traits of the subject presented by adjusting the two axes(Noisy or silent/Big or small). Then, the Receiver will guess if the Sender is describing the animal or object. After the Receiver makes a guess, both players receive feedback on whether the Receiver makes the correct guess. This marks the end of a trial.

The two clients exchange information through the hyperScanning backend, which uses a client-server model to share the states. Each client has a separate state machine. The server only forwards the information between two clients. Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class, which is the parent class of the application module. For more information, please refer to the hyperScanning framework wiki page: https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning.

==Video Overview==
 
<youtube alignment="center">https://youtu.be/I1sSamSsTK4</youtube>
 

==Timeline==
<gallery mode="packed" widths=600px heights=500px>
File:Hyperscanning pipe line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=750px heights=421px>
File:Hyperscanning_1.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Anais Llorens (anaisllorens@hotmail.com) and Athina Tzovara (athina.tzovara@unibe.ch) conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org), Max Marcus (bigmaxmarcus@gmail.com) and Sigurd Alnes (sigurd.alnes@unibe.ch) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
To run the server, you’ll need a Linux or macOS machine—Windows is not supported at this time. The steps below walk you through deploying the server on AWS. 
1. Prepare the AWS key. 

2. In your terminal or shell, run 
<pre> chmod 400 <key_path> </pre>
to make the key file read-only for the owner. 

3. Connect to the AWS server using SSH: 
<pre> ssh -i <key path> <user-name>@<ip-address> </pre>

4. Pull the code from GitHub. 
<pre>git clone https://github.com/neurotechcenter/hyperscanning-backend</pre>

5. Navigate to the server directory: 
<pre>cd hyperscanning-backend</pre>

6. To compile the project, run:
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>

5. Launch the server by running: 
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application must be restarted after BCI2000 has been closed.
 

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:CommunicationTask batch.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====StimuliMatrix====
Shared parameter, matrix of stimulus information, including: 
1. ImageReceiver and ImageSender(the path of images). 
2. Sender(the role of players),1 is the sender), 2 is the receiver. 
3. Jitter(the duration to present the role). 
4. CorrectResponse(1: left, 2:right). 
5. Training(1: training, 0: main task). 
6. Category(1: object, 2: animal). 
7. Difficulty(1: easy, 2: moderate, 3: hard). 
8. Dimension1a and Dimension1b(bar#1 left text and right text). 
9. Dimension2a and Dimension2b(bar#2 left text and right text). 
10. Option1 and Option2(left option text and right option text).

====BreakTrialSequece====
The sequence of break trials, a break will happen after the break trial.

====FeedbackDuration====
Duration of feedback(ITI). Indicate the receiver to make a correct or incorrect guess. 

The server will generate the InitialTrialNumber and StimuliSequence, and save them into a parameter file named by IP addresses on the server. You don't need to worry about these two parameters. Unlike the parameters described above, they are saved on the server rather than on local computers.

====InitialTrialNumber====
The trial number to begin with. We provide the resume option, allowing clients to pause and resume the game from where they stop. After one of the clients quits the game, the server will discover it and save the current trial number and sequence. When the same clients(same IP address) reconnect the server again, the server will send the previous trial number to them. Otherwise, the InitialTrailNumber will be initialized by 0. Usually, you don't need to touch this parameter.

====StimuliSequence====
The sequence of stimuli(images). The server will generate a random stimuli sequence for every pair of clients (identified by the IP address).

===Local Parameters===

====PreTrialFlash====
Have the patch on the left bottom corner of the screen only flash before the trial starts: 
- The square is white by default 
- 500 ms before trial start, the square switches to black 
- At trial start, the square switches back to white and stays white until next trial 

====StimuliWidth====
StimulusWidth in percent of screen width (zero for original pixel size).

====InstructionImagesSeque====
The sequence of instruction images path.

====InstructionWidth====
Instruction width in percent of screen width (zero for original pixel size).

====SliderWidth====
SliderWidth in percent of screen width (zero for original pixel size).

====BarColor====
Color of the slider bar.

====AxeActiveColor====
Color of active slider axe.

====AxeInActiveColor====
Color of inactive slider axe.

====DimensionFontColor====
Color of the text under the slider.

====DimensionHeight====
Height of text in percent of the screen height.

====OptionFontActiveColor====
Color of the active options.

====OptionFontInActiveColor====
Color of the inactive options.

====OptionHeight====
Height of text in percent of the screen height.

====RoleFontColor====
Color of the role text.

====RoleHeight====
Height of text in percent of the screen height.

====FeedbackWidth====
Width of feedback in percent of screen width.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===TrialStart===
The onset time of the beginning of trial

===PhaseNumber===
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the 10 slides instruction images are present on the screen) 
[1] indicates the client is waiting for the other client to push the button to start the game. ( We are waiting for another player; once she/he is ready, we're ready to go!) 
[2] When the role text is present on the screen.(Sender or Receiver). 
[3] When the sliders and stimulus are present on the screen. 
[4] Feedback: After the receiver locks the answer, it comes to phase [4], showing whether the answer is correct. 
[5]Break: (Well done! Are you ready for the next block? \n\n Press SPACEBAR) 
[6]End: (Well done! You have finished all the trials.)

===TrialNumber===
Index of trials. (8 bits)

===StimulusCode===
The stimulus ID

===Photodiode===
The photodiode state. 1: flash, 0: no flash

===SampleBlockCounter===
Count the block number in one phase

===BarOneValue===
Value of slider#1. (32 bits)

===BarTwoValue===
Value of slider#2. (32 bits)

===BarOneActive, BarTwoActive===
0: slider is not selected. 1: slider is selected. (8 bits)

===ResponseValue===
1: object. 2: animal. (8 bits)

===SenderLock, ReceiverLock===
0: client is moving the slider/making a guess. 1: client has locked the answer. (8 bits)

===isReadyStart0, isReadyStart1===
0: client isn't ready to start/resume/continue the game(not yet pushing the button). 1: client is ready to start/resume/continue the game(push the button). (8 bits)

===ClientNumber===
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits)

==Example==
The hyperscanning application module is almost the same as a BCI2000 application module, except that the typical BCI2000 module is inherited from ApplicationBase, and the hyperscanning application module is inherited from HyperscanningApplicationBase. Basically, the HyperscanningApplicationBase class is the same as ApplicationBase class with adding the communication with the server. So instead of using Publish, Preflight, Process, etc. We are using SharedPublish, SharedPreflight, SharedProcess, etc. These methods behave in the exact same way, except they also call the client loops which interact with the server.

Communication_task_dualTask.h:
<pre>
#include "ApplicationBase.h"
#include "Slider.h"
#include <map>
#include <vector>
#include <string>
#include "TextStimulus.h"
#include "ImageStimulus.h"
#include "Shapes.h"
#include "HyperscanningApplicationBase.h"

class Communication_task_dualTask : public HyperscanningApplicationBase
{
public:
Communication_task_dualTask();
~Communication_task_dualTask();
void SharedPublish() override;
void SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const override;
void SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) override;
void SharedAutoConfig( const SignalProperties& Input ) override;
void SharedStartRun() override;
void SharedProcess( const GenericSignal& Input, GenericSignal& Output ) override;
void SharedStopRun() override;
void SharedHalt() override;

private:
//define your own private members here
ApplicationWindow& mrDisplay;

//define your own private methods here

};
</pre>

Manipulate the shared state is the same as the BCI2000 state. "isReadyStart1" is a shared state.
<pre>
State("isReadyStart1") = 1; // assign 1 to "isReadyStart1"
</pre>

Get the value of the shared state "isReadyStart1"
<pre>
//Both of the two players are ready, move to the next phase
if (State("isReadyStart0") && State("isReadyStart1")) {
m_instruction_container->Conceal();
m_role_txt->Conceal();
my_phase = role_text;
m_block_in_phase = 0;
}
</pre>

Contributions:CommunicationTask

2025-10-09T20:42:21Z

Lingling: /* Local Parameters */

==Synopsis==
The hyperscanning task is a turn-based communication game between two clients. This game aims to guess what the subject is in Sender's computer without talking. For each trial, the two players will alternate between the roles of Sender and Receiver. The Sender will describe traits of the subject presented by adjusting the two axes(Noisy or silent/Big or small). Then, the Receiver will guess if the Sender is describing the animal or object. After the Receiver makes a guess, both players receive feedback on whether the Receiver makes the correct guess. This marks the end of a trial.

The two clients exchange information through the hyperScanning backend, which uses a client-server model to share the states. Each client has a separate state machine. The server only forwards the information between two clients. Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class, which is the parent class of the application module. For more information, please refer to the hyperScanning framework wiki page: https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning.

==Video Overview==
 
<youtube alignment="center">https://youtu.be/I1sSamSsTK4</youtube>
 

==Timeline==
<gallery mode="packed" widths=600px heights=500px>
File:Hyperscanning pipe line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=750px heights=421px>
File:Hyperscanning_1.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Anais Llorens (anaisllorens@hotmail.com) and Athina Tzovara (athina.tzovara@unibe.ch) conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org), Max Marcus (bigmaxmarcus@gmail.com) and Sigurd Alnes (sigurd.alnes@unibe.ch) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
To run the server, you’ll need a Linux or macOS machine—Windows is not supported at this time. The steps below walk you through deploying the server on AWS. 
1. Prepare the AWS key. 

2. In your terminal or shell, run 
<pre> chmod 400 <key_path> </pre>
to make the key file read-only for the owner. 

3. Connect to the AWS server using SSH: 
<pre> ssh -i <key path> <user-name>@<ip-address> </pre>

4. Pull the code from GitHub. 
<pre>git clone https://github.com/neurotechcenter/hyperscanning-backend</pre>

5. Navigate to the server directory: 
<pre>cd hyperscanning-backend</pre>

6. To compile the project, run:
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>

5. Launch the server by running: 
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application must be restarted after BCI2000 has been closed.
 

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:CommunicationTask batch.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====StimuliMatrix====
Shared parameter, matrix of stimulus information, including: 
1. ImageReceiver and ImageSender(the path of images). 
2. Sender(the role of players),1 is the sender), 2 is the receiver. 
3. Jitter(the duration to present the role). 
4. CorrectResponse(1: left, 2:right). 
5. Training(1: training, 0: main task). 
6. Category(1: object, 2: animal). 
7. Difficulty(1: easy, 2: moderate, 3: hard). 
8. Dimension1a and Dimension1b(bar#1 left text and right text). 
9. Dimension2a and Dimension2b(bar#2 left text and right text). 
10. Option1 and Option2(left option text and right option text).

====BreakTrialSequece====
The sequence of break trials, a break will happen after the break trial.

====FeedbackDuration====
Duration of feedback(ITI). Indicate the receiver to make a correct or incorrect guess. 

The server will generate the InitialTrialNumber and StimuliSequence, and save them into a parameter file named by IP addresses on the server. You don't need to worry about these two parameters. Unlike the parameters described above, they are saved on the server rather than on local computers.

====InitialTrialNumber====
The trial number to begin with. We provide the resume option, allowing clients to pause and resume the game from where they stop. After one of the clients quits the game, the server will discover it and save the current trial number and sequence. When the same clients(same IP address) reconnect the server again, the server will send the previous trial number to them. Otherwise, the InitialTrailNumber will be initialized by 0. Usually, you don't need to touch this parameter.

====StimuliSequence====
The sequence of stimuli(images). The server will generate a random stimuli sequence for every pair of clients (identified by the IP address).

===Local Parameters===

====PreTrialFlash====
Have the patch on the left bottom corner of the screen only flash before the trial starts: 
- The square is white by default 
- 500 ms before trial start, the square switches to black 
- At trial start, the square switches back to white and stays white until next trial 

====StimuliWidth====
StimulusWidth in percent of screen width (zero for original pixel size).

====InstructionImagesSeque====
The sequence of instruction images path.

====InstructionWidth====
Instruction width in percent of screen width (zero for original pixel size).

====SliderWidth====
SliderWidth in percent of screen width (zero for original pixel size).

====BarColor====
Color of the slider bar.

====AxeActiveColor====
Color of active slider axe.

====AxeInActiveColor====
Color of inactive slider axe.

====DimensionFontColor====
Color of the text under the slider.

====DimensionHeight====
Height of text in percent of the screen height.

====OptionFontActiveColor====
Color of the active options.

====OptionFontInActiveColor====
Color of the inactive options.

====OptionHeight====
Height of text in percent of the screen height.

====RoleFontColor====
Color of the role text.

====RoleHeight====
Height of text in percent of the screen height.

====FeedbackWidth====
Width of feedback in percent of screen width.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===PhaseNumber===
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the 10 slides instruction images are present on the screen) 
[1] indicates the client is waiting for the other client to push the button to start the game. ( We are waiting for another player; once she/he is ready, we're ready to go!) 
[2] When the role text is present on the screen.(Sender or Receiver). 
[3] When the sliders and stimulus are present on the screen. 
[4] Feedback: After the receiver locks the answer, it comes to phase [4], showing whether the answer is correct. 
[5]Break: (Well done! Are you ready for the next block? \n\n Press SPACEBAR) 
[6]End: (Well done! You have finished all the trials.)

===TrialNumber===
Index of trials. (8 bits)

===StimulusCode===
The stimulus ID

===Photodiode===
The photodiode state. 1: flash, 0: no flash

===SampleBlockCounter===
Count the block number in one phase

===BarOneValue===
Value of slider#1. (32 bits)

===BarTwoValue===
Value of slider#2. (32 bits)

===BarOneActive, BarTwoActive===
0: slider is not selected. 1: slider is selected. (8 bits)

===ResponseValue===
1: object. 2: animal. (8 bits)

===SenderLock, ReceiverLock===
0: client is moving the slider/making a guess. 1: client has locked the answer. (8 bits)

===isReadyStart0, isReadyStart1===
0: client isn't ready to start/resume/continue the game(not yet pushing the button). 1: client is ready to start/resume/continue the game(push the button). (8 bits)

===ClientNumber===
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits)

==Example==
The hyperscanning application module is almost the same as a BCI2000 application module, except that the typical BCI2000 module is inherited from ApplicationBase, and the hyperscanning application module is inherited from HyperscanningApplicationBase. Basically, the HyperscanningApplicationBase class is the same as ApplicationBase class with adding the communication with the server. So instead of using Publish, Preflight, Process, etc. We are using SharedPublish, SharedPreflight, SharedProcess, etc. These methods behave in the exact same way, except they also call the client loops which interact with the server.

Communication_task_dualTask.h:
<pre>
#include "ApplicationBase.h"
#include "Slider.h"
#include <map>
#include <vector>
#include <string>
#include "TextStimulus.h"
#include "ImageStimulus.h"
#include "Shapes.h"
#include "HyperscanningApplicationBase.h"

class Communication_task_dualTask : public HyperscanningApplicationBase
{
public:
Communication_task_dualTask();
~Communication_task_dualTask();
void SharedPublish() override;
void SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const override;
void SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) override;
void SharedAutoConfig( const SignalProperties& Input ) override;
void SharedStartRun() override;
void SharedProcess( const GenericSignal& Input, GenericSignal& Output ) override;
void SharedStopRun() override;
void SharedHalt() override;

private:
//define your own private members here
ApplicationWindow& mrDisplay;

//define your own private methods here

};
</pre>

Manipulate the shared state is the same as the BCI2000 state. "isReadyStart1" is a shared state.
<pre>
State("isReadyStart1") = 1; // assign 1 to "isReadyStart1"
</pre>

Get the value of the shared state "isReadyStart1"
<pre>
//Both of the two players are ready, move to the next phase
if (State("isReadyStart0") && State("isReadyStart1")) {
m_instruction_container->Conceal();
m_role_txt->Conceal();
my_phase = role_text;
m_block_in_phase = 0;
}
</pre>

BCI2000 Hyperscanning

2025-09-15T16:46:49Z

Lingling:

BCI2000 Hyperscanning is a multiplayer simulation, a program that is synchronized over multiple computers, that supports the connection of two or more clients, the computers that are involved in the simulation. BCI2000 Hyperscanning also has subjects, which are the people that are using the client computers.

In a multiplayer simulation, each client involved must know the current state of the game. This game state allows each client to determine the output that is shown to the user. In order for each client to display the same game to each user, each client must have the same game state. The game state is stored as a collection of state variables in a state machine.
A state machine is a set of variables, or states, that correspond with values. In essence, it is a simple database. The data in the database describes the state of the game (see figure \ref{fig:gamestate}).

BCI2000 Hyperscanning has a master state machine that is stored on a centralized back-end server and one state machine for each client. Each client is connected to the back-end server through a TCP socket to ensure that each connection is maintained and everything that is sent is received. The clients output a stimulus to the user based on their state machines, and update their state machines based on user inputs. When one client updates its state machine, the server saves the game state in its master state machine and updates the other clients (see figure \ref{fig:gamestateupdate}).

[[File:GameStateFigure.png|center]]
'''''Game State.''' The game state shows synchrony between the master game state, which is stored on the server, and the client game states.''

[[File:GameStateUpdateFigure.png|center]]
'''''Game State Updates.''' The game state updates (bottom) show a typical interaction that would result in a game state update to the master game state and the ensuing update to the other client(s). In this example, the user clicks, indicating they would like to place a marker in the tic-tac-toe game, and this triggers a local game state update. This local game state update is sent to the server. The server saves the update and synchronizes the remaining client(s). After the interaction has concluded, each client is synchronized.''

[[File:StateUpdatesFigure.png|center]]
'''''Game State Update Scenarios.''' In scenario 1, the client updated its game state locally because of a user mouse press. This caused synchronization between it and the master game state to be lost. In this scenario, the client updates the master game state to match its game state. In scenario 2, a different client updated the master game state because of a user mouse press. This caused synchronization between the first client and the master game state to be lost. In this scenario, the server updates the first client to match its game state.''

== Server ==
The purpose of the server, or back-end, is to store, update, and distribute a master list of states. It synchronizes each of the client's state machines, so that each client displays the same game.

At a given time, one of the clients may have a state variable set to a value that is different from the value that the server has that state set to. At this point there are two possibilities. If that state was changed based on user inputs, then the server will update its state machine to reflect that user input. Otherwise, if the client has an old value, one that has been changed by another client, then the server will update the client with the new value of the state, so that each client is synchronized (see figure \ref{fig:gamestateupdatescenarios}).

In addition to synchronizing states between clients, the backend must also synchronize many initial parameters to ensure that the exact same experiment is being run for each subject, e.g. the order of stimulus images needs to be synchronized. To solve this, the server contains a BCI2000 parameter file that is sent to each client when it connects to the server. This also serves as a greeting message to ensure that the connection is functioning before the experiment begins.

The server application can be run from any mac or linux computer, whether it is local to one of the clients or in the cloud, as long as it is configured to allow TCP traffic. It is a collection of c++ classes and methods that are implemented into an application file. This application file is then run on the server computer. The server is not an instance of BCI2000. Rather, it is a separate application that interacts with client instances of BCI2000.

While the idea for this hyperscanning architecture propagated from one experimental design, we ensured that this technology was robust enough to be used reused for any experiment, even if it is radically different from our initial one. The core of the back-end is simple and abstracted. It is a state machine that can be updated from clients and will propagate those updates to other clients. This simplicity means that the central parts of the back-end will work for any experimental paradigm. The simplicity of the core also allows for a more specific framework to be built surrounding the core, should that be necessary for a specific application.

For each paradigm, an application file is implemented on the server. This application file will always contain the basic backend framework, like connecting to clients and running the actual data exchange loop, but it can also contain more specific instructions. For example, if parameters need to be randomly generated and synchronized across clients the core design is flexible enough to allow that to be built. Parameters can be added to the previously mentioned parameter file through the application file to solve this particular example. If there is a paradigm requiring more complex changes to the standard backend, the core can also be broken down into its individual steps to allow that.

The backend runs in a continuous loop of data exchanges with the clients. This loop continues for as long as the experiment runs. The end to the session, and thus the loop, is singaled by one of the clients breaking its connection with the server.

Even though a client disconnects, the experiment may not be concluded. There could have been a crash, internet issues, or the investigator may have wanted to pause the experiment, but the server cannot continue operating properly after a client has disconnected. To solve this issue, the application file can access the state machine after the loop has ended, and save any of the states that are necessary to redetermine the experimental state after a restart. These values can then be passed to BCI2000 as parameters when it is restarted. For example, the trial number can be saved and passed to BCI2000 as an initial trial number parameter (see figure \ref{fig:pause}).

[[File:PauseFigure.png|center]]
'''''Example paradigm with pause feature.''' This is a stimulus presentation paradigm, with a progression of faces being shown to the subject. During the first recording session, the subject gets through the first two trials before the session ends. The current trial number is saved to the server. During the next recording session, the server sends the current trial number, three, to the client; the client begins the session at trial number three and completes the paradigm.''

=== Server Loop ===
The loop has three main steps (see figure \ref{fig:serverloop}). First, the server updates any states changed by the clients. Second, the server reconciles all of the updated states. Third, the server sends updated states back to the clients.

[[File:ReconcilliationFigure.png|center]]
'''''Progression of state updates over time.''' Each client sends state updates, indicated by black arrows, to the server-side-client state machines, indicated by pink arrows. The server side state machines send the state updates to the master state machine. These state updates include conflicting information; the master state machine saves the state update from client 1 and disregards the conflicting update from client 2. The server sends the changed states, indicated by triangular arrows and blue ovals, back to the server-side-client state machines. The server-side-client state machines send their changed states back to the clients.''

==== Client Updates ====

In this step, the server simply waits for at least one of the clients to send states that were changed locally. If a client has not sent any data, then the server will wait for 2ms before checking another client. The server saves the data sent by the client in a state machine that tracks the current values of the states on each client. These are the server-side-client state machines.

==== Reconciliation ====
In this step, the server decides which states to save and prepares the updates to send to each client. After each client sends its updates, the server-side-client machines are different from the master state machine and from each other, but they are synchronized with their respective clients. The server has to synchronize all of these state machines by saving client changes to the master state machine and sending updates to the clients, but it is necessary to save only one version of each state and to send only updates with new information. If the server repeats state updates by sending the same update twice or by echoing a state change back to the client that sent it, that state will be changed at multiple times for that client, which can cause irregularities and bugs. %Tracker state machines, which track the changes when a state machine is updated, are used to ensure that only actual changes are sent to the clients. One tracker is used to determine all the changes to the master state machine from the client updates. These changes are then used to update the server-side-client state machines. The changes to the server-side-client state machines are only the updates from other clients that were saved as master states, so they are then used to update the actual client state machines.

To solve this, each state must pass two tests to get sent to a client. First, it must have been saved to the master state machine. Second, it must have been sent by a different client. These tests are implemented using tracker state machines, which track the changes that occur when a state machine is updated. For the first test, the server updates the master state machine from the server-side-client state machines and tracks the changes. For the second test, the changes to the master state machine are used to update the server-side-client state machines, and the changes from this interaction are tracked. The changes to the server-side-client state machines pass both tests, because they were changed on the master state machine (they were saved to the master state machine) and one of the client state machines (they weren't sent by that client because, in that case, they would have already been updated). These changes can be sent to the clients.

==== Update Clients ====
This final step is the opposite of the first step. The server sends the prepared states to the clients. After this step, the loop repeats, and the server waits for the client to send updates again.

== Clients ==
The purpose of the clients is to display the stimulus to the subject. Additionally, it is responsible for actually calculating the values of the game states. Each client is a separate instance of BCI2000, which are run on separate computers. They can be next to each other or hundreds of miles apart depending on the needs of the experiment.

Once again, the structure is designed to be robust and reusable. To this end, the client exists in two pieces. The true frontend, which is responsible for calculating state values and outputting the stimulus, and the network logger, which is responsible for communication with the server. The true frontend is designed as a typical BCI2000 experiment, and thus will be different for every experiment. The network logger contains everything that will be the exact same for every BCI2000 Hyperscanning experiment. Thus, the network logger can be reused, while the true frontend is redesigned for every new experiment.

The network logger is a part of the hyperscanning application base, which is a c++ class that a hyperscanning paradigm can be built upon. The hyperscanning application base will connect the network logger to the application module.

BCI2000 has its own built in state machine. The network logger seamlessly updates a predefined set of these BCI2000 states based on server activity and the activity of other clients. It translates server data into BCI2000 states. The list of states that are updated by the network logger is defined in a BCI2000 parameter called shared states that contains both the names and the sizes of each of the states that the designer wants to be synchronized amongst the clients. To ensure that the states are sent rapidly, only the necessary states should be sent between clients, so they must be defined in this parameter. Other BCI2000 states will not be synchronized.

=== Client Loops ===
Much like the server, the network logger loops, however, in order to conform with BCI2000 two distinct loops are utilized. One of them is synchronous with the rest of BCI2000. BCI2000 only allows its states to be changed during specific phases, so one of the loops must be synchronized with BCI2000. %The limitations of BCI2000 states require that state changes occur only during a specific time period, which necessitates synchronizing the loop with BCI2000.
While BCI2000 has a type of state that can be written to asynchronously, called an event, they are added to a queue and changed at a later time. This means the network logger cannot differentiate changes it made from changes the frontend made, so it doesn't know which changes to send to the server. The other loop is asynchronous, and makes use of multi-threading and parallel processing to increase the speed that data transfers can be made at, ensuring the greatest possible synchronicity between clients.

Because these loops are both operating on the same data, i.e. the states that need to be changed, there is the risk of data corruption if both try to operate at the same time. The data is stored in mutexed buffers to ensure that does not happen. Mutexed buffers can only be written to or read by a single source at a time. If multiple sources try to access a mutexed buffer, one of them must wait for the other to finish its operation.

Two buffers are shared between the two loops (see figure \ref{fig:clientloops}). One is a state machine that contains the name and value of each shared state, along with whether or not the state has a change from the server that hasn't been updated to the BCI2000 states, and the other is a message for the server that contains the states that have been updated by the frontend.

[[File:clientloopsfigure.png|center]]
'''''Synchronous and asynchronous client loops and their data exchanges.''' The client updates a state, e.g. they indicate their move in tic-tac-toe with a mouse click, and the synchronous client loop adds that change to the message for the server. The asynchronous loop sends the message to the server. The asynchronous loop continues looping until it gets a response from the server. When it gets a response from the server, e.g. the other client's move, it adds it to the changed states buffer. The synchronous loop saves the changes in the changed states buffer to the BCI2000 state machine.''

==== Synchronous Loop ====

The synchronous loop first updates all of the BCI2000 states that have been changed by the server. %to the value sent by the server.
The loop then determines if any of the states in the mutexed state machine are different from their BCI2000 counterpart. Because all of the states that were different from BCI2000 because of a server update were just updated, all of the remaining discrepancies must be due to a client change. These are then recorded in the message for the server.

It is very important for analyzing the experiment that the investigator knows when states were changed in relation to the recorded data. This could be complicated when states are being sent over the internet with delays and lag, but the network logger and BCI2000 radically simplify it. The important timestamp to record is when the state had an effect on the actual stimulus, because this is when it can have an effect on the subject. The timestamp of BCI2000 states is recorded whenever they are changed, and it is the BCI2000 states that have an effect on the stimulus. It is also BCI2000 that is providing the timestamps for the recorded data, therefore those timestamps will provide an accurate comparison between state changes and recorded data.

==== Asynchronous Loop ====

The asynchronous loop first sends the mutexed message to the server. If the message is empty, it doesn't send anything. This is the message that the server waits for in section 2.1.1. The loop then waits for a message from the server with the changes other clients have made. It waits 2ms for the server before moving on. This is the message the server sends in section 2.1.3. The loop then records these changes in the mutexed state machine and flags that they have a change from the server.

=== Client Initialization ===

The client initializes its connection with the server during the AutoConfig phase of BCI2000. This occurs after the Set Config button is pressed. The client first ensures that it hasn't already established a connection with the server, then it connects to the server. It uses user defined parameters to determine the IP address and port of the server application. The port of the server is defined by the designer in the server application file. The client then waits for the server to send an initial message that contains a client number and initial parameters. The client number is an id for the client to use to differentiate itself from other clients. For example, if each subject plays a different role in the paradigm, then the client number can be used to differentiate between roles. The parameters are then used to set BCI2000's parameters.

== Example Paradigm Design ==
A BCI2000 Hyperscanning paradigm is designed very similarly to a typical BCI2000 paradigm with a couple key differences. First, states we want to be shared with other clients must be stated in the batch file, either under the optional parameter SharedStates (for states we want to be shared that BCI2000 Hyperscanning will define for us) or the optional parameter PreDefinedSharedStates (for states we want to be shared that we will define ourselves). Second, instead of the regular BCI2000 methods, i.e. Publish, Preflight, Process, etc., we use Hyperscanning Application Base methods, which are prefixed with Shared, i.e. SharedPublish, SharedPreflight, SharedProcess, etc.. The BCI2000 Hyperscanning methods behave in the exact same way, except they also call the client loops which interact with the server.

=== Turn Based Stimulus ===

The well-known game Tic-Tac-Toe is an example of a turn based game. One player takes their turn, then the other player takes their turn. Each turn is taken after the previous one, with no overlap in timing. Here is our implementation of Tic-Tac-Toe to show how a turn based game works with BCI2000 hyperscanning:

TicTacToe.cpp:
<syntaxhighlight lang="cpp">
#include "TicTacToe.h"
#include "Shapes.h"
#include "TextField.h"
#include <limits>
#include "BCIEvent.h"
#include <string>

//Shared States
//grid, 32
//turn, 8
//x, 8
//y, 8

RegisterFilter( TicTacToe, 3 );

TicTacToe::TicTacToe() : winText( NULL ), highlight( NULL ), tiles( NULL ), board( NULL ), mrDisplay( Window() ) {
}

void TicTacToe::SharedPublish() {
}

void TicTacToe::SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const {
State( "grid" );
State( "turn" );
State( "ClientNumber" );
State( "KeyDown" );
State( "x" );
State( "y" );

Parameter( "SampleBlockSize" );
}

void TicTacToe::SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) {
ApplicationBase::Initialize( Input, Output );

board = new ImageStimulus( mrDisplay );
board->SetObjectRect( { 0.f, 0.f, 1.f, 1.f } );
board->SetScalingMode( GUI::ScalingMode::AdjustHeight );
board->SetRenderingMode( GUI::RenderingMode::Transparent );
board->SetFile( "../tasks/hyperscanning_test/tictactoe.png" );
board->SetZOrder( 12 );

winText = new TextField( mrDisplay );
winText->SetVisible( true );
winText->SetObjectRect( { 0.2f, 0.4f, 0.8f, 0.6f } );
board->SetZOrder( 1 );

tiles = ( ImageStimulus** ) malloc( sizeof( ImageStimulus ) * 9 );
for ( int i = 0; i < 9; i++ ) {
tiles[ i ] = new ImageStimulus( mrDisplay );
int x = i % 3;
int y = i / 3;
tiles[ i ]->SetObjectRect( { x / 3.f, y / 3.f, x / 3.f + 0.33f, y / 3.f + 0.33f } );
tiles[ i ]->SetScalingMode( GUI::ScalingMode::AdjustBoth );
tiles[ i ]->SetRenderingMode( GUI::RenderingMode::Opaque );
tiles[ i ]->SetZOrder( i + 2 );
}

highlight = new ImageStimulus( mrDisplay );
highlight->SetObjectRect( { 0.f, 0.f, 0.33f, 0.33f } );
highlight->SetScalingMode( GUI::ScalingMode::AdjustBoth );
highlight->SetRenderingMode( GUI::RenderingMode::Transparent );
highlight->SetFile( "../tasks/hyperscanning_test/highlight.png" );
highlight->SetZOrder( 11 );

}

void TicTacToe::SharedProcess( const GenericSignal& Input, GenericSignal& Output ) {
board->Present();
highlight->Present();
for ( int i = 0; i < 9; i++ ) {
tiles[ i ]->Present();
}

if ( State( "turn" ) == 3 ) {
if ( CheckKeyPress( "KeyDown", 32 ) ) { //Space
Reset();
}
}

if ( State( "ClientNumber" ) == State( "turn" ) ) {
if ( CheckKeyPress( "KeyDown", 38 ) && State( "y" ) >= 1 ) { //Up
State( "y" ) = State( "y" ) - 1;
}

if ( CheckKeyPress( "KeyDown", 40 ) && State( "y" ) <= 1 ) { //Down
State( "y" ) = State( "y" ) + 1;
}

if ( CheckKeyPress( "KeyDown", 37 ) && State( "x" ) >= 1 ) { //Left
State( "x" ) = State( "x" ) - 1;
}

if ( CheckKeyPress( "KeyDown", 39 ) && State( "x" ) <= 1 ) { //Right
State( "x" ) = State( "x" ) + 1;
}

if ( CheckKeyPress( "KeyDown", 32 ) ) { //Space
long xflag = 1UL << ( 2 * ( State( "y" ) * 3 + State( "x" ) ) );
long oflag = 1UL << ( 2 * ( State( "y" ) * 3 + State( "x" ) ) + 1 );

if ( !( State( "grid" ) & xflag ) && !( State( "grid" ) & oflag ) ) {
if ( State( "ClientNumber" ) == 0 ) {
State( "grid" ) = State( "grid" ) | xflag;
State( "turn" ) = 1;
}

else {
State( "grid" ) = State( "grid" ) | oflag;
State( "turn" ) = 0;
}
}
}
}

long flag = 1UL;
for ( int i = 0; i < 9; i++ ) {
if ( State( "grid" ) & flag ) {
tiles[ i ]->SetFile( "../tasks/hyperscanning_test/x.png" );
}
flag <<= 1;
if ( State( "grid" ) & flag ) {
tiles[ i ]->SetFile( "../tasks/hyperscanning_test/o.png" );
}
flag <<= 1;
}

long hwin = horizontal_win;
long vwin = vertical_win;
long dwin1 = diagonal_win_1;
long dwin2 = diagonal_win_2;

if ( ( State( "grid" ) & dwin1 ) == dwin1 || ( State( "grid" ) & dwin2 ) == dwin2 ) {
State( "turn" ) = 3;
winText->SetText( "X Wins" );
}

dwin1 <<= 1;
dwin2 <<= 1;

if ( ( State( "grid" ) & dwin1 ) == dwin1 || ( State( "grid" ) & dwin2 ) == dwin2 ) {
State( "turn" ) = 3;
winText->SetText( "O Wins" );
}

for ( int i = 0; i < 3; i++ ) {
if ( ( State( "grid" ) & hwin ) == hwin || ( State( "grid" ) & vwin ) == vwin ) {
State( "turn" ) = 3;
winText->SetText( "X Wins" );
}

hwin <<= 1;
vwin <<= 1;

if ( ( State( "grid" ) & hwin ) == hwin || ( State( "grid" ) & vwin ) == vwin ) {
State( "turn" ) = 3;
winText->SetText( "O Wins" );
}

hwin <<= 5;
vwin <<= 1;
}

highlight->SetObjectRect( { State("x") / 3.f, State("y") / 3.f, (State("x") + 1) / 3.f, (State("y") + 1) / 3.f } );
}

bool TicTacToe::CheckKeyPress( std::string event_name, int value ) {
for ( unsigned int i = 0; i < Parameter( "SampleBlockSize" ); i++ ) {
if ( State( event_name )( i ) == value ) {
return true;
}
}
return false;
}

void TicTacToe::Reset() {
State( "turn" ) = 0;
State( "grid" ) = 0;

delete board;
board = new ImageStimulus( mrDisplay );
board->SetObjectRect( { 0.f, 0.f, 1.f, 1.f } );
board->SetScalingMode( GUI::ScalingMode::AdjustHeight );
board->SetRenderingMode( GUI::RenderingMode::Transparent );
board->SetFile( "../tasks/hyperscanning_test/tictactoe.png" );
board->SetZOrder( 12 );

delete winText;
winText = new TextField( mrDisplay );
winText->SetVisible( true );
winText->SetObjectRect( { 0.2f, 0.4f, 0.8f, 0.6f } );
board->SetZOrder( 1 );

for ( int i = 0; i < 9; i++ ) {
delete tiles[ i ];
}
free( tiles );

tiles = ( ImageStimulus** ) malloc( sizeof( ImageStimulus ) * 9 );
for ( int i = 0; i < 9; i++ ) {
tiles[ i ] = new ImageStimulus( mrDisplay );
int x = i % 3;
int y = i / 3;
tiles[ i ]->SetObjectRect( { x / 3.f, y / 3.f, x / 3.f + 0.33f, y / 3.f + 0.33f } );
tiles[ i ]->SetScalingMode( GUI::ScalingMode::AdjustBoth );
tiles[ i ]->SetRenderingMode( GUI::RenderingMode::Opaque );
tiles[ i ]->SetZOrder( i + 2 );
}

delete highlight;

highlight = new ImageStimulus( mrDisplay );
highlight->SetObjectRect( { 0.f, 0.f, 0.33f, 0.33f } );
highlight->SetScalingMode( GUI::ScalingMode::AdjustBoth );
highlight->SetRenderingMode( GUI::RenderingMode::Transparent );
highlight->SetFile( "../tasks/hyperscanning_test/highlight.png" );
highlight->SetZOrder( 11 );
}
</syntaxhighlight>

TicTacToe.h
<syntaxhighlight lang="cpp">
#include "Shapes.h"
#include "TextField.h"
#include "ApplicationWindow.h"
#include "ImageStimulus.h"
#include "HyperscanningApplicationBase.h"

class TicTacToe : public HyperscanningApplicationBase {
public:
TicTacToe();

void SharedPublish() override;

void SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const override;
void SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) override;
void SharedProcess( const GenericSignal& Input, GenericSignal& Output ) override;

bool CheckKeyPress( std::string, int );

void Reset();

private:
ApplicationWindow& mrDisplay;

ImageStimulus* board;
ImageStimulus** tiles;
ImageStimulus* highlight;

TextField* winText;

long horizontal_win = 21;
long vertical_win = 4161;
long diagonal_win_1 = 65793;
long diagonal_win_2 = 4368;
};
</syntaxhighlight>

and TicTacToe.bat
Change directory $BCI2000LAUNCHDIR
Show window; Set title ${Extract file base $0}
Reset system
Startup system localhost
Start executable SignalGenerator --local --LogKeyboard=1
Start executable DummySignalProcessing --local
Start executable TicTacToe --local --Port=1234 --IPAddress=192.168.1.102 --SharedStates=grid,32&turn,8&x,8&y,8
Wait for Connected
Load parameterfile "../parms/CommunicationTask/Communication_task_dual.prm"

== Important Notes ==
The most are important sections to draw your attention to are:

if ( State( "ClientNumber" ) == State( "turn" ) ) {

ClientNumber is a state that is automatically sent by the server. It is an id, between 0 and N, where N is the number of clients connected, that can be used to differentiate between each client without having to run a separate application on each. "turn" is a shared state between the clients. Shared states are accessed in the exact same way that a normal BCI2000 state is accessed. This way we can use shared states and the client number to determine which client should be placing their mark.

State( "turn" ) = 1;

Shared states are also written to the exact same way as normal BCI2000 shared states. They will be automatically updated for the other clients.

Start executable TicTacToe --local --Port=1234 --IPAddress=192.168.1.102 --SharedStates=grid,32&turn,8&x,8&y,8

This is where we define the states that we want to share with "--SharedStates=". The format is:
--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...
We can also define predefined shared states here in a similar way, but without the size (because the size is already defined), using:
--PreDefinedSharedStates=<state-1>&<state-2>&<state-3>

--Port and --IPAddress are additional parameters that tell the client where to find the server on the internet. All of these parameters can also be changed from the Config menu, and the client connects to the server after "Set Config" is pressed.

=== Live Interaction Stimulus ===

The classic video game pong is an example of live interaction. Both players can interact with the game simultaneously. There are no discrete turns. We implemented pong with BCI2000 hyperscanning to demonstrate a live interaction.

pong.cpp
<syntaxhighlight lang="cpp">
#include "Pong.h"
#include "Shapes.h"
#include <limits>
#include "BCIEvent.h"

//Shared States
//BallX 32
//BallY 32
//BallVX 8
//BallVY 8
//Player1Y 32
//Player2Y 32
//Player1Ready 1
//Player2Ready 1
//GamePhase 8
//
//Game Phases
//0 : Instruction
//1 : Game
//2 : Between Rounds

RegisterFilter( Pong, 3 );

Pong::Pong() : player1Paddle( NULL ), player2Paddle( NULL ), ball( NULL ), mrDisplay( Window() ) {
}

void Pong::SharedPublish() {
}

void Pong::SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const {
State( "BallX" );
State( "BallY" );
State( "BallVX" );
State( "BallVY" );
State( "Player1Y" );
State( "Player2Y" );
State( "Player1Ready" );
State( "Player2Ready" );
State( "GamePhase" );
State("ClientNumber");
// State( "KeyDown" );
Parameter( "SampleBlockSize" );
}

void Pong::SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) {
player1Paddle = new RectangularShape( mrDisplay );
player1Paddle->SetFillColor( RGBColor::Teal );
player1Paddle->SetVisible( true );

player2Paddle = new RectangularShape( mrDisplay );
player2Paddle->SetFillColor( RGBColor::Red );
player2Paddle->SetVisible( true );

ball = new RectangularShape( mrDisplay );
ball->SetFillColor( RGBColor::Black );
ball->SetVisible( true );

}

void Pong::SharedStartRun() {
State( "BallX" ) = 500;
State( "BallY" ) = 500;
State( "Player1Y" ) = 200;
State( "Player2Y" ) = 800;
State( "BallVX" ) = 493;
State( "BallVY" ) = 497;
State( "GamePhase" ) = 2;
}

void Pong::SharedProcess( const GenericSignal& Input, GenericSignal& Output ) {
if ( State( "GamePhase" ) == 1 ) {
if ( State( "ClientNumber" ) == 0 ) {
State( "BallX" ) = State( "BallX" ) + State( "BallVX" ) - 500;
State( "BallY" ) = State( "BallY" ) + State( "BallVY" ) - 500;

if ( State( "BallY" ) > 950 || State( "BallY" ) < 50 ) {
State( "BallVY" ) = 1000 - State( "BallVY" );
}

if ( State( "BallX" ) + 50 > 875 && State( "BallX" ) - 50 < 925 && State( "BallY" ) + 50 > State( "Player2Y" ) - 100 && State( "BallY" ) - 50 < State( "Player2Y" ) + 100 ) {
State( "BallVX" ) = 1000 - State( "BallVX" );
State( "BallX" ) = 875 - 50;
}

if ( State( "BallX" ) + 50 > 75 && State( "BallX" ) - 50 < 125 && State( "BallY" ) + 50 > State( "Player1Y" ) - 100 && State( "BallY" ) - 50 < State( "Player1Y" ) + 100 ) {
State( "BallVX" ) = 1000 - State( "BallVX" );
State( "BallX" ) = 125 + 50;
}

if ( State( "BallX" ) + 50 > 1000 || State( "BallX" ) - 50 < 0 ) {
State( "BallX" ) = 500;
State( "BallVY" ) = State( "BallVY" ) + 1;
State( "GamePhase" ) = 2;
}
}

if ( CheckKeyPress( "KeyDown", 38 ) ) { //Up
if ( State( "ClientNumber" ) == 0 )
State( "Player1Y" ) = State( "Player1Y" ) - 30;
else
State( "Player2Y" ) = State( "Player2Y" ) - 30;
}

if ( CheckKeyPress( "KeyDown", 40 ) ) { //Down
if ( State( "ClientNumber" ) == 0 )
State( "Player1Y" ) = State( "Player1Y" ) + 30;
else
State( "Player2Y" ) = State( "Player2Y" ) + 30;
}
}

if ( State( "GamePhase" ) == 2 ) {
if ( CheckKeyPress( "KeyDown", 32 ) == 0 ) { //Space
if ( State( "ClientNumber" ) == 0 )
State( "Player1Ready" ) = 1;
else
State( "Player2Ready" ) = 1;
}

if ( State( "Player1Ready" ) == 1 && State( "Player2Ready" ) == 1 ) {
State( "GamePhase" ) = 1;
State( "Player1Ready" ) = 0;
State( "Player2Ready" ) = 0;
}
}

bciout << "Ball: (" << State("BallX") << ", " << State("BallY") << ")";
bciout << "Player1: " << State("Player1Y");

GUI::Rect rect = { ( State( "BallX" ) / 1000.f ) - 0.05, ( State( "BallY" ) / 1000.f ) - 0.05, ( State( "BallX" ) / 1000.f ) + 0.05, ( State( "BallY" ) / 1000.f ) + 0.05 };
ball->SetObjectRect( rect );

rect = { 0.075f, ( State( "Player1Y" ) / 1000.f ) - 0.1f, 0.125f, ( State( "Player1Y" ) / 1000.f ) + 0.1f };
player1Paddle->SetObjectRect( rect );

rect = { 0.875f, ( State( "Player2Y" ) / 1000.f ) - 0.1f, 0.925f, ( State( "Player2Y" ) / 1000.f ) + 0.1f };
player2Paddle->SetObjectRect( rect );

}

bool Pong::CheckKeyPress( std::string event_name, int value ) {
for ( unsigned int i = 0; i < Parameter( "SampleBlockSize" ); i++ ) {
if ( State( event_name )( i ) == value ) {
return true;
}
}
return false;
}
</syntaxhighlight>
pong.h
<syntaxhighlight lang="cpp">
#include "Shapes.h"
#include "ApplicationWindow.h"
#include "HyperscanningApplicationBase.h"

class Pong : public HyperscanningApplicationBase {
public:
Pong();

void SharedPublish() override;

void SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const override;
void SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) override;
void SharedProcess( const GenericSignal& Input, GenericSignal& Output ) override;
void SharedStartRun() override;

bool CheckKeyPress( std::string event_name, int value );

private:
ApplicationWindow& mrDisplay;
RectangularShape* player1Paddle;
RectangularShape* player2Paddle;
RectangularShape* ball;
};
</syntaxhighlight>
and pong.bat
Change directory $BCI2000LAUNCHDIR
Show window; Set title ${Extract file base $0}
Reset system
Startup system localhost
Start executable SignalGenerator --local --LogKeyboard=1
Start executable DummySignalProcessing --local
Start executable Pong --local --Port=1234 --IPAddress=192.168.1.102 --SharedStates=BallX,32&BallY,32&Player1Y,32&Player2Y,32&BallVX,32&BallVY,32&Player1Ready,8&Player2Ready,8&GamePhase,8&Player1Score,8&Player2Score,8
Wait for Connected
Load parameterfile "../parms/CommunicationTask/Communication_task_dual.prm"

This behaves very similarly to the tic-tac-toe example, with the key difference being both clients can interact with states simultaneously, whereas in tic-tac-toe only one client was changing states at a time.

Any processing of game states, for example changing the position of the ball in pong, can occur on either the clients or the server depending on the wants and needs of each implementation. If they are placed on the client side, only one of clients should be responsible for actually processing the data because otherwise there could be multiple versions of the same state that are equally correct, because they were each accurately calculated by a different client, so the server would have to choose one state to save to the master state machine and discard the other versions. This could lead to jumpiness when displaying the state or bugs. Because only one client is processing data, only that client will have a greater load than the others. If the overhead of the game is too significant, this could become problematic. If the processing is done on the server, there will not be an issue with one client running slower, but it will be more tedious to implement, because a custom installation will have to be designed instead of a premade backend application, and a more powerful server will be required.

For turn based games, this is a non-issue because each client can process the game state for their own turn. It only becomes an issue when a game state needs to be calculated that isn't based on client inputs, once again like the movement of the ball in pong, as opposed to the movement of the paddles in pong.

=== Example Server Application ===
application.cpp
<syntaxhighlight lang="cpp">
#include "statemachine.h"
#include "game.h"
#include "port.h"
#include "client.h"
#include "statemachine.h"
#include <iostream>
#include <thread>
#include <chrono>
#include <fstream>
#include <algorithm>
#include <random>
#include "params.h"

int main() {

</syntaxhighlight>
Here we load a general parameter file to ensure that the experiment is the same on each client. We also load a parameter file for an existing game, so we can resume where we left off. We will write to the existing game file in the final section of the application file. If this is the first session, then we will randomly generate a stimuli sequence.

<syntaxhighlight lang="cpp">
// Load Parameter File
Params params = Params( "Parameters.prm" );

// Load previous parameters
Params existing = Params( "ExistingGame.prm" );

std::string stimuliSequence;

// Check if saved parameters from previous game are populated
if ( existing.contents.size() > 0 ) {
params.contents += existing.contents;

stimuliSequence = existing.GetParam( "StimuliSequence" )->line;
} // If they are not then generate them, and they will be saved when this game finishes
else {
// Generate Random Sequence

Param* stimmat = params.GetParam( "StimuliMatrix" );

std::vector<int> order = std::vector<int>( stimmat->width );
for ( int i = 0; i < stimmat->width; i++ )
order[ i ] = i;

std::random_device rd;
auto rng = std::default_random_engine( rd() );
std::shuffle( std::begin( order ), std::end( order ), rng );

stimuliSequence = "\nApplication:Sequence intlist StimuliSequence= ";
stimuliSequence += std::to_string( stimmat->width );
stimuliSequence += " ";
for ( int i = 0; i < stimmat->width; i++ ) {
stimuliSequence += std::to_string( order[ i ] );
stimuliSequence += " ";
}
stimuliSequence += "% % % //Random Stimuli Sequence";

params.AddParam( stimuliSequence );

params.AddParam( "Application int InitialTrialNumber= 0 % % % // trial number" );
}

params.contents.push_back( 0 );
</syntaxhighlight>

This is the only necessary part of the main function. Here we open the port for listening, connect to the clients, and start the loop.
<syntaxhighlight lang="cpp">
//Open the port for listening
Port port( 1234, 100 );
if ( !port.open )
return 0;
std::cout << "Connected to port " << 1234 << std::endl;

// Initialize Game class
Game game = Game( port, params.contents );

std::cout << "Waiting for clients" << std::endl;

// Wait for a client to open a socket connection then connect them to the game
Client* client1 = port.WaitForClient();
game.Connect( client1 );

std::cout << "Connected to first client" << std::endl;
std::cout << "Waiting for second client" << std::endl;

// Do the same for a second client
game.Connect( port.WaitForClient() );

std::cout << "Connected to second client" << std::endl;

// Run the server loop and save the final states
StateMachine out_states = game.Loop();
</syntaxhighlight>

Here we take data from the master state machine and save it to the existing game parameter file, so we can use it when we restart the paradigm.

<syntaxhighlight lang="cpp">
// Save the trial number from when the paradigm was ended
std::string InitialTrialNumber = out_states.GetState( "TrialNumber" );
std::cout << "Trial Number: " << InitialTrialNumber << std::endl;

// Make sure that the trial number is populated and subtract one to repeat the unfinished trial
if ( InitialTrialNumber.size() == 0 ) InitialTrialNumber = "\1";
std::cout << "Saving Trial Number: " << ( int ) *InitialTrialNumber.c_str() - 1 << std::endl;

// Save Initial Trial Number and random stimuli sequence
std::ofstream egof( "ExistingGame.prm" );
egof << "Application int InitialTrialNumber= " << ( int )*InitialTrialNumber.c_str() - 1 << " % % % // trial number" << std::endl;
egof << stimuliSequence << std::endl;

// All Done!
std::cout << "All done!" << std::endl;
}
</syntaxhighlight>

== Important Notes ==
The server must be configured to allow inbound TCP traffic. Most only server services, like AWS or Azure, will allow you to do this easily.

In AWS:
# Select an instance
# Go to the "Security" tab
# Select one of the security groups
# With one of the security groups selected, go to the "inbound rules" tab
# Press "edit inbound rules"
# Press "Add Rule"
# Set "Type" to "Any TCP"
# Set "Source" to the IP Addresses of each of your clients or to "Anywhere IPv4"
# Press "Save Rules"

To create an instance in AWS:
# Go to [aws.amazon.com/ec2|AWS] and create an account or log in
# Press "Launch Instance"
# Give your instance a name
# Select "Amazon Linux" or any other non-windows operating system of your choice
# Select the tier of server you would like. If you are doing the processing on the clients then the free-tier or cheapest option will suffice with no performance penalties. If you followed the example server application, then you are doing the processing on the clients. If you are doing processing on the server, then select whichever performance tier is necessary to run your application at an acceptable speed.
# Under Key Pair, press "Create New Key Pair"
# Name is whatever you would like
# Select RSA for key pair type
# Select .pem for private key file format
# Press create key pair and remember where you save it to. We will need to use this to connect to the server.
# Now press "Launch Instance"

To configure and run your aws instance (if it isn't an aws instance the same applies, except instead of "ec2-user" you will use the username for your server or if it is local ignore the ssh step):
Open a terminal or shell
Enter the command
ssh -i </path/key-pair-name.pem> ec2-user@<public-IPv4-address>
The public IPv4 address can be found by selecting the instance in the instance dashboard. If you do not see one, ensure that the instance is running.
If prompted with
The authenticity of host 'ec2-198-51-100-1.compute-1.amazonaws.com (198-51-100-1)' can't be established.
ECDSA key fingerprint is l4UB/neBad9tvkgJf1QZWxheQmR59WgrgzEimCG6kZY.
Are you sure you want to continue connecting (yes/no)?
Type
yes
Clone the github repository with
git clone https://github.com/MaxwellMarcus/hyperscanning-backend
Go to the directory
cd hyperscanning-backend
Edit or create an application in the file application.cpp, if you aren't using the default tutorial application file
Build the application with
make
If you are working on remote servers over SSH. Please use the command "screen", which keeps the server running even if you disconnect. 
Creat a screen called dual
<syntaxhighlight>
screen -S dual
</syntaxhighlight>

Run the application with
./application
The application will only run as long as the experiment and will have to be restarted.

BCI2000 Hyperscanning

2025-09-15T16:43:31Z

Lingling:

BCI2000 Hyperscanning is a multiplayer simulation, a program that is synchronized over multiple computers, that supports the connection of two or more clients, the computers that are involved in the simulation. BCI2000 Hyperscanning also has subjects, which are the people that are using the client computers.

In a multiplayer simulation, each client involved must know the current state of the game. This game state allows each client to determine the output that is shown to the user. In order for each client to display the same game to each user, each client must have the same game state. The game state is stored as a collection of state variables in a state machine.
A state machine is a set of variables, or states, that correspond with values. In essence, it is a simple database. The data in the database describes the state of the game (see figure \ref{fig:gamestate}).

BCI2000 Hyperscanning has a master state machine that is stored on a centralized back-end server and one state machine for each client. Each client is connected to the back-end server through a TCP socket to ensure that each connection is maintained and everything that is sent is received. The clients output a stimulus to the user based on their state machines, and update their state machines based on user inputs. When one client updates its state machine, the server saves the game state in its master state machine and updates the other clients (see figure \ref{fig:gamestateupdate}).

[[File:GameStateFigure.png|center]]
'''''Game State.''' The game state shows synchrony between the master game state, which is stored on the server, and the client game states.''

[[File:GameStateUpdateFigure.png|center]]
'''''Game State Updates.''' The game state updates (bottom) show a typical interaction that would result in a game state update to the master game state and the ensuing update to the other client(s). In this example, the user clicks, indicating they would like to place a marker in the tic-tac-toe game, and this triggers a local game state update. This local game state update is sent to the server. The server saves the update and synchronizes the remaining client(s). After the interaction has concluded, each client is synchronized.''

[[File:StateUpdatesFigure.png|center]]
'''''Game State Update Scenarios.''' In scenario 1, the client updated its game state locally because of a user mouse press. This caused synchronization between it and the master game state to be lost. In this scenario, the client updates the master game state to match its game state. In scenario 2, a different client updated the master game state because of a user mouse press. This caused synchronization between the first client and the master game state to be lost. In this scenario, the server updates the first client to match its game state.''

== Server ==
The purpose of the server, or back-end, is to store, update, and distribute a master list of states. It synchronizes each of the client's state machines, so that each client displays the same game.

At a given time, one of the clients may have a state variable set to a value that is different from the value that the server has that state set to. At this point there are two possibilities. If that state was changed based on user inputs, then the server will update its state machine to reflect that user input. Otherwise, if the client has an old value, one that has been changed by another client, then the server will update the client with the new value of the state, so that each client is synchronized (see figure \ref{fig:gamestateupdatescenarios}).

In addition to synchronizing states between clients, the backend must also synchronize many initial parameters to ensure that the exact same experiment is being run for each subject, e.g. the order of stimulus images needs to be synchronized. To solve this, the server contains a BCI2000 parameter file that is sent to each client when it connects to the server. This also serves as a greeting message to ensure that the connection is functioning before the experiment begins.

The server application can be run from any mac or linux computer, whether it is local to one of the clients or in the cloud, as long as it is configured to allow TCP traffic. It is a collection of c++ classes and methods that are implemented into an application file. This application file is then run on the server computer. The server is not an instance of BCI2000. Rather, it is a separate application that interacts with client instances of BCI2000.

While the idea for this hyperscanning architecture propagated from one experimental design, we ensured that this technology was robust enough to be used reused for any experiment, even if it is radically different from our initial one. The core of the back-end is simple and abstracted. It is a state machine that can be updated from clients and will propagate those updates to other clients. This simplicity means that the central parts of the back-end will work for any experimental paradigm. The simplicity of the core also allows for a more specific framework to be built surrounding the core, should that be necessary for a specific application.

For each paradigm, an application file is implemented on the server. This application file will always contain the basic backend framework, like connecting to clients and running the actual data exchange loop, but it can also contain more specific instructions. For example, if parameters need to be randomly generated and synchronized across clients the core design is flexible enough to allow that to be built. Parameters can be added to the previously mentioned parameter file through the application file to solve this particular example. If there is a paradigm requiring more complex changes to the standard backend, the core can also be broken down into its individual steps to allow that.

The backend runs in a continuous loop of data exchanges with the clients. This loop continues for as long as the experiment runs. The end to the session, and thus the loop, is singaled by one of the clients breaking its connection with the server.

Even though a client disconnects, the experiment may not be concluded. There could have been a crash, internet issues, or the investigator may have wanted to pause the experiment, but the server cannot continue operating properly after a client has disconnected. To solve this issue, the application file can access the state machine after the loop has ended, and save any of the states that are necessary to redetermine the experimental state after a restart. These values can then be passed to BCI2000 as parameters when it is restarted. For example, the trial number can be saved and passed to BCI2000 as an initial trial number parameter (see figure \ref{fig:pause}).

[[File:PauseFigure.png|center]]
'''''Example paradigm with pause feature.''' This is a stimulus presentation paradigm, with a progression of faces being shown to the subject. During the first recording session, the subject gets through the first two trials before the session ends. The current trial number is saved to the server. During the next recording session, the server sends the current trial number, three, to the client; the client begins the session at trial number three and completes the paradigm.''

=== Server Loop ===
The loop has three main steps (see figure \ref{fig:serverloop}). First, the server updates any states changed by the clients. Second, the server reconciles all of the updated states. Third, the server sends updated states back to the clients.

[[File:ReconcilliationFigure.png|center]]
'''''Progression of state updates over time.''' Each client sends state updates, indicated by black arrows, to the server-side-client state machines, indicated by pink arrows. The server side state machines send the state updates to the master state machine. These state updates include conflicting information; the master state machine saves the state update from client 1 and disregards the conflicting update from client 2. The server sends the changed states, indicated by triangular arrows and blue ovals, back to the server-side-client state machines. The server-side-client state machines send their changed states back to the clients.''

==== Client Updates ====

In this step, the server simply waits for at least one of the clients to send states that were changed locally. If a client has not sent any data, then the server will wait for 2ms before checking another client. The server saves the data sent by the client in a state machine that tracks the current values of the states on each client. These are the server-side-client state machines.

==== Reconciliation ====
In this step, the server decides which states to save and prepares the updates to send to each client. After each client sends its updates, the server-side-client machines are different from the master state machine and from each other, but they are synchronized with their respective clients. The server has to synchronize all of these state machines by saving client changes to the master state machine and sending updates to the clients, but it is necessary to save only one version of each state and to send only updates with new information. If the server repeats state updates by sending the same update twice or by echoing a state change back to the client that sent it, that state will be changed at multiple times for that client, which can cause irregularities and bugs. %Tracker state machines, which track the changes when a state machine is updated, are used to ensure that only actual changes are sent to the clients. One tracker is used to determine all the changes to the master state machine from the client updates. These changes are then used to update the server-side-client state machines. The changes to the server-side-client state machines are only the updates from other clients that were saved as master states, so they are then used to update the actual client state machines.

To solve this, each state must pass two tests to get sent to a client. First, it must have been saved to the master state machine. Second, it must have been sent by a different client. These tests are implemented using tracker state machines, which track the changes that occur when a state machine is updated. For the first test, the server updates the master state machine from the server-side-client state machines and tracks the changes. For the second test, the changes to the master state machine are used to update the server-side-client state machines, and the changes from this interaction are tracked. The changes to the server-side-client state machines pass both tests, because they were changed on the master state machine (they were saved to the master state machine) and one of the client state machines (they weren't sent by that client because, in that case, they would have already been updated). These changes can be sent to the clients.

==== Update Clients ====
This final step is the opposite of the first step. The server sends the prepared states to the clients. After this step, the loop repeats, and the server waits for the client to send updates again.

== Clients ==
The purpose of the clients is to display the stimulus to the subject. Additionally, it is responsible for actually calculating the values of the game states. Each client is a separate instance of BCI2000, which are run on separate computers. They can be next to each other or hundreds of miles apart depending on the needs of the experiment.

Once again, the structure is designed to be robust and reusable. To this end, the client exists in two pieces. The true frontend, which is responsible for calculating state values and outputting the stimulus, and the network logger, which is responsible for communication with the server. The true frontend is designed as a typical BCI2000 experiment, and thus will be different for every experiment. The network logger contains everything that will be the exact same for every BCI2000 Hyperscanning experiment. Thus, the network logger can be reused, while the true frontend is redesigned for every new experiment.

The network logger is a part of the hyperscanning application base, which is a c++ class that a hyperscanning paradigm can be built upon. The hyperscanning application base will connect the network logger to the application module.

BCI2000 has its own built in state machine. The network logger seamlessly updates a predefined set of these BCI2000 states based on server activity and the activity of other clients. It translates server data into BCI2000 states. The list of states that are updated by the network logger is defined in a BCI2000 parameter called shared states that contains both the names and the sizes of each of the states that the designer wants to be synchronized amongst the clients. To ensure that the states are sent rapidly, only the necessary states should be sent between clients, so they must be defined in this parameter. Other BCI2000 states will not be synchronized.

=== Client Loops ===
Much like the server, the network logger loops, however, in order to conform with BCI2000 two distinct loops are utilized. One of them is synchronous with the rest of BCI2000. BCI2000 only allows its states to be changed during specific phases, so one of the loops must be synchronized with BCI2000. %The limitations of BCI2000 states require that state changes occur only during a specific time period, which necessitates synchronizing the loop with BCI2000.
While BCI2000 has a type of state that can be written to asynchronously, called an event, they are added to a queue and changed at a later time. This means the network logger cannot differentiate changes it made from changes the frontend made, so it doesn't know which changes to send to the server. The other loop is asynchronous, and makes use of multi-threading and parallel processing to increase the speed that data transfers can be made at, ensuring the greatest possible synchronicity between clients.

Because these loops are both operating on the same data, i.e. the states that need to be changed, there is the risk of data corruption if both try to operate at the same time. The data is stored in mutexed buffers to ensure that does not happen. Mutexed buffers can only be written to or read by a single source at a time. If multiple sources try to access a mutexed buffer, one of them must wait for the other to finish its operation.

Two buffers are shared between the two loops (see figure \ref{fig:clientloops}). One is a state machine that contains the name and value of each shared state, along with whether or not the state has a change from the server that hasn't been updated to the BCI2000 states, and the other is a message for the server that contains the states that have been updated by the frontend.

[[File:clientloopsfigure.png|center]]
'''''Synchronous and asynchronous client loops and their data exchanges.''' The client updates a state, e.g. they indicate their move in tic-tac-toe with a mouse click, and the synchronous client loop adds that change to the message for the server. The asynchronous loop sends the message to the server. The asynchronous loop continues looping until it gets a response from the server. When it gets a response from the server, e.g. the other client's move, it adds it to the changed states buffer. The synchronous loop saves the changes in the changed states buffer to the BCI2000 state machine.''

==== Synchronous Loop ====

The synchronous loop first updates all of the BCI2000 states that have been changed by the server. %to the value sent by the server.
The loop then determines if any of the states in the mutexed state machine are different from their BCI2000 counterpart. Because all of the states that were different from BCI2000 because of a server update were just updated, all of the remaining discrepancies must be due to a client change. These are then recorded in the message for the server.

It is very important for analyzing the experiment that the investigator knows when states were changed in relation to the recorded data. This could be complicated when states are being sent over the internet with delays and lag, but the network logger and BCI2000 radically simplify it. The important timestamp to record is when the state had an effect on the actual stimulus, because this is when it can have an effect on the subject. The timestamp of BCI2000 states is recorded whenever they are changed, and it is the BCI2000 states that have an effect on the stimulus. It is also BCI2000 that is providing the timestamps for the recorded data, therefore those timestamps will provide an accurate comparison between state changes and recorded data.

==== Asynchronous Loop ====

The asynchronous loop first sends the mutexed message to the server. If the message is empty, it doesn't send anything. This is the message that the server waits for in section 2.1.1. The loop then waits for a message from the server with the changes other clients have made. It waits 2ms for the server before moving on. This is the message the server sends in section 2.1.3. The loop then records these changes in the mutexed state machine and flags that they have a change from the server.

=== Client Initialization ===

The client initializes its connection with the server during the AutoConfig phase of BCI2000. This occurs after the Set Config button is pressed. The client first ensures that it hasn't already established a connection with the server, then it connects to the server. It uses user defined parameters to determine the IP address and port of the server application. The port of the server is defined by the designer in the server application file. The client then waits for the server to send an initial message that contains a client number and initial parameters. The client number is an id for the client to use to differentiate itself from other clients. For example, if each subject plays a different role in the paradigm, then the client number can be used to differentiate between roles. The parameters are then used to set BCI2000's parameters.

== Example Paradigm Design ==
A BCI2000 Hyperscanning paradigm is designed very similarly to a typical BCI2000 paradigm with a couple key differences. First, states we want to be shared with other clients must be stated in the batch file, either under the optional parameter SharedStates (for states we want to be shared that BCI2000 Hyperscanning will define for us) or the optional parameter PreDefinedSharedStates (for states we want to be shared that we will define ourselves). Second, instead of the regular BCI2000 methods, i.e. Publish, Preflight, Process, etc., we use Hyperscanning Application Base methods, which are prefixed with Shared, i.e. SharedPublish, SharedPreflight, SharedProcess, etc.. The BCI2000 Hyperscanning methods behave in the exact same way, except they also call the client loops which interact with the server.

=== Turn Based Stimulus ===

The well-known game Tic-Tac-Toe is an example of a turn based game. One player takes their turn, then the other player takes their turn. Each turn is taken after the previous one, with no overlap in timing. Here is our implementation of Tic-Tac-Toe to show how a turn based game works with BCI2000 hyperscanning:

TicTacToe.cpp:
<syntaxhighlight lang="cpp">
#include "TicTacToe.h"
#include "Shapes.h"
#include "TextField.h"
#include <limits>
#include "BCIEvent.h"
#include <string>

//Shared States
//grid, 32
//turn, 8
//x, 8
//y, 8

RegisterFilter( TicTacToe, 3 );

TicTacToe::TicTacToe() : winText( NULL ), highlight( NULL ), tiles( NULL ), board( NULL ), mrDisplay( Window() ) {
}

void TicTacToe::SharedPublish() {
}

void TicTacToe::SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const {
State( "grid" );
State( "turn" );
State( "ClientNumber" );
State( "KeyDown" );
State( "x" );
State( "y" );

Parameter( "SampleBlockSize" );
}

void TicTacToe::SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) {
ApplicationBase::Initialize( Input, Output );

board = new ImageStimulus( mrDisplay );
board->SetObjectRect( { 0.f, 0.f, 1.f, 1.f } );
board->SetScalingMode( GUI::ScalingMode::AdjustHeight );
board->SetRenderingMode( GUI::RenderingMode::Transparent );
board->SetFile( "../tasks/hyperscanning_test/tictactoe.png" );
board->SetZOrder( 12 );

winText = new TextField( mrDisplay );
winText->SetVisible( true );
winText->SetObjectRect( { 0.2f, 0.4f, 0.8f, 0.6f } );
board->SetZOrder( 1 );

tiles = ( ImageStimulus** ) malloc( sizeof( ImageStimulus ) * 9 );
for ( int i = 0; i < 9; i++ ) {
tiles[ i ] = new ImageStimulus( mrDisplay );
int x = i % 3;
int y = i / 3;
tiles[ i ]->SetObjectRect( { x / 3.f, y / 3.f, x / 3.f + 0.33f, y / 3.f + 0.33f } );
tiles[ i ]->SetScalingMode( GUI::ScalingMode::AdjustBoth );
tiles[ i ]->SetRenderingMode( GUI::RenderingMode::Opaque );
tiles[ i ]->SetZOrder( i + 2 );
}

highlight = new ImageStimulus( mrDisplay );
highlight->SetObjectRect( { 0.f, 0.f, 0.33f, 0.33f } );
highlight->SetScalingMode( GUI::ScalingMode::AdjustBoth );
highlight->SetRenderingMode( GUI::RenderingMode::Transparent );
highlight->SetFile( "../tasks/hyperscanning_test/highlight.png" );
highlight->SetZOrder( 11 );

}

void TicTacToe::SharedProcess( const GenericSignal& Input, GenericSignal& Output ) {
board->Present();
highlight->Present();
for ( int i = 0; i < 9; i++ ) {
tiles[ i ]->Present();
}

if ( State( "turn" ) == 3 ) {
if ( CheckKeyPress( "KeyDown", 32 ) ) { //Space
Reset();
}
}

if ( State( "ClientNumber" ) == State( "turn" ) ) {
if ( CheckKeyPress( "KeyDown", 38 ) && State( "y" ) >= 1 ) { //Up
State( "y" ) = State( "y" ) - 1;
}

if ( CheckKeyPress( "KeyDown", 40 ) && State( "y" ) <= 1 ) { //Down
State( "y" ) = State( "y" ) + 1;
}

if ( CheckKeyPress( "KeyDown", 37 ) && State( "x" ) >= 1 ) { //Left
State( "x" ) = State( "x" ) - 1;
}

if ( CheckKeyPress( "KeyDown", 39 ) && State( "x" ) <= 1 ) { //Right
State( "x" ) = State( "x" ) + 1;
}

if ( CheckKeyPress( "KeyDown", 32 ) ) { //Space
long xflag = 1UL << ( 2 * ( State( "y" ) * 3 + State( "x" ) ) );
long oflag = 1UL << ( 2 * ( State( "y" ) * 3 + State( "x" ) ) + 1 );

if ( !( State( "grid" ) & xflag ) && !( State( "grid" ) & oflag ) ) {
if ( State( "ClientNumber" ) == 0 ) {
State( "grid" ) = State( "grid" ) | xflag;
State( "turn" ) = 1;
}

else {
State( "grid" ) = State( "grid" ) | oflag;
State( "turn" ) = 0;
}
}
}
}

long flag = 1UL;
for ( int i = 0; i < 9; i++ ) {
if ( State( "grid" ) & flag ) {
tiles[ i ]->SetFile( "../tasks/hyperscanning_test/x.png" );
}
flag <<= 1;
if ( State( "grid" ) & flag ) {
tiles[ i ]->SetFile( "../tasks/hyperscanning_test/o.png" );
}
flag <<= 1;
}

long hwin = horizontal_win;
long vwin = vertical_win;
long dwin1 = diagonal_win_1;
long dwin2 = diagonal_win_2;

if ( ( State( "grid" ) & dwin1 ) == dwin1 || ( State( "grid" ) & dwin2 ) == dwin2 ) {
State( "turn" ) = 3;
winText->SetText( "X Wins" );
}

dwin1 <<= 1;
dwin2 <<= 1;

if ( ( State( "grid" ) & dwin1 ) == dwin1 || ( State( "grid" ) & dwin2 ) == dwin2 ) {
State( "turn" ) = 3;
winText->SetText( "O Wins" );
}

for ( int i = 0; i < 3; i++ ) {
if ( ( State( "grid" ) & hwin ) == hwin || ( State( "grid" ) & vwin ) == vwin ) {
State( "turn" ) = 3;
winText->SetText( "X Wins" );
}

hwin <<= 1;
vwin <<= 1;

if ( ( State( "grid" ) & hwin ) == hwin || ( State( "grid" ) & vwin ) == vwin ) {
State( "turn" ) = 3;
winText->SetText( "O Wins" );
}

hwin <<= 5;
vwin <<= 1;
}

highlight->SetObjectRect( { State("x") / 3.f, State("y") / 3.f, (State("x") + 1) / 3.f, (State("y") + 1) / 3.f } );
}

bool TicTacToe::CheckKeyPress( std::string event_name, int value ) {
for ( unsigned int i = 0; i < Parameter( "SampleBlockSize" ); i++ ) {
if ( State( event_name )( i ) == value ) {
return true;
}
}
return false;
}

void TicTacToe::Reset() {
State( "turn" ) = 0;
State( "grid" ) = 0;

delete board;
board = new ImageStimulus( mrDisplay );
board->SetObjectRect( { 0.f, 0.f, 1.f, 1.f } );
board->SetScalingMode( GUI::ScalingMode::AdjustHeight );
board->SetRenderingMode( GUI::RenderingMode::Transparent );
board->SetFile( "../tasks/hyperscanning_test/tictactoe.png" );
board->SetZOrder( 12 );

delete winText;
winText = new TextField( mrDisplay );
winText->SetVisible( true );
winText->SetObjectRect( { 0.2f, 0.4f, 0.8f, 0.6f } );
board->SetZOrder( 1 );

for ( int i = 0; i < 9; i++ ) {
delete tiles[ i ];
}
free( tiles );

tiles = ( ImageStimulus** ) malloc( sizeof( ImageStimulus ) * 9 );
for ( int i = 0; i < 9; i++ ) {
tiles[ i ] = new ImageStimulus( mrDisplay );
int x = i % 3;
int y = i / 3;
tiles[ i ]->SetObjectRect( { x / 3.f, y / 3.f, x / 3.f + 0.33f, y / 3.f + 0.33f } );
tiles[ i ]->SetScalingMode( GUI::ScalingMode::AdjustBoth );
tiles[ i ]->SetRenderingMode( GUI::RenderingMode::Opaque );
tiles[ i ]->SetZOrder( i + 2 );
}

delete highlight;

highlight = new ImageStimulus( mrDisplay );
highlight->SetObjectRect( { 0.f, 0.f, 0.33f, 0.33f } );
highlight->SetScalingMode( GUI::ScalingMode::AdjustBoth );
highlight->SetRenderingMode( GUI::RenderingMode::Transparent );
highlight->SetFile( "../tasks/hyperscanning_test/highlight.png" );
highlight->SetZOrder( 11 );
}
</syntaxhighlight>

TicTacToe.h
<syntaxhighlight lang="cpp">
#include "Shapes.h"
#include "TextField.h"
#include "ApplicationWindow.h"
#include "ImageStimulus.h"
#include "HyperscanningApplicationBase.h"

class TicTacToe : public HyperscanningApplicationBase {
public:
TicTacToe();

void SharedPublish() override;

void SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const override;
void SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) override;
void SharedProcess( const GenericSignal& Input, GenericSignal& Output ) override;

bool CheckKeyPress( std::string, int );

void Reset();

private:
ApplicationWindow& mrDisplay;

ImageStimulus* board;
ImageStimulus** tiles;
ImageStimulus* highlight;

TextField* winText;

long horizontal_win = 21;
long vertical_win = 4161;
long diagonal_win_1 = 65793;
long diagonal_win_2 = 4368;
};
</syntaxhighlight>

and TicTacToe.bat
Change directory $BCI2000LAUNCHDIR
Show window; Set title ${Extract file base $0}
Reset system
Startup system localhost
Start executable SignalGenerator --local --LogKeyboard=1
Start executable DummySignalProcessing --local
Start executable TicTacToe --local --Port=1234 --IPAddress=192.168.1.102 --SharedStates=grid,32&turn,8&x,8&y,8
Wait for Connected
Load parameterfile "../parms/CommunicationTask/Communication_task_dual.prm"

== Important Notes ==
The most are important sections to draw your attention to are:

if ( State( "ClientNumber" ) == State( "turn" ) ) {

ClientNumber is a state that is automatically sent by the server. It is an id, between 0 and N, where N is the number of clients connected, that can be used to differentiate between each client without having to run a separate application on each. "turn" is a shared state between the clients. Shared states are accessed in the exact same way that a normal BCI2000 state is accessed. This way we can use shared states and the client number to determine which client should be placing their mark.

State( "turn" ) = 1;

Shared states are also written to the exact same way as normal BCI2000 shared states. They will be automatically updated for the other clients.

Start executable TicTacToe --local --Port=1234 --IPAddress=192.168.1.102 --SharedStates=grid,32&turn,8&x,8&y,8

This is where we define the states that we want to share with "--SharedStates=". The format is:
--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...
We can also define predefined shared states here in a similar way, but without the size (because the size is already defined), using:
--PreDefinedSharedStates=<state-1>&<state-2>&<state-3>

--Port and --IPAddress are additional parameters that tell the client where to find the server on the internet. All of these parameters can also be changed from the Config menu, and the client connects to the server after "Set Config" is pressed.

=== Live Interaction Stimulus ===

The classic video game pong is an example of live interaction. Both players can interact with the game simultaneously. There are no discrete turns. We implemented pong with BCI2000 hyperscanning to demonstrate a live interaction.

pong.cpp
<syntaxhighlight lang="cpp">
#include "Pong.h"
#include "Shapes.h"
#include <limits>
#include "BCIEvent.h"

//Shared States
//BallX 32
//BallY 32
//BallVX 8
//BallVY 8
//Player1Y 32
//Player2Y 32
//Player1Ready 1
//Player2Ready 1
//GamePhase 8
//
//Game Phases
//0 : Instruction
//1 : Game
//2 : Between Rounds

RegisterFilter( Pong, 3 );

Pong::Pong() : player1Paddle( NULL ), player2Paddle( NULL ), ball( NULL ), mrDisplay( Window() ) {
}

void Pong::SharedPublish() {
}

void Pong::SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const {
State( "BallX" );
State( "BallY" );
State( "BallVX" );
State( "BallVY" );
State( "Player1Y" );
State( "Player2Y" );
State( "Player1Ready" );
State( "Player2Ready" );
State( "GamePhase" );
State("ClientNumber");
// State( "KeyDown" );
Parameter( "SampleBlockSize" );
}

void Pong::SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) {
player1Paddle = new RectangularShape( mrDisplay );
player1Paddle->SetFillColor( RGBColor::Teal );
player1Paddle->SetVisible( true );

player2Paddle = new RectangularShape( mrDisplay );
player2Paddle->SetFillColor( RGBColor::Red );
player2Paddle->SetVisible( true );

ball = new RectangularShape( mrDisplay );
ball->SetFillColor( RGBColor::Black );
ball->SetVisible( true );

}

void Pong::SharedStartRun() {
State( "BallX" ) = 500;
State( "BallY" ) = 500;
State( "Player1Y" ) = 200;
State( "Player2Y" ) = 800;
State( "BallVX" ) = 493;
State( "BallVY" ) = 497;
State( "GamePhase" ) = 2;
}

void Pong::SharedProcess( const GenericSignal& Input, GenericSignal& Output ) {
if ( State( "GamePhase" ) == 1 ) {
if ( State( "ClientNumber" ) == 0 ) {
State( "BallX" ) = State( "BallX" ) + State( "BallVX" ) - 500;
State( "BallY" ) = State( "BallY" ) + State( "BallVY" ) - 500;

if ( State( "BallY" ) > 950 || State( "BallY" ) < 50 ) {
State( "BallVY" ) = 1000 - State( "BallVY" );
}

if ( State( "BallX" ) + 50 > 875 && State( "BallX" ) - 50 < 925 && State( "BallY" ) + 50 > State( "Player2Y" ) - 100 && State( "BallY" ) - 50 < State( "Player2Y" ) + 100 ) {
State( "BallVX" ) = 1000 - State( "BallVX" );
State( "BallX" ) = 875 - 50;
}

if ( State( "BallX" ) + 50 > 75 && State( "BallX" ) - 50 < 125 && State( "BallY" ) + 50 > State( "Player1Y" ) - 100 && State( "BallY" ) - 50 < State( "Player1Y" ) + 100 ) {
State( "BallVX" ) = 1000 - State( "BallVX" );
State( "BallX" ) = 125 + 50;
}

if ( State( "BallX" ) + 50 > 1000 || State( "BallX" ) - 50 < 0 ) {
State( "BallX" ) = 500;
State( "BallVY" ) = State( "BallVY" ) + 1;
State( "GamePhase" ) = 2;
}
}

if ( CheckKeyPress( "KeyDown", 38 ) ) { //Up
if ( State( "ClientNumber" ) == 0 )
State( "Player1Y" ) = State( "Player1Y" ) - 30;
else
State( "Player2Y" ) = State( "Player2Y" ) - 30;
}

if ( CheckKeyPress( "KeyDown", 40 ) ) { //Down
if ( State( "ClientNumber" ) == 0 )
State( "Player1Y" ) = State( "Player1Y" ) + 30;
else
State( "Player2Y" ) = State( "Player2Y" ) + 30;
}
}

if ( State( "GamePhase" ) == 2 ) {
if ( CheckKeyPress( "KeyDown", 32 ) == 0 ) { //Space
if ( State( "ClientNumber" ) == 0 )
State( "Player1Ready" ) = 1;
else
State( "Player2Ready" ) = 1;
}

if ( State( "Player1Ready" ) == 1 && State( "Player2Ready" ) == 1 ) {
State( "GamePhase" ) = 1;
State( "Player1Ready" ) = 0;
State( "Player2Ready" ) = 0;
}
}

bciout << "Ball: (" << State("BallX") << ", " << State("BallY") << ")";
bciout << "Player1: " << State("Player1Y");

GUI::Rect rect = { ( State( "BallX" ) / 1000.f ) - 0.05, ( State( "BallY" ) / 1000.f ) - 0.05, ( State( "BallX" ) / 1000.f ) + 0.05, ( State( "BallY" ) / 1000.f ) + 0.05 };
ball->SetObjectRect( rect );

rect = { 0.075f, ( State( "Player1Y" ) / 1000.f ) - 0.1f, 0.125f, ( State( "Player1Y" ) / 1000.f ) + 0.1f };
player1Paddle->SetObjectRect( rect );

rect = { 0.875f, ( State( "Player2Y" ) / 1000.f ) - 0.1f, 0.925f, ( State( "Player2Y" ) / 1000.f ) + 0.1f };
player2Paddle->SetObjectRect( rect );

}

bool Pong::CheckKeyPress( std::string event_name, int value ) {
for ( unsigned int i = 0; i < Parameter( "SampleBlockSize" ); i++ ) {
if ( State( event_name )( i ) == value ) {
return true;
}
}
return false;
}
</syntaxhighlight>
pong.h
<syntaxhighlight lang="cpp">
#include "Shapes.h"
#include "ApplicationWindow.h"
#include "HyperscanningApplicationBase.h"

class Pong : public HyperscanningApplicationBase {
public:
Pong();

void SharedPublish() override;

void SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const override;
void SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) override;
void SharedProcess( const GenericSignal& Input, GenericSignal& Output ) override;
void SharedStartRun() override;

bool CheckKeyPress( std::string event_name, int value );

private:
ApplicationWindow& mrDisplay;
RectangularShape* player1Paddle;
RectangularShape* player2Paddle;
RectangularShape* ball;
};
</syntaxhighlight>
and pong.bat
Change directory $BCI2000LAUNCHDIR
Show window; Set title ${Extract file base $0}
Reset system
Startup system localhost
Start executable SignalGenerator --local --LogKeyboard=1
Start executable DummySignalProcessing --local
Start executable Pong --local --Port=1234 --IPAddress=192.168.1.102 --SharedStates=BallX,32&BallY,32&Player1Y,32&Player2Y,32&BallVX,32&BallVY,32&Player1Ready,8&Player2Ready,8&GamePhase,8&Player1Score,8&Player2Score,8
Wait for Connected
Load parameterfile "../parms/CommunicationTask/Communication_task_dual.prm"

This behaves very similarly to the tic-tac-toe example, with the key difference being both clients can interact with states simultaneously, whereas in tic-tac-toe only one client was changing states at a time.

Any processing of game states, for example changing the position of the ball in pong, can occur on either the clients or the server depending on the wants and needs of each implementation. If they are placed on the client side, only one of clients should be responsible for actually processing the data because otherwise there could be multiple versions of the same state that are equally correct, because they were each accurately calculated by a different client, so the server would have to choose one state to save to the master state machine and discard the other versions. This could lead to jumpiness when displaying the state or bugs. Because only one client is processing data, only that client will have a greater load than the others. If the overhead of the game is too significant, this could become problematic. If the processing is done on the server, there will not be an issue with one client running slower, but it will be more tedious to implement, because a custom installation will have to be designed instead of a premade backend application, and a more powerful server will be required.

For turn based games, this is a non-issue because each client can process the game state for their own turn. It only becomes an issue when a game state needs to be calculated that isn't based on client inputs, once again like the movement of the ball in pong, as opposed to the movement of the paddles in pong.

=== Example Server Application ===
application.cpp
<syntaxhighlight lang="cpp">
#include "statemachine.h"
#include "game.h"
#include "port.h"
#include "client.h"
#include "statemachine.h"
#include <iostream>
#include <thread>
#include <chrono>
#include <fstream>
#include <algorithm>
#include <random>
#include "params.h"

int main() {

</syntaxhighlight>
Here we load a general parameter file to ensure that the experiment is the same on each client. We also load a parameter file for an existing game, so we can resume where we left off. We will write to the existing game file in the final section of the application file. If this is the first session, then we will randomly generate a stimuli sequence.

<syntaxhighlight lang="cpp">
// Load Parameter File
Params params = Params( "Parameters.prm" );

// Load previous parameters
Params existing = Params( "ExistingGame.prm" );

std::string stimuliSequence;

// Check if saved parameters from previous game are populated
if ( existing.contents.size() > 0 ) {
params.contents += existing.contents;

stimuliSequence = existing.GetParam( "StimuliSequence" )->line;
} // If they are not then generate them, and they will be saved when this game finishes
else {
// Generate Random Sequence

Param* stimmat = params.GetParam( "StimuliMatrix" );

std::vector<int> order = std::vector<int>( stimmat->width );
for ( int i = 0; i < stimmat->width; i++ )
order[ i ] = i;

std::random_device rd;
auto rng = std::default_random_engine( rd() );
std::shuffle( std::begin( order ), std::end( order ), rng );

stimuliSequence = "\nApplication:Sequence intlist StimuliSequence= ";
stimuliSequence += std::to_string( stimmat->width );
stimuliSequence += " ";
for ( int i = 0; i < stimmat->width; i++ ) {
stimuliSequence += std::to_string( order[ i ] );
stimuliSequence += " ";
}
stimuliSequence += "% % % //Random Stimuli Sequence";

params.AddParam( stimuliSequence );

params.AddParam( "Application int InitialTrialNumber= 0 % % % // trial number" );
}

params.contents.push_back( 0 );
</syntaxhighlight>

This is the only necessary part of the main function. Here we open the port for listening, connect to the clients, and start the loop.
<syntaxhighlight lang="cpp">
//Open the port for listening
Port port( 1234, 100 );
if ( !port.open )
return 0;
std::cout << "Connected to port " << 1234 << std::endl;

// Initialize Game class
Game game = Game( port, params.contents );

std::cout << "Waiting for clients" << std::endl;

// Wait for a client to open a socket connection then connect them to the game
Client* client1 = port.WaitForClient();
game.Connect( client1 );

std::cout << "Connected to first client" << std::endl;
std::cout << "Waiting for second client" << std::endl;

// Do the same for a second client
game.Connect( port.WaitForClient() );

std::cout << "Connected to second client" << std::endl;

// Run the server loop and save the final states
StateMachine out_states = game.Loop();
</syntaxhighlight>

Here we take data from the master state machine and save it to the existing game parameter file, so we can use it when we restart the paradigm.

<syntaxhighlight lang="cpp">
// Save the trial number from when the paradigm was ended
std::string InitialTrialNumber = out_states.GetState( "TrialNumber" );
std::cout << "Trial Number: " << InitialTrialNumber << std::endl;

// Make sure that the trial number is populated and subtract one to repeat the unfinished trial
if ( InitialTrialNumber.size() == 0 ) InitialTrialNumber = "\1";
std::cout << "Saving Trial Number: " << ( int ) *InitialTrialNumber.c_str() - 1 << std::endl;

// Save Initial Trial Number and random stimuli sequence
std::ofstream egof( "ExistingGame.prm" );
egof << "Application int InitialTrialNumber= " << ( int )*InitialTrialNumber.c_str() - 1 << " % % % // trial number" << std::endl;
egof << stimuliSequence << std::endl;

// All Done!
std::cout << "All done!" << std::endl;
}
</syntaxhighlight>

== Important Notes ==
The server must be configured to allow inbound TCP traffic. Most only server services, like AWS or Azure, will allow you to do this easily.

In AWS:
# Select an instance
# Go to the "Security" tab
# Select one of the security groups
# With one of the security groups selected, go to the "inbound rules" tab
# Press "edit inbound rules"
# Press "Add Rule"
# Set "Type" to "Any TCP"
# Set "Source" to the IP Addresses of each of your clients or to "Anywhere IPv4"
# Press "Save Rules"

To create an instance in AWS:
# Go to [aws.amazon.com/ec2|AWS] and create an account or log in
# Press "Launch Instance"
# Give your instance a name
# Select "Amazon Linux" or any other non-windows operating system of your choice
# Select the tier of server you would like. If you are doing the processing on the clients then the free-tier or cheapest option will suffice with no performance penalties. If you followed the example server application, then you are doing the processing on the clients. If you are doing processing on the server, then select whichever performance tier is necessary to run your application at an acceptable speed.
# Under Key Pair, press "Create New Key Pair"
# Name is whatever you would like
# Select RSA for key pair type
# Select .pem for private key file format
# Press create key pair and remember where you save it to. We will need to use this to connect to the server.
# Now press "Launch Instance"

To configure and run your aws instance (if it isn't an aws instance the same applies, except instead of "ec2-user" you will use the username for your server or if it is local ignore the ssh step):
Open a terminal or shell
Enter the command
ssh -i </path/key-pair-name.pem> ec2-user@<public-IPv4-address>
The public IPv4 address can be found by selecting the instance in the instance dashboard. If you do not see one, ensure that the instance is running.
If prompted with
The authenticity of host 'ec2-198-51-100-1.compute-1.amazonaws.com (198-51-100-1)' can't be established.
ECDSA key fingerprint is l4UB/neBad9tvkgJf1QZWxheQmR59WgrgzEimCG6kZY.
Are you sure you want to continue connecting (yes/no)?
Type
yes
Clone the github repository with
git clone https://github.com/MaxwellMarcus/hyperscanning-backend
Go to the directory
cd hyperscanning-backend
Edit or create an application in the file application.cpp, if you aren't using the default tutorial application file
Build the application with
make
If you are working on remote servers over SSH. Please use the command "screen", which keeps the server running even if you disconnect.
Creat a screen called dual
screen -S dual

Run the application with
./application
The application will only run as long as the experiment and will have to be restarted.

Contributions:CommunicationTask

2025-04-29T20:12:39Z

Lingling: /* Deploy the Server */

==Synopsis==
The hyperscanning task is a turn-based communication game between two clients. This game aims to guess what the subject is in Sender's computer without talking. For each trial, the two players will alternate between the roles of Sender and Receiver. The Sender will describe traits of the subject presented by adjusting the two axes(Noisy or silent/Big or small). Then, the Receiver will guess if the Sender is describing the animal or object. After the Receiver makes a guess, both players receive feedback on whether the Receiver makes the correct guess. This marks the end of a trial.

The two clients exchange information through the hyperScanning backend, which uses a client-server model to share the states. Each client has a separate state machine. The server only forwards the information between two clients. Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class, which is the parent class of the application module. For more information, please refer to the hyperScanning framework wiki page: https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning.

==Video Overview==
 
<youtube alignment="center">https://youtu.be/I1sSamSsTK4</youtube>
 

==Timeline==
<gallery mode="packed" widths=600px heights=500px>
File:Hyperscanning pipe line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=750px heights=421px>
File:Hyperscanning_1.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Anais Llorens (anaisllorens@hotmail.com) and Athina Tzovara (athina.tzovara@unibe.ch) conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org), Max Marcus (bigmaxmarcus@gmail.com) and Sigurd Alnes (sigurd.alnes@unibe.ch) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
To run the server, you’ll need a Linux or macOS machine—Windows is not supported at this time. The steps below walk you through deploying the server on AWS. 
1. Prepare the AWS key. 

2. In your terminal or shell, run 
<pre> chmod 400 <key_path> </pre>
to make the key file read-only for the owner. 

3. Connect to the AWS server using SSH: 
<pre> ssh -i <key path> <user-name>@<ip-address> </pre>

4. Pull the code from GitHub. 
<pre>git clone https://github.com/neurotechcenter/hyperscanning-backend</pre>

5. Navigate to the server directory: 
<pre>cd hyperscanning-backend</pre>

6. To compile the project, run:
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>

5. Launch the server by running: 
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application must be restarted after BCI2000 has been closed.
 

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:CommunicationTask batch.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====StimuliMatrix====
Shared parameter, matrix of stimulus information, including: 
1. ImageReceiver and ImageSender(the path of images). 
2. Sender(the role of players),1 is the sender), 2 is the receiver. 
3. Jitter(the duration to present the role). 
4. CorrectResponse(1: left, 2:right). 
5. Training(1: training, 0: main task). 
6. Category(1: object, 2: animal). 
7. Difficulty(1: easy, 2: moderate, 3: hard). 
8. Dimension1a and Dimension1b(bar#1 left text and right text). 
9. Dimension2a and Dimension2b(bar#2 left text and right text). 
10. Option1 and Option2(left option text and right option text).

====BreakTrialSequece====
The sequence of break trials, a break will happen after the break trial.

====FeedbackDuration====
Duration of feedback(ITI). Indicate the receiver to make a correct or incorrect guess. 

The server will generate the InitialTrialNumber and StimuliSequence, and save them into a parameter file named by IP addresses on the server. You don't need to worry about these two parameters. Unlike the parameters described above, they are saved on the server rather than on local computers.

====InitialTrialNumber====
The trial number to begin with. We provide the resume option, allowing clients to pause and resume the game from where they stop. After one of the clients quits the game, the server will discover it and save the current trial number and sequence. When the same clients(same IP address) reconnect the server again, the server will send the previous trial number to them. Otherwise, the InitialTrailNumber will be initialized by 0. Usually, you don't need to touch this parameter.

====StimuliSequence====
The sequence of stimuli(images). The server will generate a random stimuli sequence for every pair of clients (identified by the IP address).

===Local Parameters===

====StimuliWidth====
StimulusWidth in percent of screen width (zero for original pixel size).

====InstructionImagesSeque====
The sequence of instruction images path.

====InstructionWidth====
Instruction width in percent of screen width (zero for original pixel size).

====SliderWidth====
SliderWidth in percent of screen width (zero for original pixel size).

====BarColor====
Color of the slider bar.

====AxeActiveColor====
Color of active slider axe.

====AxeInActiveColor====
Color of inactive slider axe.

====DimensionFontColor====
Color of the text under the slider.

====DimensionHeight====
Height of text in percent of the screen height.

====OptionFontActiveColor====
Color of the active options.

====OptionFontInActiveColor====
Color of the inactive options.

====OptionHeight====
Height of text in percent of the screen height.

====RoleFontColor====
Color of the role text.

====RoleHeight====
Height of text in percent of the screen height.

====FeedbackWidth====
Width of feedback in percent of screen width.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===PhaseNumber===
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the 10 slides instruction images are present on the screen) 
[1] indicates the client is waiting for the other client to push the button to start the game. ( We are waiting for another player; once she/he is ready, we're ready to go!) 
[2] When the role text is present on the screen.(Sender or Receiver). 
[3] When the sliders and stimulus are present on the screen. 
[4] Feedback: After the receiver locks the answer, it comes to phase [4], showing whether the answer is correct. 
[5]Break: (Well done! Are you ready for the next block? \n\n Press SPACEBAR) 
[6]End: (Well done! You have finished all the trials.)

===TrialNumber===
Index of trials. (8 bits)

===StimulusCode===
The stimulus ID

===Photodiode===
The photodiode state. 1: flash, 0: no flash

===SampleBlockCounter===
Count the block number in one phase

===BarOneValue===
Value of slider#1. (32 bits)

===BarTwoValue===
Value of slider#2. (32 bits)

===BarOneActive, BarTwoActive===
0: slider is not selected. 1: slider is selected. (8 bits)

===ResponseValue===
1: object. 2: animal. (8 bits)

===SenderLock, ReceiverLock===
0: client is moving the slider/making a guess. 1: client has locked the answer. (8 bits)

===isReadyStart0, isReadyStart1===
0: client isn't ready to start/resume/continue the game(not yet pushing the button). 1: client is ready to start/resume/continue the game(push the button). (8 bits)

===ClientNumber===
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits)

==Example==
The hyperscanning application module is almost the same as a BCI2000 application module, except that the typical BCI2000 module is inherited from ApplicationBase, and the hyperscanning application module is inherited from HyperscanningApplicationBase. Basically, the HyperscanningApplicationBase class is the same as ApplicationBase class with adding the communication with the server. So instead of using Publish, Preflight, Process, etc. We are using SharedPublish, SharedPreflight, SharedProcess, etc. These methods behave in the exact same way, except they also call the client loops which interact with the server.

Communication_task_dualTask.h:
<pre>
#include "ApplicationBase.h"
#include "Slider.h"
#include <map>
#include <vector>
#include <string>
#include "TextStimulus.h"
#include "ImageStimulus.h"
#include "Shapes.h"
#include "HyperscanningApplicationBase.h"

class Communication_task_dualTask : public HyperscanningApplicationBase
{
public:
Communication_task_dualTask();
~Communication_task_dualTask();
void SharedPublish() override;
void SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const override;
void SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) override;
void SharedAutoConfig( const SignalProperties& Input ) override;
void SharedStartRun() override;
void SharedProcess( const GenericSignal& Input, GenericSignal& Output ) override;
void SharedStopRun() override;
void SharedHalt() override;

private:
//define your own private members here
ApplicationWindow& mrDisplay;

//define your own private methods here

};
</pre>

Manipulate the shared state is the same as the BCI2000 state. "isReadyStart1" is a shared state.
<pre>
State("isReadyStart1") = 1; // assign 1 to "isReadyStart1"
</pre>

Get the value of the shared state "isReadyStart1"
<pre>
//Both of the two players are ready, move to the next phase
if (State("isReadyStart0") && State("isReadyStart1")) {
m_instruction_container->Conceal();
m_role_txt->Conceal();
my_phase = role_text;
m_block_in_phase = 0;
}
</pre>

Contributions:CommunicationTask

2025-04-24T16:26:20Z

Lingling: /* TrialNumber */

==Synopsis==
The hyperscanning task is a turn-based communication game between two clients. This game aims to guess what the subject is in Sender's computer without talking. For each trial, the two players will alternate between the roles of Sender and Receiver. The Sender will describe traits of the subject presented by adjusting the two axes(Noisy or silent/Big or small). Then, the Receiver will guess if the Sender is describing the animal or object. After the Receiver makes a guess, both players receive feedback on whether the Receiver makes the correct guess. This marks the end of a trial.

The two clients exchange information through the hyperScanning backend, which uses a client-server model to share the states. Each client has a separate state machine. The server only forwards the information between two clients. Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class, which is the parent class of the application module. For more information, please refer to the hyperScanning framework wiki page: https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning.

==Video Overview==
 
<youtube alignment="center">https://youtu.be/I1sSamSsTK4</youtube>
 

==Timeline==
<gallery mode="packed" widths=600px heights=500px>
File:Hyperscanning pipe line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=750px heights=421px>
File:Hyperscanning_1.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Anais Llorens (anaisllorens@hotmail.com) and Athina Tzovara (athina.tzovara@unibe.ch) conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org), Max Marcus (bigmaxmarcus@gmail.com) and Sigurd Alnes (sigurd.alnes@unibe.ch) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
To run the server, you’ll need a Linux or macOS machine—Windows is not supported at this time. The steps below walk you through deploying the server on AWS. 
1. Prepare the AWS key. 

2. In your terminal or shell, run 
<pre> chmod 400 <key_path> </pre>
to make the key file read-only for the owner. 

3. Connect to the AWS server using SSH: 
<pre> ssh -i <key path> <user-name>@<ip-address> </pre>

4. Pull the code from GitHub. 
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>

5. Navigate to the server directory: 
<pre>cd hyperscanning-backend</pre>

6. To compile the project, run:
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>

5. Launch the server by running: 
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application must be restarted after BCI2000 has been closed.
 

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:CommunicationTask batch.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====StimuliMatrix====
Shared parameter, matrix of stimulus information, including: 
1. ImageReceiver and ImageSender(the path of images). 
2. Sender(the role of players),1 is the sender), 2 is the receiver. 
3. Jitter(the duration to present the role). 
4. CorrectResponse(1: left, 2:right). 
5. Training(1: training, 0: main task). 
6. Category(1: object, 2: animal). 
7. Difficulty(1: easy, 2: moderate, 3: hard). 
8. Dimension1a and Dimension1b(bar#1 left text and right text). 
9. Dimension2a and Dimension2b(bar#2 left text and right text). 
10. Option1 and Option2(left option text and right option text).

====BreakTrialSequece====
The sequence of break trials, a break will happen after the break trial.

====FeedbackDuration====
Duration of feedback(ITI). Indicate the receiver to make a correct or incorrect guess. 

The server will generate the InitialTrialNumber and StimuliSequence, and save them into a parameter file named by IP addresses on the server. You don't need to worry about these two parameters. Unlike the parameters described above, they are saved on the server rather than on local computers.

====InitialTrialNumber====
The trial number to begin with. We provide the resume option, allowing clients to pause and resume the game from where they stop. After one of the clients quits the game, the server will discover it and save the current trial number and sequence. When the same clients(same IP address) reconnect the server again, the server will send the previous trial number to them. Otherwise, the InitialTrailNumber will be initialized by 0. Usually, you don't need to touch this parameter.

====StimuliSequence====
The sequence of stimuli(images). The server will generate a random stimuli sequence for every pair of clients (identified by the IP address).

===Local Parameters===

====StimuliWidth====
StimulusWidth in percent of screen width (zero for original pixel size).

====InstructionImagesSeque====
The sequence of instruction images path.

====InstructionWidth====
Instruction width in percent of screen width (zero for original pixel size).

====SliderWidth====
SliderWidth in percent of screen width (zero for original pixel size).

====BarColor====
Color of the slider bar.

====AxeActiveColor====
Color of active slider axe.

====AxeInActiveColor====
Color of inactive slider axe.

====DimensionFontColor====
Color of the text under the slider.

====DimensionHeight====
Height of text in percent of the screen height.

====OptionFontActiveColor====
Color of the active options.

====OptionFontInActiveColor====
Color of the inactive options.

====OptionHeight====
Height of text in percent of the screen height.

====RoleFontColor====
Color of the role text.

====RoleHeight====
Height of text in percent of the screen height.

====FeedbackWidth====
Width of feedback in percent of screen width.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===PhaseNumber===
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the 10 slides instruction images are present on the screen) 
[1] indicates the client is waiting for the other client to push the button to start the game. ( We are waiting for another player; once she/he is ready, we're ready to go!) 
[2] When the role text is present on the screen.(Sender or Receiver). 
[3] When the sliders and stimulus are present on the screen. 
[4] Feedback: After the receiver locks the answer, it comes to phase [4], showing whether the answer is correct. 
[5]Break: (Well done! Are you ready for the next block? \n\n Press SPACEBAR) 
[6]End: (Well done! You have finished all the trials.)

===TrialNumber===
Index of trials. (8 bits)

===StimulusCode===
The stimulus ID

===Photodiode===
The photodiode state. 1: flash, 0: no flash

===SampleBlockCounter===
Count the block number in one phase

===BarOneValue===
Value of slider#1. (32 bits)

===BarTwoValue===
Value of slider#2. (32 bits)

===BarOneActive, BarTwoActive===
0: slider is not selected. 1: slider is selected. (8 bits)

===ResponseValue===
1: object. 2: animal. (8 bits)

===SenderLock, ReceiverLock===
0: client is moving the slider/making a guess. 1: client has locked the answer. (8 bits)

===isReadyStart0, isReadyStart1===
0: client isn't ready to start/resume/continue the game(not yet pushing the button). 1: client is ready to start/resume/continue the game(push the button). (8 bits)

===ClientNumber===
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits)

==Example==
The hyperscanning application module is almost the same as a BCI2000 application module, except that the typical BCI2000 module is inherited from ApplicationBase, and the hyperscanning application module is inherited from HyperscanningApplicationBase. Basically, the HyperscanningApplicationBase class is the same as ApplicationBase class with adding the communication with the server. So instead of using Publish, Preflight, Process, etc. We are using SharedPublish, SharedPreflight, SharedProcess, etc. These methods behave in the exact same way, except they also call the client loops which interact with the server.

Communication_task_dualTask.h:
<pre>
#include "ApplicationBase.h"
#include "Slider.h"
#include <map>
#include <vector>
#include <string>
#include "TextStimulus.h"
#include "ImageStimulus.h"
#include "Shapes.h"
#include "HyperscanningApplicationBase.h"

class Communication_task_dualTask : public HyperscanningApplicationBase
{
public:
Communication_task_dualTask();
~Communication_task_dualTask();
void SharedPublish() override;
void SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const override;
void SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) override;
void SharedAutoConfig( const SignalProperties& Input ) override;
void SharedStartRun() override;
void SharedProcess( const GenericSignal& Input, GenericSignal& Output ) override;
void SharedStopRun() override;
void SharedHalt() override;

private:
//define your own private members here
ApplicationWindow& mrDisplay;

//define your own private methods here

};
</pre>

Manipulate the shared state is the same as the BCI2000 state. "isReadyStart1" is a shared state.
<pre>
State("isReadyStart1") = 1; // assign 1 to "isReadyStart1"
</pre>

Get the value of the shared state "isReadyStart1"
<pre>
//Both of the two players are ready, move to the next phase
if (State("isReadyStart0") && State("isReadyStart1")) {
m_instruction_container->Conceal();
m_role_txt->Conceal();
my_phase = role_text;
m_block_in_phase = 0;
}
</pre>

Contributions:CommunicationTask

2025-04-23T16:39:06Z

Lingling: /* Deploy the Server */

==Synopsis==
The hyperscanning task is a turn-based communication game between two clients. This game aims to guess what the subject is in Sender's computer without talking. For each trial, the two players will alternate between the roles of Sender and Receiver. The Sender will describe traits of the subject presented by adjusting the two axes(Noisy or silent/Big or small). Then, the Receiver will guess if the Sender is describing the animal or object. After the Receiver makes a guess, both players receive feedback on whether the Receiver makes the correct guess. This marks the end of a trial.

The two clients exchange information through the hyperScanning backend, which uses a client-server model to share the states. Each client has a separate state machine. The server only forwards the information between two clients. Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class, which is the parent class of the application module. For more information, please refer to the hyperScanning framework wiki page: https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning.

==Video Overview==
 
<youtube alignment="center">https://youtu.be/I1sSamSsTK4</youtube>
 

==Timeline==
<gallery mode="packed" widths=600px heights=500px>
File:Hyperscanning pipe line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=750px heights=421px>
File:Hyperscanning_1.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Anais Llorens (anaisllorens@hotmail.com) and Athina Tzovara (athina.tzovara@unibe.ch) conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org), Max Marcus (bigmaxmarcus@gmail.com) and Sigurd Alnes (sigurd.alnes@unibe.ch) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
To run the server, you’ll need a Linux or macOS machine—Windows is not supported at this time. The steps below walk you through deploying the server on AWS. 
1. Prepare the AWS key. 

2. In your terminal or shell, run 
<pre> chmod 400 <key_path> </pre>
to make the key file read-only for the owner. 

3. Connect to the AWS server using SSH: 
<pre> ssh -i <key path> <user-name>@<ip-address> </pre>

4. Pull the code from GitHub. 
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>

5. Navigate to the server directory: 
<pre>cd hyperscanning-backend</pre>

6. To compile the project, run:
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>

5. Launch the server by running: 
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application must be restarted after BCI2000 has been closed.
 

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:CommunicationTask batch.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====StimuliMatrix====
Shared parameter, matrix of stimulus information, including: 
1. ImageReceiver and ImageSender(the path of images). 
2. Sender(the role of players),1 is the sender), 2 is the receiver. 
3. Jitter(the duration to present the role). 
4. CorrectResponse(1: left, 2:right). 
5. Training(1: training, 0: main task). 
6. Category(1: object, 2: animal). 
7. Difficulty(1: easy, 2: moderate, 3: hard). 
8. Dimension1a and Dimension1b(bar#1 left text and right text). 
9. Dimension2a and Dimension2b(bar#2 left text and right text). 
10. Option1 and Option2(left option text and right option text).

====BreakTrialSequece====
The sequence of break trials, a break will happen after the break trial.

====FeedbackDuration====
Duration of feedback(ITI). Indicate the receiver to make a correct or incorrect guess. 

The server will generate the InitialTrialNumber and StimuliSequence, and save them into a parameter file named by IP addresses on the server. You don't need to worry about these two parameters. Unlike the parameters described above, they are saved on the server rather than on local computers.

====InitialTrialNumber====
The trial number to begin with. We provide the resume option, allowing clients to pause and resume the game from where they stop. After one of the clients quits the game, the server will discover it and save the current trial number and sequence. When the same clients(same IP address) reconnect the server again, the server will send the previous trial number to them. Otherwise, the InitialTrailNumber will be initialized by 0. Usually, you don't need to touch this parameter.

====StimuliSequence====
The sequence of stimuli(images). The server will generate a random stimuli sequence for every pair of clients (identified by the IP address).

===Local Parameters===

====StimuliWidth====
StimulusWidth in percent of screen width (zero for original pixel size).

====InstructionImagesSeque====
The sequence of instruction images path.

====InstructionWidth====
Instruction width in percent of screen width (zero for original pixel size).

====SliderWidth====
SliderWidth in percent of screen width (zero for original pixel size).

====BarColor====
Color of the slider bar.

====AxeActiveColor====
Color of active slider axe.

====AxeInActiveColor====
Color of inactive slider axe.

====DimensionFontColor====
Color of the text under the slider.

====DimensionHeight====
Height of text in percent of the screen height.

====OptionFontActiveColor====
Color of the active options.

====OptionFontInActiveColor====
Color of the inactive options.

====OptionHeight====
Height of text in percent of the screen height.

====RoleFontColor====
Color of the role text.

====RoleHeight====
Height of text in percent of the screen height.

====FeedbackWidth====
Width of feedback in percent of screen width.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===PhaseNumber===
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the 10 slides instruction images are present on the screen) 
[1] indicates the client is waiting for the other client to push the button to start the game. ( We are waiting for another player; once she/he is ready, we're ready to go!) 
[2] When the role text is present on the screen.(Sender or Receiver). 
[3] When the sliders and stimulus are present on the screen. 
[4] Feedback: After the receiver locks the answer, it comes to phase [4], showing whether the answer is correct. 
[5]Break: (Well done! Are you ready for the next block? \n\n Press SPACEBAR) 
[6]End: (Well done! You have finished all the trials.)

===TrialNumber===
Index of trials. (8 bits)

===BarOneValue===
Value of slider#1. (32 bits)

===BarTwoValue===
Value of slider#2. (32 bits)

===BarOneActive, BarTwoActive===
0: slider is not selected. 1: slider is selected. (8 bits)

===ResponseValue===
1: object. 2: animal. (8 bits)

===SenderLock, ReceiverLock===
0: client is moving the slider/making a guess. 1: client has locked the answer. (8 bits)

===isReadyStart0, isReadyStart1===
0: client isn't ready to start/resume/continue the game(not yet pushing the button). 1: client is ready to start/resume/continue the game(push the button). (8 bits)

===ClientNumber===
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits)

==Example==
The hyperscanning application module is almost the same as a BCI2000 application module, except that the typical BCI2000 module is inherited from ApplicationBase, and the hyperscanning application module is inherited from HyperscanningApplicationBase. Basically, the HyperscanningApplicationBase class is the same as ApplicationBase class with adding the communication with the server. So instead of using Publish, Preflight, Process, etc. We are using SharedPublish, SharedPreflight, SharedProcess, etc. These methods behave in the exact same way, except they also call the client loops which interact with the server.

Communication_task_dualTask.h:
<pre>
#include "ApplicationBase.h"
#include "Slider.h"
#include <map>
#include <vector>
#include <string>
#include "TextStimulus.h"
#include "ImageStimulus.h"
#include "Shapes.h"
#include "HyperscanningApplicationBase.h"

class Communication_task_dualTask : public HyperscanningApplicationBase
{
public:
Communication_task_dualTask();
~Communication_task_dualTask();
void SharedPublish() override;
void SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const override;
void SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) override;
void SharedAutoConfig( const SignalProperties& Input ) override;
void SharedStartRun() override;
void SharedProcess( const GenericSignal& Input, GenericSignal& Output ) override;
void SharedStopRun() override;
void SharedHalt() override;

private:
//define your own private members here
ApplicationWindow& mrDisplay;

//define your own private methods here

};
</pre>

Manipulate the shared state is the same as the BCI2000 state. "isReadyStart1" is a shared state.
<pre>
State("isReadyStart1") = 1; // assign 1 to "isReadyStart1"
</pre>

Get the value of the shared state "isReadyStart1"
<pre>
//Both of the two players are ready, move to the next phase
if (State("isReadyStart0") && State("isReadyStart1")) {
m_instruction_container->Conceal();
m_role_txt->Conceal();
my_phase = role_text;
m_block_in_phase = 0;
}
</pre>

Contributions:CommunicationTask

2025-04-23T15:16:16Z

Lingling: /* Deploy the Server */

==Synopsis==
The hyperscanning task is a turn-based communication game between two clients. This game aims to guess what the subject is in Sender's computer without talking. For each trial, the two players will alternate between the roles of Sender and Receiver. The Sender will describe traits of the subject presented by adjusting the two axes(Noisy or silent/Big or small). Then, the Receiver will guess if the Sender is describing the animal or object. After the Receiver makes a guess, both players receive feedback on whether the Receiver makes the correct guess. This marks the end of a trial.

The two clients exchange information through the hyperScanning backend, which uses a client-server model to share the states. Each client has a separate state machine. The server only forwards the information between two clients. Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class, which is the parent class of the application module. For more information, please refer to the hyperScanning framework wiki page: https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning.

==Video Overview==
 
<youtube alignment="center">https://youtu.be/I1sSamSsTK4</youtube>
 

==Timeline==
<gallery mode="packed" widths=600px heights=500px>
File:Hyperscanning pipe line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=750px heights=421px>
File:Hyperscanning_1.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Anais Llorens (anaisllorens@hotmail.com) and Athina Tzovara (athina.tzovara@unibe.ch) conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org), Max Marcus (bigmaxmarcus@gmail.com) and Sigurd Alnes (sigurd.alnes@unibe.ch) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
To run the server, you’ll need a Linux or macOS machine—Windows is not supported at this time. The steps below walk you through deploying the server on AWS. 
1. Prepare the SSH key. 

2. In your terminal or shell, run 
<pre> chmod 400 <key_path> </pre>
to make the key file read-only for the owner. 

3. Connect to the AWS server using SSH: 
<pre> ssh -i <key path> <user-name>@<ip-address> </pre>

4. Pull the code from GitHub. 
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>

5. Navigate to the server directory: 
<pre>cd hyperscanning-backend</pre>

6. To compile the project, run:
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>

5. Launch the server by running: 
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application must be restarted after BCI2000 has been closed.
 

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:CommunicationTask batch.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====StimuliMatrix====
Shared parameter, matrix of stimulus information, including: 
1. ImageReceiver and ImageSender(the path of images). 
2. Sender(the role of players),1 is the sender), 2 is the receiver. 
3. Jitter(the duration to present the role). 
4. CorrectResponse(1: left, 2:right). 
5. Training(1: training, 0: main task). 
6. Category(1: object, 2: animal). 
7. Difficulty(1: easy, 2: moderate, 3: hard). 
8. Dimension1a and Dimension1b(bar#1 left text and right text). 
9. Dimension2a and Dimension2b(bar#2 left text and right text). 
10. Option1 and Option2(left option text and right option text).

====BreakTrialSequece====
The sequence of break trials, a break will happen after the break trial.

====FeedbackDuration====
Duration of feedback(ITI). Indicate the receiver to make a correct or incorrect guess. 

The server will generate the InitialTrialNumber and StimuliSequence, and save them into a parameter file named by IP addresses on the server. You don't need to worry about these two parameters. Unlike the parameters described above, they are saved on the server rather than on local computers.

====InitialTrialNumber====
The trial number to begin with. We provide the resume option, allowing clients to pause and resume the game from where they stop. After one of the clients quits the game, the server will discover it and save the current trial number and sequence. When the same clients(same IP address) reconnect the server again, the server will send the previous trial number to them. Otherwise, the InitialTrailNumber will be initialized by 0. Usually, you don't need to touch this parameter.

====StimuliSequence====
The sequence of stimuli(images). The server will generate a random stimuli sequence for every pair of clients (identified by the IP address).

===Local Parameters===

====StimuliWidth====
StimulusWidth in percent of screen width (zero for original pixel size).

====InstructionImagesSeque====
The sequence of instruction images path.

====InstructionWidth====
Instruction width in percent of screen width (zero for original pixel size).

====SliderWidth====
SliderWidth in percent of screen width (zero for original pixel size).

====BarColor====
Color of the slider bar.

====AxeActiveColor====
Color of active slider axe.

====AxeInActiveColor====
Color of inactive slider axe.

====DimensionFontColor====
Color of the text under the slider.

====DimensionHeight====
Height of text in percent of the screen height.

====OptionFontActiveColor====
Color of the active options.

====OptionFontInActiveColor====
Color of the inactive options.

====OptionHeight====
Height of text in percent of the screen height.

====RoleFontColor====
Color of the role text.

====RoleHeight====
Height of text in percent of the screen height.

====FeedbackWidth====
Width of feedback in percent of screen width.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===PhaseNumber===
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the 10 slides instruction images are present on the screen) 
[1] indicates the client is waiting for the other client to push the button to start the game. ( We are waiting for another player; once she/he is ready, we're ready to go!) 
[2] When the role text is present on the screen.(Sender or Receiver). 
[3] When the sliders and stimulus are present on the screen. 
[4] Feedback: After the receiver locks the answer, it comes to phase [4], showing whether the answer is correct. 
[5]Break: (Well done! Are you ready for the next block? \n\n Press SPACEBAR) 
[6]End: (Well done! You have finished all the trials.)

===TrialNumber===
Index of trials. (8 bits)

===BarOneValue===
Value of slider#1. (32 bits)

===BarTwoValue===
Value of slider#2. (32 bits)

===BarOneActive, BarTwoActive===
0: slider is not selected. 1: slider is selected. (8 bits)

===ResponseValue===
1: object. 2: animal. (8 bits)

===SenderLock, ReceiverLock===
0: client is moving the slider/making a guess. 1: client has locked the answer. (8 bits)

===isReadyStart0, isReadyStart1===
0: client isn't ready to start/resume/continue the game(not yet pushing the button). 1: client is ready to start/resume/continue the game(push the button). (8 bits)

===ClientNumber===
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits)

==Example==
The hyperscanning application module is almost the same as a BCI2000 application module, except that the typical BCI2000 module is inherited from ApplicationBase, and the hyperscanning application module is inherited from HyperscanningApplicationBase. Basically, the HyperscanningApplicationBase class is the same as ApplicationBase class with adding the communication with the server. So instead of using Publish, Preflight, Process, etc. We are using SharedPublish, SharedPreflight, SharedProcess, etc. These methods behave in the exact same way, except they also call the client loops which interact with the server.

Communication_task_dualTask.h:
<pre>
#include "ApplicationBase.h"
#include "Slider.h"
#include <map>
#include <vector>
#include <string>
#include "TextStimulus.h"
#include "ImageStimulus.h"
#include "Shapes.h"
#include "HyperscanningApplicationBase.h"

class Communication_task_dualTask : public HyperscanningApplicationBase
{
public:
Communication_task_dualTask();
~Communication_task_dualTask();
void SharedPublish() override;
void SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const override;
void SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) override;
void SharedAutoConfig( const SignalProperties& Input ) override;
void SharedStartRun() override;
void SharedProcess( const GenericSignal& Input, GenericSignal& Output ) override;
void SharedStopRun() override;
void SharedHalt() override;

private:
//define your own private members here
ApplicationWindow& mrDisplay;

//define your own private methods here

};
</pre>

Manipulate the shared state is the same as the BCI2000 state. "isReadyStart1" is a shared state.
<pre>
State("isReadyStart1") = 1; // assign 1 to "isReadyStart1"
</pre>

Get the value of the shared state "isReadyStart1"
<pre>
//Both of the two players are ready, move to the next phase
if (State("isReadyStart0") && State("isReadyStart1")) {
m_instruction_container->Conceal();
m_role_txt->Conceal();
my_phase = role_text;
m_block_in_phase = 0;
}
</pre>

Contributions:CommunicationTask

2025-04-23T15:11:57Z

Lingling: /* Versioning */

==Synopsis==
The hyperscanning task is a turn-based communication game between two clients. This game aims to guess what the subject is in Sender's computer without talking. For each trial, the two players will alternate between the roles of Sender and Receiver. The Sender will describe traits of the subject presented by adjusting the two axes(Noisy or silent/Big or small). Then, the Receiver will guess if the Sender is describing the animal or object. After the Receiver makes a guess, both players receive feedback on whether the Receiver makes the correct guess. This marks the end of a trial.

The two clients exchange information through the hyperScanning backend, which uses a client-server model to share the states. Each client has a separate state machine. The server only forwards the information between two clients. Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class, which is the parent class of the application module. For more information, please refer to the hyperScanning framework wiki page: https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning.

==Video Overview==
 
<youtube alignment="center">https://youtu.be/I1sSamSsTK4</youtube>
 

==Timeline==
<gallery mode="packed" widths=600px heights=500px>
File:Hyperscanning pipe line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=750px heights=421px>
File:Hyperscanning_1.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Anais Llorens (anaisllorens@hotmail.com) and Athina Tzovara (athina.tzovara@unibe.ch) conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org), Max Marcus (bigmaxmarcus@gmail.com) and Sigurd Alnes (sigurd.alnes@unibe.ch) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps outline the process for deploying the server on AWS. 
1. Prepare the SSH key. 

2. In your terminal or shell, run 
<pre> chmod 400 <key_path> </pre>
to make the key file read-only for the owner. 

3. Connect to the AWS server using SSH: 
<pre> ssh -i <key path> <user-name>@<ip-address> </pre>

4. Pull the code from GitHub. 
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>

5. Navigate to the server directory: 
<pre>cd hyperscanning-backend</pre>

6. To compile the project, run:
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>

5. Launch the server by running: 
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application must be restarted after BCI2000 has been closed.
 

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:CommunicationTask batch.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====StimuliMatrix====
Shared parameter, matrix of stimulus information, including: 
1. ImageReceiver and ImageSender(the path of images). 
2. Sender(the role of players),1 is the sender), 2 is the receiver. 
3. Jitter(the duration to present the role). 
4. CorrectResponse(1: left, 2:right). 
5. Training(1: training, 0: main task). 
6. Category(1: object, 2: animal). 
7. Difficulty(1: easy, 2: moderate, 3: hard). 
8. Dimension1a and Dimension1b(bar#1 left text and right text). 
9. Dimension2a and Dimension2b(bar#2 left text and right text). 
10. Option1 and Option2(left option text and right option text).

====BreakTrialSequece====
The sequence of break trials, a break will happen after the break trial.

====FeedbackDuration====
Duration of feedback(ITI). Indicate the receiver to make a correct or incorrect guess. 

The server will generate the InitialTrialNumber and StimuliSequence, and save them into a parameter file named by IP addresses on the server. You don't need to worry about these two parameters. Unlike the parameters described above, they are saved on the server rather than on local computers.

====InitialTrialNumber====
The trial number to begin with. We provide the resume option, allowing clients to pause and resume the game from where they stop. After one of the clients quits the game, the server will discover it and save the current trial number and sequence. When the same clients(same IP address) reconnect the server again, the server will send the previous trial number to them. Otherwise, the InitialTrailNumber will be initialized by 0. Usually, you don't need to touch this parameter.

====StimuliSequence====
The sequence of stimuli(images). The server will generate a random stimuli sequence for every pair of clients (identified by the IP address).

===Local Parameters===

====StimuliWidth====
StimulusWidth in percent of screen width (zero for original pixel size).

====InstructionImagesSeque====
The sequence of instruction images path.

====InstructionWidth====
Instruction width in percent of screen width (zero for original pixel size).

====SliderWidth====
SliderWidth in percent of screen width (zero for original pixel size).

====BarColor====
Color of the slider bar.

====AxeActiveColor====
Color of active slider axe.

====AxeInActiveColor====
Color of inactive slider axe.

====DimensionFontColor====
Color of the text under the slider.

====DimensionHeight====
Height of text in percent of the screen height.

====OptionFontActiveColor====
Color of the active options.

====OptionFontInActiveColor====
Color of the inactive options.

====OptionHeight====
Height of text in percent of the screen height.

====RoleFontColor====
Color of the role text.

====RoleHeight====
Height of text in percent of the screen height.

====FeedbackWidth====
Width of feedback in percent of screen width.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===PhaseNumber===
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the 10 slides instruction images are present on the screen) 
[1] indicates the client is waiting for the other client to push the button to start the game. ( We are waiting for another player; once she/he is ready, we're ready to go!) 
[2] When the role text is present on the screen.(Sender or Receiver). 
[3] When the sliders and stimulus are present on the screen. 
[4] Feedback: After the receiver locks the answer, it comes to phase [4], showing whether the answer is correct. 
[5]Break: (Well done! Are you ready for the next block? \n\n Press SPACEBAR) 
[6]End: (Well done! You have finished all the trials.)

===TrialNumber===
Index of trials. (8 bits)

===BarOneValue===
Value of slider#1. (32 bits)

===BarTwoValue===
Value of slider#2. (32 bits)

===BarOneActive, BarTwoActive===
0: slider is not selected. 1: slider is selected. (8 bits)

===ResponseValue===
1: object. 2: animal. (8 bits)

===SenderLock, ReceiverLock===
0: client is moving the slider/making a guess. 1: client has locked the answer. (8 bits)

===isReadyStart0, isReadyStart1===
0: client isn't ready to start/resume/continue the game(not yet pushing the button). 1: client is ready to start/resume/continue the game(push the button). (8 bits)

===ClientNumber===
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits)

==Example==
The hyperscanning application module is almost the same as a BCI2000 application module, except that the typical BCI2000 module is inherited from ApplicationBase, and the hyperscanning application module is inherited from HyperscanningApplicationBase. Basically, the HyperscanningApplicationBase class is the same as ApplicationBase class with adding the communication with the server. So instead of using Publish, Preflight, Process, etc. We are using SharedPublish, SharedPreflight, SharedProcess, etc. These methods behave in the exact same way, except they also call the client loops which interact with the server.

Communication_task_dualTask.h:
<pre>
#include "ApplicationBase.h"
#include "Slider.h"
#include <map>
#include <vector>
#include <string>
#include "TextStimulus.h"
#include "ImageStimulus.h"
#include "Shapes.h"
#include "HyperscanningApplicationBase.h"

class Communication_task_dualTask : public HyperscanningApplicationBase
{
public:
Communication_task_dualTask();
~Communication_task_dualTask();
void SharedPublish() override;
void SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const override;
void SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) override;
void SharedAutoConfig( const SignalProperties& Input ) override;
void SharedStartRun() override;
void SharedProcess( const GenericSignal& Input, GenericSignal& Output ) override;
void SharedStopRun() override;
void SharedHalt() override;

private:
//define your own private members here
ApplicationWindow& mrDisplay;

//define your own private methods here

};
</pre>

Manipulate the shared state is the same as the BCI2000 state. "isReadyStart1" is a shared state.
<pre>
State("isReadyStart1") = 1; // assign 1 to "isReadyStart1"
</pre>

Get the value of the shared state "isReadyStart1"
<pre>
//Both of the two players are ready, move to the next phase
if (State("isReadyStart0") && State("isReadyStart1")) {
m_instruction_container->Conceal();
m_role_txt->Conceal();
my_phase = role_text;
m_block_in_phase = 0;
}
</pre>

Contributions:CommunicationTask

2025-04-23T15:11:15Z

Lingling: /* Deploy the Server */

==Synopsis==
The hyperscanning task is a turn-based communication game between two clients. This game aims to guess what the subject is in Sender's computer without talking. For each trial, the two players will alternate between the roles of Sender and Receiver. The Sender will describe traits of the subject presented by adjusting the two axes(Noisy or silent/Big or small). Then, the Receiver will guess if the Sender is describing the animal or object. After the Receiver makes a guess, both players receive feedback on whether the Receiver makes the correct guess. This marks the end of a trial.

The two clients exchange information through the hyperScanning backend, which uses a client-server model to share the states. Each client has a separate state machine. The server only forwards the information between two clients. Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class, which is the parent class of the application module. For more information, please refer to the hyperScanning framework wiki page: https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning.

==Video Overview==
 
<youtube alignment="center">https://youtu.be/I1sSamSsTK4</youtube>
 

==Timeline==
<gallery mode="packed" widths=600px heights=500px>
File:Hyperscanning pipe line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=750px heights=421px>
File:Hyperscanning_1.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Anais Llorens (anaisllorens@hotmail.com) and Athina Tzovara (athina.tzovara@unibe.ch) conceived this paradigm. 
Max Marcus (bigmaxmarcus@gmail.com), Huiling Huang (huiling@neurotechcenter.org), and Sigurd Alnes (sigurd.alnes@unibe.ch) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps outline the process for deploying the server on AWS. 
1. Prepare the SSH key. 

2. In your terminal or shell, run 
<pre> chmod 400 <key_path> </pre>
to make the key file read-only for the owner. 

3. Connect to the AWS server using SSH: 
<pre> ssh -i <key path> <user-name>@<ip-address> </pre>

4. Pull the code from GitHub. 
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>

5. Navigate to the server directory: 
<pre>cd hyperscanning-backend</pre>

6. To compile the project, run:
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>

5. Launch the server by running: 
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application must be restarted after BCI2000 has been closed.
 

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:CommunicationTask batch.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====StimuliMatrix====
Shared parameter, matrix of stimulus information, including: 
1. ImageReceiver and ImageSender(the path of images). 
2. Sender(the role of players),1 is the sender), 2 is the receiver. 
3. Jitter(the duration to present the role). 
4. CorrectResponse(1: left, 2:right). 
5. Training(1: training, 0: main task). 
6. Category(1: object, 2: animal). 
7. Difficulty(1: easy, 2: moderate, 3: hard). 
8. Dimension1a and Dimension1b(bar#1 left text and right text). 
9. Dimension2a and Dimension2b(bar#2 left text and right text). 
10. Option1 and Option2(left option text and right option text).

====BreakTrialSequece====
The sequence of break trials, a break will happen after the break trial.

====FeedbackDuration====
Duration of feedback(ITI). Indicate the receiver to make a correct or incorrect guess. 

The server will generate the InitialTrialNumber and StimuliSequence, and save them into a parameter file named by IP addresses on the server. You don't need to worry about these two parameters. Unlike the parameters described above, they are saved on the server rather than on local computers.

====InitialTrialNumber====
The trial number to begin with. We provide the resume option, allowing clients to pause and resume the game from where they stop. After one of the clients quits the game, the server will discover it and save the current trial number and sequence. When the same clients(same IP address) reconnect the server again, the server will send the previous trial number to them. Otherwise, the InitialTrailNumber will be initialized by 0. Usually, you don't need to touch this parameter.

====StimuliSequence====
The sequence of stimuli(images). The server will generate a random stimuli sequence for every pair of clients (identified by the IP address).

===Local Parameters===

====StimuliWidth====
StimulusWidth in percent of screen width (zero for original pixel size).

====InstructionImagesSeque====
The sequence of instruction images path.

====InstructionWidth====
Instruction width in percent of screen width (zero for original pixel size).

====SliderWidth====
SliderWidth in percent of screen width (zero for original pixel size).

====BarColor====
Color of the slider bar.

====AxeActiveColor====
Color of active slider axe.

====AxeInActiveColor====
Color of inactive slider axe.

====DimensionFontColor====
Color of the text under the slider.

====DimensionHeight====
Height of text in percent of the screen height.

====OptionFontActiveColor====
Color of the active options.

====OptionFontInActiveColor====
Color of the inactive options.

====OptionHeight====
Height of text in percent of the screen height.

====RoleFontColor====
Color of the role text.

====RoleHeight====
Height of text in percent of the screen height.

====FeedbackWidth====
Width of feedback in percent of screen width.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===PhaseNumber===
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the 10 slides instruction images are present on the screen) 
[1] indicates the client is waiting for the other client to push the button to start the game. ( We are waiting for another player; once she/he is ready, we're ready to go!) 
[2] When the role text is present on the screen.(Sender or Receiver). 
[3] When the sliders and stimulus are present on the screen. 
[4] Feedback: After the receiver locks the answer, it comes to phase [4], showing whether the answer is correct. 
[5]Break: (Well done! Are you ready for the next block? \n\n Press SPACEBAR) 
[6]End: (Well done! You have finished all the trials.)

===TrialNumber===
Index of trials. (8 bits)

===BarOneValue===
Value of slider#1. (32 bits)

===BarTwoValue===
Value of slider#2. (32 bits)

===BarOneActive, BarTwoActive===
0: slider is not selected. 1: slider is selected. (8 bits)

===ResponseValue===
1: object. 2: animal. (8 bits)

===SenderLock, ReceiverLock===
0: client is moving the slider/making a guess. 1: client has locked the answer. (8 bits)

===isReadyStart0, isReadyStart1===
0: client isn't ready to start/resume/continue the game(not yet pushing the button). 1: client is ready to start/resume/continue the game(push the button). (8 bits)

===ClientNumber===
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits)

==Example==
The hyperscanning application module is almost the same as a BCI2000 application module, except that the typical BCI2000 module is inherited from ApplicationBase, and the hyperscanning application module is inherited from HyperscanningApplicationBase. Basically, the HyperscanningApplicationBase class is the same as ApplicationBase class with adding the communication with the server. So instead of using Publish, Preflight, Process, etc. We are using SharedPublish, SharedPreflight, SharedProcess, etc. These methods behave in the exact same way, except they also call the client loops which interact with the server.

Communication_task_dualTask.h:
<pre>
#include "ApplicationBase.h"
#include "Slider.h"
#include <map>
#include <vector>
#include <string>
#include "TextStimulus.h"
#include "ImageStimulus.h"
#include "Shapes.h"
#include "HyperscanningApplicationBase.h"

class Communication_task_dualTask : public HyperscanningApplicationBase
{
public:
Communication_task_dualTask();
~Communication_task_dualTask();
void SharedPublish() override;
void SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const override;
void SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) override;
void SharedAutoConfig( const SignalProperties& Input ) override;
void SharedStartRun() override;
void SharedProcess( const GenericSignal& Input, GenericSignal& Output ) override;
void SharedStopRun() override;
void SharedHalt() override;

private:
//define your own private members here
ApplicationWindow& mrDisplay;

//define your own private methods here

};
</pre>

Manipulate the shared state is the same as the BCI2000 state. "isReadyStart1" is a shared state.
<pre>
State("isReadyStart1") = 1; // assign 1 to "isReadyStart1"
</pre>

Get the value of the shared state "isReadyStart1"
<pre>
//Both of the two players are ready, move to the next phase
if (State("isReadyStart0") && State("isReadyStart1")) {
m_instruction_container->Conceal();
m_role_txt->Conceal();
my_phase = role_text;
m_block_in_phase = 0;
}
</pre>

Contributions:EglyDriverTask

2025-03-18T17:30:08Z

Lingling: /* Parameters */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000.

==titration rule==
In titration task, we use 3-down-1-up to adjust the contrast: decrease the contrast by one degree if 3 consecutive correct responses happens. Increase the contrast by one degree if 1 incorrect response happens. 
In the main task: 
1. Start with the first 15 trials: 

Record accuracy for the initial 15 match trials. 
Calculate the average accuracy of these trials. 
Adjust the contrast based on the computed average. 
2. Ongoing updates with a sliding window: 

After every set of 5 new trials: 
Incorporate these 5 new trials into the dataset. 
Remove the oldest 5 trials from the sequence. 
Recalculate the average accuracy of the updated 15-trial window. 
Adjust the contrast accordingly. 
This process continues for every subsequent batch of 5 trials.

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier; the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar. range [0,1]

===FixationWidth===
The width of the fixation cross. range [0,1]

===CueThick===
The thickness of the cue. range [0,1]

===TargetWidth===
The width of the target. range [0,1]

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%). range [0,100]

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%). range [0,100]

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%). range [0,100]

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task. range [0,100]

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle. range [0,360]

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AdjustContrastUpdateTrialNum===
The number of update trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy. range [0,1]

===AccuracyLow===
The low boundary of the accuracy. range [0,1]

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version. range [0,1]

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX, PushButton===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable. 
We also have a backup State called "PushButton." It registers when the software detects the keyboard or button push or release. There is a delay after the software detects the response, so the backup "PushButton" happens later than the actual keyboard or button response. You only need the backup "PushButton" when the "DCXX" or "KeyDown" is not available for some reason.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Response===
1: correct. 
2: incorrect

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode". It registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup "Photodiode" happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2025-03-17T22:00:59Z

Lingling: /* titration rule */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000.

==titration rule==
In titration task, we use 3-down-1-up to adjust the contrast: decrease the contrast by one degree if 3 consecutive correct responses happens. Increase the contrast by one degree if 1 incorrect response happens. 
In the main task: 
1. Start with the first 15 trials: 

Record accuracy for the initial 15 match trials. 
Calculate the average accuracy of these trials. 
Adjust the contrast based on the computed average. 
2. Ongoing updates with a sliding window: 

After every set of 5 new trials: 
Incorporate these 5 new trials into the dataset. 
Remove the oldest 5 trials from the sequence. 
Recalculate the average accuracy of the updated 15-trial window. 
Adjust the contrast accordingly. 
This process continues for every subsequent batch of 5 trials.

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier; the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AdjustContrastUpdateTrialNum===
The number of update trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX, PushButton===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable. 
We also have a backup State called "PushButton." It registers when the software detects the keyboard or button push or release. There is a delay after the software detects the response, so the backup "PushButton" happens later than the actual keyboard or button response. You only need the backup "PushButton" when the "DCXX" or "KeyDown" is not available for some reason.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Response===
1: correct. 
2: incorrect

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode". It registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup "Photodiode" happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2025-03-17T22:00:31Z

Lingling: /* titration rule */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000.

==titration rule==
In titration task, we use 3-down-1-up to adjust the contrast: decrease the contrast by one degree if 3 consecutive correct responses happens. Increase the contrast by one degree if 1 incorrect response happens. 
In the main task: 
1. Start with the first 15 trials: 

Record accuracy for the initial 15 match trials. 
Calculate the average accuracy of these trials. 
Adjust the contrast based on the computed average. 
2. Ongoing updates with a sliding window: 

After every set of 5 new trials: 
Incorporate these 5 new trials into the dataset. 
Remove the oldest 5 trials from the sequence. 
Recalculate the average accuracy of the updated 15-trial window. 
Adjust the contrast accordingly. 
This process continues for every subsequent batch of 5 trials.

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier; the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AdjustContrastUpdateTrialNum===
The number of update trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX, PushButton===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable. 
We also have a backup State called "PushButton." It registers when the software detects the keyboard or button push or release. There is a delay after the software detects the response, so the backup "PushButton" happens later than the actual keyboard or button response. You only need the backup "PushButton" when the "DCXX" or "KeyDown" is not available for some reason.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Response===
1: correct. 
2: incorrect

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode". It registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup "Photodiode" happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2025-03-17T22:00:14Z

Lingling: /* titration rule */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000.

==titration rule==
In titration task, we use 3-down-1-up to adjust the contrast: decrease the contrast by one degree if 3 consecutive correct responses happens. Increase the contrast by one degree if 1 incorrect response happens. 
In the main task: 
1. Start with the first 15 trials: 

Record accuracy for the initial 15 match trials. 
Calculate the average accuracy of these trials. 
Adjust the contrast based on the computed average. 
2. Ongoing updates with a sliding window: 

After every set of 5 new trials: 
Incorporate these 5 new trials into the dataset. 
Remove the oldest 5 trials from the sequence. 
Recalculate the average accuracy of the updated 15-trial window. 
Adjust the contrast accordingly. 
This process continues for every subsequent batch of 5 trials.

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier; the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AdjustContrastUpdateTrialNum===
The number of update trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX, PushButton===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable. 
We also have a backup State called "PushButton." It registers when the software detects the keyboard or button push or release. There is a delay after the software detects the response, so the backup "PushButton" happens later than the actual keyboard or button response. You only need the backup "PushButton" when the "DCXX" or "KeyDown" is not available for some reason.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Response===
1: correct. 
2: incorrect

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode". It registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup "Photodiode" happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2025-03-17T21:54:10Z

Lingling: /* Parameters */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000.

==titration rule==
In titration task, we use 3-down-1-up to adjust the contrast: decrease the contrast by one degree if 3 consecutive correct responses happens. Increase the contrast by one degree if 1 incorrect response happens. 
In the main task, we choose the slide window size as 15 trials and calculate the accuracy for the most recent 15 trials. If accuracy > 80%, decrease the contrast by one degree; otherwise, increase by one degree until the color is the same as the bar color.

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier; the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AdjustContrastUpdateTrialNum===
The number of update trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX, PushButton===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable. 
We also have a backup State called "PushButton." It registers when the software detects the keyboard or button push or release. There is a delay after the software detects the response, so the backup "PushButton" happens later than the actual keyboard or button response. You only need the backup "PushButton" when the "DCXX" or "KeyDown" is not available for some reason.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Response===
1: correct. 
2: incorrect

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode". It registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup "Photodiode" happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2025-03-13T15:37:01Z

Lingling: /* Authors */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000.

==titration rule==
In titration task, we use 3-down-1-up to adjust the contrast: decrease the contrast by one degree if 3 consecutive correct responses happens. Increase the contrast by one degree if 1 incorrect response happens. 
In the main task, we choose the slide window size as 15 trials and calculate the accuracy for the most recent 15 trials. If accuracy > 80%, decrease the contrast by one degree; otherwise, increase by one degree until the color is the same as the bar color.

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier; the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX, PushButton===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable. 
We also have a backup State called "PushButton." It registers when the software detects the keyboard or button push or release. There is a delay after the software detects the response, so the backup "PushButton" happens later than the actual keyboard or button response. You only need the backup "PushButton" when the "DCXX" or "KeyDown" is not available for some reason.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Response===
1: correct. 
2: incorrect

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode". It registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup "Photodiode" happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2025-03-13T15:28:16Z

Lingling: /* titration rule */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org)

==titration rule==
In titration task, we use 3-down-1-up to adjust the contrast: decrease the contrast by one degree if 3 consecutive correct responses happens. Increase the contrast by one degree if 1 incorrect response happens. 
In the main task, we choose the slide window size as 15 trials and calculate the accuracy for the most recent 15 trials. If accuracy > 80%, decrease the contrast by one degree; otherwise, increase by one degree until the color is the same as the bar color.

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier; the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX, PushButton===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable. 
We also have a backup State called "PushButton." It registers when the software detects the keyboard or button push or release. There is a delay after the software detects the response, so the backup "PushButton" happens later than the actual keyboard or button response. You only need the backup "PushButton" when the "DCXX" or "KeyDown" is not available for some reason.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Response===
1: correct. 
2: incorrect

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode". It registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup "Photodiode" happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2025-03-13T15:27:58Z

Lingling: /* Parameters */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org)

==titration rule==
In titration task: we use 3-down-1-up to adjust the contrast, decrease the contrast by one degree if 3 consecutive correct responses happens. Increase the contrast by one degree if 1 incorrect response happens. 
In the main task, we choose the slide window size as 15 trials and calculate the accuracy for the most recent 15 trials. If accuracy > 80%, decrease the contrast by one degree; otherwise, increase by one degree until the color is the same as the bar color.

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier; the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX, PushButton===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable. 
We also have a backup State called "PushButton." It registers when the software detects the keyboard or button push or release. There is a delay after the software detects the response, so the backup "PushButton" happens later than the actual keyboard or button response. You only need the backup "PushButton" when the "DCXX" or "KeyDown" is not available for some reason.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Response===
1: correct. 
2: incorrect

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode". It registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup "Photodiode" happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

File:GuiltTaskVideo.gif

2025-03-03T20:52:32Z

Lingling: Lingling uploaded a new version of File:GuiltTaskVideo.gif

GuiltTask

2025-03-03T20:38:17Z

Lingling: /* Timeline */

==Synopsis==
In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task.
During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots.
After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

==Timeline==
<gallery mode="packed" widths=1500px heights=1200px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=800px heights=450px>
File:GuiltTaskVideo.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:xxx.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====Stimuli====
Shared parameter, stimulus information, including: 
1. ImagePath(the path of dots images).

====MyStimuliSequence====
The sequence of dots images.

====StimuliSequencePractice====
Practice trial stimuli sequence

====InstructionPathTrans====
Transgressor instruction image path

====InstructionPathVicT====
Victim instruction image path

====FeedbackPathList====
Feedback icon path list

====TrialSequece1, TrialSequece2====
There are two sequences of trial types, for each experiment, we can run them alternatively, we can specify the sequence through the Parameter "TrialTypeSequenceID". 
Sequence of trial type. 
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====InstructionImagesSequence====
The sequence of instruction images path.

====FixationDurationList====
Duration of Fixation(ITI) list.

====DotsDuration====
Duration of displaying the dots

====ResponseDuration====
The maximum time allows the subject to make a response.

====OutcomeDuration====
The duration to display the outcome.

====CompensationDuration====
The duration to display the compensation.

====EnablePractice====
Enable the practice trial or not

====StartPoints====
The initial total points of the game

====GuessDots====
INstruction of the guessing the number of the dots

====DotsNumber====
Guess the number of dots is greater or less than the "DotsNumber", "DotsNumber" is the number to be compared with.

====optionOne, optionTwo====
guess option one/two, for example "Greater" and "Less"

====CompensationQuestion====
Instruction of compensation phase

====CompensationOne, CompensationTwo, CompensationThree, CompensationFour====
Compensation options

====ForgivenessQuestion====
Instruction of forgiveness phase

====ForgivenessOne, ForgivenessTwo, ForgivenessThree, ForgivenessFour====
Forgiveness options

Unlike the parameters described above, they are saved on the server rather than on local computers.

===Local Parameters===

====FontSize, FixationSize====
Font/Fixation size.

====FontColor, FixationColor====
Color of the font/fixation.

====FontActiveColor====
Color of the active font(be selected)

====GUIScale====
Scale the GUI, 1 is maximum, 0 is minimium

====TrialTypeSequenceID====
Specify the trial type sequence, see Parameter "TrialSequece1 and TrialSequece2"

====ProgressBar====
Display progress bar.

====ProgressBarHeight, ProgressBarWidth====
Progress bar height/width in pixels.

====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Color of progress bar background/foreground.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===Shared State===

====isReadyStart0, isReadyStart1====
Check if client0/client1 is ready to move to the next phase or trial.

====ClientNumber====
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits) 
0: Transgressor. 1: Victim

====Compensation====
The compensation that the transgressor gives in each trial

====Forgiveness====
The forgiveness that the victim gives in each trial

===Local State===
====PhaseNumber====
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen) 
[1] present the instruction showing the end of the practice trial 
[2] present the fixation on the screen. 
[3] present the dots on the screen. 
[4] The subject estimates the number of dots. 
[5] Display the outcome. 
[6] reset the states and GUI 
[7] Choose the compensation/forgiveness level. 
[8] display the compensation/forgiveness that another player selects 
[9] The end of the game, shows the total score, compensation and average forgiveness. 
[10] End: (Well done! You have finished all the trials.) 
[11] none, the initial value of the state. 

====TrialNumber====
Index of trials. (8 bits)

====TrialType====
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====StimulusCode====
The id of the stimulus in each trial

====ResponseValue====
1: greater. 2: smaller. (8 bits)

====FixationDuration====
The duration of the fixation phase in each trial.

====Photodiode====
1: active;
2: non-active

File:Guilty task time line.png

2025-03-03T20:36:12Z

Lingling: Lingling uploaded a new version of File:Guilty task time line.png

GuiltTask

2025-03-03T17:15:17Z

Lingling: /* PhaseNumber */

==Synopsis==
In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task.
During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots.
After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

==Timeline==
<gallery mode="packed" widths=1200px heights=700px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=800px heights=450px>
File:GuiltTaskVideo.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:xxx.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====Stimuli====
Shared parameter, stimulus information, including: 
1. ImagePath(the path of dots images).

====MyStimuliSequence====
The sequence of dots images.

====StimuliSequencePractice====
Practice trial stimuli sequence

====InstructionPathTrans====
Transgressor instruction image path

====InstructionPathVicT====
Victim instruction image path

====FeedbackPathList====
Feedback icon path list

====TrialSequece1, TrialSequece2====
There are two sequences of trial types, for each experiment, we can run them alternatively, we can specify the sequence through the Parameter "TrialTypeSequenceID". 
Sequence of trial type. 
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====InstructionImagesSequence====
The sequence of instruction images path.

====FixationDurationList====
Duration of Fixation(ITI) list.

====DotsDuration====
Duration of displaying the dots

====ResponseDuration====
The maximum time allows the subject to make a response.

====OutcomeDuration====
The duration to display the outcome.

====CompensationDuration====
The duration to display the compensation.

====EnablePractice====
Enable the practice trial or not

====StartPoints====
The initial total points of the game

====GuessDots====
INstruction of the guessing the number of the dots

====DotsNumber====
Guess the number of dots is greater or less than the "DotsNumber", "DotsNumber" is the number to be compared with.

====optionOne, optionTwo====
guess option one/two, for example "Greater" and "Less"

====CompensationQuestion====
Instruction of compensation phase

====CompensationOne, CompensationTwo, CompensationThree, CompensationFour====
Compensation options

====ForgivenessQuestion====
Instruction of forgiveness phase

====ForgivenessOne, ForgivenessTwo, ForgivenessThree, ForgivenessFour====
Forgiveness options

Unlike the parameters described above, they are saved on the server rather than on local computers.

===Local Parameters===

====FontSize, FixationSize====
Font/Fixation size.

====FontColor, FixationColor====
Color of the font/fixation.

====FontActiveColor====
Color of the active font(be selected)

====GUIScale====
Scale the GUI, 1 is maximum, 0 is minimium

====TrialTypeSequenceID====
Specify the trial type sequence, see Parameter "TrialSequece1 and TrialSequece2"

====ProgressBar====
Display progress bar.

====ProgressBarHeight, ProgressBarWidth====
Progress bar height/width in pixels.

====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Color of progress bar background/foreground.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===Shared State===

====isReadyStart0, isReadyStart1====
Check if client0/client1 is ready to move to the next phase or trial.

====ClientNumber====
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits) 
0: Transgressor. 1: Victim

====Compensation====
The compensation that the transgressor gives in each trial

====Forgiveness====
The forgiveness that the victim gives in each trial

===Local State===
====PhaseNumber====
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen) 
[1] present the instruction showing the end of the practice trial 
[2] present the fixation on the screen. 
[3] present the dots on the screen. 
[4] The subject estimates the number of dots. 
[5] Display the outcome. 
[6] reset the states and GUI 
[7] Choose the compensation/forgiveness level. 
[8] display the compensation/forgiveness that another player selects 
[9] The end of the game, shows the total score, compensation and average forgiveness. 
[10] End: (Well done! You have finished all the trials.) 
[11] none, the initial value of the state. 

====TrialNumber====
Index of trials. (8 bits)

====TrialType====
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====StimulusCode====
The id of the stimulus in each trial

====ResponseValue====
1: greater. 2: smaller. (8 bits)

====FixationDuration====
The duration of the fixation phase in each trial.

====Photodiode====
1: active;
2: non-active

GuiltTask

2025-03-03T17:09:12Z

Lingling: /* PhaseNumber */

==Synopsis==
In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task.
During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots.
After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

==Timeline==
<gallery mode="packed" widths=1200px heights=700px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=800px heights=450px>
File:GuiltTaskVideo.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:xxx.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====Stimuli====
Shared parameter, stimulus information, including: 
1. ImagePath(the path of dots images).

====MyStimuliSequence====
The sequence of dots images.

====StimuliSequencePractice====
Practice trial stimuli sequence

====InstructionPathTrans====
Transgressor instruction image path

====InstructionPathVicT====
Victim instruction image path

====FeedbackPathList====
Feedback icon path list

====TrialSequece1, TrialSequece2====
There are two sequences of trial types, for each experiment, we can run them alternatively, we can specify the sequence through the Parameter "TrialTypeSequenceID". 
Sequence of trial type. 
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====InstructionImagesSequence====
The sequence of instruction images path.

====FixationDurationList====
Duration of Fixation(ITI) list.

====DotsDuration====
Duration of displaying the dots

====ResponseDuration====
The maximum time allows the subject to make a response.

====OutcomeDuration====
The duration to display the outcome.

====CompensationDuration====
The duration to display the compensation.

====EnablePractice====
Enable the practice trial or not

====StartPoints====
The initial total points of the game

====GuessDots====
INstruction of the guessing the number of the dots

====DotsNumber====
Guess the number of dots is greater or less than the "DotsNumber", "DotsNumber" is the number to be compared with.

====optionOne, optionTwo====
guess option one/two, for example "Greater" and "Less"

====CompensationQuestion====
Instruction of compensation phase

====CompensationOne, CompensationTwo, CompensationThree, CompensationFour====
Compensation options

====ForgivenessQuestion====
Instruction of forgiveness phase

====ForgivenessOne, ForgivenessTwo, ForgivenessThree, ForgivenessFour====
Forgiveness options

Unlike the parameters described above, they are saved on the server rather than on local computers.

===Local Parameters===

====FontSize, FixationSize====
Font/Fixation size.

====FontColor, FixationColor====
Color of the font/fixation.

====FontActiveColor====
Color of the active font(be selected)

====GUIScale====
Scale the GUI, 1 is maximum, 0 is minimium

====TrialTypeSequenceID====
Specify the trial type sequence, see Parameter "TrialSequece1 and TrialSequece2"

====ProgressBar====
Display progress bar.

====ProgressBarHeight, ProgressBarWidth====
Progress bar height/width in pixels.

====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Color of progress bar background/foreground.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===Shared State===

====isReadyStart0, isReadyStart1====
Check if client0/client1 is ready to move to the next phase or trial.

====ClientNumber====
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits) 
0: Transgressor. 1: Victim

====Compensation====
The compensation that the transgressor gives in each trial

====Forgiveness====
The forgiveness that the victim gives in each trial

===Local State===
====PhaseNumber====
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen) 
[1] present the instruction showing the end of the practice trial 
[2] present the fixation on the screen. 
[3] present the dots on the screen. 
[4] The subject estimates the number of dots. 
[5] Display the outcome. 
[6] reset the states and GUI 
[7] Choose the compensation/forgiveness level. 
[8] display the compensation/forgiveness that another player selects
[9] The end of the game, shows the total score, compensation and average forgiveness. 
[10] End: (Well done! You have finished all the trials.) 
[11] none, the initial value of the state. 

====TrialNumber====
Index of trials. (8 bits)

====TrialType====
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====StimulusCode====
The id of the stimulus in each trial

====ResponseValue====
1: greater. 2: smaller. (8 bits)

====FixationDuration====
The duration of the fixation phase in each trial.

====Photodiode====
1: active;
2: non-active

GuiltTask

2025-02-26T17:36:57Z

Lingling: /* PhaseNumber */

==Synopsis==
In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task.
During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots.
After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

==Timeline==
<gallery mode="packed" widths=1200px heights=700px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=800px heights=450px>
File:GuiltTaskVideo.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:xxx.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====Stimuli====
Shared parameter, stimulus information, including: 
1. ImagePath(the path of dots images).

====MyStimuliSequence====
The sequence of dots images.

====StimuliSequencePractice====
Practice trial stimuli sequence

====InstructionPathTrans====
Transgressor instruction image path

====InstructionPathVicT====
Victim instruction image path

====FeedbackPathList====
Feedback icon path list

====TrialSequece1, TrialSequece2====
There are two sequences of trial types, for each experiment, we can run them alternatively, we can specify the sequence through the Parameter "TrialTypeSequenceID". 
Sequence of trial type. 
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====InstructionImagesSequence====
The sequence of instruction images path.

====FixationDurationList====
Duration of Fixation(ITI) list.

====DotsDuration====
Duration of displaying the dots

====ResponseDuration====
The maximum time allows the subject to make a response.

====OutcomeDuration====
The duration to display the outcome.

====CompensationDuration====
The duration to display the compensation.

====EnablePractice====
Enable the practice trial or not

====StartPoints====
The initial total points of the game

====GuessDots====
INstruction of the guessing the number of the dots

====DotsNumber====
Guess the number of dots is greater or less than the "DotsNumber", "DotsNumber" is the number to be compared with.

====optionOne, optionTwo====
guess option one/two, for example "Greater" and "Less"

====CompensationQuestion====
Instruction of compensation phase

====CompensationOne, CompensationTwo, CompensationThree, CompensationFour====
Compensation options

====ForgivenessQuestion====
Instruction of forgiveness phase

====ForgivenessOne, ForgivenessTwo, ForgivenessThree, ForgivenessFour====
Forgiveness options

Unlike the parameters described above, they are saved on the server rather than on local computers.

===Local Parameters===

====FontSize, FixationSize====
Font/Fixation size.

====FontColor, FixationColor====
Color of the font/fixation.

====FontActiveColor====
Color of the active font(be selected)

====GUIScale====
Scale the GUI, 1 is maximum, 0 is minimium

====TrialTypeSequenceID====
Specify the trial type sequence, see Parameter "TrialSequece1 and TrialSequece2"

====ProgressBar====
Display progress bar.

====ProgressBarHeight, ProgressBarWidth====
Progress bar height/width in pixels.

====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Color of progress bar background/foreground.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===Shared State===

====isReadyStart0, isReadyStart1====
Check if client0/client1 is ready to move to the next phase or trial.

====ClientNumber====
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits) 
0: Transgressor. 1: Victim

====Compensation====
The compensation that the transgressor gives in each trial

====Forgiveness====
The forgiveness that the victim gives in each trial

===Local State===
====PhaseNumber====
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen) 
[1] present the instruction showing the end of the practice trial 
[2] present the fixation on the screen. 
[3] present the dots on the screen. 
[4] The subject estimates the number of dots. 
[5] Display the outcome. 
[6] reset the states and GUI
[7] Choose the compensation/forgiveness level. 
[8] display the compensation/forgiveness that another player selects
[9] The end of the game, shows the total score, compensation and average forgiveness. 
[10] End: (Well done! You have finished all the trials.) 
[11] none, the initial value of the state. 

====TrialNumber====
Index of trials. (8 bits)

====TrialType====
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====StimulusCode====
The id of the stimulus in each trial

====ResponseValue====
1: greater. 2: smaller. (8 bits)

====FixationDuration====
The duration of the fixation phase in each trial.

====Photodiode====
1: active;
2: non-active

Contributions:CommunicationTask

2025-01-28T22:12:31Z

Lingling: /* Timeline */

==Synopsis==
The hyperscanning task is a turn-based communication game between two clients. This game aims to guess what the subject is in Sender's computer without talking. For each trial, the two players will alternate between the roles of Sender and Receiver. The Sender will describe traits of the subject presented by adjusting the two axes(Noisy or silent/Big or small). Then, the Receiver will guess if the Sender is describing the animal or object. After the Receiver makes a guess, both players receive feedback on whether the Receiver makes the correct guess. This marks the end of a trial.

The two clients exchange information through the hyperScanning backend, which uses a client-server model to share the states. Each client has a separate state machine. The server only forwards the information between two clients. Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class, which is the parent class of the application module. For more information, please refer to the hyperScanning framework wiki page: https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning.

==Video Overview==
 
<youtube alignment="center">https://youtu.be/I1sSamSsTK4</youtube>
 

==Timeline==
<gallery mode="packed" widths=600px heights=500px>
File:Hyperscanning pipe line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=750px heights=421px>
File:Hyperscanning_1.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Anais Llorens (anaisllorens@hotmail.com) and Athina Tzovara (athina.tzovara@unibe.ch) conceived this paradigm. 
Max Marcus (bigmaxmarcus@gmail.com), Huiling Huang (huiling@neurotechcenter.org), and Sigurd Alnes (sigurd.alnes@unibe.ch) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:CommunicationTask batch.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====StimuliMatrix====
Shared parameter, matrix of stimulus information, including: 
1. ImageReceiver and ImageSender(the path of images). 
2. Sender(the role of players),1 is the sender), 2 is the receiver. 
3. Jitter(the duration to present the role). 
4. CorrectResponse(1: left, 2:right). 
5. Training(1: training, 0: main task). 
6. Category(1: object, 2: animal). 
7. Difficulty(1: easy, 2: moderate, 3: hard). 
8. Dimension1a and Dimension1b(bar#1 left text and right text). 
9. Dimension2a and Dimension2b(bar#2 left text and right text). 
10. Option1 and Option2(left option text and right option text).

====BreakTrialSequece====
The sequence of break trials, a break will happen after the break trial.

====FeedbackDuration====
Duration of feedback(ITI). Indicate the receiver to make a correct or incorrect guess. 

The server will generate the InitialTrialNumber and StimuliSequence, and save them into a parameter file named by IP addresses on the server. You don't need to worry about these two parameters. Unlike the parameters described above, they are saved on the server rather than on local computers.

====InitialTrialNumber====
The trial number to begin with. We provide the resume option, allowing clients to pause and resume the game from where they stop. After one of the clients quits the game, the server will discover it and save the current trial number and sequence. When the same clients(same IP address) reconnect the server again, the server will send the previous trial number to them. Otherwise, the InitialTrailNumber will be initialized by 0. Usually, you don't need to touch this parameter.

====StimuliSequence====
The sequence of stimuli(images). The server will generate a random stimuli sequence for every pair of clients (identified by the IP address).

===Local Parameters===

====StimuliWidth====
StimulusWidth in percent of screen width (zero for original pixel size).

====InstructionImagesSeque====
The sequence of instruction images path.

====InstructionWidth====
Instruction width in percent of screen width (zero for original pixel size).

====SliderWidth====
SliderWidth in percent of screen width (zero for original pixel size).

====BarColor====
Color of the slider bar.

====AxeActiveColor====
Color of active slider axe.

====AxeInActiveColor====
Color of inactive slider axe.

====DimensionFontColor====
Color of the text under the slider.

====DimensionHeight====
Height of text in percent of the screen height.

====OptionFontActiveColor====
Color of the active options.

====OptionFontInActiveColor====
Color of the inactive options.

====OptionHeight====
Height of text in percent of the screen height.

====RoleFontColor====
Color of the role text.

====RoleHeight====
Height of text in percent of the screen height.

====FeedbackWidth====
Width of feedback in percent of screen width.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===PhaseNumber===
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the 10 slides instruction images are present on the screen) 
[1] indicates the client is waiting for the other client to push the button to start the game. ( We are waiting for another player; once she/he is ready, we're ready to go!) 
[2] When the role text is present on the screen.(Sender or Receiver). 
[3] When the sliders and stimulus are present on the screen. 
[4] Feedback: After the receiver locks the answer, it comes to phase [4], showing whether the answer is correct. 
[5]Break: (Well done! Are you ready for the next block? \n\n Press SPACEBAR) 
[6]End: (Well done! You have finished all the trials.)

===TrialNumber===
Index of trials. (8 bits)

===BarOneValue===
Value of slider#1. (32 bits)

===BarTwoValue===
Value of slider#2. (32 bits)

===BarOneActive, BarTwoActive===
0: slider is not selected. 1: slider is selected. (8 bits)

===ResponseValue===
1: object. 2: animal. (8 bits)

===SenderLock, ReceiverLock===
0: client is moving the slider/making a guess. 1: client has locked the answer. (8 bits)

===isReadyStart0, isReadyStart1===
0: client isn't ready to start/resume/continue the game(not yet pushing the button). 1: client is ready to start/resume/continue the game(push the button). (8 bits)

===ClientNumber===
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits)

==Example==
The hyperscanning application module is almost the same as a BCI2000 application module, except that the typical BCI2000 module is inherited from ApplicationBase, and the hyperscanning application module is inherited from HyperscanningApplicationBase. Basically, the HyperscanningApplicationBase class is the same as ApplicationBase class with adding the communication with the server. So instead of using Publish, Preflight, Process, etc. We are using SharedPublish, SharedPreflight, SharedProcess, etc. These methods behave in the exact same way, except they also call the client loops which interact with the server.

Communication_task_dualTask.h:
<pre>
#include "ApplicationBase.h"
#include "Slider.h"
#include <map>
#include <vector>
#include <string>
#include "TextStimulus.h"
#include "ImageStimulus.h"
#include "Shapes.h"
#include "HyperscanningApplicationBase.h"

class Communication_task_dualTask : public HyperscanningApplicationBase
{
public:
Communication_task_dualTask();
~Communication_task_dualTask();
void SharedPublish() override;
void SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const override;
void SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) override;
void SharedAutoConfig( const SignalProperties& Input ) override;
void SharedStartRun() override;
void SharedProcess( const GenericSignal& Input, GenericSignal& Output ) override;
void SharedStopRun() override;
void SharedHalt() override;

private:
//define your own private members here
ApplicationWindow& mrDisplay;

//define your own private methods here

};
</pre>

Manipulate the shared state is the same as the BCI2000 state. "isReadyStart1" is a shared state.
<pre>
State("isReadyStart1") = 1; // assign 1 to "isReadyStart1"
</pre>

Get the value of the shared state "isReadyStart1"
<pre>
//Both of the two players are ready, move to the next phase
if (State("isReadyStart0") && State("isReadyStart1")) {
m_instruction_container->Conceal();
m_role_txt->Conceal();
my_phase = role_text;
m_block_in_phase = 0;
}
</pre>

Contributions:EglyDriverTask

2024-10-02T18:40:57Z

Lingling: /* Response */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org)

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier; the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX, PushButton===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable. 
We also have a backup State called "PushButton." It registers when the software detects the keyboard or button push or release. There is a delay after the software detects the response, so the backup "PushButton" happens later than the actual keyboard or button response. You only need the backup "PushButton" when the "DCXX" or "KeyDown" is not available for some reason.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Response===
1: correct. 
2: incorrect

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode". It registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup "Photodiode" happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2024-10-02T18:40:49Z

Lingling: /* States */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org)

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier; the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX, PushButton===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable. 
We also have a backup State called "PushButton." It registers when the software detects the keyboard or button push or release. There is a delay after the software detects the response, so the backup "PushButton" happens later than the actual keyboard or button response. You only need the backup "PushButton" when the "DCXX" or "KeyDown" is not available for some reason.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Response===
1: correct. <br\>
2: incorrect

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode". It registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup "Photodiode" happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2024-09-17T20:10:19Z

Lingling: /* KeyDown, KeyUp, DCXX */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org)

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier; the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX, PushButton===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable. 
We also have a backup State called "PushButton." It registers when the software detects the keyboard or button push or release. There is a delay after the software detects the response, so the backup "PushButton" happens later than the actual keyboard or button response. You only need the backup "PushButton" when the "DCXX" or "KeyDown" is not available for some reason.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode". It registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup "Photodiode" happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2024-09-17T20:08:59Z

Lingling: /* KeyDown, KeyUp, DCXX */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org)

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier; the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable. 
We also have a backup State called "PushButton." It registers when the software detects the keyboard or button push or release. There is a delay after the software detects the response, so the backup "PushButton" happens later than the actual keyboard or button response. You only need the backup "PushButton" when the "DCXX" or "KeyDown" is not available for some reason.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode". It registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup "Photodiode" happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2024-09-17T20:08:43Z

Lingling: /* KeyDown, KeyUp, DCXX */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org)

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier; the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable. 
We also have a backup State called "PushButton." It registers when the software detects the keyboard or button push or release. There is a delay after the software detects the response, so the backup "PushButton" happens later than the actual keyboard or button response. You only need the backup "PushButton" when the "DCXX" or "KeyDown" is not available for some reason.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode". It registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup "Photodiode" happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2024-09-17T20:08:18Z

Lingling: /* States */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org)

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier; the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable. 
We also have a backup State called "PushButton." It registers when the software detects the keyboard or button push or release. There is a delay after the software detects the response, so the backup "PushButton" happens later than the actual keyboard or button response. You only need the backup "PushButton" when the "DCXX" or "KeyDown" is not available for some reason.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode". It registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup "Photodiode" happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2024-09-16T21:06:42Z

Lingling: /* PushButtonType */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org)

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier; the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode", it registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup Photodiode happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2024-09-16T21:05:40Z

Lingling: /* States */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org)

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier, the delay is minor, and can be ignored. Please confirm with the experimenter the variable name where the PushButtom is stored. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===KeyDown, KeyUp, DCXX===
Recording when the subject is pushing or releasing the button. 
We provide 3 sources of pushbuttons: DC, analog, and keyboard.
DC and analog: The push button is directly connected to the amplifier, so the delay is minor and can be ignored. Please confirm the variable name where the PushButtom is stored with the experimenter. The variable name varies with the channel the push button connects to through the amplifier. Usually, the variable name begins with "DC"; for example, "DC02", the number "02" is the channel ID. 
Keyboard: This usually has a tens of millisecond delay. When a key is pressed, "KeyDown" will be set to the key's [http://msdn.microsoft.com/en-us/library/ms927178.aspx ''virtual key code''] at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable.

===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode", it registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup Photodiode happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2024-09-16T21:01:33Z

Lingling: /* Parameters */

==Synopsis==

==Timeline==
<gallery mode="packed" widths=600px heights=450px>
File:Egly_driver_Timeline.jpg|Figure 1: Single trial timeline.
</gallery>

<gallery mode="packed" widths=400px heights=600px>
File:Egly_driver_trial_types.jpg|Figure 2: Trial types
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=1920px heights=1080px>
File:Egly driver visualize.gif
</gallery>

==Versioning==
===Authors===
Huiling Huang (huiling@neurotechcenter.org)

==Parameters==
===PushButtonType===
We provide 3 sources of pushbuttons: DC, analog, and keyboard. 
DC and analog: the push button is directly connected to the amplifier, the delay is minor, and can be ignored. Please confirm with the experimenter the variable name where the PushButtom is stored. The variable name varies with the channel that the push button connects to through the amplifier. 
keyboard: usually has tens of milliseconds delay.

===FixationColor, BarColor, CueColor, TargetColor===
The color of the fixation, bar, cue, target.

===BarThick===
The thickness of the bar.

===FixationWidth===
The width of the fixation cross.

===CueThick===
The thickness of the cue.

===TargetWidth===
The width of the target.

===FixationDurationMin, FixationDurationMax===
Minimum/Maximum duration of the fixation phase.

===BarDurationMin, BarDurationMax===
Minimum/Maximum duration of the bar phase.

===CueDuration===
Duration of cue.

===CueToTargetDurationMin, CueToTargetDurationMax===
Minimum/Maximum interval time between cue and target.

===TargetDuration===
Duration of target.

===PostTargetResponseTime===
The maximum time allows the subject to respond after the target disappears.

===FeedbackDuration===
Duration of the feedback

===TotalTrial===
Number of the total trials.

===CatchTrialPerctg===
The percentage of the catch trial(no target)(%).

===CueTgtMatchPerctg===
The percentage of the cue matches the target trial(%).

===CueTgtSmObjctPerctg===
The percentage of the target mismatches the cue, on the same object(%).

===CueTgtDifObjctPerctg===
The percentage of the target mismatches the cue, on the different objects(%). Set as 0 when it is a simplified task.

===ScreenWidth, ScreenHeight===
Width/height of the monitor screen in cm.

===EyeToSreenDistance===
Distance from the subject's eyes to the screen in cm.

===VisualAngle===
The degrees of visual angle.

===AdjustContrastBy===
Adjust the contrast of the target color by: 0 overall accuracy, 1 match accuracy, 2 non-match accuracy.

===AdjustContrastTrialNum===
The number of trials needed to calculate the accuracy for adjusting the contrast.

===AccuracyUp===
The up boundary of the accuracy.

===AccuracyLow===
The low boundary of the accuracy.

===Simplified===
Enable the simplified version, only has two squares rather than two bars.

===SquareLength===
The lenght of square in simplified version.

===IsStairCase===
Enable the Staircase.

===DownCounts===
Contrast decreases one step following the number of consecutive correct trials.

===UpCounts===
Contrast increases one step following the number of consecutive incorrect trials.

===ProgressBar===
Display progress bar.

===ProgressBarHeight, ProgressBarWidth===
Progress bar height/width in pixels.

===ProgressBarBackgroundColor, ProgressBarForegroundColor===
Color of progress bar background/foreground.

===PhotoDiodePatch===
Display a photo diode patch on the stimulus window. Recording from a photo diode located on that patch will allow triggering on actual stimulus delivery (see User_Reference:P3TemporalFilter#OnsetExpression).

=== PhotoDiodePatchHeight, PhotoDiodePatchWidth===
Photo diode patch height/width in relative coordinates (between 0 and 1).

===PhotoDiodePatchLeft, PhotoDiodePatchTop ===
Photo diode patch left/top position in relative coordinates (between 0 and 1).

===PhotoDiodePatchShape===
Photo diode patch shape: 0 rectangle, 1 ellipse.

===PhotoDiodePatchActiveColor===
Photo diode patch color when active (RGB color in format 0xrrggbb).

===PhotoDiodePatchInactiveColor===
Photo diode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
===PhaseNumber===
The index of phase in each trial. (8 bits)
0: none; 1: Beginning of the trial; 2: Fixation; 3: Bar; 4: Cue; 5: Cue to target; 6: Target; 7: Post target response; 8: Feedback.

===TrialNumber===
Index of trials. (16 bits)

===BarDirection===
Main task: 1: Vertical; 2: Horizontal. 
Simplified task: 1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===CuePosition, TargetPosition===
1: LeftTop; 2: RightTop; 3: RightBottom; 4: LeftBottom.

===TrialType===
1: no target, catch trial; 2: cue target match; 3:cue target don't match, on the same object; 
4: cue target don't match, on the different object;

===FixationDuration===
Duration of the phase Fixation by the number of blocks.

===BarDuration===
Duration of the phase Bar by the number of blocks.

===CueToTargetDuration===
Duration of the phase CueToTargetDuration by the number of blocks.

===TargetColor===
The color of the target. Represent in decimal numbers.

===Photodiode===
The Photodiode is stored in the .bat file, and the name begins with "DC". For example, "DC03", the number after "DC" represents the channel number, because the photodiode is directly connected to the amplifier, the name depends on the hardware connection. Please confirm the name of the Photodiode with the experimenter before starting the analysis. 
We also have a backup State called "Photodiode", it registers when the software sends the command to hardware to present the stimulus or whenever we need to flash the photodiode. Between the software sending the command to the hardware actual response, there are roughly about 20 ms delays. So the backup Photodiode happens earlier than the actual photodiode flashes. You only need the backup Phtodiode when the "DCXX" is not available for some reason.

1: active; 
2: non-active

==See also==
[[Contributions:Applications]]
[[Category:Contributions]][[Category:User Application]]

Contributions:EglyDriverTask

2024-09-16T17:38:22Z

Lingling: /* Photodiode */

Contributions:EglyDriverTask

2024-09-16T17:37:57Z

Lingling: /* Photodiode */

GuiltTask

2024-08-14T16:53:53Z

Lingling: /* InstructionPathVicT= */

==Synopsis==
In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task.
During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots.
After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

==Timeline==
<gallery mode="packed" widths=1200px heights=700px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=800px heights=450px>
File:GuiltTaskVideo.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:xxx.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====Stimuli====
Shared parameter, stimulus information, including: 
1. ImagePath(the path of dots images).

====MyStimuliSequence====
The sequence of dots images.

====StimuliSequencePractice====
Practice trial stimuli sequence

====InstructionPathTrans====
Transgressor instruction image path

====InstructionPathVicT====
Victim instruction image path

====FeedbackPathList====
Feedback icon path list

====TrialSequece1, TrialSequece2====
There are two sequences of trial types, for each experiment, we can run them alternatively, we can specify the sequence through the Parameter "TrialTypeSequenceID". 
Sequence of trial type. 
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====InstructionImagesSequence====
The sequence of instruction images path.

====FixationDurationList====
Duration of Fixation(ITI) list.

====DotsDuration====
Duration of displaying the dots

====ResponseDuration====
The maximum time allows the subject to make a response.

====OutcomeDuration====
The duration to display the outcome.

====CompensationDuration====
The duration to display the compensation.

====EnablePractice====
Enable the practice trial or not

====StartPoints====
The initial total points of the game

====GuessDots====
INstruction of the guessing the number of the dots

====DotsNumber====
Guess the number of dots is greater or less than the "DotsNumber", "DotsNumber" is the number to be compared with.

====optionOne, optionTwo====
guess option one/two, for example "Greater" and "Less"

====CompensationQuestion====
Instruction of compensation phase

====CompensationOne, CompensationTwo, CompensationThree, CompensationFour====
Compensation options

====ForgivenessQuestion====
Instruction of forgiveness phase

====ForgivenessOne, ForgivenessTwo, ForgivenessThree, ForgivenessFour====
Forgiveness options

Unlike the parameters described above, they are saved on the server rather than on local computers.

===Local Parameters===

====FontSize, FixationSize====
Font/Fixation size.

====FontColor, FixationColor====
Color of the font/fixation.

====FontActiveColor====
Color of the active font(be selected)

====GUIScale====
Scale the GUI, 1 is maximum, 0 is minimium

====TrialTypeSequenceID====
Specify the trial type sequence, see Parameter "TrialSequece1 and TrialSequece2"

====ProgressBar====
Display progress bar.

====ProgressBarHeight, ProgressBarWidth====
Progress bar height/width in pixels.

====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Color of progress bar background/foreground.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===Shared State===

====isReadyStart0, isReadyStart1====
Check if client0/client1 is ready to move to the next phase or trial.

====ClientNumber====
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits) 
0: Transgressor. 1: Victim

====Compensation====
The compensation that the transgressor gives in each trial

====Forgiveness====
The forgiveness that the victim gives in each trial

===Local State===
====PhaseNumber====
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen) 
[1] present the instruction showing the end of the practice trial 
[2] present the fixation on the screen. 
[3] present the dots on the screen. 
[4] The subject estimates the number of dots. 
[5] Display the outcome. 
[6] Choose the compensation/forgiveness level. 
[7] The end of the game, shows the total score, compensation and average forgiveness. 
[8] End: (Well done! You have finished all the trials.) 
[9] none, the initial value of the state. 

====TrialNumber====
Index of trials. (8 bits)

====TrialType====
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====StimulusCode====
The id of the stimulus in each trial

====ResponseValue====
1: greater. 2: smaller. (8 bits)

====FixationDuration====
The duration of the fixation phase in each trial.

====Photodiode====
1: active;
2: non-active

GuiltTask

2024-08-14T16:53:47Z

Lingling: /* InstructionPathTrans= */

==Synopsis==
In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task.
During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots.
After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

==Timeline==
<gallery mode="packed" widths=1200px heights=700px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=800px heights=450px>
File:GuiltTaskVideo.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:xxx.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====Stimuli====
Shared parameter, stimulus information, including: 
1. ImagePath(the path of dots images).

====MyStimuliSequence====
The sequence of dots images.

====StimuliSequencePractice====
Practice trial stimuli sequence

====InstructionPathTrans====
Transgressor instruction image path

====InstructionPathVicT=====
Victim instruction image path

====FeedbackPathList====
Feedback icon path list

====TrialSequece1, TrialSequece2====
There are two sequences of trial types, for each experiment, we can run them alternatively, we can specify the sequence through the Parameter "TrialTypeSequenceID". 
Sequence of trial type. 
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====InstructionImagesSequence====
The sequence of instruction images path.

====FixationDurationList====
Duration of Fixation(ITI) list.

====DotsDuration====
Duration of displaying the dots

====ResponseDuration====
The maximum time allows the subject to make a response.

====OutcomeDuration====
The duration to display the outcome.

====CompensationDuration====
The duration to display the compensation.

====EnablePractice====
Enable the practice trial or not

====StartPoints====
The initial total points of the game

====GuessDots====
INstruction of the guessing the number of the dots

====DotsNumber====
Guess the number of dots is greater or less than the "DotsNumber", "DotsNumber" is the number to be compared with.

====optionOne, optionTwo====
guess option one/two, for example "Greater" and "Less"

====CompensationQuestion====
Instruction of compensation phase

====CompensationOne, CompensationTwo, CompensationThree, CompensationFour====
Compensation options

====ForgivenessQuestion====
Instruction of forgiveness phase

====ForgivenessOne, ForgivenessTwo, ForgivenessThree, ForgivenessFour====
Forgiveness options

Unlike the parameters described above, they are saved on the server rather than on local computers.

===Local Parameters===

====FontSize, FixationSize====
Font/Fixation size.

====FontColor, FixationColor====
Color of the font/fixation.

====FontActiveColor====
Color of the active font(be selected)

====GUIScale====
Scale the GUI, 1 is maximum, 0 is minimium

====TrialTypeSequenceID====
Specify the trial type sequence, see Parameter "TrialSequece1 and TrialSequece2"

====ProgressBar====
Display progress bar.

====ProgressBarHeight, ProgressBarWidth====
Progress bar height/width in pixels.

====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Color of progress bar background/foreground.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===Shared State===

====isReadyStart0, isReadyStart1====
Check if client0/client1 is ready to move to the next phase or trial.

====ClientNumber====
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits) 
0: Transgressor. 1: Victim

====Compensation====
The compensation that the transgressor gives in each trial

====Forgiveness====
The forgiveness that the victim gives in each trial

===Local State===
====PhaseNumber====
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen) 
[1] present the instruction showing the end of the practice trial 
[2] present the fixation on the screen. 
[3] present the dots on the screen. 
[4] The subject estimates the number of dots. 
[5] Display the outcome. 
[6] Choose the compensation/forgiveness level. 
[7] The end of the game, shows the total score, compensation and average forgiveness. 
[8] End: (Well done! You have finished all the trials.) 
[9] none, the initial value of the state. 

====TrialNumber====
Index of trials. (8 bits)

====TrialType====
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====StimulusCode====
The id of the stimulus in each trial

====ResponseValue====
1: greater. 2: smaller. (8 bits)

====FixationDuration====
The duration of the fixation phase in each trial.

====Photodiode====
1: active;
2: non-active

GuiltTask

2024-08-14T16:53:11Z

Lingling: /* Parameters */

==Synopsis==
In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task.
During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots.
After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

==Timeline==
<gallery mode="packed" widths=1200px heights=700px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=800px heights=450px>
File:GuiltTaskVideo.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:xxx.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====Stimuli====
Shared parameter, stimulus information, including: 
1. ImagePath(the path of dots images).

====MyStimuliSequence====
The sequence of dots images.

====StimuliSequencePractice====
Practice trial stimuli sequence

====InstructionPathTrans=====
Transgressor instruction image path

====InstructionPathVicT=====
Victim instruction image path

====FeedbackPathList====
Feedback icon path list

====TrialSequece1, TrialSequece2====
There are two sequences of trial types, for each experiment, we can run them alternatively, we can specify the sequence through the Parameter "TrialTypeSequenceID". 
Sequence of trial type. 
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====InstructionImagesSequence====
The sequence of instruction images path.

====FixationDurationList====
Duration of Fixation(ITI) list.

====DotsDuration====
Duration of displaying the dots

====ResponseDuration====
The maximum time allows the subject to make a response.

====OutcomeDuration====
The duration to display the outcome.

====CompensationDuration====
The duration to display the compensation.

====EnablePractice====
Enable the practice trial or not

====StartPoints====
The initial total points of the game

====GuessDots====
INstruction of the guessing the number of the dots

====DotsNumber====
Guess the number of dots is greater or less than the "DotsNumber", "DotsNumber" is the number to be compared with.

====optionOne, optionTwo====
guess option one/two, for example "Greater" and "Less"

====CompensationQuestion====
Instruction of compensation phase

====CompensationOne, CompensationTwo, CompensationThree, CompensationFour====
Compensation options

====ForgivenessQuestion====
Instruction of forgiveness phase

====ForgivenessOne, ForgivenessTwo, ForgivenessThree, ForgivenessFour====
Forgiveness options

Unlike the parameters described above, they are saved on the server rather than on local computers.

===Local Parameters===

====FontSize, FixationSize====
Font/Fixation size.

====FontColor, FixationColor====
Color of the font/fixation.

====FontActiveColor====
Color of the active font(be selected)

====GUIScale====
Scale the GUI, 1 is maximum, 0 is minimium

====TrialTypeSequenceID====
Specify the trial type sequence, see Parameter "TrialSequece1 and TrialSequece2"

====ProgressBar====
Display progress bar.

====ProgressBarHeight, ProgressBarWidth====
Progress bar height/width in pixels.

====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Color of progress bar background/foreground.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===Shared State===

====isReadyStart0, isReadyStart1====
Check if client0/client1 is ready to move to the next phase or trial.

====ClientNumber====
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits) 
0: Transgressor. 1: Victim

====Compensation====
The compensation that the transgressor gives in each trial

====Forgiveness====
The forgiveness that the victim gives in each trial

===Local State===
====PhaseNumber====
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen) 
[1] present the instruction showing the end of the practice trial 
[2] present the fixation on the screen. 
[3] present the dots on the screen. 
[4] The subject estimates the number of dots. 
[5] Display the outcome. 
[6] Choose the compensation/forgiveness level. 
[7] The end of the game, shows the total score, compensation and average forgiveness. 
[8] End: (Well done! You have finished all the trials.) 
[9] none, the initial value of the state. 

====TrialNumber====
Index of trials. (8 bits)

====TrialType====
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====StimulusCode====
The id of the stimulus in each trial

====ResponseValue====
1: greater. 2: smaller. (8 bits)

====FixationDuration====
The duration of the fixation phase in each trial.

====Photodiode====
1: active;
2: non-active

GuiltTask

2024-08-09T16:22:43Z

Lingling: /* PhaseNumber */

==Synopsis==
In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task.
During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots.
After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

==Timeline==
<gallery mode="packed" widths=1200px heights=700px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=800px heights=450px>
File:GuiltTaskVideo.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:xxx.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====Stimuli====
Shared parameter, stimulus information, including: 
1. ImagePath(the path of dots images).

====MyStimuliSequence====
The sequence of dots images.

====StimuliSequencePractice====
Practice trial stimuli sequence

====InstructionPathTrans=====
Transgressor instruction image path

====InstructionPathVicT=====
Victim instruction image path

====FeedbackPathList====
Feedback icon path list

====TrialSequece1, TrialSequece2====
There are two sequences of trial types, for each experiment, we can run them alternatively, we can specify the sequence through the Parameter "TrialTypeSequenceID". 
Sequence of trial type. 
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====InstructionImagesSequence====
The sequence of instruction images path.

====FixationDurationList====
Duration of Fixation(ITI) list.

====DotsDuration====
Duration of displaying the dots

====ResponseDuration====
The maximum time allows the subject to make a response.

====OutcomeDuration====
The duration to display the outcome.

====CompensationDuration====
The duration to display the compensation.

====EnablePractice====
Enable the practice trial or not

====StartPoints====
The initial total points of the game

====GuessDots====
INstruction of the guessing the number of the dots

====DotsNumber====
Guess the number of dots is greater or less than the "DotsNumber", "DotsNumber" is the number to be compared with.

====optionOne, optionTwo====
guess option one/two, for example "Greater" and "Less"

====CompensationQuestion====
Instruction of compensation phase

====CompensationOne, CompensationTwo, CompensationThree, CompensationFour====
Compensation options

====ForgivenessQuestion====
Instruction of forgiveness phase

====ForgivenessOne, ForgivenessTwo, ForgivenessThree, ForgivenessFour====
Forgiveness options

Unlike the parameters described above, they are saved on the server rather than on local computers.

===Local Parameters===

====FontSize, FixationSize====
Font/Fixation size.

====FontColor, FixationColor====
Color of the font/fixation.

====FontActiveColor====
Color of the active font(be selected)

====GUIScale====
Scale the GUI, 1 is maximum, 0 is minimium

====TrialTypeSequenceID====
Specify the trial type sequence, see Parameter "TrialSequece1 and TrialSequece2"

====ProgressBar====
Display progress bar.

====ProgressBarHeight, ProgressBarWidth====
Progress bar height/width in pixels.

====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Color of progress bar background/foreground.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===Shared State===

====isReadyStart0, isReadyStart1====
Check if client0/client1 is ready to move to the next phase or trial.

====ClientNumber====
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits) 
0: Transgressor. 1: Victim

====Compensation====
The compensation that the transgressor gives in each trial

====Forgiveness====
The forgiveness that the victim gives in each trial

===Local State===
====PhaseNumber====
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen) 
[1] present the instruction showing the end of the practice trial 
[2] present the fixation on the screen. 
[3] present the dots on the screen. 
[4] The subject estimates the number of dots. 
[5] Display the outcome. 
[6] Choose the compensation/forgiveness level. 
[7] The end of the game, shows the total score, compensation and average forgiveness. 
[8] End: (Well done! You have finished all the trials.) 
[9] none, the initial value of the state. 

====TrialNumber====
Index of trials. (8 bits)

====TrialType====
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====StimulusCode====
The id of the stimulus in each trial

====ResponseValue====
1: greater. 2: smaller. (8 bits)

====FixationDuration====
The duration of the fixation phase in each trial.

====Photodiode====
1: active;
2: non-active

GuiltTask

2024-08-09T16:22:13Z

Lingling: /* States */

==Synopsis==
In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task.
During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots.
After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

==Timeline==
<gallery mode="packed" widths=1200px heights=700px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=800px heights=450px>
File:GuiltTaskVideo.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:xxx.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====Stimuli====
Shared parameter, stimulus information, including: 
1. ImagePath(the path of dots images).

====MyStimuliSequence====
The sequence of dots images.

====StimuliSequencePractice====
Practice trial stimuli sequence

====InstructionPathTrans=====
Transgressor instruction image path

====InstructionPathVicT=====
Victim instruction image path

====FeedbackPathList====
Feedback icon path list

====TrialSequece1, TrialSequece2====
There are two sequences of trial types, for each experiment, we can run them alternatively, we can specify the sequence through the Parameter "TrialTypeSequenceID". 
Sequence of trial type. 
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====InstructionImagesSequence====
The sequence of instruction images path.

====FixationDurationList====
Duration of Fixation(ITI) list.

====DotsDuration====
Duration of displaying the dots

====ResponseDuration====
The maximum time allows the subject to make a response.

====OutcomeDuration====
The duration to display the outcome.

====CompensationDuration====
The duration to display the compensation.

====EnablePractice====
Enable the practice trial or not

====StartPoints====
The initial total points of the game

====GuessDots====
INstruction of the guessing the number of the dots

====DotsNumber====
Guess the number of dots is greater or less than the "DotsNumber", "DotsNumber" is the number to be compared with.

====optionOne, optionTwo====
guess option one/two, for example "Greater" and "Less"

====CompensationQuestion====
Instruction of compensation phase

====CompensationOne, CompensationTwo, CompensationThree, CompensationFour====
Compensation options

====ForgivenessQuestion====
Instruction of forgiveness phase

====ForgivenessOne, ForgivenessTwo, ForgivenessThree, ForgivenessFour====
Forgiveness options

Unlike the parameters described above, they are saved on the server rather than on local computers.

===Local Parameters===

====FontSize, FixationSize====
Font/Fixation size.

====FontColor, FixationColor====
Color of the font/fixation.

====FontActiveColor====
Color of the active font(be selected)

====GUIScale====
Scale the GUI, 1 is maximum, 0 is minimium

====TrialTypeSequenceID====
Specify the trial type sequence, see Parameter "TrialSequece1 and TrialSequece2"

====ProgressBar====
Display progress bar.

====ProgressBarHeight, ProgressBarWidth====
Progress bar height/width in pixels.

====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Color of progress bar background/foreground.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===Shared State===

====isReadyStart0, isReadyStart1====
Check if client0/client1 is ready to move to the next phase or trial.

====ClientNumber====
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits) 
0: Transgressor. 1: Victim

====Compensation====
The compensation that the transgressor gives in each trial

====Forgiveness====
The forgiveness that the victim gives in each trial

===Local State===
====PhaseNumber====
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen)<be>
[1] present the instruction showing the end of the practice trial 
[2] present the fixation on the screen. 
[3] present the dots on the screen. 
[4] The subject estimates the number of dots. 
[5] Display the outcome.<be>
[6] Choose the compensation/forgiveness level.<be>
[7] The end of the game, shows the total score, compensation and average forgiveness. 
[8] End: (Well done! You have finished all the trials.)
[9] none, the initial value of the state.
====TrialNumber====
Index of trials. (8 bits)

====TrialType====
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====StimulusCode====
The id of the stimulus in each trial

====ResponseValue====
1: greater. 2: smaller. (8 bits)

====FixationDuration====
The duration of the fixation phase in each trial.

====Photodiode====
1: active;
2: non-active

GuiltTask

2024-08-09T16:16:45Z

Lingling: /* States */

==Synopsis==
In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task.
During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots.
After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

==Timeline==
<gallery mode="packed" widths=1200px heights=700px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=800px heights=450px>
File:GuiltTaskVideo.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:xxx.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====Stimuli====
Shared parameter, stimulus information, including: 
1. ImagePath(the path of dots images).

====MyStimuliSequence====
The sequence of dots images.

====StimuliSequencePractice====
Practice trial stimuli sequence

====InstructionPathTrans=====
Transgressor instruction image path

====InstructionPathVicT=====
Victim instruction image path

====FeedbackPathList====
Feedback icon path list

====TrialSequece1, TrialSequece2====
There are two sequences of trial types, for each experiment, we can run them alternatively, we can specify the sequence through the Parameter "TrialTypeSequenceID". 
Sequence of trial type. 
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====InstructionImagesSequence====
The sequence of instruction images path.

====FixationDurationList====
Duration of Fixation(ITI) list.

====DotsDuration====
Duration of displaying the dots

====ResponseDuration====
The maximum time allows the subject to make a response.

====OutcomeDuration====
The duration to display the outcome.

====CompensationDuration====
The duration to display the compensation.

====EnablePractice====
Enable the practice trial or not

====StartPoints====
The initial total points of the game

====GuessDots====
INstruction of the guessing the number of the dots

====DotsNumber====
Guess the number of dots is greater or less than the "DotsNumber", "DotsNumber" is the number to be compared with.

====optionOne, optionTwo====
guess option one/two, for example "Greater" and "Less"

====CompensationQuestion====
Instruction of compensation phase

====CompensationOne, CompensationTwo, CompensationThree, CompensationFour====
Compensation options

====ForgivenessQuestion====
Instruction of forgiveness phase

====ForgivenessOne, ForgivenessTwo, ForgivenessThree, ForgivenessFour====
Forgiveness options

Unlike the parameters described above, they are saved on the server rather than on local computers.

===Local Parameters===

====FontSize, FixationSize====
Font/Fixation size.

====FontColor, FixationColor====
Color of the font/fixation.

====FontActiveColor====
Color of the active font(be selected)

====GUIScale====
Scale the GUI, 1 is maximum, 0 is minimium

====TrialTypeSequenceID====
Specify the trial type sequence, see Parameter "TrialSequece1 and TrialSequece2"

====ProgressBar====
Display progress bar.

====ProgressBarHeight, ProgressBarWidth====
Progress bar height/width in pixels.

====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Color of progress bar background/foreground.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===Shared State===

====isReadyStart0, isReadyStart1====
Check if client0/client1 is ready to move to the next phase or trial.

====ClientNumber====
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits) 
0: Transgressor. 1: Victim

====Compensation====
The compensation that the transgressor gives in each trial

====Forgiveness====
The forgiveness that the victim gives in each trial

===Local State===
====PhaseNumber====
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen) 
[1] present the fixation on the screen. 
[2] present the dots on the screen. 
[3] The subject estimates the number of dots. 
[4] Display the outcome. 
[5]End: (Well done! You have finished all the trials.)

====TrialNumber====
Index of trials. (8 bits)

====TrialType====
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====StimulusCode====
The id of the stimulus in each trial

====ResponseValue====
1: greater. 2: smaller. (8 bits)

====FixationDuration====
The duration of the fixation phase in each trial.

====Photodiode====
1: active;
2: non-active

GuiltTask

2024-08-09T16:09:53Z

Lingling: /* Parameters */

==Synopsis==
In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task.
During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots.
After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

==Timeline==
<gallery mode="packed" widths=1200px heights=700px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=800px heights=450px>
File:GuiltTaskVideo.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:xxx.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====Stimuli====
Shared parameter, stimulus information, including: 
1. ImagePath(the path of dots images).

====MyStimuliSequence====
The sequence of dots images.

====StimuliSequencePractice====
Practice trial stimuli sequence

====InstructionPathTrans=====
Transgressor instruction image path

====InstructionPathVicT=====
Victim instruction image path

====FeedbackPathList====
Feedback icon path list

====TrialSequece1, TrialSequece2====
There are two sequences of trial types, for each experiment, we can run them alternatively, we can specify the sequence through the Parameter "TrialTypeSequenceID". 
Sequence of trial type. 
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====InstructionImagesSequence====
The sequence of instruction images path.

====FixationDurationList====
Duration of Fixation(ITI) list.

====DotsDuration====
Duration of displaying the dots

====ResponseDuration====
The maximum time allows the subject to make a response.

====OutcomeDuration====
The duration to display the outcome.

====CompensationDuration====
The duration to display the compensation.

====EnablePractice====
Enable the practice trial or not

====StartPoints====
The initial total points of the game

====GuessDots====
INstruction of the guessing the number of the dots

====DotsNumber====
Guess the number of dots is greater or less than the "DotsNumber", "DotsNumber" is the number to be compared with.

====optionOne, optionTwo====
guess option one/two, for example "Greater" and "Less"

====CompensationQuestion====
Instruction of compensation phase

====CompensationOne, CompensationTwo, CompensationThree, CompensationFour====
Compensation options

====ForgivenessQuestion====
Instruction of forgiveness phase

====ForgivenessOne, ForgivenessTwo, ForgivenessThree, ForgivenessFour====
Forgiveness options

Unlike the parameters described above, they are saved on the server rather than on local computers.

===Local Parameters===

====FontSize, FixationSize====
Font/Fixation size.

====FontColor, FixationColor====
Color of the font/fixation.

====FontActiveColor====
Color of the active font(be selected)

====GUIScale====
Scale the GUI, 1 is maximum, 0 is minimium

====TrialTypeSequenceID====
Specify the trial type sequence, see Parameter "TrialSequece1 and TrialSequece2"

====ProgressBar====
Display progress bar.

====ProgressBarHeight, ProgressBarWidth====
Progress bar height/width in pixels.

====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Color of progress bar background/foreground.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===PhaseNumber===
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen) 
[1] present the fixation on the screen. 
[2] present the dots on the screen. 
[3] The subject estimates the number of dots. 
[4] Display the outcome. 
[5]End: (Well done! You have finished all the trials.)

===TrialNumber===
Index of trials. (8 bits)

===TrialType===
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

===Response===
1: greater. 2: smaller. (8 bits)

===ClientNumber===
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits) 
0: Transgressor. 1: Victim

===FixationDuration===
The duration of fixation.

===Photodiode===
1: active;
2: non-active

File:GuiltTaskVideo.gif

2024-08-09T15:27:06Z

Lingling: Lingling uploaded a new version of File:GuiltTaskVideo.gif

GuiltTask

2024-08-09T15:22:35Z

Lingling: /* Visual Representation */

==Synopsis==
In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task.
During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots.
After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

==Timeline==
<gallery mode="packed" widths=1200px heights=700px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=800px heights=450px>
File:GuiltTaskVideo.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:xxx.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====Stimuli====
Shared parameter, stimulus information, including: 
1. ImagePath(the path of dots images).

====StimuliSequece====
The sequence of dots images.

====TrialSequece====
Sequence of trial type. 
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====InstructionImagesSequence====
The sequence of instruction images path.

====FixationDurationMax, FixationDurationMin====
Maximum and minimum Duration of Fixation(ITI).

====DotsDuration====
Duration of displaying the dots

====ResponseDuration====
The maximum time allows the subject to make a response.

====OutcomeDuration====
The duration to display the outcome.

Unlike the parameters described above, they are saved on the server rather than on local computers.

===Local Parameters===

====FontSize, FixationSize====
Font/Fixation size.

====FontColor, FixationColor====
Color of the font/fixation.

====ScreenWidth, ScreenHeight====
Width/height of the monitor screen in cm.

====EyeToSreenDistance====
Distance from the subject's eyes to the screen in cm.

====VisualAngle====
The degrees of visual angle.

====ProgressBar====
Display progress bar.

====ProgressBarHeight, ProgressBarWidth====
Progress bar height/width in pixels.

====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Color of progress bar background/foreground.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===PhaseNumber===
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen) 
[1] present the fixation on the screen. 
[2] present the dots on the screen. 
[3] The subject estimates the number of dots. 
[4] Display the outcome. 
[5]End: (Well done! You have finished all the trials.)

===TrialNumber===
Index of trials. (8 bits)

===TrialType===
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

===Response===
1: greater. 2: smaller. (8 bits)

===ClientNumber===
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits) 
0: Transgressor. 1: Victim

===FixationDuration===
The duration of fixation.

===Photodiode===
1: active;
2: non-active

File:GuiltTaskVideo.gif

2024-08-09T15:20:54Z

Lingling:

GuiltTask

2024-08-09T14:02:06Z

Lingling: /* Timeline */

==Synopsis==
In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task.
During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots.
After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

==Timeline==
<gallery mode="packed" widths=1200px heights=700px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=750px heights=421px>
File:xx.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:xxx.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====Stimuli====
Shared parameter, stimulus information, including: 
1. ImagePath(the path of dots images).

====StimuliSequece====
The sequence of dots images.

====TrialSequece====
Sequence of trial type. 
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====InstructionImagesSequence====
The sequence of instruction images path.

====FixationDurationMax, FixationDurationMin====
Maximum and minimum Duration of Fixation(ITI).

====DotsDuration====
Duration of displaying the dots

====ResponseDuration====
The maximum time allows the subject to make a response.

====OutcomeDuration====
The duration to display the outcome.

Unlike the parameters described above, they are saved on the server rather than on local computers.

===Local Parameters===

====FontSize, FixationSize====
Font/Fixation size.

====FontColor, FixationColor====
Color of the font/fixation.

====ScreenWidth, ScreenHeight====
Width/height of the monitor screen in cm.

====EyeToSreenDistance====
Distance from the subject's eyes to the screen in cm.

====VisualAngle====
The degrees of visual angle.

====ProgressBar====
Display progress bar.

====ProgressBarHeight, ProgressBarWidth====
Progress bar height/width in pixels.

====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Color of progress bar background/foreground.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===PhaseNumber===
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen) 
[1] present the fixation on the screen. 
[2] present the dots on the screen. 
[3] The subject estimates the number of dots. 
[4] Display the outcome. 
[5]End: (Well done! You have finished all the trials.)

===TrialNumber===
Index of trials. (8 bits)

===TrialType===
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

===Response===
1: greater. 2: smaller. (8 bits)

===ClientNumber===
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits) 
0: Transgressor. 1: Victim

===FixationDuration===
The duration of fixation.

===Photodiode===
1: active;
2: non-active

File:Guilty task time line.png

2024-08-09T14:00:41Z

Lingling: Lingling uploaded a new version of File:Guilty task time line.png

GuiltTask

2024-06-18T19:58:28Z

Lingling: /* InstructionImagesSeque */

==Synopsis==
In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task.
During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots.
After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

==Timeline==
<gallery mode="packed" widths=1000px heights=500px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=750px heights=421px>
File:xx.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:xxx.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====Stimuli====
Shared parameter, stimulus information, including: 
1. ImagePath(the path of dots images).

====StimuliSequece====
The sequence of dots images.

====TrialSequece====
Sequence of trial type. 
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====InstructionImagesSequence====
The sequence of instruction images path.

====FixationDurationMax, FixationDurationMin====
Maximum and minimum Duration of Fixation(ITI).

====DotsDuration====
Duration of displaying the dots

====ResponseDuration====
The maximum time allows the subject to make a response.

====OutcomeDuration====
The duration to display the outcome.

Unlike the parameters described above, they are saved on the server rather than on local computers.

===Local Parameters===

====FontSize, FixationSize====
Font/Fixation size.

====FontColor, FixationColor====
Color of the font/fixation.

====ScreenWidth, ScreenHeight====
Width/height of the monitor screen in cm.

====EyeToSreenDistance====
Distance from the subject's eyes to the screen in cm.

====VisualAngle====
The degrees of visual angle.

====ProgressBar====
Display progress bar.

====ProgressBarHeight, ProgressBarWidth====
Progress bar height/width in pixels.

====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Color of progress bar background/foreground.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===PhaseNumber===
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen) 
[1] present the fixation on the screen. 
[2] present the dots on the screen. 
[3] The subject estimates the number of dots. 
[4] Display the outcome. 
[5]End: (Well done! You have finished all the trials.)

===TrialNumber===
Index of trials. (8 bits)

===TrialType===
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

===Response===
1: greater. 2: smaller. (8 bits)

===ClientNumber===
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits) 
0: Transgressor. 1: Victim

===FixationDuration===
The duration of fixation.

===Photodiode===
1: active;
2: non-active

GuiltTask

2024-06-13T16:41:27Z

Lingling:

==Synopsis==
In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task.
During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots.
After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

==Timeline==
<gallery mode="packed" widths=1000px heights=500px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>

== Visual Representation ==
<gallery mode="packed" widths=750px heights=421px>
File:xx.gif|Figure 2: Visual Representation
</gallery>

==Versioning==
===Authors===
Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm. 
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000. 

==Set up==
===Deploy the Server===
You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2. 
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub.
<pre>git clone https://github.com/MaxwellMarcus/hyperscanning-backend</pre>
Go the hyperscanning directory
<pre>cd hyperscanning</pre>
Compile the project by
<pre>make -B</pre>
<gallery mode="packed" widths=600px heights=350px>
File:CommunicationTask server set up.png|Figure 3: Download and Compile the Server.
</gallery>
Run the server with
<pre>./application</pre>
<gallery mode="packed" widths=600px heights=100px>
File:CommunicationTask_server_launched.png|Figure 4: Launch the Server.
</gallery>
The application will only run as long as the experiment and will have to be restarted.

===Batch File===
The batch file is located in ./batch/CommunicationTask.bat.
<gallery mode="packed" widths=600px heights=200px>
File:xxx.png|Figure 5: Batch File.
</gallery>

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is:
<pre>--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...</pre>
IPAddress and Port indicate the server computer.

===Run the experiment on the client computer===
Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

<gallery mode="packed" widths=600px heights=400px>
File:Launch_the_experiment.gif|Figure 6: Launch the BCI2000.
</gallery>

==Troubleshooting==
After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

<gallery mode="packed" widths=400px heights=300px>
File:Kill server.png|Figure 7: Kill the Server.
</gallery>

==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

====Stimuli====
Shared parameter, stimulus information, including: 
1. ImagePath(the path of dots images).

====StimuliSequece====
The sequence of dots images.

====TrialSequece====
Sequence of trial type. 
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

====InstructionImagesSeque====
The sequence of instruction images path.

====FixationDurationMax, FixationDurationMin====
Maximum and minimum Duration of Fixation(ITI).

====DotsDuration====
Duration of displaying the dots

====ResponseDuration====
The maximum time allows the subject to make a response.

====OutcomeDuration====
The duration to display the outcome.

Unlike the parameters described above, they are saved on the server rather than on local computers.

===Local Parameters===

====FontSize, FixationSize====
Font/Fixation size.

====FontColor, FixationColor====
Color of the font/fixation.

====ScreenWidth, ScreenHeight====
Width/height of the monitor screen in cm.

====EyeToSreenDistance====
Distance from the subject's eyes to the screen in cm.

====VisualAngle====
The degrees of visual angle.

====ProgressBar====
Display progress bar.

====ProgressBarHeight, ProgressBarWidth====
Progress bar height/width in pixels.

====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Color of progress bar background/foreground.

====PhotoDiodePatch====
Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

==== PhotoDiodePatchHeight, PhotoDiodePatchWidth====
Photodiode patch height/width in relative coordinates (between 0 and 1).

====PhotoDiodePatchLeft, PhotoDiodePatchTop ====
Photodiode patch left/top position in relative coordinates (between 0 and 1).

====PhotoDiodePatchShape====
Photodiode patch shape: 0 rectangle, 1 ellipse.

====PhotoDiodePatchActiveColor====
Photodiode patch color when active (RGB color in format 0xrrggbb).

====PhotoDiodePatchInactiveColor====
Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

==States==
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

===PhaseNumber===
The index of phase in each trial. (8 bits) 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen) 
[1] present the fixation on the screen. 
[2] present the dots on the screen. 
[3] The subject estimates the number of dots. 
[4] Display the outcome. 
[5]End: (Well done! You have finished all the trials.)

===TrialNumber===
Index of trials. (8 bits)

===TrialType===
1: both correct 
2: victim incorrect 
3: transgressor incorrect 
4: both incorrect

===Response===
1: greater. 2: smaller. (8 bits)

===ClientNumber===
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits) 
0: Transgressor. 1: Victim

===FixationDuration===
The duration of fixation.

===Photodiode===
1: active;
2: non-active