https://www.bci2000.org/mediawiki/api.php?action=feedcontributions&feedformat=atom&user=TytbutlerBCI2000 Wiki - User contributions [en]2026-06-29T20:59:39ZUser contributionsMediaWiki 1.43.6https://www.bci2000.org/mediawiki/index.php?title=User_Tutorial:UnityBCI2000&diff=11773User Tutorial:UnityBCI20002025-03-14T04:33:33Z<p>Tytbutler: fixed example</p>
<hr />
<div><pre style="color:red"><br />
Red text blocks contain detailed instructions for the higher-level instructions preceding them.<br />
</pre><br />
<br />
This example comprehensively demonstrates many of the capabilities of UnityBCI2000, and as such, is more than what is necessary for many usecases. If you just want to use BCI2000 as a logging backend for an existing Unity application, see [[User Tutorial:UnityBCI2000 Barebones]].<br />
<br />
===Download Unity===<br />
<br />
Download Unity Hub from [https://unity3d.com Unity].<br />
<br />
===Setting Up BCI2000===<br />
<br />
Follow the instructions starting with [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Install_Prerequisites] to download BCI2000. <br />
<br />
===Setting Up UnityBCI2000===<br />
Download UnityBCI2000 from its GitHub page, [https://github.com/neurotechcenter/UnityBCI2000]. <br />
<pre style="color:red"><br />
Click on the "Releases" section on the right side of the page. This tutorial is intended to be used with UnityBCI2000 version 2.0.0, so scroll to that release and click on the files BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to download them.<br />
</pre><br />
<br />
===Download Tutorial Project===<br />
Download the CursorTask3 repository from [https://github.com/Personator01/CursorTask3 GitHub].<br />
<pre style="color:red"><br />
Either:<br />
-Clone the git repository<br />
-Download the respository directly from GitHub<br />
-> Click the green "Code" button <br />
-> Select "Download ZIP"<br />
-> Extract the zip file<br />
</pre><br />
The download directory contains two versions of the CursorTask3 project. One, CursorTask3-BCI2K, contains an example implementation of the task with BCI2000 integration. The other, CursorTask3-NoBCI2K, contains the same task without BCI2000 integration. This tutorial is a step by step guide on turning that second project into the first. <br />
<br />
===Opening the project===<br />
Open the project in the Unity Editor, and open the CursorTask scene.<br />
<pre style="color:red"><br />
Open Unity Hub.<br />
Click the "Add" button in the top right corner.<br />
Navigate to the CursorTask3 directory downloaded previously.<br />
Select the CursorTask3-NoBCI2K directory to add it to Unity Hub.<br />
Click the CursorTask3-NoBCI2K project in the Unity Hub.<br />
If prompted to select a version of Unity to use or install, select Unity 2022.3. The specific release number of Unity 2022.3 should not matter, so select the one labeled "LTS" for consistency.<br />
The lower panel (the asset browser) should already show the Assets/Scenes directory, which contains a single scene called SampleScene.<br />
Double-click SampleScene. This should open a scene with a box containing various lights and objects.<br />
</pre><br />
If you wish to view the completed implementation, repeat these steps, but instead open the CursorTask3-BCI2K directory. Note that in order to use the completed implementation, you will still need to set the Operator Path value of the UnityBCI2000 component of the BCI2000 game object.<br />
<br />
===Adding UnityBCI2000 to the project===<br />
Add BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to your project's assets.<br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click Assets > Open Containing Folder to open your project directory.<br />
Place the BCI2000RemoteNETStandard.dll and UnityBCI2000.cs files in the Assets folder.<br />
</pre><br />
<br />
Add an empty GameObject called 'BCI2000'. This will hold the scripts for controlling BCI2000. <br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click GameObject > Create Empty to create an empty GameObject, and name it 'BCI2000'. (The object's specific name does not actually matter, it is only needed in order to reference it within other scripts)<br />
You will notice that it now appears in the Scene Hierarchy panel, on the left side of the screen.<br />
</pre><br />
<br />
Add the UnityBCI2000 component to the object.<br />
<pre style="color:red"><br />
Click on the object in the Hierarchy panel. This will open it in the Inspector panel (the panel on the right side of the screen)<br />
In the inspector, below the new object's Transform component, click the "Add Component" button, which will open up a small window for adding components.<br />
Within this window, select Scripts > Unity BCI2000 to add the UnityBCI2000 component.<br />
</pre><br />
<br />
===Configuring UnityBCI2000===<br />
The inspector panel now contains the configuration options for UnityBCI2000. Set the options as follows:<br />
<br />
<code>Start Local Operator</code>: Checked<br />
<br />
This will start the operator on your computer when the Unity scene initializes. If we were instead connecting to an already-running instance of BCI2000, or an instance on another computer, this box would be deselected.<br />
<br />
<code>Operator Path</code>: The path to the Operator executable. This will look something like this on Windows (C://path/to/bci2000/prog/Operator.exe)<br />
<br />
<code>Operator Address</code>: 127.0.0.1<br />
<br />
This is the address of the machine on which BCI2000 is running. Since we are running BCI2000 on the same computer as Unity, we leave it as 127.0.0.1, the loopback address.<br />
<br />
<code>Operator Port</code>: 3999<br />
<br />
This is the port on which BCI2000 is listening for commands. By default, it is 3999.<br />
<br />
<code>Start Modules</code>: Checked<br />
<br />
This tells BCI2000 to start the requested Signal Source, Signal Processing, and Application modules when the Unity scene initializes. Similarly to Start Local Operator, we would deselect this box if connecting to an already-running instance. <br />
<br />
<code>Start With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to start a data collection run when the scene starts. Since we will be using BCI2000 itself to set experiment parameters, we will instead wait for BCI2000 to start from Unity, and thus will leave the box unchecked. <br />
<br />
<code>Stop With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to stop collecting data when the scene stops. Since we will be controlling BCI2000 directly, rather than entirely through Unity, we will leave this unchecked.<br />
<br />
<code>Shutdown With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to shut down alongside the Unity scene. Whether or not this value is set ultimately doesn't matter much, especially if Start Local Operator is checked. The data will be saved whether or not BCI2000 shuts down. <br />
<br />
<code>Module 1</code>: SignalGenerator<br />
<br />
The signal source module to start. We will use SignalGenerator, which generates a signal without any connected hardware.<br />
<br />
<code>Module 2</code>: DummySignalProcessing<br />
<br />
The signal processing module to start. We will use DummySignalProcessing, as there is no processing to do.<br />
<br />
<code>Module 3</code>: DummyApplication<br />
<br />
The Application module to start. Since we are using Unity, we will use DummyApplication.<br />
<br />
===Setting References===<br />
In order for the game's scripts to communicate with BCI2000, they need to hold a reference to the UnityBCI2000 component.<br />
There are three scripts which will need to communicate with BCI2000. They are <code>GameControl.cs, BallControl.cs, and MCursorControl.cs</code>.<br />
These scripts are each located within the Assets directory of the Unity project. <br />
<pre style="color:red"><br />
As before, select Assets > Open Containing Folder to open the project directory, then open the Assets folder. <br />
For each script, open it in a text editor.<br />
Add a data member of type UnityBCI2000 to the class, like so:<br />
UnityBCI2000 bci;<br />
Place the member definition above the Awake() method, for readability.<br />
Within the Awake() method, set this reference to the UnityBCI2000 component.<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
</pre><br />
Each of the three scripts should contain a section like this:<br />
<pre><br />
...<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
</pre><br />
<br />
===Adding Events===<br />
[https://www.bci2000.org/mediawiki/index.php/Programming_Reference:Events Events] are the primary way that non-signal experiment data is recorded in BCI2000. They are timestamped integer values which are encoded alongside the signal data in BCI2000 output files. Due to BCI2000's design, events must be added during a very specific part of its startup sequence, which is immediately after the BCI2000 operator starts, and before any of the modules start. As such, we cannot simply call <code>AddEvent()</code> whenever we want. Furthermore, the order in which Unity objects initialize is undefined, so it cannot even be guaranteed that calling <code>AddEvent</code> at a specific time will be consistent across multiple projects. As such, UnityBCI2000 provides a couple of methods for sending commands at well-defined points within the startup sequence. These two methods, <code>OnIdle</code> and <code>OnIdle</code> and <code>OnConnected</code> allow BCI2000 commands to be sent while the operator is in the state Idle (immediately before starting its modules) and when the operator is in the state Connected (after starting and connecting to the modules. Below is an example of using those methods to add and show an event in BCI2000.<br />
<br />
<pre><br />
class Script : MonoBehaviour {<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000Object").GetComponent<UnityBCI2000>();<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("AnEvent", 32);<br />
});<br />
}<br />
void Start() {<br />
bci.OnConnected(remote => {<br />
remote.Visualize("AnEvent");<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
As seen above, <code>OnIdle</code> and <code>OnConnected</code> take a delegate (C#'s term for a callback/closure/functor/etc.) with a single parameter of type <code>BCI2000Remote</code> (in this case called "remote"). The lambda expression given to the call to <code>OnIdle</code> uses the method <code>BCI2000Remote.AddEvent()</code> to add an event called "AnEvent" with a bit width of 32 bits. The call to <code>OnConnected</code> tells BCI2000 to show the event's value in a graphical window. A description of the BCI2000Remote class can be found [https://www.bci2000.org/mediawiki/index.php/Contributions:BCI2000RemoteNET here], and API documentation can be found [https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html here].<br />
<br />
We will now add the events relevant to the Cursor Task. Open the <code>GameControl.cs</code> script, and modify its <code>Awake()</code> to add the events <code>PreFeedback</code>, <code>Feedback</code>, <code>PostFeedback</code>, <code>TargetHit</code>, and <code>Timeout</code> with bit width 1. Additionally, add the events <code>TrialNumber</code>, <code>TargetPositionX</code>, and <code>TargetPositionY</code> with width 16. These will encode the task state and number of trials.<br />
We also need to set a parameter value so that the signal will be set to the mouse position. Using <code>BCI2000Remote.SetParameter()</code>, we will set the <code>ModulateAmplitude</code> parameter to 1.<br />
<br />
Open the <code>BallControl.cs</code> script, and within the <code>Awake()</code> function, add events <code>CursorPositionX</code> and <code>CursorPositionY</code>, with width 16. Show these events in a visualization window with <code>Visualize</code><br />
<br />
Your two scripts should now look like this: <br />
<pre><br />
>>> GameControl.cs <br />
...<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
remote.AddEvent("Feedback", 1);<br />
remote.AddEvent("PostFeedback", 1);<br />
remote.AddEvent("TargetHit", 1);<br />
remote.AddEvent("Timeout", 1);<br />
remote.AddEvent("TrialNumber", 16);<br />
remote.AddEvent("TargetPositionX", 16);<br />
remote.AddEvent("TargetPositionY", 16);<br />
remote.SetParameter("ModulateAmplitude", "1");<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
...<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("CursorPositionX", 16);<br />
remote.AddEvent("CursorPositionY", 16);<br />
});<br />
bci.OnConnected(remote => {<br />
remote.Visualize("CursorPositionX");<br />
remote.Visualize("CursorPositionY");<br />
}<br />
</pre><br />
<br />
<br />
<br />
===Using BCI2000 Parameters===<br />
====Adding Parameters====<br />
BCI2000's operator contains an interface for changing experiment parameters before running a task. By making use of this interface we can change the behavior of the task dynamically, without needing to rebuild the Unity project each time. In order to do this we need to define the parameters and add them to BCI2000, and later read their values after the operator has a chance to change them. <span style="color: red">This section is not strictly necessary. The project will function the same whether this is done or not, just without the option to change parameters at runtime. </span> <br />
<br />
First, we define add parameters to BCI2000. Similarly to events, parameters must be added while the Operator is in the <code>Idle</code> state, so we add them inside of <code>OnIdle</code>, like below:<br />
<pre><br />
public int someParameter = 5;<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddParameter("Application:ParameterPlace", "SomeParameter", someParameter.ToString()); <br />
});<br />
}<br />
<br />
The first argument to the method is the section into which the parameter is placed, that is, on which tab and under which heading the parameter will appear within the Operator's parameter editor window (note that the section is not a scope, all parameter names must be unique). The second argument is the parameter name itself. The third argument is the default value of the parameter. We pass in the value of the parameter, so when it appears in the Operator, its default value is 5 (or another value if it has been changed in the Unity Editor). Note that all parameters are handled as strings, so we need to convert its value to a string when sending it.<br />
<br />
For <code>GameControl.cs</code>, we will add parameters corresponding to the Pre-Feedback, Feedback, and Post-Feedback durations, Target Radius, and Number of Trials.<br />
For <code>BallControl.cs</code>, we will add parameters corresponding to the Acceleration Scale, Coefficient of Restitution, Coefficient of Drag, and Attraction Curve Coefficient (how quickly the Ball moves to follow the Mouse Cursor).<br />
For <code>MCursorControl.cs</code>, we will add a parameter corresponding to the Rolling Maximum Amount.<br />
<br />
Your scripts should look like this:<br />
<pre><br />
>>> GameControl.cs<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
...<br />
<br />
remote.AddParameter("Application:Task", "PreFeedbackDuration", preFeedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "FeedbackDuration", feedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "PostFeedbackDuration", postFeedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "TargetRadius", targetRadius.ToString());<br />
remote.AddParameter("Application:Task", "Trials", n_trials.ToString());<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddParameter("Application:Physics", "AccelerationScale", accelerationScale.ToString());<br />
remote.AddParameter("Application:Physics", "CoeffOfRestitution", coefficientOfRestitution.ToString());<br />
remote.AddParameter("Application:Physics", "CoeffOfDrag", coefficientOfDrag.ToString());<br />
remote.AddParameter("Application:Physics", "AccelerationCurve", attractionCurveCoefficient.ToString());<br />
})}<br />
}<br />
<br />
>>> MCursorControl.cs<br />
void Awake() {<br />
...<br />
<br />
bci.OnIdle(remote => {<br />
AddParameter("Application:Physics", "RollingMaximumAmount", rollingMaximumAmount.ToString());<br />
});<br />
}<br />
<br />
<br />
====Reading and Validating Parameters====<br />
Since we set the parameters within the BCI2000 operator, we need some way to read them back into Unity after they have been set. Specifically, we need to read them after the operator clicks the "Set Config" button within the BCI2000 Operator. How this timing synchronization is covered in the section [[Reacting to BCI2000 state changes]]. In this section we will cover reading and validating parameters.<br />
<br />
A method called <code>SetConfig</code> is provided in each of the scripts in which we added parameters previously. This method will be called after the operator changes parameters. In this method we will read in parameters and parse them into valid values. Using the same example parameter as before:<br />
<pre><br />
void SetConfig() {<br />
try {<br />
someParameter = int.Parse(bci.Control.GetParameter("SomeParameter"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse parameter SomeParameter as int");<br />
throw e;<br />
}<br />
}<br />
</pre><br />
<br />
Note that since we are now working outside the BCI2000 startup sequence, we use <code>UnityBCI2000.Control</code> to call <code>BCI2000Remote</code> methods directly, rather than using <code>OnIdle</code> or <code>OnConnected</code>. We also wrap the call within a try/catch block so that we can report erroneous parameters back to the operator. This is optional, but it keeps your project from failing silently and is otherwise useful for doing things like distributing your Unity project as a standalone executable, where logging errors can only be done through the BCI2000 operator. You can also write a helper function which handles parsing and error reporting for you:<br />
<br />
<pre><br />
int GetParseParameterInt(string paramName) {<br />
int p_val = bci.Control.GetParameter("SomeParameter");<br />
try {<br />
someParameter = int.Parse(p_val);<br />
} catch (FormatException e) {<br />
bci.Error($"Could not parse parameter {paramName} (value {p_val}) as int");<br />
throw e;<br />
}<br />
}<br />
</pre><br />
Unfortunately, since the version of C# used by Unity does not support type-parameterized parsing, you must write one of these helper functions for each type of data you want to store in a parameter (int, float, double, etc.)<br />
<br />
<br />
Read back the parameters added in the previous step. Your scripts should look like this:<br />
<br />
<pre><br />
>>> GameControl.cs <br />
void SetConfig() {<br />
try {<br />
preFeedbackDuration = float.Parse(bci.Control.GetParameter("PreFeedbackDuration"));<br />
feedbackDuration = float.Parse(bci.Control.GetParameter("FeedbackDuration"));<br />
postFeedbackDuration = float.Parse(bci.Control.GetParameter("PostFeedbackDuration"));<br />
targetRadius = float.Parse(bci.Control.GetParameter("TargetRadius"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse one of PreFeedbackDuration, FeedbackDuration, PostFeedbackDuration, or TargetRadius as a float");<br />
throw e;<br />
}<br />
try {<br />
n_trials = int.Parse(bci.Control.GetParameter("Trials"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse Trials as an int");<br />
throw e;<br />
}<br />
<br />
if (preFeedbackDuration < COUNTDOWN_DURATION) {<br />
bci.Error("preFeedbackDuration must be greater than or equal to 2.25");<br />
throw new Exception("preFeedbackDuration must be greater than or equal to 2.25");<br />
}<br />
}<br />
<br />
>>> BallControl.cs<br />
public void SetConfig() {<br />
try {<br />
accelerationScale = float.Parse(bci.Control.GetParameter("AccelerationScale"));<br />
coefficientOfRestitution = float.Parse(bci.Control.GetParameter("CoeffOfRestitution"));<br />
coefficientOfDrag = float.Parse(bci.Control.GetParameter("CoeffOfDrag"));<br />
attractionCurveCoefficient = float.Parse(bci.Control.GetParameter("AccelerationCurve"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse one of AccelerationScale, CoeffOfRestitution, CoeffOfDrag, AccelerationCurve as float");<br />
throw e;<br />
}<br />
}<br />
<br />
>>> MCursorControl.cs<br />
public void SetConfig() {<br />
try {<br />
rollingMaximumAmount = int.Parse(bci.Control.GetParameter("RollingMaximumAmount"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse parameter RollingMaximumAmount as int");<br />
throw e;<br />
}<br />
signalsX = new int[rollingMaximumAmount];<br />
signalsY = new int[rollingMaximumAmount];<br />
}<br />
</pre><br />
<br />
Note that in <code>GameControl.cs</code>, we also verify that the Pre-Feedback Duration is longer than the duration of the countdown that happens before each trial, and report errors to BCI2000 accordingly.<br />
<br />
<br />
===Reacting to BCI2000 state changes===<br />
Since we will be controlling the Unity task from BCI2000, we need some way to wait for BCI2000 to be in a specific state, for example, waiting for the operator to click Start and put the Operator Module into the Running state. UnityBCI2000 provides a method for this, the <code>UnityBCI2000.PollSystemState</code> method. In order to wait for the Operator Module to be in the <code>Running</code> state:<br />
<pre><br />
bci.PollSystemState(BCI2000Remote.SystemState.Running);<br />
</pre><br />
This will check once per frame whether or not the Operator is in the <code>Running</code> state, and only continue once BCI2000 is in the <code>Running</code> state. Note that since <code>SystemState</code> is a member of <code>BCI2000Remote</code>, we also need to add a <code>using BCI2000RemoteNET</code> statement to our script.<br />
<br />
In our case, we need to react to the operator setting the parameters, starting the data collection, and stopping the data collection. These correspond to the Operator Module entering the <code>Resting</code> state, entering the <code>Running</code> state, and exiting the <code>Running</code> state.<br />
<br />
In the <code>GameControl.cs</code> script, we will wait for the system to be in the <code>Resting</code> state at the start of the <code>ControLoop</code> method, and wait for the system to be in the <code>Running</code> state immediately before the entering the trial loop. Note that this code is within a coroutine and we do not want it to block, so we use a <code>yield return</code> statement.<br />
<pre><br />
>>> GameControl.cs<br />
<br />
IEnumerator ControlLoop() {<br />
while (True) {<br />
<br />
yield return bci.PollSystemState(BCI2000Remote.SystemState.Resting);<br />
<br />
try {<br />
...<br />
} catch (Exception e) {<br />
continue;<br />
}<br />
<br />
int trials = 0;<br />
<br />
yield return bci.PollSystemState(BCI2000Remote.SystemState.Running);<br />
<br />
<br />
yield return new WaitForSeconds(preRunDuration);<br />
while (IsContinue() && trials < n_trials) {<br />
...<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
We also need to check for the operator stopping data collection, so we modify the <code>IsContinue()</code> method.<br />
<br />
<pre><br />
bool IsContinue () {<br />
return bci.Control.GetSystemState() == BCI2000Remote.SystemState.Running;<br />
}<br />
</pre><br />
<br />
Remember to add <code>using BCI2000RemoteNET;</code> to the top of the script, so you can access the <code>SystemState</code> enum.<br />
<br />
===Reading the control signal===<br />
We will be using the control signal to control the cursor. Open the <code>MCursorControl.cs</code> script.<br />
<br />
The commented out section of the <code>GetPos()</code> method contains the code required to turn the control signal waveform coming from the Signal Source and Signal Processing modules into screen coordinates. <br />
Uncomment the commented part and delete the line <code>Ray r = camera.ScreenPointToRay(Input.MousePosition);</code>.<br />
Change the <code>double signalX = 0;</code> and <code>double signalY = 0;</code> to. <br />
<br />
Your <code>GetPos()</code> method should look like this:<br />
<pre><br />
Vector3 GetPos() {<br />
double signalX = bci.Control.GetSignal(1, bci.CurrentSampleOffset());<br />
double signalY = bci.Control.GetSignal(2, bci.CurrentSampleOffset());<br />
signalsX[signalIndex] = signalX;<br />
signalsY[signalIndex] = signalY;<br />
<br />
signalIndex = signalIndex + 1 >= rollingMaximumAmount ? 0 : signalIndex + 1;<br />
double max_x = signalsX.Max();<br />
double max_y = signalsY.Max();<br />
Ray r = camera.ScreenPointToRay(new Vector3((float) max_x * Screen.width, (float) max_y * Screen.height, 0));<br />
float p;<br />
if (!plane.Raycast(r, out p)) {<br />
throw new Exception("error casting ray to plane, invalid mouse position?");<br />
}<br />
return r.GetPoint(p);<br />
}<br />
</pre><br />
<br />
Note the use of the <code>UnityBCI2000.CurrentSampleOffset()</code> method. This is a special method which gets the offset into the current block such that the sample is exactly one block length later than when it was collected by the hardware. This is to normalize the latency between when the hardware collects the signal and the software receives the signal, due to how BCI2000 processes data in blocks.<br />
<br />
===Sending events back to BCI2000===<br />
<br />
The primary way to communicate game state back to BCI2000 is via the use of Events, which are integer values encoded alongside the signal data.<br />
<br />
We will send the events that we added in a previous section.<br />
<br />
First, we will send back the current position of the cursor. Within the <code>BallControl.cs</code> script, within the <code>Update()</code> method, immediately after <code>Move()</code> is called, set the <code>CursorPositionX</code> and <code>CursorPositionY</code> events. <br />
<br />
<pre><br />
>>> BallControl.cs<br />
void Update() {<br />
...<br />
if (isTrialRunning) {<br />
...<br />
Move();<br />
bci.Control.SetEvent("CursorPositionX", (uint) ((transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("CursorPositionY", (uint) ((transform.position.y + 4.5) * 1000));<br />
}<br />
...<br />
</pre><br />
<br />
Notice that we transform the value of the cursor's position. This is because events in BCI2000 are represented as unsigned integers, so, for example, the cursor's range of movement in the x axis, -7 to 7, would not be directly representable within a BCI2000 event, so we add 7 so it is positive, and multiply by 1000 so that we have a more precise measure of the cursor's position. The range of [-7,7] becomes [0,14000].<br />
<br />
<br />
We will also set the events corresponding to the game state within <code>GameControl.cs</code>. First we will set <code>PreFeedback</code>, <code>Feedback</code>, and <code>PostFeedback</code> to represent when the game is in these states. To do this, at the beginning and end of <code>PreTrial()</code>, <code>Trial()</code>, and <code>PostTrial()</code>, we will set the corresponding event values to 1 and 0, respectively.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
bci.Control.SetEvent("PreFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PreFeedback", 0);<br />
}<br />
IEnumerator Trial() {<br />
bci.Control.SetEvent("Feedback", 1);<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
}<br />
IEnumerator PostTrial() {<br />
bci.Control.SetEvent("PostFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PostFeedback", 0);<br />
}<br />
</pre><br />
<br />
We will also set the events which happen at the end of each trial. The <code>TargetHit</code> event is activated when the subject hits the target, and the <code>Timeout</code> event is activated when the subject runs out of time.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator Trial() {<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
if (lastTrialSucceeded) {<br />
bci.Control.PulseEvent("TargetHit", 1);<br />
} else {<br />
bci.Control.PulseEvent("Timeout", 1);<br />
}<br />
}<br />
<br />
Notice that we use <code>BCI2000Remote.PulseEvent()</code> rather than <code>BCI2000Remote.SetEvent()</code>. This results in the event being set to the value <code>1</code> for exactly one sample duration, then returning to zero.<br />
<br />
We will also record the position of the target. Similarly to the cursor, we will transform the target's coordinates to be a positive integer.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
...<br />
target.SetActive(true);<br />
bci.Control.SetEvent("TargetPositionX", (uint) ((target.transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("TargetPositionY", (uint) ((target.transform.position.y + 4.5) * 1000));<br />
...<br />
}<br />
</pre><br />
<br />
The last event we need to set is the trial number.<br />
<br />
<pre><br />
IEnumerator ControlLoop() {<br />
...<br />
while (IsContinue() && trials < n_trials) {<br />
bci.Control.SetEvent("TrialNumber", trials + 1);<br />
...<br />
}<br />
}<br />
</pre><br />
<br />
===Unity Player Settings===<br />
Additionally, due to how Unity detects changes in BCI2000 state, it must be allowed to run in the background.<br />
<br />
<pre style="color:red"><br />
In the Unity menu bar:<br />
Edit > Project Settings > Player > Resolution and Presentation<br />
Check the "Run In Background" box.<br />
</pre><br />
<br />
<br />
===Usage===<br />
<br />
Now, when the Unity application runs, BCI2000 will open. From here, parameters can be set via the Config window, then clicking Set Config and Start will start data collection.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=User_Tutorial:UnityBCI2000&diff=11772User Tutorial:UnityBCI20002025-03-14T03:57:46Z<p>Tytbutler: Fixed broken code block</p>
<hr />
<div><pre style="color:red"><br />
Red text blocks contain detailed instructions for the higher-level instructions preceding them.<br />
</pre><br />
<br />
This example comprehensively demonstrates many of the capabilities of UnityBCI2000, and as such, is more than what is necessary for many usecases. If you just want to use BCI2000 as a logging backend for an existing Unity application, see [[User Tutorial:UnityBCI2000 Barebones]].<br />
<br />
===Download Unity===<br />
<br />
Download Unity Hub from [https://unity3d.com Unity].<br />
<br />
===Setting Up BCI2000===<br />
<br />
Follow the instructions starting with [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Install_Prerequisites] to download BCI2000. <br />
<br />
===Setting Up UnityBCI2000===<br />
Download UnityBCI2000 from its GitHub page, [https://github.com/neurotechcenter/UnityBCI2000]. <br />
<pre style="color:red"><br />
Click on the "Releases" section on the right side of the page. This tutorial is intended to be used with UnityBCI2000 version 2.0.0, so scroll to that release and click on the files BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to download them.<br />
</pre><br />
<br />
===Download Tutorial Project===<br />
Download the CursorTask3 repository from [https://github.com/Personator01/CursorTask3 GitHub].<br />
<pre style="color:red"><br />
Either:<br />
-Clone the git repository<br />
-Download the respository directly from GitHub<br />
-> Click the green "Code" button <br />
-> Select "Download ZIP"<br />
-> Extract the zip file<br />
</pre><br />
The download directory contains two versions of the CursorTask3 project. One, CursorTask3-BCI2K, contains an example implementation of the task with BCI2000 integration. The other, CursorTask3-NoBCI2K, contains the same task without BCI2000 integration. This tutorial is a step by step guide on turning that second project into the first. <br />
<br />
===Opening the project===<br />
Open the project in the Unity Editor, and open the CursorTask scene.<br />
<pre style="color:red"><br />
Open Unity Hub.<br />
Click the "Add" button in the top right corner.<br />
Navigate to the CursorTask3 directory downloaded previously.<br />
Select the CursorTask3-NoBCI2K directory to add it to Unity Hub.<br />
Click the CursorTask3-NoBCI2K project in the Unity Hub.<br />
If prompted to select a version of Unity to use or install, select Unity 2022.3. The specific release number of Unity 2022.3 should not matter, so select the one labeled "LTS" for consistency.<br />
The lower panel (the asset browser) should already show the Assets/Scenes directory, which contains a single scene called SampleScene.<br />
Double-click SampleScene. This should open a scene with a box containing various lights and objects.<br />
</pre><br />
If you wish to view the completed implementation, repeat these steps, but instead open the CursorTask3-BCI2K directory. Note that in order to use the completed implementation, you will still need to set the Operator Path value of the UnityBCI2000 component of the BCI2000 game object.<br />
<br />
===Adding UnityBCI2000 to the project===<br />
Add BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to your project's assets.<br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click Assets > Open Containing Folder to open your project directory.<br />
Place the BCI2000RemoteNETStandard.dll and UnityBCI2000.cs files in the Assets folder.<br />
</pre><br />
<br />
Add an empty GameObject called 'BCI2000'. This will hold the scripts for controlling BCI2000. <br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click GameObject > Create Empty to create an empty GameObject, and name it 'BCI2000'. (The object's specific name does not actually matter, it is only needed in order to reference it within other scripts)<br />
You will notice that it now appears in the Scene Hierarchy panel, on the left side of the screen.<br />
</pre><br />
<br />
Add the UnityBCI2000 component to the object.<br />
<pre style="color:red"><br />
Click on the object in the Hierarchy panel. This will open it in the Inspector panel (the panel on the right side of the screen)<br />
In the inspector, below the new object's Transform component, click the "Add Component" button, which will open up a small window for adding components.<br />
Within this window, select Scripts > Unity BCI2000 to add the UnityBCI2000 component.<br />
</pre><br />
<br />
===Configuring UnityBCI2000===<br />
The inspector panel now contains the configuration options for UnityBCI2000. Set the options as follows:<br />
<br />
<code>Start Local Operator</code>: Checked<br />
<br />
This will start the operator on your computer when the Unity scene initializes. If we were instead connecting to an already-running instance of BCI2000, or an instance on another computer, this box would be deselected.<br />
<br />
<code>Operator Path</code>: The path to the Operator executable. This will look something like this on Windows (C://path/to/bci2000/prog/Operator.exe)<br />
<br />
<code>Operator Address</code>: 127.0.0.1<br />
<br />
This is the address of the machine on which BCI2000 is running. Since we are running BCI2000 on the same computer as Unity, we leave it as 127.0.0.1, the loopback address.<br />
<br />
<code>Operator Port</code>: 3999<br />
<br />
This is the port on which BCI2000 is listening for commands. By default, it is 3999.<br />
<br />
<code>Start Modules</code>: Checked<br />
<br />
This tells BCI2000 to start the requested Signal Source, Signal Processing, and Application modules when the Unity scene initializes. Similarly to Start Local Operator, we would deselect this box if connecting to an already-running instance. <br />
<br />
<code>Start With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to start a data collection run when the scene starts. Since we will be using BCI2000 itself to set experiment parameters, we will instead wait for BCI2000 to start from Unity, and thus will leave the box unchecked. <br />
<br />
<code>Stop With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to stop collecting data when the scene stops. Since we will be controlling BCI2000 directly, rather than entirely through Unity, we will leave this unchecked.<br />
<br />
<code>Shutdown With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to shut down alongside the Unity scene. Whether or not this value is set ultimately doesn't matter much, especially if Start Local Operator is checked. The data will be saved whether or not BCI2000 shuts down. <br />
<br />
<code>Module 1</code>: SignalGenerator<br />
<br />
The signal source module to start. We will use SignalGenerator, which generates a signal without any connected hardware.<br />
<br />
<code>Module 2</code>: DummySignalProcessing<br />
<br />
The signal processing module to start. We will use DummySignalProcessing, as there is no processing to do.<br />
<br />
<code>Module 3</code>: DummyApplication<br />
<br />
The Application module to start. Since we are using Unity, we will use DummyApplication.<br />
<br />
===Setting References===<br />
In order for the game's scripts to communicate with BCI2000, they need to hold a reference to the UnityBCI2000 component.<br />
There are three scripts which will need to communicate with BCI2000. They are <code>GameControl.cs, BallControl.cs, and MCursorControl.cs</code>.<br />
These scripts are each located within the Assets directory of the Unity project. <br />
<pre style="color:red"><br />
As before, select Assets > Open Containing Folder to open the project directory, then open the Assets folder. <br />
For each script, open it in a text editor.<br />
Add a data member of type UnityBCI2000 to the class, like so:<br />
UnityBCI2000 bci;<br />
Place the member definition above the Awake() method, for readability.<br />
Within the Awake() method, set this reference to the UnityBCI2000 component.<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
</pre><br />
Each of the three scripts should contain a section like this:<br />
<pre><br />
...<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
</pre><br />
<br />
===Adding Events===<br />
[https://www.bci2000.org/mediawiki/index.php/Programming_Reference:Events Events] are the primary way that non-signal experiment data is recorded in BCI2000. They are timestamped integer values which are encoded alongside the signal data in BCI2000 output files. Due to BCI2000's design, events must be added during a very specific part of its startup sequence, which is immediately after the BCI2000 operator starts, and before any of the modules start. As such, we cannot simply call <code>AddEvent()</code> whenever we want. Furthermore, the order in which Unity objects initialize is undefined, so it cannot even be guaranteed that calling <code>AddEvent</code> at a specific time will be consistent across multiple projects. As such, UnityBCI2000 provides a couple of methods for sending commands at well-defined points within the startup sequence. These two methods, <code>OnIdle</code> and <code>OnIdle</code> and <code>OnConnected</code> allow BCI2000 commands to be sent while the operator is in the state Idle (immediately before starting its modules) and when the operator is in the state Connected (after starting and connecting to the modules. Below is an example of using those methods to add and show an event in BCI2000.<br />
<br />
<pre><br />
class Script : MonoBehaviour {<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000Object").GetComponent<UnityBCI2000>();<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("AnEvent", 32);<br />
});<br />
}<br />
void Start() {<br />
bci.OnConnected(remote => {<br />
remote.Visualize("AnEvent");<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
As seen above, <code>OnIdle</code> and <code>OnConnected</code> take a delegate (C#'s term for a callback/closure/functor/etc.) with a single parameter of type <code>BCI2000Remote</code> (in this case called "remote"). The lambda expression given to the call to <code>OnIdle</code> uses the method <code>BCI2000Remote.AddEvent()</code> to add an event called "AnEvent" with a bit width of 32 bits. The call to <code>OnConnected</code> tells BCI2000 to show the event's value in a graphical window. A description of the BCI2000Remote class can be found [https://www.bci2000.org/mediawiki/index.php/Contributions:BCI2000RemoteNET here], and API documentation can be found [https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html here].<br />
<br />
We will now add the events relevant to the Cursor Task. Open the <code>GameControl.cs</code> script, and modify its <code>Awake()</code> to add the events <code>PreFeedback</code>, <code>Feedback</code>, <code>PostFeedback</code>, <code>TargetHit</code>, and <code>Timeout</code> with bit width 1. Additionally, add the events <code>TrialNumber</code>, <code>TargetPositionX</code>, and <code>TargetPositionY</code> with width 16. These will encode the task state and number of trials.<br />
We also need to set a parameter value so that the signal will be set to the mouse position. Using <code>BCI2000Remote.SetParameter()</code>, we will set the <code>ModulateAmplitude</code> parameter to 1.<br />
<br />
Open the <code>BallControl.cs</code> script, and within the <code>Awake()</code> function, add events <code>CursorPositionX</code> and <code>CursorPositionY</code>, with width 16. Show these events in a visualization window with <code>Visualize</code><br />
<br />
Your two scripts should now look like this: <br />
<pre><br />
>>> GameControl.cs <br />
...<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
remote.AddEvent("Feedback", 1);<br />
remote.AddEvent("PostFeedback", 1);<br />
remote.AddEvent("TargetHit", 1);<br />
remote.AddEvent("Timeout", 1);<br />
remote.AddEvent("TrialNumber", 16);<br />
remote.AddEvent("TargetPositionX", 16);<br />
remote.AddEvent("TargetPositionY", 16);<br />
remote.SetParameter("ModulateAmplitude", "1");<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
...<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("CursorPositionX", 16);<br />
remote.AddEvent("CursorPositionY", 16);<br />
});<br />
bci.OnConnected(remote => {<br />
remote.Visualize("CursorPositionX");<br />
remote.Visualize("CursorPositionY");<br />
}<br />
</pre><br />
<br />
<br />
<br />
===Using BCI2000 Parameters===<br />
====Adding Parameters====<br />
BCI2000's operator contains an interface for changing experiment parameters before running a task. By making use of this interface we can change the behavior of the task dynamically, without needing to rebuild the Unity project each time. In order to do this we need to define the parameters and add them to BCI2000, and later read their values after the operator has a chance to change them. <span style="color: red">This section is not strictly necessary. The project will function the same whether this is done or not, just without the option to change parameters at runtime. </span> <br />
<br />
First, we define add parameters to BCI2000. Similarly to events, parameters must be added while the Operator is in the <code>Idle</code> state, so we add them inside of <code>OnIdle</code>, like below:<br />
<pre><br />
public int someParameter = 5;<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddParameter("Application:ParameterPlace", "SomeParameter", someParameter.ToString()); <br />
});<br />
}<br />
<br />
The first argument to the method is the section into which the parameter is placed, that is, on which tab and under which heading the parameter will appear within the Operator's parameter editor window (note that the section is not a scope, all parameter names must be unique). The second argument is the parameter name itself. The third argument is the default value of the parameter. We pass in the value of the parameter, so when it appears in the Operator, its default value is 5 (or another value if it has been changed in the Unity Editor). Note that all parameters are handled as strings, so we need to convert its value to a string when sending it.<br />
<br />
For <code>GameControl.cs</code>, we will add parameters corresponding to the Pre-Feedback, Feedback, and Post-Feedback durations, Target Radius, and Number of Trials.<br />
For <code>BallControl.cs</code>, we will add parameters corresponding to the Acceleration Scale, Coefficient of Restitution, Coefficient of Drag, and Attraction Curve Coefficient (how quickly the Ball moves to follow the Mouse Cursor).<br />
For <code>MCursorControl.cs</code>, we will add a parameter corresponding to the Rolling Maximum Amount.<br />
<br />
Your scripts should look like this:<br />
<pre><br />
>>> GameControl.cs<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
...<br />
<br />
remote.AddParameter("Application:Task", "PreFeedbackDuration", preFeedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "FeedbackDuration", feedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "PostFeedbackDuration", postFeedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "TargetRadius", targetRadius.ToString());<br />
remote.AddParameter("Application:Task", "Trials", n_trials.ToString());<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddParameter("Application:Physics", "AccelerationScale", accelerationScale.ToString());<br />
remote.AddParameter("Application:Physics", "CoeffOfRestitution", coefficientOfRestitution.ToString());<br />
remote.AddParameter("Application:Physics", "CoeffOfDrag", coefficientOfDrag.ToString());<br />
remote.AddParameter("Application:Physics", "AccelerationCurve", attractionCurveCoefficient.ToString());<br />
})}<br />
}<br />
<br />
>>> MCursorControl.cs<br />
void Awake() {<br />
...<br />
<br />
bci.OnIdle(remote => {<br />
AddParameter("Application:Physics", "RollingMaximumAmount", rollingMaximumAmount.ToString());<br />
});<br />
}<br />
<br />
<br />
====Reading and Validating Parameters====<br />
Since we set the parameters within the BCI2000 operator, we need some way to read them back into Unity after they have been set. Specifically, we need to read them after the operator clicks the "Set Config" button within the BCI2000 Operator. How this timing synchronization is covered in the section [[Reacting to BCI2000 state changes]]. In this section we will cover reading and validating parameters.<br />
<br />
A method called <code>SetConfig</code> is provided in each of the scripts in which we added parameters previously. This method will be called after the operator changes parameters. In this method we will read in parameters and parse them into valid values. Using the same example parameter as before:<br />
<pre><br />
void SetConfig() {<br />
try {<br />
someParameter = int.Parse(bci.Control.GetParameter("SomeParameter"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse parameter SomeParameter as int");<br />
throw e;<br />
}<br />
}<br />
</pre><br />
<br />
Note that since we are now working outside the BCI2000 startup sequence, we use <code>UnityBCI2000.Control</code> to call <code>BCI2000Remote</code> methods directly, rather than using <code>OnIdle</code> or <code>OnConnected</code>. We also wrap the call within a try/catch block so that we can report erroneous parameters back to the operator. This is optional, but it keeps your project from failing silently and is otherwise useful for doing things like distributing your Unity project as a standalone executable, where logging errors can only be done through the BCI2000 operator. You can also write a helper function which handles parsing and error reporting for you:<br />
<br />
<pre><br />
int GetParseParameterInt(string paramName) {<br />
int p_val = bci.Control.GetParameter("SomeParameter");<br />
try {<br />
someParameter = int.Parse(p_val);<br />
} catch (FormatException e) {<br />
bci.Error($"Could not parse parameter {paramName} (value {p_val}) as int");<br />
throw e;<br />
}<br />
}<br />
</pre><br />
Unfortunately, since the version of C# used by Unity does not support type-parameterized parsing, you must write one of these helper functions for each type of data you want to store in a parameter (int, float, double, etc.)<br />
<br />
<br />
Read back the parameters added in the previous step. Your scripts should look like this:<br />
<br />
<pre><br />
>>> GameControl.cs <br />
void SetConfig() {<br />
try {<br />
preFeedbackDuration = float.Parse(bci.Control.GetParameter("PreFeedbackDuration"));<br />
feedbackDuration = float.Parse(bci.Control.GetParameter("FeedbackDuration"));<br />
postFeedbackDuration = float.Parse(bci.Control.GetParameter("PostFeedbackDuration"));<br />
targetRadius = float.Parse(bci.Control.GetParameter("TargetRadius"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse one of PreFeedbackDuration, FeedbackDuration, PostFeedbackDuration, or TargetRadius as a float");<br />
throw e;<br />
}<br />
try {<br />
n_trials = int.Parse(bci.Control.GetParameter("Trials"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse Trials as an int");<br />
throw e;<br />
}<br />
<br />
if (preFeedbackDuration < COUNTDOWN_DURATION) {<br />
bci.Error("preFeedbackDuration must be greater than or equal to 2.25");<br />
throw new Exception("preFeedbackDuration must be greater than or equal to 2.25");<br />
}<br />
}<br />
<br />
>>> BallControl.cs<br />
public void SetConfig() {<br />
try {<br />
accelerationScale = float.Parse(bci.Control.GetParameter("AccelerationScale"));<br />
coefficientOfRestitution = float.Parse(bci.Control.GetParameter("CoeffOfRestitution"));<br />
coefficientOfDrag = float.Parse(bci.Control.GetParameter("CoeffOfDrag"));<br />
attractionCurveCoefficient = float.Parse(bci.Control.GetParameter("AccelerationCurve"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse one of AccelerationScale, CoeffOfRestitution, CoeffOfDrag, AccelerationCurve as float");<br />
throw e;<br />
}<br />
}<br />
<br />
>>> MCursorControl.cs<br />
public void SetConfig() {<br />
try {<br />
rollingMaximumAmount = int.Parse(bci.Control.GetParameter("RollingMaximumAmount"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse parameter RollingMaximumAmount as int");<br />
throw e;<br />
}<br />
signalsX = new int[rollingMaximumAmount];<br />
signalsY = new int[rollingMaximumAmount];<br />
}<br />
</pre><br />
<br />
Note that in <code>GameControl.cs</code>, we also verify that the Pre-Feedback Duration is longer than the duration of the countdown that happens before each trial, and report errors to BCI2000 accordingly.<br />
<br />
<br />
===Reacting to BCI2000 state changes===<br />
Since we will be controlling the Unity task from BCI2000, we need some way to wait for BCI2000 to be in a specific state, for example, waiting for the operator to click Start and put the Operator Module into the Running state. UnityBCI2000 provides a method for this, the <code>UnityBCI2000.PollSystemState</code> method. In order to wait for the Operator Module to be in the <code>Running</code> state:<br />
<pre><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Running));<br />
</pre><br />
This will check once per frame whether or not the Operator is in the <code>Running</code> state, and only continue once BCI2000 is in the <code>Running</code> state. Note that since <code>SystemState</code> is a member of <code>BCI2000Remote</code>, we also need to add a <code>using BCI2000RemoteNET</code> statement to our script.<br />
<br />
In our case, we need to react to the operator setting the parameters, starting the data collection, and stopping the data collection. These correspond to the Operator Module entering the <code>Resting</code> state, entering the <code>Running</code> state, and exiting the <code>Running</code> state.<br />
<br />
In the <code>GameControl.cs</code> script, we will wait for the system to be in the <code>Resting</code> state at the start of the <code>ControLoop</code> method, and wait for the system to be in the <code>Running</code> state immediately before the entering the trial loop. <br />
<pre><br />
>>> GameControl.cs<br />
<br />
IEnumerator ControlLoop() {<br />
while (True) {<br />
<br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Resting));<br />
<br />
try {<br />
...<br />
} catch (Exception e) {<br />
continue;<br />
}<br />
<br />
int trials = 0;<br />
<br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Running));<br />
<br />
<br />
yield return new WaitForSeconds(preRunDuration);<br />
while (IsContinue() && trials < n_trials) {<br />
...<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
We also need to check for the operator stopping data collection, so we modify the <code>IsContinue()</code> method.<br />
<br />
<pre><br />
bool IsContinue () {<br />
return bci.Control.GetSystemState() == BCI2000Remote.SystemState.Running;<br />
}<br />
</pre><br />
<br />
Remember to add <code>using BCI2000RemoteNET;</code> to the top of the script, so you can access the <code>SystemState</code> enum.<br />
<br />
===Reading the control signal===<br />
We will be using the control signal to control the cursor. Open the <code>MCursorControl.cs</code> script.<br />
<br />
The commented out section of the <code>GetPos()</code> method contains the code required to turn the control signal waveform coming from the Signal Source and Signal Processing modules into screen coordinates. <br />
Uncomment the commented part and delete the line <code>Ray r = camera.ScreenPointToRay(Input.MousePosition);</code>.<br />
Change the <code>double signalX = 0;</code> and <code>double signalY = 0;</code> to. <br />
<br />
Your <code>GetPos()</code> method should look like this:<br />
<pre><br />
Vector3 GetPos() {<br />
double signalX = bci.Control.GetSignal(1, bci.CurrentSampleOffset());<br />
double signalY = bci.Control.GetSignal(2, bci.CurrentSampleOffset());<br />
signalsX[signalIndex] = signalX;<br />
signalsY[signalIndex] = signalY;<br />
<br />
signalIndex = signalIndex + 1 >= rollingMaximumAmount ? 0 : signalIndex + 1;<br />
double max_x = signalsX.Max();<br />
double max_y = signalsY.Max();<br />
Ray r = camera.ScreenPointToRay(new Vector3((float) max_x * Screen.width, (float) max_y * Screen.height, 0));<br />
float p;<br />
if (!plane.Raycast(r, out p)) {<br />
throw new Exception("error casting ray to plane, invalid mouse position?");<br />
}<br />
return r.GetPoint(p);<br />
}<br />
</pre><br />
<br />
Note the use of the <code>UnityBCI2000.CurrentSampleOffset()</code> method. This is a special method which gets the offset into the current block such that the sample is exactly one block length later than when it was collected by the hardware. This is to normalize the latency between when the hardware collects the signal and the software receives the signal, due to how BCI2000 processes data in blocks.<br />
<br />
===Sending events back to BCI2000===<br />
<br />
The primary way to communicate game state back to BCI2000 is via the use of Events, which are integer values encoded alongside the signal data.<br />
<br />
We will send the events that we added in a previous section.<br />
<br />
First, we will send back the current position of the cursor. Within the <code>BallControl.cs</code> script, within the <code>Update()</code> method, immediately after <code>Move()</code> is called, set the <code>CursorPositionX</code> and <code>CursorPositionY</code> events. <br />
<br />
<pre><br />
>>> BallControl.cs<br />
void Update() {<br />
...<br />
if (isTrialRunning) {<br />
...<br />
Move();<br />
bci.Control.SetEvent("CursorPositionX", (uint) ((transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("CursorPositionY", (uint) ((transform.position.y + 4.5) * 1000));<br />
}<br />
...<br />
</pre><br />
<br />
Notice that we transform the value of the cursor's position. This is because events in BCI2000 are represented as unsigned integers, so, for example, the cursor's range of movement in the x axis, -7 to 7, would not be directly representable within a BCI2000 event, so we add 7 so it is positive, and multiply by 1000 so that we have a more precise measure of the cursor's position. The range of [-7,7] becomes [0,14000].<br />
<br />
<br />
We will also set the events corresponding to the game state within <code>GameControl.cs</code>. First we will set <code>PreFeedback</code>, <code>Feedback</code>, and <code>PostFeedback</code> to represent when the game is in these states. To do this, at the beginning and end of <code>PreTrial()</code>, <code>Trial()</code>, and <code>PostTrial()</code>, we will set the corresponding event values to 1 and 0, respectively.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
bci.Control.SetEvent("PreFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PreFeedback", 0);<br />
}<br />
IEnumerator Trial() {<br />
bci.Control.SetEvent("Feedback", 1);<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
}<br />
IEnumerator PostTrial() {<br />
bci.Control.SetEvent("PostFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PostFeedback", 0);<br />
}<br />
</pre><br />
<br />
We will also set the events which happen at the end of each trial. The <code>TargetHit</code> event is activated when the subject hits the target, and the <code>Timeout</code> event is activated when the subject runs out of time.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator Trial() {<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
if (lastTrialSucceeded) {<br />
bci.Control.PulseEvent("TargetHit", 1);<br />
} else {<br />
bci.Control.PulseEvent("Timeout", 1);<br />
}<br />
}<br />
<br />
Notice that we use <code>BCI2000Remote.PulseEvent()</code> rather than <code>BCI2000Remote.SetEvent()</code>. This results in the event being set to the value <code>1</code> for exactly one sample duration, then returning to zero.<br />
<br />
We will also record the position of the target. Similarly to the cursor, we will transform the target's coordinates to be a positive integer.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
...<br />
target.SetActive(true);<br />
bci.Control.SetEvent("TargetPositionX", (uint) ((target.transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("TargetPositionY", (uint) ((target.transform.position.y + 4.5) * 1000));<br />
...<br />
}<br />
</pre><br />
<br />
The last event we need to set is the trial number.<br />
<br />
<pre><br />
IEnumerator ControlLoop() {<br />
...<br />
while (IsContinue() && trials < n_trials) {<br />
bci.Control.SetEvent("TrialNumber", trials + 1);<br />
...<br />
}<br />
}<br />
</pre><br />
<br />
===Unity Player Settings===<br />
Additionally, due to how Unity detects changes in BCI2000 state, it must be allowed to run in the background.<br />
<br />
<pre style="color:red"><br />
In the Unity menu bar:<br />
Edit > Project Settings > Player > Resolution and Presentation<br />
Check the "Run In Background" box.<br />
</pre><br />
<br />
<br />
===Usage===<br />
<br />
Now, when the Unity application runs, BCI2000 will open. From here, parameters can be set via the Config window, then clicking Set Config and Start will start data collection.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:UnityBCI2000&diff=11534Contributions:UnityBCI20002024-08-16T14:51:25Z<p>Tytbutler: </p>
<hr />
<div>==Synopsis==<br />
UnityBCI2000 is an extension for the Unity game/3D application development platform that enables control of and communication with the BCI2000 brain-computer interface research platform. It consists of a .NET library for communication with the BCI2000 operator and a Unity package which provides integration with Unity itself.<br />
<br />
==Prerequisites==<br />
Alongside UnityBCI2000, install Unity per the instructions at [https://unity.com/download the Unity website], and the [[Programming_Howto:Building_and_Customizing_BCI2000|BCI2000 setup tutorial]].<br />
<br />
==Adding UnityBCI2000 to a Unity Project==<br />
Download the latest release of UnityBCI2000 from [https://github.com/neurotechcenter/UnityBCI2000 GitHub]. Place the <code>UnityBCI2000.cs</code> and <code>BCI2000RemoteNETStandard.dll</code> files in the <code>Assets</code> folder of the Unity project.<br />
<br />
Add the <code>UnityBCI2000.cs</code> script to a Unity object as a component.<br />
<br />
For a comprehensive tutorial of integrating BCI2000 with a Unity project, see [[User Tutorial:UnityBCI2000]]. <br />
<br />
For a minimal tutorial on using BCI2000 as a logging service for Unity, see [[User Tutorial:UnityBCI2000 Barebones]].<br />
<br />
<br />
<br />
==Documentation==<br />
[https://bci2000.org/BCI2000Unity/classUnityBCI2000.html Interface documentation]</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:UnityBCI2000&diff=11533Contributions:UnityBCI20002024-08-16T14:50:46Z<p>Tytbutler: </p>
<hr />
<div>==Synopsis==<br />
UnityBCI2000 is an extension for the Unity game/3D application development platform that enables control of and communication with the BCI2000 brain-computer interface research platform. It consists of a .NET library for communication with the BCI2000 operator and a Unity package which provides integration with Unity itself.<br />
<br />
==Prerequisites==<br />
Alongside UnityBCI2000, install Unity per the instructions at [https://unity.com/download the Unity website], and the [[Programming_Howto:Install_Prerequisites|BCI2000 setup tutorial]].<br />
<br />
==Adding UnityBCI2000 to a Unity Project==<br />
Download the latest release of UnityBCI2000 from [https://github.com/neurotechcenter/UnityBCI2000 GitHub]. Place the <code>UnityBCI2000.cs</code> and <code>BCI2000RemoteNETStandard.dll</code> files in the <code>Assets</code> folder of the Unity project.<br />
<br />
Add the <code>UnityBCI2000.cs</code> script to a Unity object as a component.<br />
<br />
For a comprehensive tutorial of integrating BCI2000 with a Unity project, see [[User Tutorial:UnityBCI2000]]. <br />
<br />
For a minimal tutorial on using BCI2000 as a logging service for Unity, see [[User Tutorial:UnityBCI2000 Barebones]].<br />
<br />
<br />
<br />
==Documentation==<br />
[https://bci2000.org/BCI2000Unity/classUnityBCI2000.html Interface documentation]</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:UnityBCI2000&diff=11532Contributions:UnityBCI20002024-08-16T14:50:20Z<p>Tytbutler: </p>
<hr />
<div>==Synopsis==<br />
UnityBCI2000 is an extension for the Unity game/3D application development platform that enables control of and communication with the BCI2000 brain-computer interface research platform. It consists of a .NET library for communication with the BCI2000 operator and a Unity package which provides integration with Unity itself.<br />
<br />
==Prerequisites==<br />
Alongside UnityBCI2000, install Unity per the instructions at [https://unity.com/download the Unity website], and the [[https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Install_Prerequisites|BCI2000 setup tutorial]].<br />
<br />
==Adding UnityBCI2000 to a Unity Project==<br />
Download the latest release of UnityBCI2000 from [https://github.com/neurotechcenter/UnityBCI2000 GitHub]. Place the <code>UnityBCI2000.cs</code> and <code>BCI2000RemoteNETStandard.dll</code> files in the <code>Assets</code> folder of the Unity project.<br />
<br />
Add the <code>UnityBCI2000.cs</code> script to a Unity object as a component.<br />
<br />
For a comprehensive tutorial of integrating BCI2000 with a Unity project, see [[User Tutorial:UnityBCI2000]]. <br />
<br />
For a minimal tutorial on using BCI2000 as a logging service for Unity, see [[User Tutorial:UnityBCI2000 Barebones]].<br />
<br />
<br />
<br />
==Documentation==<br />
[https://bci2000.org/BCI2000Unity/classUnityBCI2000.html Interface documentation]</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:UnityBCI2000&diff=11531Contributions:UnityBCI20002024-08-16T13:37:27Z<p>Tytbutler: </p>
<hr />
<div>==Synopsis==<br />
UnityBCI2000 is an extension for the Unity game/3D application development platform that enables control of and communication with the BCI2000 brain-computer interface research platform. It consists of a .NET library for communication with the BCI2000 operator and a Unity package which provides integration with Unity itself.<br />
<br />
==Prerequisites==<br />
Alongside UnityBCI2000, install Unity per the instructions at [https://unity.com/download the Unity website], and the [BCI2000 setup tutorial https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Install_Prerequisites].<br />
<br />
==Adding UnityBCI2000 to a Unity Project==<br />
Download the latest release of UnityBCI2000 from [https://github.com/neurotechcenter/UnityBCI2000 GitHub]. Place the <code>UnityBCI2000.cs</code> and <code>BCI2000RemoteNETStandard.dll</code> files in the <code>Assets</code> folder of the Unity project.<br />
<br />
Add the <code>UnityBCI2000.cs</code> script to a Unity object as a component.<br />
<br />
For a comprehensive tutorial of integrating BCI2000 with a Unity project, see [[User Tutorial:UnityBCI2000]]. <br />
<br />
For a minimal tutorial on using BCI2000 as a logging service for Unity, see [[User Tutorial:UnityBCI2000 Barebones]].<br />
<br />
<br />
<br />
==Documentation==<br />
[https://bci2000.org/BCI2000Unity/classUnityBCI2000.html Interface documentation]</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:UnityBCI2000&diff=11530Contributions:UnityBCI20002024-08-16T13:37:15Z<p>Tytbutler: </p>
<hr />
<div>==Synopsis==<br />
UnityBCI2000 is an extension for the Unity game/3D application development platform that enables control of and communication with the BCI2000 brain-computer interface research platform. It consists of a .NET library for communication with the BCI2000 operator and a Unity package which provides integration with Unity itself.<br />
<br />
==Prerequisites==<br />
Alongside UnityBCI2000, install Unity per the instructions at [https://unity.com/download the Unity website], and the [BCI2000 setup tutorial https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Install_Prerequisites].<br />
<br />
==Adding UnityBCI2000 to a Unity Project==<br />
Download the latest release of UnityBCI2000 from [https://github.com/neurotechcenter/UnityBCI2000 GitHub]. Place the <code>UnityBCI2000.cs</code> and <code>BCI2000RemoteNETStandard.dll</code> files in the <code>Assets</code> folder of the Unity project.<br />
<br />
Add the <code>UnityBCI2000.cs</code> script to a Unity object as a component.<br />
<br />
For a comprehensive tutorial of integrating BCI2000 with a Unity project, see [[User Tutorial:UnityBCI2000]]. <br />
For a minimal tutorial on using BCI2000 as a logging service for Unity, see [[User Tutorial:UnityBCI2000 Barebones]]<br />
<br />
<br />
<br />
==Documentation==<br />
[https://bci2000.org/BCI2000Unity/classUnityBCI2000.html Interface documentation]</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=User_Tutorial:UnityBCI2000&diff=11529User Tutorial:UnityBCI20002024-08-16T02:31:51Z<p>Tytbutler: </p>
<hr />
<div><pre style="color:red"><br />
Red text blocks contain detailed instructions for the higher-level instructions preceding them.<br />
</pre><br />
<br />
This example comprehensively demonstrates many of the capabilities of UnityBCI2000, and as such, is more than what is necessary for many usecases. If you just want to use BCI2000 as a logging backend for an existing Unity application, see [[User Tutorial:UnityBCI2000 Barebones]].<br />
<br />
===Download Unity===<br />
<br />
Download Unity Hub from [https://unity3d.com Unity].<br />
<br />
===Setting Up BCI2000===<br />
<br />
Follow the instructions starting with [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Install_Prerequisites] to download BCI2000. <br />
<br />
===Setting Up UnityBCI2000===<br />
Download UnityBCI2000 from its GitHub page, [https://github.com/neurotechcenter/UnityBCI2000]. <br />
<pre style="color:red"><br />
Click on the "Releases" section on the right side of the page. This tutorial is intended to be used with UnityBCI2000 version 2.0.0, so scroll to that release and click on the files BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to download them.<br />
</pre><br />
<br />
===Download Tutorial Project===<br />
Download the CursorTask3 repository from [https://github.com/Personator01/CursorTask3 GitHub].<br />
<pre style="color:red"><br />
Either:<br />
-Clone the git repository<br />
-Download the respository directly from GitHub<br />
-> Click the green "Code" button <br />
-> Select "Download ZIP"<br />
-> Extract the zip file<br />
</pre><br />
The download directory contains two versions of the CursorTask3 project. One, CursorTask3-BCI2K, contains an example implementation of the task with BCI2000 integration. The other, CursorTask3-NoBCI2K, contains the same task without BCI2000 integration. This tutorial is a step by step guide on turning that second project into the first. <br />
<br />
===Opening the project===<br />
Open the project in the Unity Editor, and open the CursorTask scene.<br />
<pre style="color:red"><br />
Open Unity Hub.<br />
Click the "Add" button in the top right corner.<br />
Navigate to the CursorTask3 directory downloaded previously.<br />
Select the CursorTask3-NoBCI2K directory to add it to Unity Hub.<br />
Click the CursorTask3-NoBCI2K project in the Unity Hub.<br />
If prompted to select a version of Unity to use or install, select Unity 2022.3. The specific release number of Unity 2022.3 should not matter, so select the one labeled "LTS" for consistency.<br />
The lower panel (the asset browser) should already show the Assets/Scenes directory, which contains a single scene called SampleScene.<br />
Double-click SampleScene. This should open a scene with a box containing various lights and objects.<br />
</pre><br />
If you wish to view the completed implementation, repeat these steps, but instead open the CursorTask3-BCI2K directory. Note that in order to use the completed implementation, you will still need to set the Operator Path value of the UnityBCI2000 component of the BCI2000 game object.<br />
<br />
===Adding UnityBCI2000 to the project===<br />
Add BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to your project's assets.<br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click Assets > Open Containing Folder to open your project directory.<br />
Place the BCI2000RemoteNETStandard.dll and UnityBCI2000.cs files in the Assets folder.<br />
</pre><br />
<br />
Add an empty GameObject called 'BCI2000'. This will hold the scripts for controlling BCI2000. <br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click GameObject > Create Empty to create an empty GameObject, and name it 'BCI2000'. (The object's specific name does not actually matter, it is only needed in order to reference it within other scripts)<br />
You will notice that it now appears in the Scene Hierarchy panel, on the left side of the screen.<br />
</pre><br />
<br />
Add the UnityBCI2000 component to the object.<br />
<pre style="color:red"><br />
Click on the object in the Hierarchy panel. This will open it in the Inspector panel (the panel on the right side of the screen)<br />
In the inspector, below the new object's Transform component, click the "Add Component" button, which will open up a small window for adding components.<br />
Within this window, select Scripts > Unity BCI2000 to add the UnityBCI2000 component.<br />
</pre><br />
<br />
===Configuring UnityBCI2000===<br />
The inspector panel now contains the configuration options for UnityBCI2000. Set the options as follows:<br />
<br />
<code>Start Local Operator</code>: Checked<br />
<br />
This will start the operator on your computer when the Unity scene initializes. If we were instead connecting to an already-running instance of BCI2000, or an instance on another computer, this box would be deselected.<br />
<br />
<code>Operator Path</code>: The path to the Operator executable. This will look something like this on Windows (C://path/to/bci2000/prog/Operator.exe)<br />
<br />
<code>Operator Address</code>: 127.0.0.1<br />
<br />
This is the address of the machine on which BCI2000 is running. Since we are running BCI2000 on the same computer as Unity, we leave it as 127.0.0.1, the loopback address.<br />
<br />
<code>Operator Port</code>: 3999<br />
<br />
This is the port on which BCI2000 is listening for commands. By default, it is 3999.<br />
<br />
<code>Start Modules</code>: Checked<br />
<br />
This tells BCI2000 to start the requested Signal Source, Signal Processing, and Application modules when the Unity scene initializes. Similarly to Start Local Operator, we would deselect this box if connecting to an already-running instance. <br />
<br />
<code>Start With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to start a data collection run when the scene starts. Since we will be using BCI2000 itself to set experiment parameters, we will instead wait for BCI2000 to start from Unity, and thus will leave the box unchecked. <br />
<br />
<code>Stop With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to stop collecting data when the scene stops. Since we will be controlling BCI2000 directly, rather than entirely through Unity, we will leave this unchecked.<br />
<br />
<code>Shutdown With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to shut down alongside the Unity scene. Whether or not this value is set ultimately doesn't matter much, especially if Start Local Operator is checked. The data will be saved whether or not BCI2000 shuts down. <br />
<br />
<code>Module 1</code>: SignalGenerator<br />
<br />
The signal source module to start. We will use SignalGenerator, which generates a signal without any connected hardware.<br />
<br />
<code>Module 2</code>: DummySignalProcessing<br />
<br />
The signal processing module to start. We will use DummySignalProcessing, as there is no processing to do.<br />
<br />
<code>Module 3</code>: DummyApplication<br />
<br />
The Application module to start. Since we are using Unity, we will use DummyApplication.<br />
<br />
===Setting References===<br />
In order for the game's scripts to communicate with BCI2000, they need to hold a reference to the UnityBCI2000 component.<br />
There are three scripts which will need to communicate with BCI2000. They are <code>GameControl.cs, BallControl.cs, and MCursorControl.cs</code>.<br />
These scripts are each located within the Assets directory of the Unity project. <br />
<pre style="color:red"><br />
As before, select Assets > Open Containing Folder to open the project directory, then open the Assets folder. <br />
For each script, open it in a text editor.<br />
Add a data member of type UnityBCI2000 to the class, like so:<br />
UnityBCI2000 bci;<br />
Place the member definition above the Awake() method, for readability.<br />
Within the Awake() method, set this reference to the UnityBCI2000 component.<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
</pre><br />
Each of the three scripts should contain a section like this:<br />
<pre><br />
...<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
</pre><br />
<br />
===Adding Events===<br />
[https://www.bci2000.org/mediawiki/index.php/Programming_Reference:Events Events] are the primary way that non-signal experiment data is recorded in BCI2000. They are timestamped integer values which are encoded alongside the signal data in BCI2000 output files. Due to BCI2000's design, events must be added during a very specific part of its startup sequence, which is immediately after the BCI2000 operator starts, and before any of the modules start. As such, we cannot simply call <code>AddEvent()</code> whenever we want. Furthermore, the order in which Unity objects initialize is undefined, so it cannot even be guaranteed that calling <code>AddEvent</code> at a specific time will be consistent across multiple projects. As such, UnityBCI2000 provides a couple of methods for sending commands at well-defined points within the startup sequence. These two methods, <code>OnIdle</code> and <code>OnIdle</code> and <code>OnConnected</code> allow BCI2000 commands to be sent while the operator is in the state Idle (immediately before starting its modules) and when the operator is in the state Connected (after starting and connecting to the modules. Below is an example of using those methods to add and show an event in BCI2000.<br />
<br />
<pre><br />
class Script : MonoBehaviour {<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000Object").GetComponent<UnityBCI2000>();<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("AnEvent", 32);<br />
});<br />
}<br />
void Start() {<br />
bci.OnConnected(remote => {<br />
remote.Visualize("AnEvent");<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
As seen above, <code>OnIdle</code> and <code>OnConnected</code> take a delegate (C#'s term for a callback/closure/functor/etc.) with a single parameter of type <code>BCI2000Remote</code> (in this case called "remote"). The lambda expression given to the call to <code>OnIdle</code> uses the method <code>BCI2000Remote.AddEvent()</code> to add an event called "AnEvent" with a bit width of 32 bits. The call to <code>OnConnected</code> tells BCI2000 to show the event's value in a graphical window. A description of the BCI2000Remote class can be found [https://www.bci2000.org/mediawiki/index.php/Contributions:BCI2000RemoteNET here], and API documentation can be found [https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html here].<br />
<br />
We will now add the events relevant to the Cursor Task. Open the <code>GameControl.cs</code> script, and modify its <code>Awake()</code> to add the events <code>PreFeedback</code>, <code>Feedback</code>, <code>PostFeedback</code>, <code>TargetHit</code>, and <code>Timeout</code> with bit width 1. Additionally, add the events <code>TrialNumber</code>, <code>TargetPositionX</code>, and <code>TargetPositionY</code> with width 16. These will encode the task state and number of trials.<br />
We also need to set a parameter value so that the signal will be set to the mouse position. Using <code>BCI2000Remote.SetParameter()</code>, we will set the <code>ModulateAmplitude</code> parameter to 1.<br />
<br />
Open the <code>BallControl.cs</code> script, and within the <code>Awake()</code> function, add events <code>CursorPositionX</code> and <code>CursorPositionY</code>, with width 16. Show these events in a visualization window with <code>Visualize</code><br />
<br />
Your two scripts should now look like this: <br />
<pre><br />
>>> GameControl.cs <br />
...<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
remote.AddEvent("Feedback", 1);<br />
remote.AddEvent("PostFeedback", 1);<br />
remote.AddEvent("TargetHit", 1);<br />
remote.AddEvent("Timeout", 1);<br />
remote.AddEvent("TrialNumber", 16);<br />
remote.AddEvent("TargetPositionX", 16);<br />
remote.AddEvent("TargetPositionY", 16);<br />
remote.SetParameter("ModulateAmplitude", "1");<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
...<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("CursorPositionX", 16);<br />
remote.AddEvent("CursorPositionY", 16);<br />
});<br />
bci.OnConnected(remote => {<br />
remote.Visualize("CursorPositionX");<br />
remote.Visualize("CursorPositionY");<br />
}<br />
</pre><br />
<br />
<br />
<br />
===Using BCI2000 Parameters===<br />
====Adding Parameters====<br />
BCI2000's operator contains an interface for changing experiment parameters before running a task. By making use of this interface we can change the behavior of the task dynamically, without needing to rebuild the Unity project each time. In order to do this we need to define the parameters and add them to BCI2000, and later read their values after the operator has a chance to change them. <span style="color: red">This section is not strictly necessary. The project will function the same whether this is done or not, just without the option to change parameters at runtime. </span> <br />
<br />
First, we define add parameters to BCI2000. Similarly to events, parameters must be added while the Operator is in the <code>Idle</code> state, so we add them inside of <code>OnIdle</code>, like below:<br />
<pre><br />
public int someParameter = 5;<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddParameter("Application:ParameterPlace", "SomeParameter", someParameter.ToString()); <br />
});<br />
}<br />
<br />
The first argument to the method is the section into which the parameter is placed, that is, on which tab and under which heading the parameter will appear within the Operator's parameter editor window (note that the section is not a scope, all parameter names must be unique). The second argument is the parameter name itself. The third argument is the default value of the parameter. We pass in the value of the parameter, so when it appears in the Operator, its default value is 5 (or another value if it has been changed in the Unity Editor). Note that all parameters are handled as strings, so we need to convert its value to a string when sending it.<br />
<br />
For <code>GameControl.cs</code>, we will add parameters corresponding to the Pre-Feedback, Feedback, and Post-Feedback durations, Target Radius, and Number of Trials.<br />
For <code>BallControl.cs</code>, we will add parameters corresponding to the Acceleration Scale, Coefficient of Restitution, Coefficient of Drag, and Attraction Curve Coefficient (how quickly the Ball moves to follow the Mouse Cursor).<br />
For <code>MCursorControl.cs</code>, we will add a parameter corresponding to the Rolling Maximum Amount.<br />
<br />
Your scripts should look like this:<br />
<pre><br />
>>> GameControl.cs<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
...<br />
<br />
remote.AddParameter("Application:Task", "PreFeedbackDuration", preFeedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "FeedbackDuration", feedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "PostFeedbackDuration", postFeedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "TargetRadius", targetRadius.ToString());<br />
remote.AddParameter("Application:Task", "Trials", n_trials.ToString());<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddParameter("Application:Physics", "AccelerationScale", accelerationScale.ToString());<br />
remote.AddParameter("Application:Physics", "CoeffOfRestitution", coefficientOfRestitution.ToString());<br />
remote.AddParameter("Application:Physics", "CoeffOfDrag", coefficientOfDrag.ToString());<br />
remote.AddParameter("Application:Physics", "AccelerationCurve", attractionCurveCoefficient.ToString());<br />
})}<br />
}<br />
<br />
>>> MCursorControl.cs<br />
void Awake() {<br />
...<br />
<br />
bci.OnIdle(remote => {<br />
AddParameter("Application:Physics", "RollingMaximumAmount", rollingMaximumAmount.ToString());<br />
});<br />
}<br />
<br />
<br />
====Reading and Validating Parameters====<br />
Since we set the parameters within the BCI2000 operator, we need some way to read them back into Unity after they have been set. Specifically, we need to read them after the operator clicks the "Set Config" button within the BCI2000 Operator. How this timing synchronization is covered in the section [[Reacting to BCI2000 state changes]]. In this section we will cover reading and validating parameters.<br />
<br />
A method called <code>SetConfig</code> is provided in each of the scripts in which we added parameters previously. This method will be called after the operator changes parameters. In this method we will read in parameters and parse them into valid values. Using the same example parameter as before:<br />
<pre><br />
void SetConfig() {<br />
try {<br />
someParameter = int.Parse(bci.Control.GetParameter("SomeParameter"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse parameter SomeParameter as int");<br />
throw e;<br />
}<br />
}<br />
</pre><br />
<br />
Note that since we are now working outside the BCI2000 startup sequence, we use <code>UnityBCI2000.Control</code> to call <code>BCI2000Remote</code> methods directly, rather than using <code>OnIdle</code> or <code>OnConnected</code>. We also wrap the call within a try/catch block so that we can report erroneous parameters back to the operator. This is optional, but it keeps your project from failing silently and is otherwise useful for doing things like distributing your Unity project as a standalone executable, where logging errors can only be done through the BCI2000 operator. You can also write a helper function which handles parsing and error reporting for you:<br />
<br />
<pre><br />
int GetParseParameterInt(string paramName) {<br />
int p_val = bci.Control.GetParameter("SomeParameter");<br />
try {<br />
someParameter = int.Parse(p_val);<br />
} catch (FormatException e) {<br />
bci.Error($"Could not parse parameter {paramName} (value {p_val}) as int");<br />
throw e;<br />
}<br />
}<br />
</pre><br />
Unfortunately, since the version of C# used by Unity does not support type-parameterized parsing, you must write one of these helper functions for each type of data you want to store in a parameter (int, float, double, etc.)<br />
<br />
<br />
Read back the parameters added in the previous step. Your scripts should look like this:<br />
<br />
<pre><br />
>>> GameControl.cs <br />
void SetConfig() {<br />
try {<br />
preFeedbackDuration = float.Parse(bci.Control.GetParameter("PreFeedbackDuration"));<br />
feedbackDuration = float.Parse(bci.Control.GetParameter("FeedbackDuration"));<br />
postFeedbackDuration = float.Parse(bci.Control.GetParameter("PostFeedbackDuration"));<br />
targetRadius = float.Parse(bci.Control.GetParameter("TargetRadius"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse one of PreFeedbackDuration, FeedbackDuration, PostFeedbackDuration, or TargetRadius as a float");<br />
throw e;<br />
}<br />
try {<br />
n_trials = int.Parse(bci.Control.GetParameter("Trials"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse Trials as an int");<br />
throw e;<br />
}<br />
<br />
if (preFeedbackDuration < COUNTDOWN_DURATION) {<br />
bci.Error("preFeedbackDuration must be greater than or equal to 2.25");<br />
throw new Exception("preFeedbackDuration must be greater than or equal to 2.25");<br />
}<br />
}<br />
<br />
>>> BallControl.cs<br />
public void SetConfig() {<br />
try {<br />
accelerationScale = float.Parse(bci.Control.GetParameter("AccelerationScale"));<br />
coefficientOfRestitution = float.Parse(bci.Control.GetParameter("CoeffOfRestitution"));<br />
coefficientOfDrag = float.Parse(bci.Control.GetParameter("CoeffOfDrag"));<br />
attractionCurveCoefficient = float.Parse(bci.Control.GetParameter("AccelerationCurve"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse one of AccelerationScale, CoeffOfRestitution, CoeffOfDrag, AccelerationCurve as float");<br />
throw e;<br />
}<br />
}<br />
<br />
>>> MCursorControl.cs<br />
public void SetConfig() {<br />
try {<br />
rollingMaximumAmount = int.Parse(bci.Control.GetParameter("RollingMaximumAmount"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse parameter RollingMaximumAmount as int");<br />
throw e;<br />
}<br />
signalsX = new int[rollingMaximumAmount];<br />
signalsY = new int[rollingMaximumAmount];<br />
}<br />
</pre><br />
<br />
Note that in <code>GameControl.cs</code>, we also verify that the Pre-Feedback Duration is longer than the duration of the countdown that happens before each trial, and report errors to BCI2000 accordingly.<br />
<br />
<br />
===Reacting to BCI2000 state changes===<br />
Since we will be controlling the Unity task from BCI2000, we need some way to wait for BCI2000 to be in a specific state, for example, waiting for the operator to click Start and put the Operator Module into the Running state. UnityBCI2000 provides a method for this, the <code>UnityBCI2000.PollSystemState</code> method. In order to wait for the Operator Module to be in the <code>Running</code> state:<br />
<pre><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Running));<br />
</pre><br />
This will check once per frame whether or not the Operator is in the <code>Running</code> state, and only continue once BCI2000 is in the <code>Running</code> state. Note that since <code>SystemState</code> is a member of <code>BCI2000Remote</code>, we also need to add a <code>using BCI2000RemoteNET</code> statement to our script.<br />
<br />
In our case, we need to react to the operator setting the parameters, starting the data collection, and stopping the data collection. These correspond to the Operator Module entering the <code>Resting</code> state, entering the <code>Running</code> state, and exiting the <code>Running</code> state.<br />
<br />
In the <code>GameControl.cs</code> script, we will wait for the system to be in the <code>Resting</code> state at the start of the <code>ControLoop</code> method, and wait for the system to be in the <code>Running</code> state immediately before the entering the trial loop. <br />
<pre><br />
>>> GameControl.cs<br />
<br />
IEnumerator ControlLoop() {<br />
while (True) {<br />
<pre style="color: red"><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Resting));<br />
</pre><br />
<br />
try {<br />
...<br />
} catch (Exception e) {<br />
continue;<br />
}<br />
<br />
int trials = 0;<br />
<br />
</pre><br />
<pre style="color: red"><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Running));<br />
</pre><br />
<br />
yield return new WaitForSeconds(preRunDuration);<br />
while (IsContinue() && trials < n_trials) {<br />
...<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
We also need to check for the operator stopping data collection, so we modify the <code>IsContinue()</code> method.<br />
<br />
<pre><br />
bool IsContinue () {<br />
return bci.Control.GetSystemState() == BCI2000Remote.SystemState.Running;<br />
}<br />
</pre><br />
<br />
Remember to add <code>using BCI2000RemoteNET;</code> to the top of the script, so you can access the <code>SystemState</code> enum.<br />
<br />
===Reading the control signal===<br />
We will be using the control signal to control the cursor. Open the <code>MCursorControl.cs</code> script.<br />
<br />
The commented out section of the <code>GetPos()</code> method contains the code required to turn the control signal waveform coming from the Signal Source and Signal Processing modules into screen coordinates. <br />
Uncomment the commented part and delete the line <code>Ray r = camera.ScreenPointToRay(Input.MousePosition);</code>.<br />
Change the <code>double signalX = 0;</code> and <code>double signalY = 0;</code> to. <br />
<br />
Your <code>GetPos()</code> method should look like this:<br />
<pre><br />
Vector3 GetPos() {<br />
double signalX = bci.Control.GetSignal(1, bci.CurrentSampleOffset());<br />
double signalY = bci.Control.GetSignal(2, bci.CurrentSampleOffset());<br />
signalsX[signalIndex] = signalX;<br />
signalsY[signalIndex] = signalY;<br />
<br />
signalIndex = signalIndex + 1 >= rollingMaximumAmount ? 0 : signalIndex + 1;<br />
double max_x = signalsX.Max();<br />
double max_y = signalsY.Max();<br />
Ray r = camera.ScreenPointToRay(new Vector3((float) max_x * Screen.width, (float) max_y * Screen.height, 0));<br />
float p;<br />
if (!plane.Raycast(r, out p)) {<br />
throw new Exception("error casting ray to plane, invalid mouse position?");<br />
}<br />
return r.GetPoint(p);<br />
}<br />
</pre><br />
<br />
Note the use of the <code>UnityBCI2000.CurrentSampleOffset()</code> method. This is a special method which gets the offset into the current block such that the sample is exactly one block length later than when it was collected by the hardware. This is to normalize the latency between when the hardware collects the signal and the software receives the signal, due to how BCI2000 processes data in blocks.<br />
<br />
===Sending events back to BCI2000===<br />
<br />
The primary way to communicate game state back to BCI2000 is via the use of Events, which are integer values encoded alongside the signal data.<br />
<br />
We will send the events that we added in a previous section.<br />
<br />
First, we will send back the current position of the cursor. Within the <code>BallControl.cs</code> script, within the <code>Update()</code> method, immediately after <code>Move()</code> is called, set the <code>CursorPositionX</code> and <code>CursorPositionY</code> events. <br />
<br />
<pre><br />
>>> BallControl.cs<br />
void Update() {<br />
...<br />
if (isTrialRunning) {<br />
...<br />
Move();<br />
bci.Control.SetEvent("CursorPositionX", (uint) ((transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("CursorPositionY", (uint) ((transform.position.y + 4.5) * 1000));<br />
}<br />
...<br />
</pre><br />
<br />
Notice that we transform the value of the cursor's position. This is because events in BCI2000 are represented as unsigned integers, so, for example, the cursor's range of movement in the x axis, -7 to 7, would not be directly representable within a BCI2000 event, so we add 7 so it is positive, and multiply by 1000 so that we have a more precise measure of the cursor's position. The range of [-7,7] becomes [0,14000].<br />
<br />
<br />
We will also set the events corresponding to the game state within <code>GameControl.cs</code>. First we will set <code>PreFeedback</code>, <code>Feedback</code>, and <code>PostFeedback</code> to represent when the game is in these states. To do this, at the beginning and end of <code>PreTrial()</code>, <code>Trial()</code>, and <code>PostTrial()</code>, we will set the corresponding event values to 1 and 0, respectively.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
bci.Control.SetEvent("PreFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PreFeedback", 0);<br />
}<br />
IEnumerator Trial() {<br />
bci.Control.SetEvent("Feedback", 1);<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
}<br />
IEnumerator PostTrial() {<br />
bci.Control.SetEvent("PostFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PostFeedback", 0);<br />
}<br />
</pre><br />
<br />
We will also set the events which happen at the end of each trial. The <code>TargetHit</code> event is activated when the subject hits the target, and the <code>Timeout</code> event is activated when the subject runs out of time.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator Trial() {<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
if (lastTrialSucceeded) {<br />
bci.Control.PulseEvent("TargetHit", 1);<br />
} else {<br />
bci.Control.PulseEvent("Timeout", 1);<br />
}<br />
}<br />
<br />
Notice that we use <code>BCI2000Remote.PulseEvent()</code> rather than <code>BCI2000Remote.SetEvent()</code>. This results in the event being set to the value <code>1</code> for exactly one sample duration, then returning to zero.<br />
<br />
We will also record the position of the target. Similarly to the cursor, we will transform the target's coordinates to be a positive integer.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
...<br />
target.SetActive(true);<br />
bci.Control.SetEvent("TargetPositionX", (uint) ((target.transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("TargetPositionY", (uint) ((target.transform.position.y + 4.5) * 1000));<br />
...<br />
}<br />
</pre><br />
<br />
The last event we need to set is the trial number.<br />
<br />
<pre><br />
IEnumerator ControlLoop() {<br />
...<br />
while (IsContinue() && trials < n_trials) {<br />
bci.Control.SetEvent("TrialNumber", trials + 1);<br />
...<br />
}<br />
}<br />
</pre><br />
<br />
===Unity Player Settings===<br />
Additionally, due to how Unity detects changes in BCI2000 state, it must be allowed to run in the background.<br />
<br />
<pre style="color:red"><br />
In the Unity menu bar:<br />
Edit > Project Settings > Player > Resolution and Presentation<br />
Check the "Run In Background" box.<br />
</pre><br />
<br />
<br />
===Usage===<br />
<br />
Now, when the Unity application runs, BCI2000 will open. From here, parameters can be set via the Config window, then clicking Set Config and Start will start data collection.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=User_Tutorial:UnityBCI2000&diff=11528User Tutorial:UnityBCI20002024-08-16T02:31:25Z<p>Tytbutler: </p>
<hr />
<div><pre style="color:red"><br />
Red text blocks contain detailed instructions for the higher-level instructions preceding them.<br />
</pre><br />
<br />
This example comprehensively demonstrates many of the capabilities of UnityBCI2000, and as such, is more than what is necessary for many usecases. If you just want to use BCI2000 as a logging backend for an existing Unity application, see the Barebones UnityBCI2000 tutorial.<br />
<br />
===Download Unity===<br />
<br />
Download Unity Hub from [https://unity3d.com Unity].<br />
<br />
===Setting Up BCI2000===<br />
<br />
Follow the instructions starting with [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Install_Prerequisites] to download BCI2000. <br />
<br />
===Setting Up UnityBCI2000===<br />
Download UnityBCI2000 from its GitHub page, [https://github.com/neurotechcenter/UnityBCI2000]. <br />
<pre style="color:red"><br />
Click on the "Releases" section on the right side of the page. This tutorial is intended to be used with UnityBCI2000 version 2.0.0, so scroll to that release and click on the files BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to download them.<br />
</pre><br />
<br />
===Download Tutorial Project===<br />
Download the CursorTask3 repository from [https://github.com/Personator01/CursorTask3 GitHub].<br />
<pre style="color:red"><br />
Either:<br />
-Clone the git repository<br />
-Download the respository directly from GitHub<br />
-> Click the green "Code" button <br />
-> Select "Download ZIP"<br />
-> Extract the zip file<br />
</pre><br />
The download directory contains two versions of the CursorTask3 project. One, CursorTask3-BCI2K, contains an example implementation of the task with BCI2000 integration. The other, CursorTask3-NoBCI2K, contains the same task without BCI2000 integration. This tutorial is a step by step guide on turning that second project into the first. <br />
<br />
===Opening the project===<br />
Open the project in the Unity Editor, and open the CursorTask scene.<br />
<pre style="color:red"><br />
Open Unity Hub.<br />
Click the "Add" button in the top right corner.<br />
Navigate to the CursorTask3 directory downloaded previously.<br />
Select the CursorTask3-NoBCI2K directory to add it to Unity Hub.<br />
Click the CursorTask3-NoBCI2K project in the Unity Hub.<br />
If prompted to select a version of Unity to use or install, select Unity 2022.3. The specific release number of Unity 2022.3 should not matter, so select the one labeled "LTS" for consistency.<br />
The lower panel (the asset browser) should already show the Assets/Scenes directory, which contains a single scene called SampleScene.<br />
Double-click SampleScene. This should open a scene with a box containing various lights and objects.<br />
</pre><br />
If you wish to view the completed implementation, repeat these steps, but instead open the CursorTask3-BCI2K directory. Note that in order to use the completed implementation, you will still need to set the Operator Path value of the UnityBCI2000 component of the BCI2000 game object.<br />
<br />
===Adding UnityBCI2000 to the project===<br />
Add BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to your project's assets.<br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click Assets > Open Containing Folder to open your project directory.<br />
Place the BCI2000RemoteNETStandard.dll and UnityBCI2000.cs files in the Assets folder.<br />
</pre><br />
<br />
Add an empty GameObject called 'BCI2000'. This will hold the scripts for controlling BCI2000. <br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click GameObject > Create Empty to create an empty GameObject, and name it 'BCI2000'. (The object's specific name does not actually matter, it is only needed in order to reference it within other scripts)<br />
You will notice that it now appears in the Scene Hierarchy panel, on the left side of the screen.<br />
</pre><br />
<br />
Add the UnityBCI2000 component to the object.<br />
<pre style="color:red"><br />
Click on the object in the Hierarchy panel. This will open it in the Inspector panel (the panel on the right side of the screen)<br />
In the inspector, below the new object's Transform component, click the "Add Component" button, which will open up a small window for adding components.<br />
Within this window, select Scripts > Unity BCI2000 to add the UnityBCI2000 component.<br />
</pre><br />
<br />
===Configuring UnityBCI2000===<br />
The inspector panel now contains the configuration options for UnityBCI2000. Set the options as follows:<br />
<br />
<code>Start Local Operator</code>: Checked<br />
<br />
This will start the operator on your computer when the Unity scene initializes. If we were instead connecting to an already-running instance of BCI2000, or an instance on another computer, this box would be deselected.<br />
<br />
<code>Operator Path</code>: The path to the Operator executable. This will look something like this on Windows (C://path/to/bci2000/prog/Operator.exe)<br />
<br />
<code>Operator Address</code>: 127.0.0.1<br />
<br />
This is the address of the machine on which BCI2000 is running. Since we are running BCI2000 on the same computer as Unity, we leave it as 127.0.0.1, the loopback address.<br />
<br />
<code>Operator Port</code>: 3999<br />
<br />
This is the port on which BCI2000 is listening for commands. By default, it is 3999.<br />
<br />
<code>Start Modules</code>: Checked<br />
<br />
This tells BCI2000 to start the requested Signal Source, Signal Processing, and Application modules when the Unity scene initializes. Similarly to Start Local Operator, we would deselect this box if connecting to an already-running instance. <br />
<br />
<code>Start With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to start a data collection run when the scene starts. Since we will be using BCI2000 itself to set experiment parameters, we will instead wait for BCI2000 to start from Unity, and thus will leave the box unchecked. <br />
<br />
<code>Stop With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to stop collecting data when the scene stops. Since we will be controlling BCI2000 directly, rather than entirely through Unity, we will leave this unchecked.<br />
<br />
<code>Shutdown With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to shut down alongside the Unity scene. Whether or not this value is set ultimately doesn't matter much, especially if Start Local Operator is checked. The data will be saved whether or not BCI2000 shuts down. <br />
<br />
<code>Module 1</code>: SignalGenerator<br />
<br />
The signal source module to start. We will use SignalGenerator, which generates a signal without any connected hardware.<br />
<br />
<code>Module 2</code>: DummySignalProcessing<br />
<br />
The signal processing module to start. We will use DummySignalProcessing, as there is no processing to do.<br />
<br />
<code>Module 3</code>: DummyApplication<br />
<br />
The Application module to start. Since we are using Unity, we will use DummyApplication.<br />
<br />
===Setting References===<br />
In order for the game's scripts to communicate with BCI2000, they need to hold a reference to the UnityBCI2000 component.<br />
There are three scripts which will need to communicate with BCI2000. They are <code>GameControl.cs, BallControl.cs, and MCursorControl.cs</code>.<br />
These scripts are each located within the Assets directory of the Unity project. <br />
<pre style="color:red"><br />
As before, select Assets > Open Containing Folder to open the project directory, then open the Assets folder. <br />
For each script, open it in a text editor.<br />
Add a data member of type UnityBCI2000 to the class, like so:<br />
UnityBCI2000 bci;<br />
Place the member definition above the Awake() method, for readability.<br />
Within the Awake() method, set this reference to the UnityBCI2000 component.<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
</pre><br />
Each of the three scripts should contain a section like this:<br />
<pre><br />
...<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
</pre><br />
<br />
===Adding Events===<br />
[https://www.bci2000.org/mediawiki/index.php/Programming_Reference:Events Events] are the primary way that non-signal experiment data is recorded in BCI2000. They are timestamped integer values which are encoded alongside the signal data in BCI2000 output files. Due to BCI2000's design, events must be added during a very specific part of its startup sequence, which is immediately after the BCI2000 operator starts, and before any of the modules start. As such, we cannot simply call <code>AddEvent()</code> whenever we want. Furthermore, the order in which Unity objects initialize is undefined, so it cannot even be guaranteed that calling <code>AddEvent</code> at a specific time will be consistent across multiple projects. As such, UnityBCI2000 provides a couple of methods for sending commands at well-defined points within the startup sequence. These two methods, <code>OnIdle</code> and <code>OnIdle</code> and <code>OnConnected</code> allow BCI2000 commands to be sent while the operator is in the state Idle (immediately before starting its modules) and when the operator is in the state Connected (after starting and connecting to the modules. Below is an example of using those methods to add and show an event in BCI2000.<br />
<br />
<pre><br />
class Script : MonoBehaviour {<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000Object").GetComponent<UnityBCI2000>();<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("AnEvent", 32);<br />
});<br />
}<br />
void Start() {<br />
bci.OnConnected(remote => {<br />
remote.Visualize("AnEvent");<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
As seen above, <code>OnIdle</code> and <code>OnConnected</code> take a delegate (C#'s term for a callback/closure/functor/etc.) with a single parameter of type <code>BCI2000Remote</code> (in this case called "remote"). The lambda expression given to the call to <code>OnIdle</code> uses the method <code>BCI2000Remote.AddEvent()</code> to add an event called "AnEvent" with a bit width of 32 bits. The call to <code>OnConnected</code> tells BCI2000 to show the event's value in a graphical window. A description of the BCI2000Remote class can be found [https://www.bci2000.org/mediawiki/index.php/Contributions:BCI2000RemoteNET here], and API documentation can be found [https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html here].<br />
<br />
We will now add the events relevant to the Cursor Task. Open the <code>GameControl.cs</code> script, and modify its <code>Awake()</code> to add the events <code>PreFeedback</code>, <code>Feedback</code>, <code>PostFeedback</code>, <code>TargetHit</code>, and <code>Timeout</code> with bit width 1. Additionally, add the events <code>TrialNumber</code>, <code>TargetPositionX</code>, and <code>TargetPositionY</code> with width 16. These will encode the task state and number of trials.<br />
We also need to set a parameter value so that the signal will be set to the mouse position. Using <code>BCI2000Remote.SetParameter()</code>, we will set the <code>ModulateAmplitude</code> parameter to 1.<br />
<br />
Open the <code>BallControl.cs</code> script, and within the <code>Awake()</code> function, add events <code>CursorPositionX</code> and <code>CursorPositionY</code>, with width 16. Show these events in a visualization window with <code>Visualize</code><br />
<br />
Your two scripts should now look like this: <br />
<pre><br />
>>> GameControl.cs <br />
...<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
remote.AddEvent("Feedback", 1);<br />
remote.AddEvent("PostFeedback", 1);<br />
remote.AddEvent("TargetHit", 1);<br />
remote.AddEvent("Timeout", 1);<br />
remote.AddEvent("TrialNumber", 16);<br />
remote.AddEvent("TargetPositionX", 16);<br />
remote.AddEvent("TargetPositionY", 16);<br />
remote.SetParameter("ModulateAmplitude", "1");<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
...<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("CursorPositionX", 16);<br />
remote.AddEvent("CursorPositionY", 16);<br />
});<br />
bci.OnConnected(remote => {<br />
remote.Visualize("CursorPositionX");<br />
remote.Visualize("CursorPositionY");<br />
}<br />
</pre><br />
<br />
<br />
<br />
===Using BCI2000 Parameters===<br />
====Adding Parameters====<br />
BCI2000's operator contains an interface for changing experiment parameters before running a task. By making use of this interface we can change the behavior of the task dynamically, without needing to rebuild the Unity project each time. In order to do this we need to define the parameters and add them to BCI2000, and later read their values after the operator has a chance to change them. <span style="color: red">This section is not strictly necessary. The project will function the same whether this is done or not, just without the option to change parameters at runtime. </span> <br />
<br />
First, we define add parameters to BCI2000. Similarly to events, parameters must be added while the Operator is in the <code>Idle</code> state, so we add them inside of <code>OnIdle</code>, like below:<br />
<pre><br />
public int someParameter = 5;<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddParameter("Application:ParameterPlace", "SomeParameter", someParameter.ToString()); <br />
});<br />
}<br />
<br />
The first argument to the method is the section into which the parameter is placed, that is, on which tab and under which heading the parameter will appear within the Operator's parameter editor window (note that the section is not a scope, all parameter names must be unique). The second argument is the parameter name itself. The third argument is the default value of the parameter. We pass in the value of the parameter, so when it appears in the Operator, its default value is 5 (or another value if it has been changed in the Unity Editor). Note that all parameters are handled as strings, so we need to convert its value to a string when sending it.<br />
<br />
For <code>GameControl.cs</code>, we will add parameters corresponding to the Pre-Feedback, Feedback, and Post-Feedback durations, Target Radius, and Number of Trials.<br />
For <code>BallControl.cs</code>, we will add parameters corresponding to the Acceleration Scale, Coefficient of Restitution, Coefficient of Drag, and Attraction Curve Coefficient (how quickly the Ball moves to follow the Mouse Cursor).<br />
For <code>MCursorControl.cs</code>, we will add a parameter corresponding to the Rolling Maximum Amount.<br />
<br />
Your scripts should look like this:<br />
<pre><br />
>>> GameControl.cs<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
...<br />
<br />
remote.AddParameter("Application:Task", "PreFeedbackDuration", preFeedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "FeedbackDuration", feedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "PostFeedbackDuration", postFeedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "TargetRadius", targetRadius.ToString());<br />
remote.AddParameter("Application:Task", "Trials", n_trials.ToString());<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddParameter("Application:Physics", "AccelerationScale", accelerationScale.ToString());<br />
remote.AddParameter("Application:Physics", "CoeffOfRestitution", coefficientOfRestitution.ToString());<br />
remote.AddParameter("Application:Physics", "CoeffOfDrag", coefficientOfDrag.ToString());<br />
remote.AddParameter("Application:Physics", "AccelerationCurve", attractionCurveCoefficient.ToString());<br />
})}<br />
}<br />
<br />
>>> MCursorControl.cs<br />
void Awake() {<br />
...<br />
<br />
bci.OnIdle(remote => {<br />
AddParameter("Application:Physics", "RollingMaximumAmount", rollingMaximumAmount.ToString());<br />
});<br />
}<br />
<br />
<br />
====Reading and Validating Parameters====<br />
Since we set the parameters within the BCI2000 operator, we need some way to read them back into Unity after they have been set. Specifically, we need to read them after the operator clicks the "Set Config" button within the BCI2000 Operator. How this timing synchronization is covered in the section [[Reacting to BCI2000 state changes]]. In this section we will cover reading and validating parameters.<br />
<br />
A method called <code>SetConfig</code> is provided in each of the scripts in which we added parameters previously. This method will be called after the operator changes parameters. In this method we will read in parameters and parse them into valid values. Using the same example parameter as before:<br />
<pre><br />
void SetConfig() {<br />
try {<br />
someParameter = int.Parse(bci.Control.GetParameter("SomeParameter"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse parameter SomeParameter as int");<br />
throw e;<br />
}<br />
}<br />
</pre><br />
<br />
Note that since we are now working outside the BCI2000 startup sequence, we use <code>UnityBCI2000.Control</code> to call <code>BCI2000Remote</code> methods directly, rather than using <code>OnIdle</code> or <code>OnConnected</code>. We also wrap the call within a try/catch block so that we can report erroneous parameters back to the operator. This is optional, but it keeps your project from failing silently and is otherwise useful for doing things like distributing your Unity project as a standalone executable, where logging errors can only be done through the BCI2000 operator. You can also write a helper function which handles parsing and error reporting for you:<br />
<br />
<pre><br />
int GetParseParameterInt(string paramName) {<br />
int p_val = bci.Control.GetParameter("SomeParameter");<br />
try {<br />
someParameter = int.Parse(p_val);<br />
} catch (FormatException e) {<br />
bci.Error($"Could not parse parameter {paramName} (value {p_val}) as int");<br />
throw e;<br />
}<br />
}<br />
</pre><br />
Unfortunately, since the version of C# used by Unity does not support type-parameterized parsing, you must write one of these helper functions for each type of data you want to store in a parameter (int, float, double, etc.)<br />
<br />
<br />
Read back the parameters added in the previous step. Your scripts should look like this:<br />
<br />
<pre><br />
>>> GameControl.cs <br />
void SetConfig() {<br />
try {<br />
preFeedbackDuration = float.Parse(bci.Control.GetParameter("PreFeedbackDuration"));<br />
feedbackDuration = float.Parse(bci.Control.GetParameter("FeedbackDuration"));<br />
postFeedbackDuration = float.Parse(bci.Control.GetParameter("PostFeedbackDuration"));<br />
targetRadius = float.Parse(bci.Control.GetParameter("TargetRadius"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse one of PreFeedbackDuration, FeedbackDuration, PostFeedbackDuration, or TargetRadius as a float");<br />
throw e;<br />
}<br />
try {<br />
n_trials = int.Parse(bci.Control.GetParameter("Trials"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse Trials as an int");<br />
throw e;<br />
}<br />
<br />
if (preFeedbackDuration < COUNTDOWN_DURATION) {<br />
bci.Error("preFeedbackDuration must be greater than or equal to 2.25");<br />
throw new Exception("preFeedbackDuration must be greater than or equal to 2.25");<br />
}<br />
}<br />
<br />
>>> BallControl.cs<br />
public void SetConfig() {<br />
try {<br />
accelerationScale = float.Parse(bci.Control.GetParameter("AccelerationScale"));<br />
coefficientOfRestitution = float.Parse(bci.Control.GetParameter("CoeffOfRestitution"));<br />
coefficientOfDrag = float.Parse(bci.Control.GetParameter("CoeffOfDrag"));<br />
attractionCurveCoefficient = float.Parse(bci.Control.GetParameter("AccelerationCurve"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse one of AccelerationScale, CoeffOfRestitution, CoeffOfDrag, AccelerationCurve as float");<br />
throw e;<br />
}<br />
}<br />
<br />
>>> MCursorControl.cs<br />
public void SetConfig() {<br />
try {<br />
rollingMaximumAmount = int.Parse(bci.Control.GetParameter("RollingMaximumAmount"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse parameter RollingMaximumAmount as int");<br />
throw e;<br />
}<br />
signalsX = new int[rollingMaximumAmount];<br />
signalsY = new int[rollingMaximumAmount];<br />
}<br />
</pre><br />
<br />
Note that in <code>GameControl.cs</code>, we also verify that the Pre-Feedback Duration is longer than the duration of the countdown that happens before each trial, and report errors to BCI2000 accordingly.<br />
<br />
<br />
===Reacting to BCI2000 state changes===<br />
Since we will be controlling the Unity task from BCI2000, we need some way to wait for BCI2000 to be in a specific state, for example, waiting for the operator to click Start and put the Operator Module into the Running state. UnityBCI2000 provides a method for this, the <code>UnityBCI2000.PollSystemState</code> method. In order to wait for the Operator Module to be in the <code>Running</code> state:<br />
<pre><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Running));<br />
</pre><br />
This will check once per frame whether or not the Operator is in the <code>Running</code> state, and only continue once BCI2000 is in the <code>Running</code> state. Note that since <code>SystemState</code> is a member of <code>BCI2000Remote</code>, we also need to add a <code>using BCI2000RemoteNET</code> statement to our script.<br />
<br />
In our case, we need to react to the operator setting the parameters, starting the data collection, and stopping the data collection. These correspond to the Operator Module entering the <code>Resting</code> state, entering the <code>Running</code> state, and exiting the <code>Running</code> state.<br />
<br />
In the <code>GameControl.cs</code> script, we will wait for the system to be in the <code>Resting</code> state at the start of the <code>ControLoop</code> method, and wait for the system to be in the <code>Running</code> state immediately before the entering the trial loop. <br />
<pre><br />
>>> GameControl.cs<br />
<br />
IEnumerator ControlLoop() {<br />
while (True) {<br />
<pre style="color: red"><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Resting));<br />
</pre><br />
<br />
try {<br />
...<br />
} catch (Exception e) {<br />
continue;<br />
}<br />
<br />
int trials = 0;<br />
<br />
</pre><br />
<pre style="color: red"><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Running));<br />
</pre><br />
<br />
yield return new WaitForSeconds(preRunDuration);<br />
while (IsContinue() && trials < n_trials) {<br />
...<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
We also need to check for the operator stopping data collection, so we modify the <code>IsContinue()</code> method.<br />
<br />
<pre><br />
bool IsContinue () {<br />
return bci.Control.GetSystemState() == BCI2000Remote.SystemState.Running;<br />
}<br />
</pre><br />
<br />
Remember to add <code>using BCI2000RemoteNET;</code> to the top of the script, so you can access the <code>SystemState</code> enum.<br />
<br />
===Reading the control signal===<br />
We will be using the control signal to control the cursor. Open the <code>MCursorControl.cs</code> script.<br />
<br />
The commented out section of the <code>GetPos()</code> method contains the code required to turn the control signal waveform coming from the Signal Source and Signal Processing modules into screen coordinates. <br />
Uncomment the commented part and delete the line <code>Ray r = camera.ScreenPointToRay(Input.MousePosition);</code>.<br />
Change the <code>double signalX = 0;</code> and <code>double signalY = 0;</code> to. <br />
<br />
Your <code>GetPos()</code> method should look like this:<br />
<pre><br />
Vector3 GetPos() {<br />
double signalX = bci.Control.GetSignal(1, bci.CurrentSampleOffset());<br />
double signalY = bci.Control.GetSignal(2, bci.CurrentSampleOffset());<br />
signalsX[signalIndex] = signalX;<br />
signalsY[signalIndex] = signalY;<br />
<br />
signalIndex = signalIndex + 1 >= rollingMaximumAmount ? 0 : signalIndex + 1;<br />
double max_x = signalsX.Max();<br />
double max_y = signalsY.Max();<br />
Ray r = camera.ScreenPointToRay(new Vector3((float) max_x * Screen.width, (float) max_y * Screen.height, 0));<br />
float p;<br />
if (!plane.Raycast(r, out p)) {<br />
throw new Exception("error casting ray to plane, invalid mouse position?");<br />
}<br />
return r.GetPoint(p);<br />
}<br />
</pre><br />
<br />
Note the use of the <code>UnityBCI2000.CurrentSampleOffset()</code> method. This is a special method which gets the offset into the current block such that the sample is exactly one block length later than when it was collected by the hardware. This is to normalize the latency between when the hardware collects the signal and the software receives the signal, due to how BCI2000 processes data in blocks.<br />
<br />
===Sending events back to BCI2000===<br />
<br />
The primary way to communicate game state back to BCI2000 is via the use of Events, which are integer values encoded alongside the signal data.<br />
<br />
We will send the events that we added in a previous section.<br />
<br />
First, we will send back the current position of the cursor. Within the <code>BallControl.cs</code> script, within the <code>Update()</code> method, immediately after <code>Move()</code> is called, set the <code>CursorPositionX</code> and <code>CursorPositionY</code> events. <br />
<br />
<pre><br />
>>> BallControl.cs<br />
void Update() {<br />
...<br />
if (isTrialRunning) {<br />
...<br />
Move();<br />
bci.Control.SetEvent("CursorPositionX", (uint) ((transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("CursorPositionY", (uint) ((transform.position.y + 4.5) * 1000));<br />
}<br />
...<br />
</pre><br />
<br />
Notice that we transform the value of the cursor's position. This is because events in BCI2000 are represented as unsigned integers, so, for example, the cursor's range of movement in the x axis, -7 to 7, would not be directly representable within a BCI2000 event, so we add 7 so it is positive, and multiply by 1000 so that we have a more precise measure of the cursor's position. The range of [-7,7] becomes [0,14000].<br />
<br />
<br />
We will also set the events corresponding to the game state within <code>GameControl.cs</code>. First we will set <code>PreFeedback</code>, <code>Feedback</code>, and <code>PostFeedback</code> to represent when the game is in these states. To do this, at the beginning and end of <code>PreTrial()</code>, <code>Trial()</code>, and <code>PostTrial()</code>, we will set the corresponding event values to 1 and 0, respectively.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
bci.Control.SetEvent("PreFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PreFeedback", 0);<br />
}<br />
IEnumerator Trial() {<br />
bci.Control.SetEvent("Feedback", 1);<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
}<br />
IEnumerator PostTrial() {<br />
bci.Control.SetEvent("PostFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PostFeedback", 0);<br />
}<br />
</pre><br />
<br />
We will also set the events which happen at the end of each trial. The <code>TargetHit</code> event is activated when the subject hits the target, and the <code>Timeout</code> event is activated when the subject runs out of time.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator Trial() {<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
if (lastTrialSucceeded) {<br />
bci.Control.PulseEvent("TargetHit", 1);<br />
} else {<br />
bci.Control.PulseEvent("Timeout", 1);<br />
}<br />
}<br />
<br />
Notice that we use <code>BCI2000Remote.PulseEvent()</code> rather than <code>BCI2000Remote.SetEvent()</code>. This results in the event being set to the value <code>1</code> for exactly one sample duration, then returning to zero.<br />
<br />
We will also record the position of the target. Similarly to the cursor, we will transform the target's coordinates to be a positive integer.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
...<br />
target.SetActive(true);<br />
bci.Control.SetEvent("TargetPositionX", (uint) ((target.transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("TargetPositionY", (uint) ((target.transform.position.y + 4.5) * 1000));<br />
...<br />
}<br />
</pre><br />
<br />
The last event we need to set is the trial number.<br />
<br />
<pre><br />
IEnumerator ControlLoop() {<br />
...<br />
while (IsContinue() && trials < n_trials) {<br />
bci.Control.SetEvent("TrialNumber", trials + 1);<br />
...<br />
}<br />
}<br />
</pre><br />
<br />
===Unity Player Settings===<br />
Additionally, due to how Unity detects changes in BCI2000 state, it must be allowed to run in the background.<br />
<br />
<pre style="color:red"><br />
In the Unity menu bar:<br />
Edit > Project Settings > Player > Resolution and Presentation<br />
Check the "Run In Background" box.<br />
</pre><br />
<br />
<br />
===Usage===<br />
<br />
Now, when the Unity application runs, BCI2000 will open. From here, parameters can be set via the Config window, then clicking Set Config and Start will start data collection.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=User_Tutorial:UnityBCI2000_Barebones&diff=11527User Tutorial:UnityBCI2000 Barebones2024-08-16T02:31:14Z<p>Tytbutler: </p>
<hr />
<div><pre style="color:red"><br />
Red text blocks contain detailed instructions for the higher-level instructions preceding them.<br />
</pre><br />
<br />
This tutorial goes over how to use BCI2000 as a logging service for an existing Unity project. For a more comprehensive tutorial on integrating Unity with BCI2000, see [[User Tutorial:UnityBCI2000]]. This tutorial will use a sample Unity project, the same as the full tutorial.<br />
<br />
===Download Unity===<br />
<br />
Download Unity Hub from [https://unity3d.com Unity].<br />
<br />
===Setting Up BCI2000===<br />
<br />
Follow the instructions starting with [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Install_Prerequisites] to download BCI2000. <br />
<br />
===Setting Up UnityBCI2000===<br />
Download UnityBCI2000 from its GitHub page, [https://github.com/neurotechcenter/UnityBCI2000]. <br />
<pre style="color:red"><br />
Click on the "Releases" section on the right side of the page. This tutorial is intended to be used with UnityBCI2000 version 2.0.0, so scroll to that release and click on the files BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to download them.<br />
</pre><br />
<br />
===Download Tutorial Project===<br />
Download the CursorTask3 repository from [https://github.com/Personator01/CursorTask3 GitHub].<br />
<pre style="color:red"><br />
Either:<br />
-Clone the git repository<br />
-Download the respository directly from GitHub<br />
-> Click the green "Code" button <br />
-> Select "Download ZIP"<br />
-> Extract the zip file<br />
</pre><br />
The download directory contains two versions of the CursorTask3 project. One, CursorTask3-BCI2K, contains an example implementation of the task with BCI2000 integration. The other, CursorTask3-NoBCI2K, contains the same task without BCI2000 integration. This tutorial is a step by step guide on turning that second project into the first. <br />
<br />
===Opening the project===<br />
Open the project in the Unity Editor, and open the CursorTask scene.<br />
<pre style="color:red"><br />
Open Unity Hub.<br />
Click the "Add" button in the top right corner.<br />
Navigate to the CursorTask3 directory downloaded previously.<br />
Select the CursorTask3-NoBCI2K directory to add it to Unity Hub.<br />
Click the CursorTask3-NoBCI2K project in the Unity Hub.<br />
If prompted to select a version of Unity to use or install, select Unity 2022.3. The specific release number of Unity 2022.3 should not matter, so select the one labeled "LTS" for consistency.<br />
The lower panel (the asset browser) should already show the Assets/Scenes directory, which contains a single scene called SampleScene.<br />
Double-click SampleScene. This should open a scene with a box containing various lights and objects.<br />
</pre><br />
If you wish to view the completed implementation, repeat these steps, but instead open the CursorTask3-BCI2K-Barebones directory. Note that in order to use the completed implementation, you will still need to set the Operator Path value of the UnityBCI2000 component of the BCI2000 game object.<br />
<br />
===Adding UnityBCI2000 to the project===<br />
Add BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to your project's assets.<br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click Assets > Open Containing Folder to open your project directory.<br />
Place the BCI2000RemoteNETStandard.dll and UnityBCI2000.cs files in the Assets folder.<br />
</pre><br />
<br />
Add an empty GameObject called 'BCI2000'. This will hold the scripts for controlling BCI2000. <br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click GameObject > Create Empty to create an empty GameObject, and name it 'BCI2000'. (The object's specific name does not actually matter, it is only needed in order to reference it within other scripts)<br />
You will notice that it now appears in the Scene Hierarchy panel, on the left side of the screen.<br />
</pre><br />
<br />
Add the UnityBCI2000 component to the object.<br />
<pre style="color:red"><br />
Click on the object in the Hierarchy panel. This will open it in the Inspector panel (the panel on the right side of the screen)<br />
In the inspector, below the new object's Transform component, click the "Add Component" button, which will open up a small window for adding components.<br />
Within this window, select Scripts > Unity BCI2000 to add the UnityBCI2000 component.<br />
</pre><br />
<br />
===Configuring UnityBCI2000===<br />
The inspector panel now contains the configuration options for UnityBCI2000. Set the options as follows:<br />
<br />
<code>Start Local Operator</code>: Checked<br />
<br />
This will start the operator on your computer when the Unity scene initializes. If we were instead connecting to an already-running instance of BCI2000, or an instance on another computer, this box would be deselected.<br />
<br />
<code>Operator Path</code>: The path to the Operator executable. This will look something like this on Windows (C://path/to/bci2000/prog/Operator.exe)<br />
<br />
<code>Operator Address</code>: 127.0.0.1<br />
<br />
This is the address of the machine on which BCI2000 is running. Since we are running BCI2000 on the same computer as Unity, we leave it as 127.0.0.1, the loopback address.<br />
<br />
<code>Operator Port</code>: 3999<br />
<br />
This is the port on which BCI2000 is listening for commands. By default, it is 3999.<br />
<br />
<code>Start Modules</code>: Checked<br />
<br />
This tells BCI2000 to start the requested Signal Source, Signal Processing, and Application modules when the Unity scene initializes. Similarly to Start Local Operator, we would deselect this box if connecting to an already-running instance. <br />
<br />
<code>Start With Scene</code>: Checked<br />
<br />
This tells BCI2000 to start a data collection run when the scene starts. Since we will be using BCI2000 itself to set experiment parameters, we will instead wait for BCI2000 to start from Unity, and thus will leave the box unchecked. <br />
<br />
<code>Stop With Scene</code>: Checked<br />
<br />
This tells BCI2000 to stop collecting data when the scene stops. Since we will be controlling BCI2000 directly, rather than entirely through Unity, we will leave this unchecked.<br />
<br />
<code>Shutdown With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to shut down alongside the Unity scene. Whether or not this value is set ultimately doesn't matter much, especially if Start Local Operator is checked. The data will be saved whether or not BCI2000 shuts down. <br />
<br />
<code>Module 1</code>: SignalGenerator<br />
<br />
The signal source module to start. We will use SignalGenerator, which generates a signal without any connected hardware.<br />
<br />
<code>Module 2</code>: DummySignalProcessing<br />
<br />
The signal processing module to start. We will use DummySignalProcessing, as there is no processing to do.<br />
<br />
<code>Module 3</code>: DummyApplication<br />
<br />
The Application module to start. Since we are using Unity, we will use DummyApplication.<br />
<br />
<br />
<br />
===Setting References===<br />
In order for the game's scripts to communicate with BCI2000, they need to hold a reference to the UnityBCI2000 component.<br />
There are three scripts which will need to communicate with BCI2000. They are <code>GameControl.cs, BallControl.cs, and MCursorControl.cs</code>.<br />
These scripts are each located within the Assets directory of the Unity project. <br />
<pre style="color:red"><br />
As before, select Assets > Open Containing Folder to open the project directory, then open the Assets folder. <br />
For each script, open it in a text editor.<br />
Add a data member of type UnityBCI2000 to the class, like so:<br />
UnityBCI2000 bci;<br />
Place the member definition above the Awake() method, for readability.<br />
Within the Awake() method, set this reference to the UnityBCI2000 component.<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
</pre><br />
Each of the three scripts should contain a section like this:<br />
<pre><br />
...<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
</pre><br />
<br />
===Adding Events===<br />
[https://www.bci2000.org/mediawiki/index.php/Programming_Reference:Events Events] are the primary way that non-signal experiment data is recorded in BCI2000. They are timestamped integer values which are encoded alongside the signal data in BCI2000 output files. Due to BCI2000's design, events must be added during a very specific part of its startup sequence, which is immediately after the BCI2000 operator starts, and before any of the modules start. As such, we cannot simply call <code>AddEvent()</code> whenever we want. Furthermore, the order in which Unity objects initialize is undefined, so it cannot even be guaranteed that calling <code>AddEvent</code> at a specific time will be consistent across multiple projects. As such, UnityBCI2000 provides a couple of methods for sending commands at well-defined points within the startup sequence. These two methods, <code>OnIdle</code> and <code>OnIdle</code> and <code>OnConnected</code> allow BCI2000 commands to be sent while the operator is in the state Idle (immediately before starting its modules) and when the operator is in the state Connected (after starting and connecting to the modules. Below is an example of using those methods to add and show an event in BCI2000.<br />
<br />
<pre><br />
class Script : MonoBehaviour {<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000Object").GetComponent<UnityBCI2000>();<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("AnEvent", 32);<br />
});<br />
}<br />
void Start() {<br />
bci.OnConnected(remote => {<br />
remote.Visualize("AnEvent");<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
As seen above, <code>OnIdle</code> and <code>OnConnected</code> take a delegate (C#'s term for a callback/closure/functor/etc.) with a single parameter of type <code>BCI2000Remote</code> (in this case called "remote"). The lambda expression given to the call to <code>OnIdle</code> uses the method <code>BCI2000Remote.AddEvent()</code> to add an event called "AnEvent" with a bit width of 32 bits. The call to <code>OnConnected</code> tells BCI2000 to show the event's value in a graphical window. A description of the BCI2000Remote class can be found [https://www.bci2000.org/mediawiki/index.php/Contributions:BCI2000RemoteNET here], and API documentation can be found [https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html here].<br />
<br />
We will now add the events relevant to the Cursor Task. Open the <code>GameControl.cs</code> script, and modify its <code>Awake()</code> to add the events <code>PreFeedback</code>, <code>Feedback</code>, <code>PostFeedback</code>, <code>TargetHit</code>, and <code>Timeout</code> with bit width 1. Additionally, add the events <code>TrialNumber</code>, <code>TargetPositionX</code>, and <code>TargetPositionY</code> with width 16. These will encode the task state and number of trials.<br />
We also need to set a parameter value so that the signal will be set to the mouse position. Using <code>BCI2000Remote.SetParameter()</code>, we will set the <code>ModulateAmplitude</code> parameter to 1.<br />
<br />
Open the <code>BallControl.cs</code> script, and within the <code>Awake()</code> function, add events <code>CursorPositionX</code> and <code>CursorPositionY</code>, with width 16. Show these events in a visualization window with <code>Visualize</code><br />
<br />
Your two scripts should now look like this: <br />
<pre><br />
>>> GameControl.cs <br />
...<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
remote.AddEvent("Feedback", 1);<br />
remote.AddEvent("PostFeedback", 1);<br />
remote.AddEvent("TargetHit", 1);<br />
remote.AddEvent("Timeout", 1);<br />
remote.AddEvent("TrialNumber", 16);<br />
remote.AddEvent("TargetPositionX", 16);<br />
remote.AddEvent("TargetPositionY", 16);<br />
remote.SetParameter("ModulateAmplitude", "1");<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
...<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("CursorPositionX", 16);<br />
remote.AddEvent("CursorPositionY", 16);<br />
});<br />
bci.OnConnected(remote => {<br />
remote.Visualize("CursorPositionX");<br />
remote.Visualize("CursorPositionY");<br />
}<br />
</pre><br />
<br />
===Reading the control signal===<br />
We will be using the control signal to control the cursor. Open the <code>MCursorControl.cs</code> script.<br />
<br />
The commented out section of the <code>GetPos()</code> method contains the code required to turn the control signal waveform coming from the Signal Source and Signal Processing modules into screen coordinates. <br />
Uncomment the commented part and delete the line <code>Ray r = camera.ScreenPointToRay(Input.MousePosition);</code>.<br />
Change the <code>double signalX = 0;</code> and <code>double signalY = 0;</code> to. <br />
<br />
Your <code>GetPos()</code> method should look like this:<br />
<pre><br />
Vector3 GetPos() {<br />
double signalX = bci.Control.GetSignal(1, bci.CurrentSampleOffset());<br />
double signalY = bci.Control.GetSignal(2, bci.CurrentSampleOffset());<br />
signalsX[signalIndex] = signalX;<br />
signalsY[signalIndex] = signalY;<br />
<br />
signalIndex = signalIndex + 1 >= rollingMaximumAmount ? 0 : signalIndex + 1;<br />
double max_x = signalsX.Max();<br />
double max_y = signalsY.Max();<br />
Ray r = camera.ScreenPointToRay(new Vector3((float) max_x * Screen.width, (float) max_y * Screen.height, 0));<br />
float p;<br />
if (!plane.Raycast(r, out p)) {<br />
throw new Exception("error casting ray to plane, invalid mouse position?");<br />
}<br />
return r.GetPoint(p);<br />
}<br />
</pre><br />
<br />
Note the use of the <code>UnityBCI2000.CurrentSampleOffset()</code> method. This is a special method which gets the offset into the current block such that the sample is exactly one block length later than when it was collected by the hardware. This is to normalize the latency between when the hardware collects the signal and the software receives the signal, due to how BCI2000 processes data in blocks.<br />
<br />
===Sending events back to BCI2000===<br />
<br />
The primary way to communicate game state back to BCI2000 is via the use of Events, which are integer values encoded alongside the signal data.<br />
<br />
We will send the events that we added in a previous section.<br />
<br />
First, we will send back the current position of the cursor. Within the <code>BallControl.cs</code> script, within the <code>Update()</code> method, immediately after <code>Move()</code> is called, set the <code>CursorPositionX</code> and <code>CursorPositionY</code> events. <br />
<br />
<pre><br />
>>> BallControl.cs<br />
void Update() {<br />
...<br />
if (isTrialRunning) {<br />
...<br />
Move();<br />
bci.Control.SetEvent("CursorPositionX", (uint) ((transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("CursorPositionY", (uint) ((transform.position.y + 4.5) * 1000));<br />
}<br />
...<br />
</pre><br />
<br />
Notice that we transform the value of the cursor's position. This is because events in BCI2000 are represented as unsigned integers, so, for example, the cursor's range of movement in the x axis, -7 to 7, would not be directly representable within a BCI2000 event, so we add 7 so it is positive, and multiply by 1000 so that we have a more precise measure of the cursor's position. The range of [-7,7] becomes [0,14000].<br />
<br />
<br />
We will also set the events corresponding to the game state within <code>GameControl.cs</code>. First we will set <code>PreFeedback</code>, <code>Feedback</code>, and <code>PostFeedback</code> to represent when the game is in these states. To do this, at the beginning and end of <code>PreTrial()</code>, <code>Trial()</code>, and <code>PostTrial()</code>, we will set the corresponding event values to 1 and 0, respectively.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
bci.Control.SetEvent("PreFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PreFeedback", 0);<br />
}<br />
IEnumerator Trial() {<br />
bci.Control.SetEvent("Feedback", 1);<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
}<br />
IEnumerator PostTrial() {<br />
bci.Control.SetEvent("PostFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PostFeedback", 0);<br />
}<br />
</pre><br />
<br />
We will also set the events which happen at the end of each trial. The <code>TargetHit</code> event is activated when the subject hits the target, and the <code>Timeout</code> event is activated when the subject runs out of time.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator Trial() {<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
if (lastTrialSucceeded) {<br />
bci.Control.PulseEvent("TargetHit", 1);<br />
} else {<br />
bci.Control.PulseEvent("Timeout", 1);<br />
}<br />
}<br />
<br />
Notice that we use <code>BCI2000Remote.PulseEvent()</code> rather than <code>BCI2000Remote.SetEvent()</code>. This results in the event being set to the value <code>1</code> for exactly one sample duration, then returning to zero.<br />
<br />
We will also record the position of the target. Similarly to the cursor, we will transform the target's coordinates to be a positive integer.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
...<br />
target.SetActive(true);<br />
bci.Control.SetEvent("TargetPositionX", (uint) ((target.transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("TargetPositionY", (uint) ((target.transform.position.y + 4.5) * 1000));<br />
...<br />
}<br />
</pre><br />
<br />
The last event we need to set is the trial number.<br />
<br />
<pre><br />
IEnumerator ControlLoop() {<br />
...<br />
while (IsContinue() && trials < n_trials) {<br />
bci.Control.SetEvent("TrialNumber", trials + 1);<br />
...<br />
}<br />
}<br />
</pre><br />
<br />
===Unity Player Settings===<br />
Additionally, due to how Unity detects changes in BCI2000 state, it must be allowed to run in the background.<br />
<br />
<pre style="color:red"><br />
In the Unity menu bar:<br />
Edit > Project Settings > Player > Resolution and Presentation<br />
Check the "Run In Background" box.<br />
</pre><br />
<br />
<br />
===Usage===<br />
<br />
Now, when the Unity application runs, BCI2000 will open and start collecting data.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=User_Tutorial:UnityBCI2000_Barebones&diff=11526User Tutorial:UnityBCI2000 Barebones2024-08-16T02:30:12Z<p>Tytbutler: Created page with "<pre style="color:red"> Red text blocks contain detailed instructions for the higher-level instructions preceding them. </pre> This tutorial goes over how to use BCI2000 as a logging service for an existing Unity project. For a more comprehensive tutorial on integrating Unity with BCI2000, see [User Tutorial:UnityBCI2000]. This tutorial will use a sample Unity project, the same as the full tutorial. ===Download Unity=== Download Unity Hub from [https://unity3d.com Uni..."</p>
<hr />
<div><pre style="color:red"><br />
Red text blocks contain detailed instructions for the higher-level instructions preceding them.<br />
</pre><br />
<br />
This tutorial goes over how to use BCI2000 as a logging service for an existing Unity project. For a more comprehensive tutorial on integrating Unity with BCI2000, see [User Tutorial:UnityBCI2000]. This tutorial will use a sample Unity project, the same as the full tutorial.<br />
<br />
===Download Unity===<br />
<br />
Download Unity Hub from [https://unity3d.com Unity].<br />
<br />
===Setting Up BCI2000===<br />
<br />
Follow the instructions starting with [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Install_Prerequisites] to download BCI2000. <br />
<br />
===Setting Up UnityBCI2000===<br />
Download UnityBCI2000 from its GitHub page, [https://github.com/neurotechcenter/UnityBCI2000]. <br />
<pre style="color:red"><br />
Click on the "Releases" section on the right side of the page. This tutorial is intended to be used with UnityBCI2000 version 2.0.0, so scroll to that release and click on the files BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to download them.<br />
</pre><br />
<br />
===Download Tutorial Project===<br />
Download the CursorTask3 repository from [https://github.com/Personator01/CursorTask3 GitHub].<br />
<pre style="color:red"><br />
Either:<br />
-Clone the git repository<br />
-Download the respository directly from GitHub<br />
-> Click the green "Code" button <br />
-> Select "Download ZIP"<br />
-> Extract the zip file<br />
</pre><br />
The download directory contains two versions of the CursorTask3 project. One, CursorTask3-BCI2K, contains an example implementation of the task with BCI2000 integration. The other, CursorTask3-NoBCI2K, contains the same task without BCI2000 integration. This tutorial is a step by step guide on turning that second project into the first. <br />
<br />
===Opening the project===<br />
Open the project in the Unity Editor, and open the CursorTask scene.<br />
<pre style="color:red"><br />
Open Unity Hub.<br />
Click the "Add" button in the top right corner.<br />
Navigate to the CursorTask3 directory downloaded previously.<br />
Select the CursorTask3-NoBCI2K directory to add it to Unity Hub.<br />
Click the CursorTask3-NoBCI2K project in the Unity Hub.<br />
If prompted to select a version of Unity to use or install, select Unity 2022.3. The specific release number of Unity 2022.3 should not matter, so select the one labeled "LTS" for consistency.<br />
The lower panel (the asset browser) should already show the Assets/Scenes directory, which contains a single scene called SampleScene.<br />
Double-click SampleScene. This should open a scene with a box containing various lights and objects.<br />
</pre><br />
If you wish to view the completed implementation, repeat these steps, but instead open the CursorTask3-BCI2K-Barebones directory. Note that in order to use the completed implementation, you will still need to set the Operator Path value of the UnityBCI2000 component of the BCI2000 game object.<br />
<br />
===Adding UnityBCI2000 to the project===<br />
Add BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to your project's assets.<br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click Assets > Open Containing Folder to open your project directory.<br />
Place the BCI2000RemoteNETStandard.dll and UnityBCI2000.cs files in the Assets folder.<br />
</pre><br />
<br />
Add an empty GameObject called 'BCI2000'. This will hold the scripts for controlling BCI2000. <br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click GameObject > Create Empty to create an empty GameObject, and name it 'BCI2000'. (The object's specific name does not actually matter, it is only needed in order to reference it within other scripts)<br />
You will notice that it now appears in the Scene Hierarchy panel, on the left side of the screen.<br />
</pre><br />
<br />
Add the UnityBCI2000 component to the object.<br />
<pre style="color:red"><br />
Click on the object in the Hierarchy panel. This will open it in the Inspector panel (the panel on the right side of the screen)<br />
In the inspector, below the new object's Transform component, click the "Add Component" button, which will open up a small window for adding components.<br />
Within this window, select Scripts > Unity BCI2000 to add the UnityBCI2000 component.<br />
</pre><br />
<br />
===Configuring UnityBCI2000===<br />
The inspector panel now contains the configuration options for UnityBCI2000. Set the options as follows:<br />
<br />
<code>Start Local Operator</code>: Checked<br />
<br />
This will start the operator on your computer when the Unity scene initializes. If we were instead connecting to an already-running instance of BCI2000, or an instance on another computer, this box would be deselected.<br />
<br />
<code>Operator Path</code>: The path to the Operator executable. This will look something like this on Windows (C://path/to/bci2000/prog/Operator.exe)<br />
<br />
<code>Operator Address</code>: 127.0.0.1<br />
<br />
This is the address of the machine on which BCI2000 is running. Since we are running BCI2000 on the same computer as Unity, we leave it as 127.0.0.1, the loopback address.<br />
<br />
<code>Operator Port</code>: 3999<br />
<br />
This is the port on which BCI2000 is listening for commands. By default, it is 3999.<br />
<br />
<code>Start Modules</code>: Checked<br />
<br />
This tells BCI2000 to start the requested Signal Source, Signal Processing, and Application modules when the Unity scene initializes. Similarly to Start Local Operator, we would deselect this box if connecting to an already-running instance. <br />
<br />
<code>Start With Scene</code>: Checked<br />
<br />
This tells BCI2000 to start a data collection run when the scene starts. Since we will be using BCI2000 itself to set experiment parameters, we will instead wait for BCI2000 to start from Unity, and thus will leave the box unchecked. <br />
<br />
<code>Stop With Scene</code>: Checked<br />
<br />
This tells BCI2000 to stop collecting data when the scene stops. Since we will be controlling BCI2000 directly, rather than entirely through Unity, we will leave this unchecked.<br />
<br />
<code>Shutdown With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to shut down alongside the Unity scene. Whether or not this value is set ultimately doesn't matter much, especially if Start Local Operator is checked. The data will be saved whether or not BCI2000 shuts down. <br />
<br />
<code>Module 1</code>: SignalGenerator<br />
<br />
The signal source module to start. We will use SignalGenerator, which generates a signal without any connected hardware.<br />
<br />
<code>Module 2</code>: DummySignalProcessing<br />
<br />
The signal processing module to start. We will use DummySignalProcessing, as there is no processing to do.<br />
<br />
<code>Module 3</code>: DummyApplication<br />
<br />
The Application module to start. Since we are using Unity, we will use DummyApplication.<br />
<br />
<br />
<br />
===Setting References===<br />
In order for the game's scripts to communicate with BCI2000, they need to hold a reference to the UnityBCI2000 component.<br />
There are three scripts which will need to communicate with BCI2000. They are <code>GameControl.cs, BallControl.cs, and MCursorControl.cs</code>.<br />
These scripts are each located within the Assets directory of the Unity project. <br />
<pre style="color:red"><br />
As before, select Assets > Open Containing Folder to open the project directory, then open the Assets folder. <br />
For each script, open it in a text editor.<br />
Add a data member of type UnityBCI2000 to the class, like so:<br />
UnityBCI2000 bci;<br />
Place the member definition above the Awake() method, for readability.<br />
Within the Awake() method, set this reference to the UnityBCI2000 component.<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
</pre><br />
Each of the three scripts should contain a section like this:<br />
<pre><br />
...<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
</pre><br />
<br />
===Adding Events===<br />
[https://www.bci2000.org/mediawiki/index.php/Programming_Reference:Events Events] are the primary way that non-signal experiment data is recorded in BCI2000. They are timestamped integer values which are encoded alongside the signal data in BCI2000 output files. Due to BCI2000's design, events must be added during a very specific part of its startup sequence, which is immediately after the BCI2000 operator starts, and before any of the modules start. As such, we cannot simply call <code>AddEvent()</code> whenever we want. Furthermore, the order in which Unity objects initialize is undefined, so it cannot even be guaranteed that calling <code>AddEvent</code> at a specific time will be consistent across multiple projects. As such, UnityBCI2000 provides a couple of methods for sending commands at well-defined points within the startup sequence. These two methods, <code>OnIdle</code> and <code>OnIdle</code> and <code>OnConnected</code> allow BCI2000 commands to be sent while the operator is in the state Idle (immediately before starting its modules) and when the operator is in the state Connected (after starting and connecting to the modules. Below is an example of using those methods to add and show an event in BCI2000.<br />
<br />
<pre><br />
class Script : MonoBehaviour {<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000Object").GetComponent<UnityBCI2000>();<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("AnEvent", 32);<br />
});<br />
}<br />
void Start() {<br />
bci.OnConnected(remote => {<br />
remote.Visualize("AnEvent");<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
As seen above, <code>OnIdle</code> and <code>OnConnected</code> take a delegate (C#'s term for a callback/closure/functor/etc.) with a single parameter of type <code>BCI2000Remote</code> (in this case called "remote"). The lambda expression given to the call to <code>OnIdle</code> uses the method <code>BCI2000Remote.AddEvent()</code> to add an event called "AnEvent" with a bit width of 32 bits. The call to <code>OnConnected</code> tells BCI2000 to show the event's value in a graphical window. A description of the BCI2000Remote class can be found [https://www.bci2000.org/mediawiki/index.php/Contributions:BCI2000RemoteNET here], and API documentation can be found [https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html here].<br />
<br />
We will now add the events relevant to the Cursor Task. Open the <code>GameControl.cs</code> script, and modify its <code>Awake()</code> to add the events <code>PreFeedback</code>, <code>Feedback</code>, <code>PostFeedback</code>, <code>TargetHit</code>, and <code>Timeout</code> with bit width 1. Additionally, add the events <code>TrialNumber</code>, <code>TargetPositionX</code>, and <code>TargetPositionY</code> with width 16. These will encode the task state and number of trials.<br />
We also need to set a parameter value so that the signal will be set to the mouse position. Using <code>BCI2000Remote.SetParameter()</code>, we will set the <code>ModulateAmplitude</code> parameter to 1.<br />
<br />
Open the <code>BallControl.cs</code> script, and within the <code>Awake()</code> function, add events <code>CursorPositionX</code> and <code>CursorPositionY</code>, with width 16. Show these events in a visualization window with <code>Visualize</code><br />
<br />
Your two scripts should now look like this: <br />
<pre><br />
>>> GameControl.cs <br />
...<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
remote.AddEvent("Feedback", 1);<br />
remote.AddEvent("PostFeedback", 1);<br />
remote.AddEvent("TargetHit", 1);<br />
remote.AddEvent("Timeout", 1);<br />
remote.AddEvent("TrialNumber", 16);<br />
remote.AddEvent("TargetPositionX", 16);<br />
remote.AddEvent("TargetPositionY", 16);<br />
remote.SetParameter("ModulateAmplitude", "1");<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
...<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("CursorPositionX", 16);<br />
remote.AddEvent("CursorPositionY", 16);<br />
});<br />
bci.OnConnected(remote => {<br />
remote.Visualize("CursorPositionX");<br />
remote.Visualize("CursorPositionY");<br />
}<br />
</pre><br />
<br />
===Reading the control signal===<br />
We will be using the control signal to control the cursor. Open the <code>MCursorControl.cs</code> script.<br />
<br />
The commented out section of the <code>GetPos()</code> method contains the code required to turn the control signal waveform coming from the Signal Source and Signal Processing modules into screen coordinates. <br />
Uncomment the commented part and delete the line <code>Ray r = camera.ScreenPointToRay(Input.MousePosition);</code>.<br />
Change the <code>double signalX = 0;</code> and <code>double signalY = 0;</code> to. <br />
<br />
Your <code>GetPos()</code> method should look like this:<br />
<pre><br />
Vector3 GetPos() {<br />
double signalX = bci.Control.GetSignal(1, bci.CurrentSampleOffset());<br />
double signalY = bci.Control.GetSignal(2, bci.CurrentSampleOffset());<br />
signalsX[signalIndex] = signalX;<br />
signalsY[signalIndex] = signalY;<br />
<br />
signalIndex = signalIndex + 1 >= rollingMaximumAmount ? 0 : signalIndex + 1;<br />
double max_x = signalsX.Max();<br />
double max_y = signalsY.Max();<br />
Ray r = camera.ScreenPointToRay(new Vector3((float) max_x * Screen.width, (float) max_y * Screen.height, 0));<br />
float p;<br />
if (!plane.Raycast(r, out p)) {<br />
throw new Exception("error casting ray to plane, invalid mouse position?");<br />
}<br />
return r.GetPoint(p);<br />
}<br />
</pre><br />
<br />
Note the use of the <code>UnityBCI2000.CurrentSampleOffset()</code> method. This is a special method which gets the offset into the current block such that the sample is exactly one block length later than when it was collected by the hardware. This is to normalize the latency between when the hardware collects the signal and the software receives the signal, due to how BCI2000 processes data in blocks.<br />
<br />
===Sending events back to BCI2000===<br />
<br />
The primary way to communicate game state back to BCI2000 is via the use of Events, which are integer values encoded alongside the signal data.<br />
<br />
We will send the events that we added in a previous section.<br />
<br />
First, we will send back the current position of the cursor. Within the <code>BallControl.cs</code> script, within the <code>Update()</code> method, immediately after <code>Move()</code> is called, set the <code>CursorPositionX</code> and <code>CursorPositionY</code> events. <br />
<br />
<pre><br />
>>> BallControl.cs<br />
void Update() {<br />
...<br />
if (isTrialRunning) {<br />
...<br />
Move();<br />
bci.Control.SetEvent("CursorPositionX", (uint) ((transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("CursorPositionY", (uint) ((transform.position.y + 4.5) * 1000));<br />
}<br />
...<br />
</pre><br />
<br />
Notice that we transform the value of the cursor's position. This is because events in BCI2000 are represented as unsigned integers, so, for example, the cursor's range of movement in the x axis, -7 to 7, would not be directly representable within a BCI2000 event, so we add 7 so it is positive, and multiply by 1000 so that we have a more precise measure of the cursor's position. The range of [-7,7] becomes [0,14000].<br />
<br />
<br />
We will also set the events corresponding to the game state within <code>GameControl.cs</code>. First we will set <code>PreFeedback</code>, <code>Feedback</code>, and <code>PostFeedback</code> to represent when the game is in these states. To do this, at the beginning and end of <code>PreTrial()</code>, <code>Trial()</code>, and <code>PostTrial()</code>, we will set the corresponding event values to 1 and 0, respectively.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
bci.Control.SetEvent("PreFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PreFeedback", 0);<br />
}<br />
IEnumerator Trial() {<br />
bci.Control.SetEvent("Feedback", 1);<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
}<br />
IEnumerator PostTrial() {<br />
bci.Control.SetEvent("PostFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PostFeedback", 0);<br />
}<br />
</pre><br />
<br />
We will also set the events which happen at the end of each trial. The <code>TargetHit</code> event is activated when the subject hits the target, and the <code>Timeout</code> event is activated when the subject runs out of time.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator Trial() {<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
if (lastTrialSucceeded) {<br />
bci.Control.PulseEvent("TargetHit", 1);<br />
} else {<br />
bci.Control.PulseEvent("Timeout", 1);<br />
}<br />
}<br />
<br />
Notice that we use <code>BCI2000Remote.PulseEvent()</code> rather than <code>BCI2000Remote.SetEvent()</code>. This results in the event being set to the value <code>1</code> for exactly one sample duration, then returning to zero.<br />
<br />
We will also record the position of the target. Similarly to the cursor, we will transform the target's coordinates to be a positive integer.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
...<br />
target.SetActive(true);<br />
bci.Control.SetEvent("TargetPositionX", (uint) ((target.transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("TargetPositionY", (uint) ((target.transform.position.y + 4.5) * 1000));<br />
...<br />
}<br />
</pre><br />
<br />
The last event we need to set is the trial number.<br />
<br />
<pre><br />
IEnumerator ControlLoop() {<br />
...<br />
while (IsContinue() && trials < n_trials) {<br />
bci.Control.SetEvent("TrialNumber", trials + 1);<br />
...<br />
}<br />
}<br />
</pre><br />
<br />
===Unity Player Settings===<br />
Additionally, due to how Unity detects changes in BCI2000 state, it must be allowed to run in the background.<br />
<br />
<pre style="color:red"><br />
In the Unity menu bar:<br />
Edit > Project Settings > Player > Resolution and Presentation<br />
Check the "Run In Background" box.<br />
</pre><br />
<br />
<br />
===Usage===<br />
<br />
Now, when the Unity application runs, BCI2000 will open and start collecting data.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=User_Tutorial:UnityBCI2000&diff=11520User Tutorial:UnityBCI20002024-08-15T16:02:06Z<p>Tytbutler: </p>
<hr />
<div><pre style="color:red"><br />
Red text blocks contain detailed instructions for the higher-level instructions preceding them.<br />
</pre><br />
<br />
This example comprehensively demonstrates many of the capabilities of UnityBCI2000, and as such, is more than what is necessary for many usecases. If you just want to use BCI2000 as a logging backend for an existing Unity application, see the Barebones UnityBCI2000 tutorial.<br />
<br />
===Download Unity===<br />
<br />
Download Unity Hub from [https://unity3d.com Unity].<br />
<br />
===Setting Up BCI2000===<br />
<br />
Follow the instructions starting with [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Install_Prerequisites] to download BCI2000. <br />
<br />
===Setting Up UnityBCI2000===<br />
Download UnityBCI2000 from its GitHub page, [https://github.com/neurotechcenter/UnityBCI2000]. <br />
<pre style="color:red"><br />
Click on the "Releases" section on the right side of the page. This tutorial is intended to be used with UnityBCI2000 version 2.0.0, so scroll to that release and click on the files BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to download them.<br />
</pre><br />
<br />
===Download Tutorial Project===<br />
Download the CursorTask3 repository from [https://github.com/Personator01/CursorTask3 GitHub].<br />
<pre style="color:red"><br />
Either:<br />
-Clone the git repository<br />
-Download the respository directly from GitHub<br />
-> Click the green "Code" button <br />
-> Select "Download ZIP"<br />
-> Extract the zip file<br />
</pre><br />
The download directory contains two versions of the CursorTask3 project. One, CursorTask3-BCI2K, contains an example implementation of the task with BCI2000 integration. The other, CursorTask3-NoBCI2K, contains the same task without BCI2000 integration. This tutorial is a step by step guide on turning that second project into the first. <br />
<br />
===Opening the project===<br />
Open the project in the Unity Editor, and open the CursorTask scene.<br />
<pre style="color:red"><br />
Open Unity Hub.<br />
Click the "Add" button in the top right corner.<br />
Navigate to the CursorTask3 directory downloaded previously.<br />
Select the CursorTask3-NoBCI2K directory to add it to Unity Hub.<br />
Click the CursorTask3-NoBCI2K project in the Unity Hub.<br />
If prompted to select a version of Unity to use or install, select Unity 2022.3. The specific release number of Unity 2022.3 should not matter, so select the one labeled "LTS" for consistency.<br />
The lower panel (the asset browser) should already show the Assets/Scenes directory, which contains a single scene called SampleScene.<br />
Double-click SampleScene. This should open a scene with a box containing various lights and objects.<br />
</pre><br />
If you wish to view the completed implementation, repeat these steps, but instead open the CursorTask3-BCI2K directory. Note that in order to use the completed implementation, you will still need to set the Operator Path value of the UnityBCI2000 component of the BCI2000 game object.<br />
<br />
===Adding UnityBCI2000 to the project===<br />
Add BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to your project's assets.<br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click Assets > Open Containing Folder to open your project directory.<br />
Place the BCI2000RemoteNETStandard.dll and UnityBCI2000.cs files in the Assets folder.<br />
</pre><br />
<br />
Add an empty GameObject called 'BCI2000'. This will hold the scripts for controlling BCI2000. <br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click GameObject > Create Empty to create an empty GameObject, and name it 'BCI2000'. (The object's specific name does not actually matter, it is only needed in order to reference it within other scripts)<br />
You will notice that it now appears in the Scene Hierarchy panel, on the left side of the screen.<br />
</pre><br />
<br />
Add the UnityBCI2000 component to the object.<br />
<pre style="color:red"><br />
Click on the object in the Hierarchy panel. This will open it in the Inspector panel (the panel on the right side of the screen)<br />
In the inspector, below the new object's Transform component, click the "Add Component" button, which will open up a small window for adding components.<br />
Within this window, select Scripts > Unity BCI2000 to add the UnityBCI2000 component.<br />
</pre><br />
<br />
===Configuring UnityBCI2000===<br />
The inspector panel now contains the configuration options for UnityBCI2000. Set the options as follows:<br />
<br />
<code>Start Local Operator</code>: Checked<br />
<br />
This will start the operator on your computer when the Unity scene initializes. If we were instead connecting to an already-running instance of BCI2000, or an instance on another computer, this box would be deselected.<br />
<br />
<code>Operator Path</code>: The path to the Operator executable. This will look something like this on Windows (C://path/to/bci2000/prog/Operator.exe)<br />
<br />
<code>Operator Address</code>: 127.0.0.1<br />
<br />
This is the address of the machine on which BCI2000 is running. Since we are running BCI2000 on the same computer as Unity, we leave it as 127.0.0.1, the loopback address.<br />
<br />
<code>Operator Port</code>: 3999<br />
<br />
This is the port on which BCI2000 is listening for commands. By default, it is 3999.<br />
<br />
<code>Start Modules</code>: Checked<br />
<br />
This tells BCI2000 to start the requested Signal Source, Signal Processing, and Application modules when the Unity scene initializes. Similarly to Start Local Operator, we would deselect this box if connecting to an already-running instance. <br />
<br />
<code>Start With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to start a data collection run when the scene starts. Since we will be using BCI2000 itself to set experiment parameters, we will instead wait for BCI2000 to start from Unity, and thus will leave the box unchecked. <br />
<br />
<code>Stop With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to stop collecting data when the scene stops. Since we will be controlling BCI2000 directly, rather than entirely through Unity, we will leave this unchecked.<br />
<br />
<code>Shutdown With Scene</code>: Unchecked<br />
<br />
This tells BCI2000 to shut down alongside the Unity scene. Whether or not this value is set ultimately doesn't matter much, especially if Start Local Operator is checked. The data will be saved whether or not BCI2000 shuts down. <br />
<br />
===Setting References===<br />
In order for the game's scripts to communicate with BCI2000, they need to hold a reference to the UnityBCI2000 component.<br />
There are three scripts which will need to communicate with BCI2000. They are <code>GameControl.cs, BallControl.cs, and MCursorControl.cs</code>.<br />
These scripts are each located within the Assets directory of the Unity project. <br />
<pre style="color:red"><br />
As before, select Assets > Open Containing Folder to open the project directory, then open the Assets folder. <br />
For each script, open it in a text editor.<br />
Add a data member of type UnityBCI2000 to the class, like so:<br />
UnityBCI2000 bci;<br />
Place the member definition above the Awake() method, for readability.<br />
Within the Awake() method, set this reference to the UnityBCI2000 component.<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
</pre><br />
Each of the three scripts should contain a section like this:<br />
<pre><br />
...<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
</pre><br />
<br />
===Adding Events===<br />
[https://www.bci2000.org/mediawiki/index.php/Programming_Reference:Events Events] are the primary way that non-signal experiment data is recorded in BCI2000. They are timestamped integer values which are encoded alongside the signal data in BCI2000 output files. Due to BCI2000's design, events must be added during a very specific part of its startup sequence, which is immediately after the BCI2000 operator starts, and before any of the modules start. As such, we cannot simply call <code>AddEvent()</code> whenever we want. Furthermore, the order in which Unity objects initialize is undefined, so it cannot even be guaranteed that calling <code>AddEvent</code> at a specific time will be consistent across multiple projects. As such, UnityBCI2000 provides a couple of methods for sending commands at well-defined points within the startup sequence. These two methods, <code>OnIdle</code> and <code>OnIdle</code> and <code>OnConnected</code> allow BCI2000 commands to be sent while the operator is in the state Idle (immediately before starting its modules) and when the operator is in the state Connected (after starting and connecting to the modules. Below is an example of using those methods to add and show an event in BCI2000.<br />
<br />
<pre><br />
class Script : MonoBehaviour {<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000Object").GetComponent<UnityBCI2000>();<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("AnEvent", 32);<br />
});<br />
}<br />
void Start() {<br />
bci.OnConnected(remote => {<br />
remote.Visualize("AnEvent");<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
As seen above, <code>OnIdle</code> and <code>OnConnected</code> take a delegate (C#'s term for a callback/closure/functor/etc.) with a single parameter of type <code>BCI2000Remote</code> (in this case called "remote"). The lambda expression given to the call to <code>OnIdle</code> uses the method <code>BCI2000Remote.AddEvent()</code> to add an event called "AnEvent" with a bit width of 32 bits. The call to <code>OnConnected</code> tells BCI2000 to show the event's value in a graphical window. A description of the BCI2000Remote class can be found [https://www.bci2000.org/mediawiki/index.php/Contributions:BCI2000RemoteNET here], and API documentation can be found [https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html here].<br />
<br />
We will now add the events relevant to the Cursor Task. Open the <code>GameControl.cs</code> script, and modify its <code>Awake()</code> to add the events <code>PreFeedback</code>, <code>Feedback</code>, <code>PostFeedback</code>, <code>TargetHit</code>, and <code>Timeout</code> with bit width 1. Additionally, add the events <code>TrialNumber</code>, <code>TargetPositionX</code>, and <code>TargetPositionY</code> with width 16. These will encode the task state and number of trials.<br />
<br />
Open the <code>BallControl.cs</code> script, and within the <code>Awake()</code> function, add events <code>CursorPositionX</code> and <code>CursorPositionY</code>, with width 16. Show these events in a visualization window with <code>Visualize</code><br />
<br />
Your two scripts should now look like this: <br />
<pre><br />
>>> GameControl.cs <br />
...<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
remote.AddEvent("Feedback", 1);<br />
remote.AddEvent("PostFeedback", 1);<br />
remote.AddEvent("TargetHit", 1);<br />
remote.AddEvent("Timeout", 1);<br />
remote.AddEvent("TrialNumber", 16);<br />
remote.AddEvent("TargetPositionX", 16);<br />
remote.AddEvent("TargetPositionY", 16);<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
...<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("CursorPositionX", 16);<br />
remote.AddEvent("CursorPositionY", 16);<br />
});<br />
bci.OnConnected(remote => {<br />
remote.Visualize("CursorPositionX");<br />
remote.Visualize("CursorPositionY");<br />
}<br />
</pre><br />
<br />
<br />
<br />
===Using BCI2000 Parameters===<br />
====Adding Parameters====<br />
BCI2000's operator contains an interface for changing experiment parameters before running a task. By making use of this interface we can change the behavior of the task dynamically, without needing to rebuild the Unity project each time. In order to do this we need to define the parameters and add them to BCI2000, and later read their values after the operator has a chance to change them. <span style="color: red">This section is not strictly necessary. The project will function the same whether this is done or not, just without the option to change parameters at runtime. </span> <br />
<br />
First, we define add parameters to BCI2000. Similarly to events, parameters must be added while the Operator is in the <code>Idle</code> state, so we add them inside of <code>OnIdle</code>, like below:<br />
<pre><br />
public int someParameter = 5;<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddParameter("Application:ParameterPlace", "SomeParameter", someParameter.ToString()); <br />
});<br />
}<br />
<br />
The first argument to the method is the section into which the parameter is placed, that is, on which tab and under which heading the parameter will appear within the Operator's parameter editor window (note that the section is not a scope, all parameter names must be unique). The second argument is the parameter name itself. The third argument is the default value of the parameter. We pass in the value of the parameter, so when it appears in the Operator, its default value is 5 (or another value if it has been changed in the Unity Editor). Note that all parameters are handled as strings, so we need to convert its value to a string when sending it.<br />
<br />
For <code>GameControl.cs</code>, we will add parameters corresponding to the Pre-Feedback, Feedback, and Post-Feedback durations, Target Radius, and Number of Trials.<br />
For <code>BallControl.cs</code>, we will add parameters corresponding to the Acceleration Scale, Coefficient of Restitution, Coefficient of Drag, and Attraction Curve Coefficient (how quickly the Ball moves to follow the Mouse Cursor).<br />
For <code>MCursorControl.cs</code>, we will add a parameter corresponding to the Rolling Maximum Amount.<br />
<br />
Your scripts should look like this:<br />
<pre><br />
>>> GameControl.cs<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
...<br />
<br />
remote.AddParameter("Application:Task", "PreFeedbackDuration", preFeedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "FeedbackDuration", feedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "PostFeedbackDuration", postFeedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "TargetRadius", targetRadius.ToString());<br />
remote.AddParameter("Application:Task", "Trials", n_trials.ToString());<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddParameter("Application:Physics", "AccelerationScale", accelerationScale.ToString());<br />
remote.AddParameter("Application:Physics", "CoeffOfRestitution", coefficientOfRestitution.ToString());<br />
remote.AddParameter("Application:Physics", "CoeffOfDrag", coefficientOfDrag.ToString());<br />
remote.AddParameter("Application:Physics", "AccelerationCurve", attractionCurveCoefficient.ToString());<br />
})}<br />
}<br />
<br />
>>> MCursorControl.cs<br />
void Awake() {<br />
...<br />
<br />
bci.OnIdle(remote => {<br />
AddParameter("Application:Physics", "RollingMaximumAmount", rollingMaximumAmount.ToString());<br />
});<br />
}<br />
<br />
<br />
====Reading and Validating Parameters====<br />
Since we set the parameters within the BCI2000 operator, we need some way to read them back into Unity after they have been set. Specifically, we need to read them after the operator clicks the "Set Config" button within the BCI2000 Operator. How this timing synchronization is covered in the section [[Reacting to BCI2000 state changes]]. In this section we will cover reading and validating parameters.<br />
<br />
A method called <code>SetConfig</code> is provided in each of the scripts in which we added parameters previously. This method will be called after the operator changes parameters. In this method we will read in parameters and parse them into valid values. Using the same example parameter as before:<br />
<pre><br />
void SetConfig() {<br />
try {<br />
someParameter = int.Parse(bci.Control.GetParameter("SomeParameter"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse parameter SomeParameter as int");<br />
throw e;<br />
}<br />
}<br />
</pre><br />
<br />
Note that since we are now working outside the BCI2000 startup sequence, we use <code>UnityBCI2000.Control</code> to call <code>BCI2000Remote</code> methods directly, rather than using <code>OnIdle</code> or <code>OnConnected</code>. We also wrap the call within a try/catch block so that we can report erroneous parameters back to the operator. This is optional, but it keeps your project from failing silently and is otherwise useful for doing things like distributing your Unity project as a standalone executable, where logging errors can only be done through the BCI2000 operator. You can also write a helper function which handles parsing and error reporting for you:<br />
<br />
<pre><br />
int GetParseParameterInt(string paramName) {<br />
int p_val = bci.Control.GetParameter("SomeParameter");<br />
try {<br />
someParameter = int.Parse(p_val);<br />
} catch (FormatException e) {<br />
bci.Error($"Could not parse parameter {paramName} (value {p_val}) as int");<br />
throw e;<br />
}<br />
}<br />
</pre><br />
Unfortunately, since the version of C# used by Unity does not support type-parameterized parsing, you must write one of these helper functions for each type of data you want to store in a parameter (int, float, double, etc.)<br />
<br />
<br />
Read back the parameters added in the previous step. Your scripts should look like this:<br />
<br />
<pre><br />
>>> GameControl.cs <br />
void SetConfig() {<br />
try {<br />
preFeedbackDuration = float.Parse(bci.Control.GetParameter("PreFeedbackDuration"));<br />
feedbackDuration = float.Parse(bci.Control.GetParameter("FeedbackDuration"));<br />
postFeedbackDuration = float.Parse(bci.Control.GetParameter("PostFeedbackDuration"));<br />
targetRadius = float.Parse(bci.Control.GetParameter("TargetRadius"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse one of PreFeedbackDuration, FeedbackDuration, PostFeedbackDuration, or TargetRadius as a float");<br />
throw e;<br />
}<br />
try {<br />
n_trials = int.Parse(bci.Control.GetParameter("Trials"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse Trials as an int");<br />
throw e;<br />
}<br />
<br />
if (preFeedbackDuration < COUNTDOWN_DURATION) {<br />
bci.Error("preFeedbackDuration must be greater than or equal to 2.25");<br />
throw new Exception("preFeedbackDuration must be greater than or equal to 2.25");<br />
}<br />
}<br />
<br />
>>> BallControl.cs<br />
public void SetConfig() {<br />
try {<br />
accelerationScale = float.Parse(bci.Control.GetParameter("AccelerationScale"));<br />
coefficientOfRestitution = float.Parse(bci.Control.GetParameter("CoeffOfRestitution"));<br />
coefficientOfDrag = float.Parse(bci.Control.GetParameter("CoeffOfDrag"));<br />
attractionCurveCoefficient = float.Parse(bci.Control.GetParameter("AccelerationCurve"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse one of AccelerationScale, CoeffOfRestitution, CoeffOfDrag, AccelerationCurve as float");<br />
throw e;<br />
}<br />
}<br />
<br />
>>> MCursorControl.cs<br />
public void SetConfig() {<br />
try {<br />
rollingMaximumAmount = int.Parse(bci.Control.GetParameter("RollingMaximumAmount"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse parameter RollingMaximumAmount as int");<br />
throw e;<br />
}<br />
signalsX = new int[rollingMaximumAmount];<br />
signalsY = new int[rollingMaximumAmount];<br />
}<br />
</pre><br />
<br />
Note that in <code>GameControl.cs</code>, we also verify that the Pre-Feedback Duration is longer than the duration of the countdown that happens before each trial, and report errors to BCI2000 accordingly.<br />
<br />
<br />
===Reacting to BCI2000 state changes===<br />
Since we will be controlling the Unity task from BCI2000, we need some way to wait for BCI2000 to be in a specific state, for example, waiting for the operator to click Start and put the Operator Module into the Running state. UnityBCI2000 provides a method for this, the <code>UnityBCI2000.PollSystemState</code> method. In order to wait for the Operator Module to be in the <code>Running</code> state:<br />
<pre><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Running));<br />
</pre><br />
This will check once per frame whether or not the Operator is in the <code>Running</code> state, and only continue once BCI2000 is in the <code>Running</code> state. Note that since <code>SystemState</code> is a member of <code>BCI2000Remote</code>, we also need to add a <code>using BCI2000RemoteNET</code> statement to our script.<br />
<br />
In our case, we need to react to the operator setting the parameters, starting the data collection, and stopping the data collection. These correspond to the Operator Module entering the <code>Resting</code> state, entering the <code>Running</code> state, and exiting the <code>Running</code> state.<br />
<br />
In the <code>GameControl.cs</code> script, we will wait for the system to be in the <code>Resting</code> state at the start of the <code>ControLoop</code> method, and wait for the system to be in the <code>Running</code> state immediately before the entering the trial loop. <br />
<pre><br />
>>> GameControl.cs<br />
<br />
IEnumerator ControlLoop() {<br />
while (True) {<br />
<pre style="color: red"><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Resting));<br />
</pre><br />
<br />
try {<br />
...<br />
} catch (Exception e) {<br />
continue;<br />
}<br />
<br />
int trials = 0;<br />
<br />
</pre><br />
<pre style="color: red"><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Running));<br />
</pre><br />
<br />
yield return new WaitForSeconds(preRunDuration);<br />
while (IsContinue() && trials < n_trials) {<br />
...<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
We also need to check for the operator stopping data collection, so we modify the <code>IsContinue()</code> method.<br />
<br />
<pre><br />
bool IsContinue () {<br />
return bci.Control.GetSystemState() == BCI2000Remote.SystemState.Running;<br />
}<br />
</pre><br />
<br />
Remember to add <code>using BCI2000RemoteNET;</code> to the top of the script, so you can access the <code>SystemState</code> enum.<br />
<br />
===Reading the control signal===<br />
We will be using the control signal to control the cursor. Open the <code>MCursorControl.cs</code> script.<br />
<br />
The commented out section of the <code>GetPos()</code> method contains the code required to turn the control signal waveform coming from the Signal Source and Signal Processing modules into screen coordinates. <br />
Uncomment the commented part and delete the line <code>Ray r = camera.ScreenPointToRay(Input.MousePosition);</code>.<br />
Change the <code>double signalX = 0;</code> and <code>double signalY = 0;</code> to. <br />
<br />
Your <code>GetPos()</code> method should look like this:<br />
<pre><br />
Vector3 GetPos() {<br />
double signalX = bci.Control.GetSignal(1, bci.CurrentSampleOffset());<br />
double signalY = bci.Control.GetSignal(2, bci.CurrentSampleOffset());<br />
signalsX[signalIndex] = signalX;<br />
signalsY[signalIndex] = signalY;<br />
<br />
signalIndex = signalIndex + 1 >= rollingMaximumAmount ? 0 : signalIndex + 1;<br />
double max_x = signalsX.Max();<br />
double max_y = signalsY.Max();<br />
Ray r = camera.ScreenPointToRay(new Vector3((float) max_x * Screen.width, (float) max_y * Screen.height, 0));<br />
float p;<br />
if (!plane.Raycast(r, out p)) {<br />
throw new Exception("error casting ray to plane, invalid mouse position?");<br />
}<br />
return r.GetPoint(p);<br />
}<br />
</pre><br />
<br />
Note the use of the <code>UnityBCI2000.CurrentSampleOffset()</code> method. This is a special method which gets the offset into the current block such that the sample is exactly one block length later than when it was collected by the hardware. This is to normalize the latency between when the hardware collects the signal and the software receives the signal, due to how BCI2000 processes data in blocks.<br />
<br />
===Sending events back to BCI2000===<br />
<br />
The primary way to communicate game state back to BCI2000 is via the use of Events, which are integer values encoded alongside the signal data.<br />
<br />
We will send the events that we added in a previous section.<br />
<br />
First, we will send back the current position of the cursor. Within the <code>BallControl.cs</code> script, within the <code>Update()</code> method, immediately after <code>Move()</code> is called, set the <code>CursorPositionX</code> and <code>CursorPositionY</code> events. <br />
<br />
<pre><br />
>>> BallControl.cs<br />
void Update() {<br />
...<br />
if (isTrialRunning) {<br />
...<br />
Move();<br />
bci.Control.SetEvent("CursorPositionX", (uint) ((transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("CursorPositionY", (uint) ((transform.position.y + 4.5) * 1000));<br />
}<br />
...<br />
</pre><br />
<br />
Notice that we transform the value of the cursor's position. This is because events in BCI2000 are represented as unsigned integers, so, for example, the cursor's range of movement in the x axis, -7 to 7, would not be directly representable within a BCI2000 event, so we add 7 so it is positive, and multiply by 1000 so that we have a more precise measure of the cursor's position. The range of [-7,7] becomes [0,14000].<br />
<br />
<br />
We will also set the events corresponding to the game state within <code>GameControl.cs</code>. First we will set <code>PreFeedback</code>, <code>Feedback</code>, and <code>PostFeedback</code> to represent when the game is in these states. To do this, at the beginning and end of <code>PreTrial()</code>, <code>Trial()</code>, and <code>PostTrial()</code>, we will set the corresponding event values to 1 and 0, respectively.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
bci.Control.SetEvent("PreFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PreFeedback", 0);<br />
}<br />
IEnumerator Trial() {<br />
bci.Control.SetEvent("Feedback", 1);<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
}<br />
IEnumerator PostTrial() {<br />
bci.Control.SetEvent("PostFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PostFeedback", 0);<br />
}<br />
</pre><br />
<br />
We will also set the events which happen at the end of each trial. The <code>TargetHit</code> event is activated when the subject hits the target, and the <code>Timeout</code> event is activated when the subject runs out of time.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator Trial() {<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
if (lastTrialSucceeded) {<br />
bci.Control.PulseEvent("TargetHit", 1);<br />
} else {<br />
bci.Control.PulseEvent("Timeout", 1);<br />
}<br />
}<br />
<br />
Notice that we use <code>BCI2000Remote.PulseEvent()</code> rather than <code>BCI2000Remote.SetEvent()</code>. This results in the event being set to the value <code>1</code> for exactly one sample duration, then returning to zero.<br />
<br />
We will also record the position of the target. Similarly to the cursor, we will transform the target's coordinates to be a positive integer.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
...<br />
target.SetActive(true);<br />
bci.Control.SetEvent("TargetPositionX", (uint) ((target.transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("TargetPositionY", (uint) ((target.transform.position.y + 4.5) * 1000));<br />
...<br />
}<br />
</pre><br />
<br />
The last event we need to set is the trial number.<br />
<br />
<pre><br />
IEnumerator ControlLoop() {<br />
...<br />
while (IsContinue() && trials < n_trials) {<br />
bci.Control.SetEvent("TrialNumber", trials + 1);<br />
...<br />
}<br />
}<br />
<br />
===Unity Player Settings===<br />
Additionally, due to how Unity detects changes in BCI2000 state, it must be allowed to run in the background.<br />
<br />
<pre style="color:red"><br />
In the Unity menu bar:<br />
Edit > Project Settings > Player > Resolution and Presentation<br />
Check the "Run In Background" box.<br />
</pre><br />
<br />
<br />
===Usage===<br />
<br />
Now, when the Unity application runs, BCI2000 will open. From here, parameters can be set via the Config window, then clicking Set Config and Start will start data collection.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=User_Tutorial:UnityBCI2000&diff=11519User Tutorial:UnityBCI20002024-08-15T01:34:18Z<p>Tytbutler: Added last parts</p>
<hr />
<div><pre style="color:red"><br />
Red text blocks contain detailed instructions for the higher-level instructions preceding them.<br />
</pre><br />
<br />
This example comprehensively demonstrates many of the capabilities of UnityBCI2000, and as such, is more than what is necessary for many usecases. If you just want to use BCI2000 as a logging backend for an existing Unity application, see the Barebones UnityBCI2000 tutorial.<br />
<br />
===Download Unity===<br />
<br />
Download Unity Hub from [https://unity3d.com Unity].<br />
<br />
===Setting Up BCI2000===<br />
<br />
Follow the instructions starting with [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Install_Prerequisites] to download BCI2000. <br />
<br />
===Setting Up UnityBCI2000===<br />
Download UnityBCI2000 from its GitHub page, [https://github.com/neurotechcenter/UnityBCI2000]. <br />
<pre style="color:red"><br />
Click on the "Releases" section on the right side of the page. This tutorial is intended to be used with UnityBCI2000 version 2.0.0, so scroll to that release and click on the files BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to download them.<br />
</pre><br />
<br />
===Download Tutorial Project===<br />
Download the CursorTask3 repository from [https://github.com/Personator01/CursorTask3 GitHub].<br />
<pre style="color:red"><br />
Either:<br />
-Clone the git repository<br />
-Download the respository directly from GitHub<br />
-> Click the green "Code" button <br />
-> Select "Download ZIP"<br />
-> Extract the zip file<br />
</pre><br />
The download directory contains two versions of the CursorTask3 project. One, CursorTask3-BCI2K, contains an example implementation of the task with BCI2000 integration. The other, CursorTask3-NoBCI2K, contains the same task without BCI2000 integration. This tutorial is a step by step guide on turning that second project into the first. <br />
<br />
===Opening the project===<br />
Open the project in the Unity Editor, and open the CursorTask scene.<br />
<pre style="color:red"><br />
Open Unity Hub.<br />
Click the "Add" button in the top right corner.<br />
Navigate to the CursorTask3 directory downloaded previously.<br />
Select the CursorTask3-NoBCI2K directory to add it to Unity Hub.<br />
Click the CursorTask3-NoBCI2K project in the Unity Hub.<br />
If prompted to select a version of Unity to use or install, select Unity 2022.3. The specific release number of Unity 2022.3 should not matter, so select the one labeled "LTS" for consistency.<br />
The lower panel (the asset browser) should already show the Assets/Scenes directory, which contains a single scene called SampleScene.<br />
Double-click SampleScene. This should open a scene with a box containing various lights and objects.<br />
</pre><br />
If you wish to view the completed implementation, repeat these steps, but instead open the CursorTask3-BCI2K directory. Note that in order to use the completed implementation, you will still need to set the Operator Path value of the UnityBCI2000 component of the BCI2000 game object.<br />
<br />
===Adding UnityBCI2000 to the project===<br />
Add BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to your project's assets.<br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click Assets > Open Containing Folder to open your project directory.<br />
Place the BCI2000RemoteNETStandard.dll and UnityBCI2000.cs files in the Assets folder.<br />
</pre><br />
<br />
Add an empty GameObject called 'BCI2000'. This will hold the scripts for controlling BCI2000. <br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click GameObject > Create Empty to create an empty GameObject, and name it 'BCI2000'. (The object's specific name does not actually matter, it is only needed in order to reference it within other scripts)<br />
You will notice that it now appears in the Scene Hierarchy panel, on the left side of the screen.<br />
</pre><br />
<br />
Add the UnityBCI2000 component to the object.<br />
<pre style="color:red"><br />
Click on the object in the Hierarchy panel. This will open it in the Inspector panel (the panel on the right side of the screen)<br />
In the inspector, below the new object's Transform component, click the "Add Component" button, which will open up a small window for adding components.<br />
Within this window, select Scripts > Unity BCI2000 to add the UnityBCI2000 component.<br />
</pre><br />
<br />
===Configuring UnityBCI2000===<br />
The inspector panel now contains the configuration options for UnityBCI2000. Set the options as follows:<br />
<br />
<code>Start Local Operator</code>: Checked<br />
This will start the operator on your computer when the Unity scene initializes. If we were instead connecting to an already-running instance of BCI2000, or an instance on another computer, this box would be deselected.<br />
<br />
<code>Operator Path</code>: The path to the Operator executable. This will look something like this on Windows (C://path/to/bci2000/prog/Operator.exe)<br />
<br />
<code>Operator Address</code>: 127.0.0.1<br />
This is the address of the machine on which BCI2000 is running. Since we are running BCI2000 on the same computer as Unity, we leave it as 127.0.0.1, the loopback address.<br />
<br />
<code>Operator Port</code>: 3999<br />
This is the port on which BCI2000 is listening for commands. By default, it is 3999.<br />
<br />
<code>Start Modules</code>: Checked<br />
This tells BCI2000 to start the requested Signal Source, Signal Processing, and Application modules when the Unity scene initializes. Similarly to Start Local Operator, we would deselect this box if connecting to an already-running instance. <br />
<br />
<code>Start With Scene</code>: Unchecked<br />
This tells BCI2000 to start a data collection run when the scene starts. Since we will be using BCI2000 itself to set experiment parameters, we will instead wait for BCI2000 to start from Unity, and thus will leave the box unchecked. <br />
<br />
<code>Stop With Scene</code>: Unchecked<br />
This tells BCI2000 to stop collecting data when the scene stops. Since we will be controlling BCI2000 directly, rather than entirely through Unity, we will leave this unchecked.<br />
<br />
<code>Shutdown With Scene</code>: Unchecked<br />
This tells BCI2000 to shut down alongside the Unity scene. Whether or not this value is set ultimately doesn't matter much, especially if Start Local Operator is checked. The data will be saved whether or not BCI2000 shuts down. <br />
<br />
===Setting References===<br />
In order for the game's scripts to communicate with BCI2000, they need to hold a reference to the UnityBCI2000 component.<br />
There are three scripts which will need to communicate with BCI2000. They are <code>GameControl.cs, BallControl.cs, and MCursorControl.cs</code>.<br />
These scripts are each located within the Assets directory of the Unity project. <br />
<pre style="color:red"><br />
As before, select Assets > Open Containing Folder to open the project directory, then open the Assets folder. <br />
For each script, open it in a text editor.<br />
Add a data member of type UnityBCI2000 to the class, like so:<br />
UnityBCI2000 bci;<br />
Place the member definition above the Awake() method, for readability.<br />
Within the Awake() method, set this reference to the UnityBCI2000 component.<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
</pre><br />
Each of the three scripts should contain a section like this:<br />
<pre><br />
...<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
</pre><br />
<br />
===Adding Events===<br />
[https://www.bci2000.org/mediawiki/index.php/Programming_Reference:Events Events] are the primary way that non-signal experiment data is recorded in BCI2000. They are timestamped integer values which are encoded alongside the signal data in BCI2000 output files. Due to BCI2000's design, events must be added during a very specific part of its startup sequence, which is immediately after the BCI2000 operator starts, and before any of the modules start. As such, we cannot simply call <code>AddEvent()</code> whenever we want. Furthermore, the order in which Unity objects initialize is undefined, so it cannot even be guaranteed that calling <code>AddEvent</code> at a specific time will be consistent across multiple projects. As such, UnityBCI2000 provides a couple of methods for sending commands at well-defined points within the startup sequence. These two methods, <code>OnIdle</code> and <code>OnIdle</code> and <code>OnConnected</code> allow BCI2000 commands to be sent while the operator is in the state Idle (immediately before starting its modules) and when the operator is in the state Connected (after starting and connecting to the modules. Below is an example of using those methods to add and show an event in BCI2000.<br />
<br />
<pre><br />
class Script : MonoBehaviour {<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000Object").GetComponent<UnityBCI2000>();<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("AnEvent", 32);<br />
});<br />
}<br />
void Start() {<br />
bci.OnConnected(remote => {<br />
remote.Visualize("AnEvent");<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
As seen above, <code>OnIdle</code> and <code>OnConnected</code> take a delegate (C#'s term for a callback/closure/functor/etc.) with a single parameter of type <code>BCI2000Remote</code> (in this case called "remote"). The lambda expression given to the call to <code>OnIdle</code> uses the method <code>BCI2000Remote.AddEvent()</code> to add an event called "AnEvent" with a bit width of 32 bits. The call to <code>OnConnected</code> tells BCI2000 to show the event's value in a graphical window. A description of the BCI2000Remote class can be found [https://www.bci2000.org/mediawiki/index.php/Contributions:BCI2000RemoteNET here], and API documentation can be found [https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html here].<br />
<br />
We will now add the events relevant to the Cursor Task. Open the <code>GameControl.cs</code> script, and modify its <code>Awake()</code> to add the events <code>PreFeedback</code>, <code>Feedback</code>, <code>PostFeedback</code>, <code>TargetHit</code>, and <code>Timeout</code> with bit width 1. Additionally, add the events <code>TrialNumber</code>, <code>TargetPositionX</code>, and <code>TargetPositionY</code> with width 16. These will encode the task state and number of trials.<br />
<br />
Open the <code>BallControl.cs</code> script, and within the <code>Awake()</code> function, add events <code>CursorPositionX</code> and <code>CursorPositionY</code>, with width 16. Show these events in a visualization window with <code>Visualize</code><br />
<br />
Your two scripts should now look like this: <br />
<pre><br />
>>> GameControl.cs <br />
...<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
remote.AddEvent("Feedback", 1);<br />
remote.AddEvent("PostFeedback", 1);<br />
remote.AddEvent("TargetHit", 1);<br />
remote.AddEvent("Timeout", 1);<br />
remote.AddEvent("TrialNumber", 16);<br />
remote.AddEvent("TargetPositionX", 16);<br />
remote.AddEvent("TargetPositionY", 16);<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
...<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("CursorPositionX", 16);<br />
remote.AddEvent("CursorPositionY", 16);<br />
});<br />
bci.OnConnected(remote => {<br />
remote.Visualize("CursorPositionX");<br />
remote.Visualize("CursorPositionY");<br />
}<br />
</pre><br />
<br />
<br />
<br />
===Using BCI2000 Parameters===<br />
====Adding Parameters====<br />
BCI2000's operator contains an interface for changing experiment parameters before running a task. By making use of this interface we can change the behavior of the task dynamically, without needing to rebuild the Unity project each time. In order to do this we need to define the parameters and add them to BCI2000, and later read their values after the operator has a chance to change them. <span style="color: red">This section is not strictly necessary. The project will function the same whether this is done or not, just without the option to change parameters at runtime. </span> <br />
<br />
First, we define add parameters to BCI2000. Similarly to events, parameters must be added while the Operator is in the <code>Idle</code> state, so we add them inside of <code>OnIdle</code>, like below:<br />
<pre><br />
public int someParameter = 5;<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddParameter("Application:ParameterPlace", "SomeParameter", someParameter.ToString()); <br />
});<br />
}<br />
<br />
The first argument to the method is the section into which the parameter is placed, that is, on which tab and under which heading the parameter will appear within the Operator's parameter editor window (note that the section is not a scope, all parameter names must be unique). The second argument is the parameter name itself. The third argument is the default value of the parameter. We pass in the value of the parameter, so when it appears in the Operator, its default value is 5 (or another value if it has been changed in the Unity Editor). Note that all parameters are handled as strings, so we need to convert its value to a string when sending it.<br />
<br />
For <code>GameControl.cs</code>, we will add parameters corresponding to the Pre-Feedback, Feedback, and Post-Feedback durations, Target Radius, and Number of Trials.<br />
For <code>BallControl.cs</code>, we will add parameters corresponding to the Acceleration Scale, Coefficient of Restitution, Coefficient of Drag, and Attraction Curve Coefficient (how quickly the Ball moves to follow the Mouse Cursor).<br />
For <code>MCursorControl.cs</code>, we will add a parameter corresponding to the Rolling Maximum Amount.<br />
<br />
Your scripts should look like this:<br />
<pre><br />
>>> GameControl.cs<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
...<br />
<br />
remote.AddParameter("Application:Task", "PreFeedbackDuration", preFeedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "FeedbackDuration", feedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "PostFeedbackDuration", postFeedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "TargetRadius", targetRadius.ToString());<br />
remote.AddParameter("Application:Task", "Trials", n_trials.ToString());<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddParameter("Application:Physics", "AccelerationScale", accelerationScale.ToString());<br />
remote.AddParameter("Application:Physics", "CoeffOfRestitution", coefficientOfRestitution.ToString());<br />
remote.AddParameter("Application:Physics", "CoeffOfDrag", coefficientOfDrag.ToString());<br />
remote.AddParameter("Application:Physics", "AccelerationCurve", attractionCurveCoefficient.ToString());<br />
})}<br />
}<br />
<br />
>>> MCursorControl.cs<br />
void Awake() {<br />
...<br />
<br />
bci.OnIdle(remote => {<br />
AddParameter("Application:Physics", "RollingMaximumAmount", rollingMaximumAmount.ToString());<br />
});<br />
}<br />
<br />
<br />
====Reading and Validating Parameters====<br />
Since we set the parameters within the BCI2000 operator, we need some way to read them back into Unity after they have been set. Specifically, we need to read them after the operator clicks the "Set Config" button within the BCI2000 Operator. How this timing synchronization is covered in the section [[Reacting to BCI2000 state changes]]. In this section we will cover reading and validating parameters.<br />
<br />
A method called <code>SetConfig</code> is provided in each of the scripts in which we added parameters previously. This method will be called after the operator changes parameters. In this method we will read in parameters and parse them into valid values. Using the same example parameter as before:<br />
<pre><br />
void SetConfig() {<br />
try {<br />
someParameter = int.Parse(bci.Control.GetParameter("SomeParameter"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse parameter SomeParameter as int");<br />
throw e;<br />
}<br />
}<br />
</pre><br />
<br />
Note that since we are now working outside the BCI2000 startup sequence, we use <code>UnityBCI2000.Control</code> to call <code>BCI2000Remote</code> methods directly, rather than using <code>OnIdle</code> or <code>OnConnected</code>. We also wrap the call within a try/catch block so that we can report erroneous parameters back to the operator. This is optional, but it keeps your project from failing silently and is otherwise useful for doing things like distributing your Unity project as a standalone executable, where logging errors can only be done through the BCI2000 operator. You can also write a helper function which handles parsing and error reporting for you:<br />
<br />
<pre><br />
int GetParseParameterInt(string paramName) {<br />
int p_val = bci.Control.GetParameter("SomeParameter");<br />
try {<br />
someParameter = int.Parse(p_val);<br />
} catch (FormatException e) {<br />
bci.Error($"Could not parse parameter {paramName} (value {p_val}) as int");<br />
throw e;<br />
}<br />
}<br />
</pre><br />
Unfortunately, since the version of C# used by Unity does not support type-parameterized parsing, you must write one of these helper functions for each type of data you want to store in a parameter (int, float, double, etc.)<br />
<br />
<br />
Read back the parameters added in the previous step. Your scripts should look like this:<br />
<br />
<pre><br />
>>> GameControl.cs <br />
void SetConfig() {<br />
try {<br />
preFeedbackDuration = float.Parse(bci.Control.GetParameter("PreFeedbackDuration"));<br />
feedbackDuration = float.Parse(bci.Control.GetParameter("FeedbackDuration"));<br />
postFeedbackDuration = float.Parse(bci.Control.GetParameter("PostFeedbackDuration"));<br />
targetRadius = float.Parse(bci.Control.GetParameter("TargetRadius"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse one of PreFeedbackDuration, FeedbackDuration, PostFeedbackDuration, or TargetRadius as a float");<br />
throw e;<br />
}<br />
try {<br />
n_trials = int.Parse(bci.Control.GetParameter("Trials"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse Trials as an int");<br />
throw e;<br />
}<br />
<br />
if (preFeedbackDuration < COUNTDOWN_DURATION) {<br />
bci.Error("preFeedbackDuration must be greater than or equal to 2.25");<br />
throw new Exception("preFeedbackDuration must be greater than or equal to 2.25");<br />
}<br />
}<br />
<br />
>>> BallControl.cs<br />
public void SetConfig() {<br />
try {<br />
accelerationScale = float.Parse(bci.Control.GetParameter("AccelerationScale"));<br />
coefficientOfRestitution = float.Parse(bci.Control.GetParameter("CoeffOfRestitution"));<br />
coefficientOfDrag = float.Parse(bci.Control.GetParameter("CoeffOfDrag"));<br />
attractionCurveCoefficient = float.Parse(bci.Control.GetParameter("AccelerationCurve"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse one of AccelerationScale, CoeffOfRestitution, CoeffOfDrag, AccelerationCurve as float");<br />
throw e;<br />
}<br />
}<br />
<br />
>>> MCursorControl.cs<br />
public void SetConfig() {<br />
try {<br />
rollingMaximumAmount = int.Parse(bci.Control.GetParameter("RollingMaximumAmount"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse parameter RollingMaximumAmount as int");<br />
throw e;<br />
}<br />
signalsX = new int[rollingMaximumAmount];<br />
signalsY = new int[rollingMaximumAmount];<br />
}<br />
</pre><br />
<br />
Note that in <code>GameControl.cs</code>, we also verify that the Pre-Feedback Duration is longer than the duration of the countdown that happens before each trial, and report errors to BCI2000 accordingly.<br />
<br />
<br />
===Reacting to BCI2000 state changes===<br />
Since we will be controlling the Unity task from BCI2000, we need some way to wait for BCI2000 to be in a specific state, for example, waiting for the operator to click Start and put the Operator Module into the Running state. UnityBCI2000 provides a method for this, the <code>UnityBCI2000.PollSystemState</code> method. In order to wait for the Operator Module to be in the <code>Running</code> state:<br />
<pre><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Running));<br />
</pre><br />
This will check once per frame whether or not the Operator is in the <code>Running</code> state, and only continue once BCI2000 is in the <code>Running</code> state. Note that since <code>SystemState</code> is a member of <code>BCI2000Remote</code>, we also need to add a <code>using BCI2000RemoteNET</code> statement to our script.<br />
<br />
In our case, we need to react to the operator setting the parameters, starting the data collection, and stopping the data collection. These correspond to the Operator Module entering the <code>Resting</code> state, entering the <code>Running</code> state, and exiting the <code>Running</code> state.<br />
<br />
In the <code>GameControl.cs</code> script, we will wait for the system to be in the <code>Resting</code> state at the start of the <code>ControLoop</code> method, and wait for the system to be in the <code>Running</code> state immediately before the entering the trial loop. <br />
<pre><br />
>>> GameControl.cs<br />
<br />
IEnumerator ControlLoop() {<br />
while (True) {<br />
<pre style="color: red"><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Resting));<br />
</pre><br />
<br />
try {<br />
...<br />
} catch (Exception e) {<br />
continue;<br />
}<br />
<br />
int trials = 0;<br />
<br />
</pre><br />
<pre style="color: red"><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Running));<br />
</pre><br />
<br />
yield return new WaitForSeconds(preRunDuration);<br />
while (IsContinue() && trials < n_trials) {<br />
...<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
We also need to check for the operator stopping data collection, so we modify the <code>IsContinue()</code> method.<br />
<br />
<pre><br />
bool IsContinue () {<br />
return bci.Control.GetSystemState() == BCI2000Remote.SystemState.Running;<br />
}<br />
</pre><br />
<br />
Remember to add <code>using BCI2000RemoteNET;</code> to the top of the script, so you can access the <code>SystemState</code> enum.<br />
<br />
===Reading the control signal===<br />
We will be using the control signal to control the cursor. Open the <code>MCursorControl.cs</code> script.<br />
<br />
The commented out section of the <code>GetPos()</code> method contains the code required to turn the control signal waveform coming from the Signal Source and Signal Processing modules into screen coordinates. <br />
Uncomment the commented part and delete the line <code>Ray r = camera.ScreenPointToRay(Input.MousePosition);</code>.<br />
Change the <code>double signalX = 0;</code> and <code>double signalY = 0;</code> to. <br />
<br />
Your <code>GetPos()</code> method should look like this:<br />
<pre><br />
Vector3 GetPos() {<br />
double signalX = bci.Control.GetSignal(1, bci.CurrentSampleOffset());<br />
double signalY = bci.Control.GetSignal(2, bci.CurrentSampleOffset());<br />
signalsX[signalIndex] = signalX;<br />
signalsY[signalIndex] = signalY;<br />
<br />
signalIndex = signalIndex + 1 >= rollingMaximumAmount ? 0 : signalIndex + 1;<br />
double max_x = signalsX.Max();<br />
double max_y = signalsY.Max();<br />
Ray r = camera.ScreenPointToRay(new Vector3((float) max_x * Screen.width, (float) max_y * Screen.height, 0));<br />
float p;<br />
if (!plane.Raycast(r, out p)) {<br />
throw new Exception("error casting ray to plane, invalid mouse position?");<br />
}<br />
return r.GetPoint(p);<br />
}<br />
</pre><br />
<br />
Note the use of the <code>UnityBCI2000.CurrentSampleOffset()</code> method. This is a special method which gets the offset into the current block such that the sample is exactly one block length later than when it was collected by the hardware. This is to normalize the latency between when the hardware collects the signal and the software receives the signal, due to how BCI2000 processes data in blocks.<br />
<br />
===Sending events back to BCI2000===<br />
<br />
The primary way to communicate game state back to BCI2000 is via the use of Events, which are integer values encoded alongside the signal data.<br />
<br />
We will send the events that we added in a previous section.<br />
<br />
First, we will send back the current position of the cursor. Within the <code>BallControl.cs</code> script, within the <code>Update()</code> method, immediately after <code>Move()</code> is called, set the <code>CursorPositionX</code> and <code>CursorPositionY</code> events. <br />
<br />
<pre><br />
>>> BallControl.cs<br />
void Update() {<br />
...<br />
if (isTrialRunning) {<br />
...<br />
Move();<br />
bci.Control.SetEvent("CursorPositionX", (uint) ((transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("CursorPositionY", (uint) ((transform.position.y + 4.5) * 1000));<br />
}<br />
...<br />
</pre><br />
<br />
Notice that we transform the value of the cursor's position. This is because events in BCI2000 are represented as unsigned integers, so, for example, the cursor's range of movement in the x axis, -7 to 7, would not be directly representable within a BCI2000 event, so we add 7 so it is positive, and multiply by 1000 so that we have a more precise measure of the cursor's position. The range of [-7,7] becomes [0,14000].<br />
<br />
<br />
We will also set the events corresponding to the game state within <code>GameControl.cs</code>. First we will set <code>PreFeedback</code>, <code>Feedback</code>, and <code>PostFeedback</code> to represent when the game is in these states. To do this, at the beginning and end of <code>PreTrial()</code>, <code>Trial()</code>, and <code>PostTrial()</code>, we will set the corresponding event values to 1 and 0, respectively.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
bci.Control.SetEvent("PreFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PreFeedback", 0);<br />
}<br />
IEnumerator Trial() {<br />
bci.Control.SetEvent("Feedback", 1);<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
}<br />
IEnumerator PostTrial() {<br />
bci.Control.SetEvent("PostFeedback", 1);<br />
...<br />
bci.Control.SetEvent("PostFeedback", 0);<br />
}<br />
</pre><br />
<br />
We will also set the events which happen at the end of each trial. The <code>TargetHit</code> event is activated when the subject hits the target, and the <code>Timeout</code> event is activated when the subject runs out of time.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator Trial() {<br />
...<br />
bci.Control.SetEvent("Feedback", 0);<br />
if (lastTrialSucceeded) {<br />
bci.Control.PulseEvent("TargetHit", 1);<br />
} else {<br />
bci.Control.PulseEvent("Timeout", 1);<br />
}<br />
}<br />
<br />
Notice that we use <code>BCI2000Remote.PulseEvent()</code> rather than <code>BCI2000Remote.SetEvent()</code>. This results in the event being set to the value <code>1</code> for exactly one sample duration, then returning to zero.<br />
<br />
We will also record the position of the target. Similarly to the cursor, we will transform the target's coordinates to be a positive integer.<br />
<br />
<pre><br />
>>> GameControl.cs<br />
IEnumerator PreTrial() {<br />
...<br />
target.SetActive(true);<br />
bci.Control.SetEvent("TargetPositionX", (uint) ((target.transform.position.x + 7) * 1000));<br />
bci.Control.SetEvent("TargetPositionY", (uint) ((target.transform.position.y + 4.5) * 1000));<br />
...<br />
}<br />
</pre><br />
<br />
The last event we need to set is the trial number.<br />
<br />
<pre><br />
IEnumerator ControlLoop() {<br />
...<br />
while (IsContinue() && trials < n_trials) {<br />
bci.Control.SetEvent("TrialNumber", trials + 1);<br />
...<br />
}<br />
}<br />
<br />
===Unity Player Settings===<br />
Additionally, due to how Unity detects changes in BCI2000 state, it must be allowed to run in the background.<br />
<br />
<pre style="color:red"><br />
In the Unity menu bar:<br />
Edit > Project Settings > Player > Resolution and Presentation<br />
Check the "Run In Background" box.<br />
</pre><br />
<br />
<br />
===Usage===<br />
<br />
Now, when the Unity application runs, BCI2000 will open. From here, parameters can be set via the Config window, then clicking Set Config and Start will start data collection.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=User_Tutorial:UnityBCI2000&diff=11492User Tutorial:UnityBCI20002024-08-06T16:10:27Z<p>Tytbutler: Added unity tutorial</p>
<hr />
<div><pre style="color:red"><br />
Red text blocks contain detailed instructions for the higher-level instructions preceding them.<br />
</pre><br />
<br />
This example demonstrates many of the capabilities of UnityBCI2000, and as such,<br />
<br />
===Download Unity===<br />
<br />
Download Unity Hub from [https://unity3d.com Unity].<br />
<br />
===Setting Up BCI2000===<br />
<br />
Follow the instructions starting with [https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Install_Prerequisites] to download BCI2000. <br />
<br />
===Setting Up UnityBCI2000===<br />
Download UnityBCI2000 from its GitHub page, [https://github.com/neurotechcenter/UnityBCI2000]. <br />
<pre style="color:red"><br />
Click on the "Releases" section on the right side of the page. This tutorial is intended to be used with UnityBCI2000 version 2.0.0, so scroll to that release and click on the files BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to download them.<br />
</pre><br />
<br />
===Download Tutorial Project===<br />
Download the CursorTask3 repository from [https://github.com/Personator01/CursorTask3 GitHub].<br />
<pre style="color:red"><br />
Either:<br />
-Clone the git repository<br />
-Download the respository directly from GitHub<br />
-> Click the green "Code" button <br />
-> Select "Download ZIP"<br />
-> Extract the zip file<br />
</pre><br />
The downloade directory contains two versions of the CursorTask3 project. One, CursorTask3-BCI2K, contains an example implementation of the task with BCI2000 integration. The other, CursorTask3-NoBCI2K, contains the same task without BCI2000 integration. This tutorial is a step by step guide on turning that second project into the first. <br />
<br />
===Opening the project===<br />
Open the project in the Unity Editor, and open the CursorTask scene.<br />
<pre style="color:red"><br />
Open Unity Hub.<br />
Click the "Add" button in the top right corner.<br />
Navigate to the CursorTask3 directory downloaded previously.<br />
Select the CursorTask3-NoBCI2K directory to add it to Unity Hub.<br />
Click the CursorTask3-NoBCI2K project in the Unity Hub.<br />
If prompted to select a version of Unity to use or install, select Unity 2022.3. The specific release number of Unity 2022.3 should not matter, so select the one labeled "LTS" for consistency.<br />
The lower panel (the asset browser) should already show the Assets/Scenes directory, which contains a single scene called SampleScene.<br />
Double-click SampleScene. This should open a scene with a box containing various lights and objects.<br />
</pre><br />
If you wish to view the completed implementation, repeat these steps, but instead open the CursorTask3-BCI2K directory. Note that in order to use the completed implementation, you will still need to set the Operator Path value of the UnityBCI2000 component of the BCI2000 game object.<br />
<br />
===Adding UnityBCI2000 to the project===<br />
Add BCI2000RemoteNETStandard.dll and UnityBCI2000.cs to your project's assets.<br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click Assets > Open Containing Folder to open your project directory.<br />
Place the BCI2000RemoteNETStandard.dll and UnityBCI2000.cs files in the Assets folder.<br />
</pre><br />
<br />
Add an empty GameObject called 'BCI2000'. This will hold the scripts for controlling BCI2000. <br />
<pre style="color:red"><br />
In the Unity Editor's menu bar, click GameObject > Create Empty to create an empty GameObject, and name it 'BCI2000'. (The object's specific name does not actually matter, it is only needed in order to reference it within other scripts)<br />
You will notice that it now appears in the Scene Hierarchy panel, on the left side of the screen.<br />
</pre><br />
<br />
Add the UnityBCI2000 component to the object.<br />
<pre style="color:red"><br />
Click on the object in the Hierarchy panel. This will open it in the Inspector panel (the panel on the right side of the screen)<br />
In the inspector, below the new object's Transform component, click the "Add Component" button, which will open up a small window for adding components.<br />
Within this window, select Scripts > Unity BCI2000 to add the UnityBCI2000 component.<br />
</pre><br />
<br />
===Configuring UnityBCI2000===<br />
The inspector panel now contains the configuration options for UnityBCI2000. Set the options as follows:<br />
<br />
<code>Start Local Operator</code>: Checked<br />
This will start the operator on your computer when the Unity scene initializes. If we were instead connecting to an already-running instance of BCI2000, or an instance on another computer, this box would be deselected.<br />
<br />
<code>Operator Path</code>: The path to the Operator executable. This will look something like this on Windows (C://path/to/bci2000/prog/Operator.exe)<br />
<br />
<code>Operator Address</code>: 127.0.0.1<br />
This is the address of the machine on which BCI2000 is running. Since we are running BCI2000 on the same computer as Unity, we leave it as 127.0.0.1, the loopback address.<br />
<br />
<code>Operator Port</code>: 3999<br />
This is the port on which BCI2000 is listening for commands. By default, it is 3999.<br />
<br />
<code>Start Modules</code>: Checked<br />
This tells BCI2000 to start the requested Signal Source, Signal Processing, and Application modules when the Unity scene initializes. Similarly to Start Local Operator, we would deselect this box if connecting to an already-running instance. <br />
<br />
<code>Start With Scene</code>: Unchecked<br />
This tells BCI2000 to start a data collection run when the scene starts. Since we will be using BCI2000 itself to set experiment parameters, we will instead wait for BCI2000 to start from Unity, and thus will leave the box unchecked. <br />
<br />
<code>Stop With Scene</code>: Unchecked<br />
This tells BCI2000 to stop collecting data when the scene stops. Since we will be controlling BCI2000 directly, rather than entirely through Unity, we will leave this unchecked.<br />
<br />
<code>Shutdown With Scene</code>: Unchecked<br />
This tells BCI2000 to shut down alongside the Unity scene. Whether or not this value is set ultimately doesn't matter much, especially if Start Local Operator is checked. The data will be saved whether or not BCI2000 shuts down. <br />
<br />
===Setting References===<br />
In order for the game's scripts to communicate with BCI2000, they need to hold a reference to the UnityBCI2000 component.<br />
There are three scripts which will need to communicate with BCI2000. They are <code>GameControl.cs, BallControl.cs, and MCursorControl.cs</code>.<br />
These scripts are each located within the Assets directory of the Unity project. <br />
<pre style="color:red"><br />
As before, select Assets > Open Containing Folder to open the project directory, then open the Assets folder. <br />
For each script, open it in a text editor.<br />
Add a data member of type UnityBCI2000 to the class, like so:<br />
UnityBCI2000 bci;<br />
Place the member definition above the Awake() method, for readability.<br />
Within the Awake() method, set this reference to the UnityBCI2000 component.<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
</pre><br />
Each of the three scripts should contain a section like this:<br />
<pre><br />
...<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
</pre><br />
<br />
===Adding Events===<br />
[https://www.bci2000.org/mediawiki/index.php/Programming_Reference:Events Events] are the primary way that non-signal experiment data is recorded in BCI2000. They are timestamped integer values which are encoded alongside the signal data in BCI2000 output files. Due to BCI2000's design, events must be added during a very specific part of its startup sequence, which is immediately after the BCI2000 operator starts, and before any of the modules start. As such, we cannot simply call <code>AddEvent()</code> whenever we want. Furthermore, the order in which Unity objects initialize is undefined, so it cannot even be guaranteed that calling <code>AddEvent</code> at a specific time will be consistent across multiple projects. As such, UnityBCI2000 provides a couple of methods for sending commands at well-defined points within the startup sequence. These two methods, <code>OnIdle</code> and <code>OnIdle</code> and <code>OnConnected</code> allow BCI2000 commands to be sent while the operator is in the state Idle (immediately before starting its modules) and when the operator is in the state Connected (after starting and connecting to the modules. Below is an example of using those methods to add and show an event in BCI2000.<br />
<br />
<pre><br />
class Script : MonoBehaviour {<br />
UnityBCI2000 bci;<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000Object").GetComponent<UnityBCI2000>();<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("AnEvent", 32);<br />
});<br />
}<br />
void Start() {<br />
bci.OnConnected(remote => {<br />
remote.Visualize("AnEvent");<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
As seen above, <code>OnIdle</code> and <code>OnConnected</code> take a delegate (C#'s term for a callback/closure/functor/etc.) with a single parameter of type <code>BCI2000Remote</code> (in this case called "remote"). The lambda expression given to the call to <code>OnIdle</code> uses the method <code>BCI2000Remote.AddEvent()</code> to add an event called "AnEvent" with a bit width of 32 bits. The call to <code>OnConnected</code> tells BCI2000 to show the event's value in a graphical window. A description of the BCI2000Remote class can be found [https://www.bci2000.org/mediawiki/index.php/Contributions:BCI2000RemoteNET here], and API documentation can be found [https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html here].<br />
<br />
We will now add the events relevant to the Cursor Task. Open the <code>GameControl.cs</code> script, and modify its <code>Awake()</code> to add the events <code>PreFeedback</code>, <code>Feedback</code>, <code>PostFeedback</code>, <code>TargetHit</code>, and <code>Timeout</code> with bit width 1. Additionally, add the event <code>TrialNumber</code> with width 16. These will encode the task state and number of trials.<br />
<br />
Open the <code>BallControl.cs</code> script, and within the <code>Awake()</code> function, add events <code>CursorPositionX</code> and <code>CursorPositionY</code>, with width 16. Show these events in a visualization window with <code>Visualize</code><br />
<br />
Your two scripts should now look like this: <br />
<pre><br />
>>> GameControl.cs <br />
...<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
remote.AddEvent("Feedback", 1);<br />
remote.AddEvent("PostFeedback", 1);<br />
remote.AddEvent("TargetHit", 1);<br />
remote.AddEvent("Timeout", 1);<br />
remote.AddEvent("TrialNumber", 16);<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
...<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("CursorPositionX", 16);<br />
remote.AddEvent("CursorPositionY", 16);<br />
});<br />
bci.OnConnected(remote => {<br />
remote.Visualize("CursorPositionX");<br />
remote.Visualize("CursorPositionY");<br />
}<br />
</pre><br />
<br />
<br />
<br />
===Using BCI2000 Parameters===<br />
====Adding Parameters====<br />
BCI2000's operator contains an interface for changing experiment parameters before running a task. By making use of this interface we can change the behavior of the task dynamically, without needing to rebuild the Unity project each time. In order to do this we need to define the parameters and add them to BCI2000, and later read their values after the operator has a chance to change them. <span style="color: red">This section is not strictly necessary. The project will function the same whether this is done or not, just without the option to change parameters at runtime. </span> <br />
<br />
First, we define add parameters to BCI2000. Similarly to events, parameters must be added while the Operator is in the <code>Idle</code> state, so we add them inside of <code>OnIdle</code>, like below:<br />
<pre><br />
public int someParameter = 5;<br />
void Awake() {<br />
bci.OnIdle(remote => {<br />
remote.AddParameter("Application:ParameterPlace", "SomeParameter", someParameter.ToString()); <br />
});<br />
}<br />
<br />
The first argument to the method is the section into which the parameter is placed, that is, on which tab and under which heading the parameter will appear within the Operator's parameter editor window (note that the section is not a scope, all parameter names must be unique). The second argument is the parameter name itself. The third argument is the default value of the parameter. We pass in the value of the parameter, so when it appears in the Operator, its default value is 5 (or another value if it has been changed in the Unity Editor). Note that all parameters are handled as strings, so we need to convert its value to a string when sending it.<br />
<br />
For <code>GameControl.cs</code>, we will add parameters corresponding to the Pre-Feedback, Feedback, and Post-Feedback durations, Target Radius, and Number of Trials.<br />
For <code>BallControl.cs</code>, we will add parameters corresponding to the Acceleration Scale, Coefficient of Restitution, Coefficient of Drag, and Attraction Curve Coefficient (how quickly the Ball moves to follow the Mouse Cursor).<br />
For <code>MCursorControl.cs</code>, we will add a parameter corresponding to the Rolling Maximum Amount.<br />
<br />
Your scripts should look like this:<br />
<pre><br />
>>> GameControl.cs<br />
void Awake() {<br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
...<br />
<br />
bci.OnIdle(remote => {<br />
remote.AddEvent("PreFeedback", 1);<br />
...<br />
<br />
remote.AddParameter("Application:Task", "PreFeedbackDuration", preFeedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "FeedbackDuration", feedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "PostFeedbackDuration", postFeedbackDuration.ToString());<br />
remote.AddParameter("Application:Task", "TargetRadius", targetRadius.ToString());<br />
remote.AddParameter("Application:Task", "Trials", n_trials.ToString());<br />
});<br />
}<br />
<br />
>>> BallControl.cs<br />
void Awake() {<br />
...<br />
bci.OnIdle(remote => {<br />
remote.AddParameter("Application:Physics", "AccelerationScale", accelerationScale.ToString());<br />
remote.AddParameter("Application:Physics", "CoeffOfRestitution", coefficientOfRestitution.ToString());<br />
remote.AddParameter("Application:Physics", "CoeffOfDrag", coefficientOfDrag.ToString());<br />
remote.AddParameter("Application:Physics", "AccelerationCurve", attractionCurveCoefficient.ToString());<br />
})}<br />
}<br />
<br />
>>> MCursorControl.cs<br />
void Awake() {<br />
...<br />
<br />
bci.OnIdle(remote => {<br />
AddParameter("Application:Physics", "RollingMaximumAmount", rollingMaximumAmount.ToString());<br />
});<br />
}<br />
<br />
<br />
====Reading and Validating Parameters====<br />
Since we set the parameters within the BCI2000 operator, we need some way to read them back into Unity after they have been set. Specifically, we need to read them after the operator clicks the "Set Config" button within the BCI2000 Operator. How this timing synchronization is covered in the section [[Reacting to BCI2000 state changes]]. In this section we will cover reading and validating parameters.<br />
<br />
A method called <code>SetConfig</code> is provided in each of the scripts in which we added parameters previously. This method will be called after the operator changes parameters. In this method we will read in parameters and parse them into valid values. Using the same example parameter as before:<br />
<pre><br />
void SetConfig() {<br />
try {<br />
someParameter = int.Parse(bci.Control.GetParameter("SomeParameter"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse parameter SomeParameter as int");<br />
throw e;<br />
}<br />
}<br />
</pre><br />
<br />
Note that since we are now working outside the BCI2000 startup sequence, we use <code>UnityBCI2000.Control</code> to call <code>BCI2000Remote</code> methods directly, rather than using <code>OnIdle</code> or <code>OnConnected</code>. We also wrap the call within a try/catch block so that we can report erroneous parameters back to the operator. This is optional, but it keeps your project from failing silently and is otherwise useful for doing things like distributing your Unity project as a standalone executable, where logging errors can only be done through the BCI2000 operator. You can also write a helper function which handles parsing and error reporting for you:<br />
<br />
<pre><br />
int GetParseParameterInt(string paramName) {<br />
int p_val = bci.Control.GetParameter("SomeParameter");<br />
try {<br />
someParameter = int.Parse(p_val);<br />
} catch (FormatException e) {<br />
bci.Error($"Could not parse parameter {paramName} (value {p_val}) as int");<br />
throw e;<br />
}<br />
}<br />
</pre><br />
Unfortunately, since the version of C# used by Unity does not support type-parameterized parsing, you must write one of these helper functions for each type of data you want to store in a parameter (int, float, double, etc.)<br />
<br />
<br />
Read back the parameters added in the previous step. Your scripts should look like this:<br />
<br />
<pre><br />
>>> GameControl.cs <br />
void SetConfig() {<br />
try {<br />
preFeedbackDuration = float.Parse(bci.Control.GetParameter("PreFeedbackDuration"));<br />
feedbackDuration = float.Parse(bci.Control.GetParameter("FeedbackDuration"));<br />
postFeedbackDuration = float.Parse(bci.Control.GetParameter("PostFeedbackDuration"));<br />
targetRadius = float.Parse(bci.Control.GetParameter("TargetRadius"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse one of PreFeedbackDuration, FeedbackDuration, PostFeedbackDuration, or TargetRadius as a float");<br />
throw e;<br />
}<br />
try {<br />
n_trials = int.Parse(bci.Control.GetParameter("Trials"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse Trials as an int");<br />
throw e;<br />
}<br />
<br />
if (preFeedbackDuration < COUNTDOWN_DURATION) {<br />
bci.Error("preFeedbackDuration must be greater than or equal to 2.25");<br />
throw new Exception("preFeedbackDuration must be greater than or equal to 2.25");<br />
}<br />
}<br />
<br />
>>> BallControl.cs<br />
public void SetConfig() {<br />
try {<br />
accelerationScale = float.Parse(bci.Control.GetParameter("AccelerationScale"));<br />
coefficientOfRestitution = float.Parse(bci.Control.GetParameter("CoeffOfRestitution"));<br />
coefficientOfDrag = float.Parse(bci.Control.GetParameter("CoeffOfDrag"));<br />
attractionCurveCoefficient = float.Parse(bci.Control.GetParameter("AccelerationCurve"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse one of AccelerationScale, CoeffOfRestitution, CoeffOfDrag, AccelerationCurve as float");<br />
throw e;<br />
}<br />
}<br />
<br />
>>> MCursorControl.cs<br />
public void SetConfig() {<br />
try {<br />
rollingMaximumAmount = int.Parse(bci.Control.GetParameter("RollingMaximumAmount"));<br />
} catch (FormatException e) {<br />
bci.Error("Could not parse parameter RollingMaximumAmount as int");<br />
throw e;<br />
}<br />
signalsX = new int[rollingMaximumAmount];<br />
signalsY = new int[rollingMaximumAmount];<br />
}<br />
</pre><br />
<br />
Note that in <code>GameControl.cs</code>, we also verify that the Pre-Feedback Duration is longer than the duration of the countdown that happens before each trial, and report errors to BCI2000 accordingly.<br />
<br />
<br />
===Reacting to BCI2000 state changes===<br />
Since we will be controlling the Unity task from BCI2000, we need some way to wait for BCI2000 to be in a specific state, for example, waiting for the operator to click Start and put the Operator Module into the Running state. UnityBCI2000 provides a method for this, the <code>UnityBCI2000.PollSystemState</code> method. In order to wait for the Operator Module to be in the <code>Running</code> state:<br />
<pre><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Running));<br />
</pre><br />
This will check once per frame whether or not the Operator is in the <code>Running</code> state, and only continue once BCI2000 is in the <code>Running</code> state. Note that since <code>SystemState</code> is a member of <code>BCI2000Remote</code>, we also need to add a <code>using BCI2000RemoteNET</code> statement to our script.<br />
<br />
In our case, we need to react to the operator setting the parameters, starting the data collection, and stopping the data collection. These correspond to the Operator Module entering the <code>Resting</code> state, entering the <code>Running</code> state, and exiting the <code>Running</code> state.<br />
<br />
In the <code>GameControl.cs</code> script, we will wait for the system to be in the <code>Resting</code> state at the start of the <code>ControLoop</code> method, and wait for the system to be in the <code>Running</code> state immediately before the entering the trial loop. <br />
<pre><br />
>>> GameControl.cs<br />
<br />
IEnumerator ControlLoop() {<br />
while (True) {<br />
<pre style="color: red"><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Resting));<br />
</pre><br />
<br />
try {<br />
...<br />
} catch (Exception e) {<br />
continue;<br />
}<br />
<br />
int trials = 0;<br />
<br />
</pre><br />
<pre style="color: red"><br />
StartCoroutine(bci.PollSystemState(BCI2000Remote.SystemState.Running));<br />
</pre><br />
<br />
yield return new WaitForSeconds(preRunDuration);<br />
while (IsContinue() && trials < n_trials) {<br />
...<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
We also need to check for the operator stopping data collection, so we modify the <code>IsContinue()</code> method.<br />
<br />
<pre><br />
bool IsContinue () {<br />
return bci.Control.GetSystemState() == BCI2000Remote.SystemState.Running;<br />
}<br />
</pre><br />
<br />
Remember to add <code>using BCI2000RemoteNET;</code> to the top of the script, so you can access the <code>SystemState</code> enum.<br />
<br />
===Reading the control signal===</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Supported_Frameworks&diff=11419Supported Frameworks2024-07-09T13:28:17Z<p>Tytbutler: Moved BCI2000RemoteNET out of 'in development' state</p>
<hr />
<div>==Purpose==<br />
BCI2000 supports many frameworks outside of its native implementation. This page gives a list of each of these frameworks and how they interact with one another.<br />
<br />
==Schematic==<br />
[[Image:ExternalInterfaces.png|center]]<br />
A visual schematic for how the varying interfaces of BCI2000 interact. Encapsulated items mean they are built on top of the larger, overarching framework. For example, BCI2000Remote is an extension of BCI2000 Operator Module Scripting. Each interface has a descriptor of the language/method/application you would use for the framework. <br />
==Documentation==<br />
===[[Contributions:External Interfaces|External Interfaces]]===<br />
*[[Contributions:BCPy2000]]<br />
*[[Contributions:BCI2000SimulinkConnector]]<br />
*[[Programming Reference:MatlabFilter]]<br />
*[[User Reference:EEGLabImport]]<br />
*[[Contributions:FieldTripBuffer]]<br />
====BCI2000 Operator Module Scripting====<br />
Documentation: [[User Reference:Module Command Line Options]], [[User Reference:Operator Module Scripting]]<br />
*[[User Reference:BCI2000Shell]]<br />
*[[User Reference:BCI2000Launcher]]<br />
*[[Contributions:BCI2000Command]]<br />
*[[Technical Reference:Operator Library]]<br />
=====BCI2000Remote=====<br />
Documentation: [[User Tutorial:BCI2000Remote]], [[Programming Reference:BCI2000Remote Class]], [[Contributions:BCI2000PythonBindings]]<br />
*[[PsychoPy]]<br />
* [[Python Visualizations]]<br />
======[[Technical Reference:BCI2000Remote Library|BCI2000RemoteLib]]======<br />
*[[Contributions:BCI2000Automation]]<br />
*[[Contributions:BCI2000PresentationLink]]<br />
<br />
==Frameworks organized by languages==<br />
'''User Interface (no coding)''': [[User Reference:BCI2000Launcher|BCI2000Launcher]]<br />
<br />
'''Python''': [[PsychoPy]], [[Contributions:BCPy2000|BCPy2000]], [[User Tutorial:BCI2000Remote#Python_Tutorial|BCI2000Remote]], [[Python Visualizations]]<br />
<br />
'''Matlab''': [[Programming Reference:MatlabFilter|MatlabFilter]], [[User Tutorial:BCI2000Remote#MatlabTutorial|BCI2000Remote]], [[Contributions:BCI2000SimulinkConnector|Simulink]]<br />
<br />
'''Command-line shell''': [[User Reference:Operator Module Scripting|Operator Module Scripting]], [[User Reference:BCI2000Shell|BCI2000Shell]], [[Contributions:BCI2000Command|BCI2000Command]]<br />
<br />
'''.NET (Visual Basic, C#)''': [[Contributions:BCI2000Automation|BCI2000Automation]], [[Contributions:BCI2000RemoteNET|BCI2000RemoteNET]]<br />
<br />
'''C++''': [[User Reference:Filters|Create a native BCI2000 filter]], [[User Tutorial:BCI2000Remote#C++_Tutorial|BCI2000Remote]]</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=User_Tutorial:BCI2000Unity&diff=11370User Tutorial:BCI2000Unity2024-05-29T19:43:03Z<p>Tytbutler: Tytbutler moved page User Tutorial:BCI2000Unity to User Tutorial:BCI2000Unity OUTDATED</p>
<hr />
<div>#REDIRECT [[User Tutorial:BCI2000Unity OUTDATED]]</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=User_Tutorial:BCI2000Unity_OUTDATED&diff=11369User Tutorial:BCI2000Unity OUTDATED2024-05-29T19:43:03Z<p>Tytbutler: Tytbutler moved page User Tutorial:BCI2000Unity to User Tutorial:BCI2000Unity OUTDATED</p>
<hr />
<div>==Synopsis==<br />
Unity is a cross-platform game engine with support for desktop, mobile, console, and virtual reality platforms. It is both easy for beginners to use and is popular for low-cost game development. This is a Unity package which integrates BCI2000. This tutorial assumes that you have already compiled BCI2000. <br />
<br />
==Video==<br />
This video is currently out of date. An updated video is coming soon!<br />
<br />
<youtube alignment="center">https://www.youtube.com/watch?v=nZG70HSR8v8</youtube><br />
<br />
==Tutorial==<br />
For information on how to use Unity itself, see the Unity [https://docs.unity3d.com/Manual/index.html manual]. This tutorial assumes knowledge of how to use Unity. It is recommended to know how GameObjects and Components work.<br />
More in-depth detail on how UnityBCI2000 works is provided in the README.md file, and on this [https://bci2000.org/BCI2000Unity/classUnityBCI2000.html page].<br />
<br />
<br />
<br />
This tutorial will walk through an example cursor control task, making use of the mouse position recorded from BCI2000 to control the cursor position in Unity. First, download UnityBCI2000 from this [https://github.com/neurotechcenter/UnityBCI2000 GitHub] page and download the MWE_UnityBCI2000CursorDemo tutorial project from this [https://github.com/neurotechcenter/ExperimentalDesignDemos GitHub] page. Copy the UnityBCI2000.cs and BCI2000RemoteNET.dll files into the Assets folder of your Unity project.<br />
<br />
[[File:UnityMoveAssets.png|500px|alt="Unity Move Assets"|Unity Move Assets]]<br />
<br />
===Connect to an Instance of BCI2000===<br />
<br />
To connect to an instance of BCI2000 in Unity, you will need to create an empty GameObject and add the script UnityBCI2000 as a Component. This will serve as the central connection to the BCI2000 Operator. As of now, it is not possible to use multiple scenes with one BCI2000 connection.<br />
<br />
1. Create a BCI2000 GameObject.<br />
<br />
[[File:UnityBCI2000GameObject.png|600px|alt="Unity BCI2000 Game Object"|Unity BCI2000 Game Object]]<br />
<br />
2. Add UnityBCI2000.cs to the GameObject as a Script Component. <br />
<br />
[[File:UnityBCI2000ScriptComponent.png|600px|alt="Unity BCI2000 Script Component"|Unity BCI2000 Script Component]]<br />
<br />
3. Use the Operator Path field to specify the path to the BCI2000 Operator.exe (usually in the C:/bci2000/prog/ directory). If you already have an instance of the operator running, use the Telnet IP and Telnet Port fields to specify the IP and port it is listening on instead.<br />
<br />
4. Specify the names of the modules to start up alongside it. Extensions can be added by expanding the Module Args field and adding an element with the appropriate extension flag. For the example that will follow, we will log the mouse extension with <br />
<br />
<tt><br />
--LogMouse=1<br />
</tt><br />
<br />
5. Specify the name of the log file to store the BCI2000 system log. '''NOTE: There is a known issue with writing to the log file; this is remedied by changing the name of the file to which to write. This is an issue with BCI2000RemoteNET and will be fixed in upcoming updates.'''<br />
<br />
[[File:UnityBCI2000Modules.png|400px|alt="Unity BCI2000 Modules"|Unity BCI2000 Modules]]<br />
<br />
===Save Unity Events in BCI2000===<br />
<br />
Next, we will modify a script to create new BCI2000 events and send event change information to BCI2000.<br />
<br />
1. Open the TargetControl script (or any script from which you would like to send information to BCI2000).<br />
<br />
2. In the class definition, instantiate BCI2000 with <br />
<br />
<tt><br />
UnityBCI2000 bci;<br />
</tt><br />
<br />
3. In the Awake() function, set the BCI2000 reference with <br />
<br />
<tt><br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
</tt><br />
<br />
4. In the Awake() function, create new BCI2000 events with the bci.AddEvent() function. The second input specifies the number of bits assigned to the new event.<br />
<br />
<tt><br />
bci.AddEvent("t1hit", 32);<br />
</tt><br />
<br />
5. It can be helpful to add watches for the events you have created so you can see their behavior in real time during the experiment. In the Awake() function, use the generic bci.ExecuteCommand() function (this function can be used to execute any BCI2000 operator scripting commands)<br />
<br />
<tt><br />
bci.ExecuteCommand("visualize watch t1hit");<br />
</tt><br />
<br />
6. It can be useful to reduce the verbosity of event logging, as event logs are written to the log file with every frame<br />
<br />
<tt><br />
bci.ExecuteCommand("Set variable LogLevel 0");<br />
</tt><br />
<br />
[[File:UnityTargetControlScript.png|500px|alt="Unity Target Control Script"|Unity Target Control Script]]<br />
<br />
7. Update the event value according to some change in the experiment using the bci.SetEvent() function in the Update() function. For example, change a target hit event "t1hit" to 1 every time a target is hit by a cursor. Note that events must be set as unsigned integers.<br />
<br />
<tt><br />
bci.SetEvent("t1hit",(int)(1));<br />
</tt><br />
<br />
[[File:UnitySetEvent.png|400px|alt="Unity Set Event"|Unity Set Event]]<br />
<br />
===Access BCI2000 Events for Control===<br />
<br />
We can also get event information from BCI2000 for Unity use. For example, you may want to control the Unity cursor position with a BCI2000 event, such as the mouse position. This example makes use of a BallMouseControl.cs script.<br />
<br />
First you will need to instantiate BCI2000 and set the BCI2000 reference as in the TargetControl.cs script<br />
<br />
1. Open the BallMouseControl.cs script.<br />
<br />
2. In the class definition, instantiate BCI2000 with <br />
<br />
<tt><br />
UnityBCI2000 bci;<br />
</tt><br />
<br />
3. In the Awake() function, set the BCI2000 reference with <br />
<br />
<tt><br />
bci = GameObject.Find("BCI2000").GetComponent<UnityBCI2000>();<br />
</tt><br />
<br />
[[File:UnityBallMouseControlScript.png|400px|alt="Unity Ball Mouse Control Script"|Unity Ball Mouse Control Script]]<br />
<br />
4. Get the value of the BCI2000 event using the bci.GetEvent() function and store the result in some variable<br />
<br />
<tt><br />
Mpx = bci.GetEvent("MousePosX");<br />
Mpy = bci.GetEvent("MousePosY");<br />
</tt><br />
<br />
This value can then be used in Unity to influence the game activity.<br />
<br />
[[File:UnityGetEvent.png|400px|alt="Unity Get Event"|Unity Get Event]]<br />
<br />
===Compile===<br />
<br />
Compile the project by navigating to file > Build and Run. This should launch the experiment and start up BCI2000!<br />
<br />
==Using BCI2000 Control Signal==<br />
<br />
The above example makes use of the BCI2000 Mouse Position events to control the Unity cursor position. However, the BCI2000 control signal can also be used in Unity. This is particularly useful for online experiments (for example, a neurofeedback task to move a cursor on the screen based on the decoded alpha power). In the demo script, navigate to the CursorTaskSignal Scene to see how the BCI2000 control signal can be utilized in Unity. Note that this only seems to work when the scene has been compiled!<br />
<br />
Access the control signal using the function<br />
<br />
<tt><br />
bci.GetSignal("ChannelNumber",1);<br />
</tt><br />
<br />
[[File:UnityGetSignal.png|500px|alt="Unity Get Signal"|Unity Get Signal]]<br />
<br />
==See also==<br />
<br />
[[Category:Tutorial]]</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:BCI2000Unity&diff=11368Contributions:BCI2000Unity2024-05-29T19:42:19Z<p>Tytbutler: Tytbutler moved page Contributions:BCI2000Unity to Contributions:BCI2000Unity OUTDATED</p>
<hr />
<div>#REDIRECT [[Contributions:BCI2000Unity OUTDATED]]</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:BCI2000Unity_OUTDATED&diff=11367Contributions:BCI2000Unity OUTDATED2024-05-29T19:42:19Z<p>Tytbutler: Tytbutler moved page Contributions:BCI2000Unity to Contributions:BCI2000Unity OUTDATED</p>
<hr />
<div>__NOINDEX__<br />
<br />
==Introduction==<br />
<br />
Unity is a cross-platform game engine with support for desktop, mobile, console, and virtual reality platforms. It is both easy for beginners to use and is popular for low-cost game development. This is a Unity package which integrates BCI2000.<br />
<br />
==Prerequisites==<br />
<br />
UnityBCI2000 depends on the BCI2000RemoteNET library, located at<br />
[https://github.com/neurotechcenter/BCI2000RemoteNET Github] or [https://www.nuget.org/packages/BCI2000RemoteNET NuGet]).<br />
Keep in mind that at the moment both BCI2000RemoteNET and BCI2000Unity are not fully released, and are still in development, so features and API structure are subject to change at any time, and bugs are to be expected.<br />
<br />
==Usage==<br />
<br />
Add the `UnityBCI2000.cs` script to one `GameObject`. This is the central script which communicates with BCI2000. <br />
Add the `BCI2000StateSender` to any object which you want to monitor with BCI2000. <br />
Before starting, you must set the operator and modules to start up, by specifying the fields<br />
`OperatorPath` and `Module[1-3]`. All other properties have default settings and will function without change. <br />
Alternatively, if you leave `OperatorPath` blank, `BCI2000Remote` will attempt to connect to an operator at<br />
`TelnetIp:TelnetPort`. This is useful for if you already have an operator open that you want to use. <br />
If you also have modules started within a running BCI2000 instance, set `DontStartModules` to `true`, this will preserve<br />
your running modules.<br />
<br />
===Using built-in variables===<br />
<br />
`BCI2000StateSender` has some variables built in. To use these, just select their check boxes in the inspector.<br />
<br />
===Adding custom variables===<br />
<br />
To add custom variables, add a script to the same object as a `BCI2000StateSender`, which inherits from `CustomVariableBase`. <br />
Then, add the `CustomVariableBase` to the "Custom Variable Supplier" field of the `BCI2000StateSender`.<br />
Then, add `CustomVariable`s to the list `customVariables` within the `CustomVariableBase`. There are some included<br />
templates and snippets which show the syntax for adding custom variables.<br />
<br />
===Custom Variables===<br />
<br />
A custom variable has four fields. These are its name, value, scale, and type. <br />
Its name is a string which holds its name. <br />
Its value is a `Func<float>` delegate which returns a float, which will be sent to BCI2000, after being multiplied by its scale. <br />
Its type is a member of the enum `UnityBCI2000.StateType`, which represents the format of the number being sent to BCI2000.<br />
<br />
===Custom Variable Class Example===<br />
<br />
Template<br />
<br />
public class <ClassName> : CustomVariableBase<br />
{<br />
public override void AddCustomVariables()<br />
{<br />
customVariables.Add(new CustomSetVariable( //Copy this for more set variables<br />
"[Name]",<br />
new Func<float>(() => [Code which returns variable to send]),<br />
[Scale],<br />
UnityBCI2000.StateType.[Type]<br />
));<br />
<br />
customVariables.Add(new CustomGetVariable( //Copy this for more get variables<br />
"[Name]", <br />
new Action<int> ((int i) => [Code which uses i])<br />
));<br />
<br />
}<br />
}<br />
<br />
Example<br />
<br />
public class CustomVariableSupplier1 : CustomVariableBase<br />
{<br />
public override void AddCustomVariables() <br />
{<br />
customVariables.Add(new CustomSetVariable(<br />
"Custom variable 1",<br />
new Func<float>(() => {return 65 / 5;}),<br />
100,<br />
UnityBCI2000.StateType.SignedInt16<br />
));<br />
customVariables.Add(new CustomSetVariable(<br />
"Custom variable 2: Frame count",<br />
new Func<float>(() => Time.frameCount),<br />
1,<br />
UnityBCI2000.StateType.UnsignedInt32<br />
));<br />
customVariables.Add(new CustomGetVariable( <br />
"StateName", <br />
new Action<int> ((int i) => {score = i})<br />
));<br />
}<br />
}<br />
<br />
===Number Formats===<br />
<br />
The available formats are found in the enum `UnityBCI2000.StateType`. As they are being accessed outside of `UnityBCI2000`, <br />
they will always be preceded by "UnityBCI2000.".<br />
<br />
The formats are `Boolean`, `UnsignedInt16`, `UnsignedInt32`, `SignedInt16`, and `SignedInt32`. <br />
These are available formats because BCI2000 takes state values in the form of unsigned integers with a bit width of powers of 2 between 1 and 32. <br />
Boolean is the same as an unsigned int of bit width 1. <br />
Signed numbers will generate a second state within BCI2000 of bit width 1, which holds their sign. If they are negative, their sign will be 1,<br />
and if they are positive, their sign will be 0. Use signed numbers if your value will ever be negative.<br />
<br />
===Other scripting===<br />
<br />
Try to avoid calling any of the methods directly. UnityBCI2000 should ideally be able to run and control BCI2000 without any intervention.<br />
<br />
==Properties==<br />
<br />
===UnityBCI2000===<br />
<br />
`Timeout`<br />
The timeout, in milliseconds, for sending and receiving commands, default 1000.<br />
<br />
`TelnetIP`<br />
The IP at which to connect to the Operator, default 127.0.0.1<br />
Note: Don't use "localhost" when setting this, as this causes errors due to ambiguity in name resolution.<br />
<br />
`TelnetPort`<br />
The port to connect to the Operator, default 3999.<br />
<br />
`OperatorPath`<br />
The path to the Operator module to start up when there is no running operator at the IP and port specified, will always connect on localhost, at the previously given port.<br />
<br />
`LogFile`<br />
The path to the file to write the log. This is overwritten on `Connect()`, default "logFile.txt", in the application's working directory.<br />
<br />
`LogStates`<br />
Whether or not to log commands to set a state, as well as the received Prompt if the command produces no errors, default false.<br />
<br />
`LogPrompts`<br />
Whether or not to log any Prompt, in which case only received output and errors will be logged, default false.<br />
<br />
===BCI2000StateSender===<br />
<br />
`UnityBCI2000 object`<br />
The object which has the attached `UnityBCI2000` script.<br />
<br />
`Custom Variable Supplier`<br />
The component which inherits from `CustomVariableBase` which supplies custom variables.<br />
<br />
Global and screen coordinates and their scales.<br />
<br />
`Camera`<br />
The camera to use for finding screen position.<br />
<br />
`Is on screen`<br />
Is the object on screen.<br />
<br />
<br />
`Velocity`<br />
The velocity of the object in any direction.<br />
<br />
`Custom Variables`<br />
Lists the names of any added custom variables.<br />
<br />
==Other Notes==<br />
<br />
`StateVariable` is a class which holds values necessary for sending states to BCI2000. <br />
They are stored in two places, a central list within `UnityBCI2000` which is only used for checking if a state already exists,<br />
and within the `BCI2000StateSender` which 'owns' the state, where they are stored within objects called `SendStateVariable`,<br />
which update the state with a new value every frame. This is done so that one state can be changed by mutiple `BCI2000StateSender`s,<br />
through the use of multiple `SendStateVariables` created using the `AddSendExistingState()` method. <br />
<br />
BCI2000Remote will write its output to a log file that is, by default, located at logFile.txt in the working directory of your Unity application.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:BCI2000RemoteNET&diff=11354Contributions:BCI2000RemoteNET2024-05-24T23:01:41Z<p>Tytbutler: Added info about the Execute method</p>
<hr />
<div>==Synopsis==<br />
BCI2000RemoteNET is a library for controlling BCI2000 from .NET programs such as Unity. With C# top-level declarations, it can also be used as a replacement for [[User Reference:BCI2000Shell]] with the added step of compilation via [https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/ <code>csc</code>]. <br />
<br />
==Operation==<br />
<br />
BCI2000RemoteNET communicates with the BCI2000 Operator via [[User Reference:Operator Module Scripting|operator module scripting commands]], which are sent as text over TCP to a running Operator. It also provides functionality for starting the Operator directly, so it can control the Operator entirely from startup to shutdown. <br />
<br />
BCI2000RemoteNET consists of two classes, <code>BCI2000Connection</code>, which provides the basic functionality necessary for starting and communicating with BCI2000, and <code>BCI2000Remote</code>, which provides a set of methods for controlling a BCI2000 experiment, such as interacting with parameters and events, as well as starting modules and experiments.<br />
<br />
BCI2000RemoteNET comes in two versions, targeting .NET 8.0 and .NET Standard 2.1. This is due to compatibility with programs such as Unity, which require .NET Standard binaries. There is little difference in functionality between the two versions, other than the behavior of the <code>Execute()</code> method, whose differences are described below.<br />
<br />
==Documentation==<br />
Documentation for the classes can be found here:<br />
<br />
====.NET 8.0====<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
====.NET Standard 2.1====<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
==Installation==<br />
Acquire the latest binary from [https://github.com/neurotechcenter/BCI2000RemoteNET GitHub], or build from source from the source code on GitHub or in the main BCI2000 Subversion repository (Keep in mind that the version in the Subversion repository will likely be behind the version on GitHub.)<br />
<br />
==Usage==<br />
====Starting the operator====<br />
If you plan on starting the operator separately, skip this step, but make sure to start the operator with its <code>--Telnet</code> option set.<br />
<br />
In order to start the operator, call the <code>BCI2000Connection.StartOperator</code> method with the path to your BCI2000 Operator executable.<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
conn.StartOperator("Path/To/BCI2000/prog/Operator.exe");<br />
</pre><br />
<br />
By default, this will start an operator listening on <code>127.0.0.1:3999</code>. You can also set the Operator to listen on another port:<br />
<pre><br />
conn.StartOperator("path", port: 51101);<br />
</pre><br />
<br />
Or if you wish to accept connections from other computers you can set BCI2000 to listen on all addresses:<br />
<pre><br />
conn.StartOperator("path", address: "0.0.0.0");<br />
</pre><br />
<br />
Or listen on a specific network interface:<br />
<pre><br />
conn.StartOperator("path", address: "10.11.198.2");<br />
</pre><br />
<br />
<br />
====Connecting to the operator====<br />
Connect to the operator with the <code>BCI2000Connection.Connect()</code> method. If you started a local operator with default settings, then you can call <code>Connect</code> with its default parameters, which will connect to the operator at <code>127.0.0.1:3999</code>. If you are connecting to an operator on another machine, say at IP address <code>11.11.11.11</code>,or one listening on a port other than 3999, call <code>Connect()</code> with its optional parameters.<br />
Please see the [[#Note On Security]] for an important caveat of setting a non-default parameter here.<br />
<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
<br />
//Connect to operator on the same machine on the default port.<br />
conn.Connect();<br />
<br />
//Connect to operator at address 11.11.11.11:3999<br />
conn.Connect(address: "11.11.11.11");<br />
<br />
BCI2000Remote bci = new(conn);<br />
<br />
</pre><br />
<br />
====Adding parameters and events====<br />
At this point you can add parameters and events to BCI2000. <br />
Parameters are values which can be changed in the BCI2000 GUI and can be used to change how experiments behave.<br />
Parameters can either be loaded from a file:<br />
<pre><br />
//path is relative to the Operator's working directory, that is, the /prog directory of the BCI2000 installation<br />
bci.LoadParameters("path/to/parameterfile.prm");<br />
</pre><br />
or added individually:<br />
<pre><br />
//Parameter in the ParamArea section within the Application tab, with default value 0 <br />
bci.AddParameter("Application:ParamArea", "Param", "0");<br />
//Parameter in the ParamArea section within the Application tab, with default value "Green" <br />
bci.AddParameter("Application:ParamArea", "Param2", "Green");<br />
//Parameter in the ParamArea2 section within the Application tab, with default value 0 and range 0-10<br />
bci.AddParameter("Application:ParamArea", "Param3", "0", "0", "10");<br />
</pre><br />
<br />
Events are values logged by BCI2000 alongside the signal data. They have a temporal resolution equivalent to the sample rate, and can be set and read throughout data collection.<br />
Events are unsigned integers with a bit width between 1 and 32:<br />
<pre><br />
//An event called "condition" representing a boolean value with possible values 0 and 1. Will be zero by default.<br />
bci.AddEvent("condition", 1);<br />
//An 32-bit event with default value 100, and range 0 to 2^32 - 1.<br />
bci.AddEvent("value1", 32, 100);<br />
</pre><br />
<br />
====Starting BCI2000 Modules====<br />
BCI2000 modules are started using the <code>StartModules()</code> method, given a dictionary of module names and argument lists. For example, to open SignalGenerator, DummySignalProcessing, and DummyApplication with keyboard and mouse logging:<br />
<pre><br />
bci.StartupModules(new Dictionary<string, IEnumerable<string>?>()<br />
{<br />
{"SignalGenerator", new List<string>() {"LogKeyboard=1", "LogMouse=1"}},<br />
{"DummySignalProcessing", null},<br />
{"DummyApplication", null}<br />
});<br />
</pre><br />
<br />
====Setting Parameters and Visualizing Values====<br />
If using BCI2000RemoteNET as a substitute for BCI2000Shell for setting up the basic environment, this would usually be where you continue using BCI2000 through its own GUI.<br />
<br />
At this point parameters can be set via <code>SetParameter</code>, for example, setting up experiment parameters:<br />
<pre><br />
bci.SetParameter("DataDirectory", "../data/theDirectory");<br />
bci.SetParameter("SubjectName", "APatient");<br />
bci.SetParameter("SubjectSession", "004");<br />
</pre><br />
<br />
You can also set values such as events to be shown in a graph view. <br />
For example, since we set the source module to start with mouse logging enabled, we can view the values of the mouse position events.<br />
<pre><br />
bci.Visualize("MousePosX");<br />
bci.Visualize("MousePosY");<br />
</pre><br />
We can also visualize the events we added earlier.<br />
<pre><br />
bci.Visualize("condition");<br />
bci.Visualize("value1");<br />
</pre><br />
<br />
====Collecting Data====<br />
Start collecting data with the <code>Start()</code> method. This will implicitly call <code>SetConfig()</code>, but it can be called separately as well.<br />
<pre><br />
bci.Start();<br />
</pre><br />
If you instead want to start BCI2000 through the GUI, and wait for it in this program, you can instead wait for BCI2000 to be in the <code>Running</code> state.<br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Running);<br />
</pre><br />
<br />
During a run you can interact with BCI2000 by setting event variables:<br />
<pre><br />
bci.SetEvent("value1", 400);<br />
</pre><br />
<br />
You can also pulse events, setting their value for one sample duration before setting them back.<br />
<pre><br />
bci.PulseEvent("condition", 1);<br />
</pre><br />
<br />
You can also get values from BCI2000. As we set the source module to log the mouse position earlier, we can retrieve its value via <code>GetEvent()</code>.<br />
<pre><br />
uint mousePositionX = bci.GetEvent("MousePosX");<br />
uint mousePositionY = bci.GetEvent("MousePosY");<br />
</pre><br />
<br />
You can also retrieve the value of the hardware signal. <br />
<pre><br />
//Get value of element 2 of channel 1 of signal<br />
double signal11 = bci.GetSignal(1, 2);X");<br />
</pre><br />
<br />
====Stopping BCI2000====<br />
When you are finished collecting data, stop BCI2000 with the <code>BCI2000Connection.Stop()</code> method.<br />
<pre><br />
bci.connection.Stop();<br />
</pre><br />
<br />
You can also shut down BCI2000.<br />
<pre><br />
bci.connection.Quit();<br />
</pre><br />
<br />
If you instead want to stop BCI2000 via the GUI, you can wait for the system to be in the <code>Suspended</code> state. <br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Connected);<br />
</pre><br />
<br />
Or if you want to poll the system state repeatedly (in a loop, for example);<br />
<pre> <br />
bool loop = true;<br />
while (loop) {<br />
...<br />
if (bci.GetSystemState() == BCI2000Remote.SystemState.Suspended) {<br />
loop = false;<br />
}<br />
}<br />
</pre><br />
<br />
====Using other BCI2000 Commands====<br />
<br />
An arbitrary operator command can be sent using the <code>BCI2000Connection.Execute</code> method. In the .NET 8.0 version, <code>Execute()</code> and <code>Execute<T>()</code> are used. <code>Execute()</code> executes the command and throws an exception if it receives anything other than an empty response, whereas <code>Execute<T></code>, where <code>T</code> is a type that implements <code>IParsable</code>, executes the command and attempts to parse the response as type <code>T</code>. <br />
<br />
For example, setting the BCI2000 log level:<br />
<br />
<pre><br />
bci.Execute("set LogLevel 0");<br />
</pre><br />
<br />
Checking if an event exists:<br />
<br />
<pre><br />
bool eventExists = bci.Execute<bool>("exists event EventName");<br />
</pre><br />
<br />
Receiving the BCI2000 system version info:<br />
<br />
<pre><br />
Console.WriteLine(bci.Execute<string>("get system version"));<br />
</pre><br />
<br />
In the .NET Standard 2.1 version, there is no generic <code>Execute<T>()</code>, because the version of C# used by .NET Standard 2.1 does not include the <code>IParsable</code> interface. Instead, <code>ExecuteString, ExecuteBool, ExecuteUInt32, and ExecuteDouble</code> provide the functionality of parsing responses as basic types. If you need to interpret the response as a different type, use <code>ExecuteString</code> and parse the result. <br />
<br />
==Examples==<br />
Embedding BCI2000RemoteNET within another program is largely covered above, so this section focuses on alternative usecases.<br />
<br />
====Using BCI2000RemoteNET as a substitute for BCI2000Shell====<br />
BCI2000RemoteNET can be used as a replacement for BCI2000Shell when starting up BCI2000, if you need more advanced language capabilities than what the operator scripting language can provide.<br />
<br />
This is the existing startup script for the Stimulus Presentation task with the software Signal Generator.<br />
<pre>/batch/StimulusPresentation_SignalGenerator.bat</pre><br />
<pre><br />
#! ../prog/BCI2000Shell<br />
@cls & ..\prog\BCI2000Shell %0 %* #! && exit /b 0 || exit /b 1\n<br />
Change directory $BCI2000LAUNCHDIR<br />
Show window; Set title ${Extract file base $0}<br />
Reset system<br />
Startup system localhost<br />
Start executable SignalGenerator --local --LogKeyboard=1 --SpinningWheel=1 --ShowDisplayStatistics=1<br />
Start executable P3SignalProcessing --local<br />
Start executable StimulusPresentation --local<br />
Wait for Connected<br />
Load parameterfile "../parms/examples/StimulusPresentation_SignalGenerator.prm"<br />
</pre><br />
<br />
This is the equivalent C# code using BCI2000RemoteNET:<br />
<pre>/batch/StimulusPresentation_SignalGenerator.cs</pre><br />
<pre><br />
using BCI2000RemoteNET;<br />
using System.RuntimeInformation.InteropServices;<br />
BCI2000Remote bci = new(new BCI2000Connection());<br />
bool isWindows = RuntimeInformation.IsOSPlatform(OSPlatform.Windows);<br />
bci.connection.StartOperator("../prog/Operator" + isWindows ? ".exe" : ""); //Add file extension if on windows <br />
bci.connection.Connect();<br />
bci.LoadParameters("../parms/examples/StimulusPresentation_SignalGenerator.prm");<br />
bci.StartupModules(new Dictionary<string, IEnumerable<string>?> {<br />
{"SignalGenerator", new() {"LogKeyboard=1", "SpinningWheel=1", "ShowDisplayStatistics=1"}},<br />
{"P3SignalProcessing", null},<br />
{"StimulusPresentation", null}<br />
});<br />
</pre> <br />
<br />
C# startup scripts have access to all of the constructs of the C# language, so different actions can be taken depending on conditions such as the operating system, as seen in the above script, or take other input such as command line options.<br />
Note that this will need to be part of a C# project, created via <code>dotnet new console</code> with its accompanied <code>.csproj</code> file.<br />
<br />
An alternative would be to instead use a PowerShell or F# script, which can then be run via <code>pwsh</code> or <code>dotnet fsi</code>. This is the equivalent F# code:<br />
<pre>/batch/StimulusPresentation_SignalGenerator.fsx</pre><br />
<pre><br />
#r "../BCI2000RemoteNET.dll"<br />
open BCI2000RemoteNET<br />
open System.Runtime.InteropServices<br />
let bci = new BCI2000Remote(new BCI2000Connection()) in<br />
let isWindows = RuntimeInformation.IsOSPlatform(OSPlatform.Windows) in<br />
let operatorPath = "../../bci2000/prog/Operator" + if isWindows then ".exe" else "" in<br />
bci.connection.StartOperator operatorPath;<br />
bci.connection.Connect ();<br />
bci.LoadParameters "../parms/examples/StimulusPresentation_SignalGenerator.prm";<br />
bci.StartupModules <| Map [<br />
("SignalGenerator", ["LogKeyboard=1"; "SpinningWheel=1"; "ShowDisplayStatistics=1"]);<br />
("P3SignalProcessing", null);<br />
("StimulusPresentation", null);<br />
]<br />
</pre><br />
This can be run directly:<br />
<code>dotnet fsi StimulusPresentation_SignalGenerator.fsx</code><br />
<br />
==Note On Security==<br />
The BCI2000 command line interface can be used to run arbitrary system shell commands. It is also entirely unsecured and unencrypted. Anyone who has access to it effectively has full access to the computer on which it runs. This is not a problem if running locally, and is generally not a problem if running on a firewalled local network. However, due to the unsecured nature of the interface, running BCI2000 across the internet is highly discouraged. That is, if you set BCI2000 to listen at an address of an external network interface, or to listen at all connections by passing the address <code>0.0.0.0</code>, make sure that port 3999 (or whichever port BCI2000 is listening on), is not forwarded beyond the local network by your router. Support for securely connecting to BCI2000 is planned for the future.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:BCI2000RemoteNET&diff=11353Contributions:BCI2000RemoteNET2024-05-24T20:54:34Z<p>Tytbutler: </p>
<hr />
<div>==Synopsis==<br />
BCI2000RemoteNET is a library for controlling BCI2000 from .NET programs such as Unity. With C# top-level declarations, it can also be used as a replacement for [[User Reference:BCI2000Shell]] with the added step of compilation via [https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/ <code>csc</code>]. <br />
<br />
==Operation==<br />
<br />
BCI2000RemoteNET communicates with the BCI2000 Operator via [[User Reference:Operator Module Scripting|operator module scripting commands]], which are sent as text over TCP to a running Operator. It also provides functionality for starting the Operator directly, so it can control the Operator entirely from startup to shutdown. <br />
<br />
BCI2000RemoteNET consists of two classes, <code>BCI2000Connection</code>, which provides the basic functionality necessary for starting and communicating with BCI2000, and <code>BCI2000Remote</code>, which provides a set of methods for controlling a BCI2000 experiment, such as interacting with parameters and events, as well as starting modules and experiments.<br />
<br />
BCI2000RemoteNET comes in two versions, targeting .NET 8.0 and .NET Standard 2.1. This is due to compatibility with programs such as Unity, which require .NET Standard binaries. There is little difference in functionality between the two versions, other than the behavior of the <code>Execute()</code> method, whose differences are described below.<br />
<br />
==Documentation==<br />
Documentation for the classes can be found here:<br />
<br />
====.NET 8.0====<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
====.NET Standard 2.1====<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
==Installation==<br />
Acquire the latest binary from [https://github.com/neurotechcenter/BCI2000RemoteNET GitHub], or build from source from the source code on GitHub or in the main BCI2000 Subversion repository (Keep in mind that the version in the Subversion repository will likely be behind the version on GitHub.)<br />
<br />
==Usage==<br />
====Starting the operator====<br />
If you plan on starting the operator separately, skip this step, but make sure to start the operator with its <code>--Telnet</code> option set.<br />
<br />
In order to start the operator, call the <code>BCI2000Connection.StartOperator</code> method with the path to your BCI2000 Operator executable.<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
conn.StartOperator("Path/To/BCI2000/prog/Operator.exe");<br />
</pre><br />
<br />
By default, this will start an operator listening on <code>127.0.0.1:3999</code>. You can also set the Operator to listen on another port:<br />
<pre><br />
conn.StartOperator("path", port: 51101);<br />
</pre><br />
<br />
Or if you wish to accept connections from other computers you can set BCI2000 to listen on all addresses:<br />
<pre><br />
conn.StartOperator("path", address: "0.0.0.0");<br />
</pre><br />
<br />
Or listen on a specific network interface:<br />
<pre><br />
conn.StartOperator("path", address: "10.11.198.2");<br />
</pre><br />
<br />
<br />
====Connecting to the operator====<br />
Connect to the operator with the <code>BCI2000Connection.Connect()</code> method. If you started a local operator with default settings, then you can call <code>Connect</code> with its default parameters, which will connect to the operator at <code>127.0.0.1:3999</code>. If you are connecting to an operator on another machine, say at IP address <code>11.11.11.11</code>,or one listening on a port other than 3999, call <code>Connect()</code> with its optional parameters.<br />
Please see the [[#Note On Security]] for an important caveat of setting a non-default parameter here.<br />
<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
<br />
//Connect to operator on the same machine on the default port.<br />
conn.Connect();<br />
<br />
//Connect to operator at address 11.11.11.11:3999<br />
conn.Connect(address: "11.11.11.11");<br />
<br />
BCI2000Remote bci = new(conn);<br />
<br />
</pre><br />
<br />
====Adding parameters and events====<br />
At this point you can add parameters and events to BCI2000. <br />
Parameters are values which can be changed in the BCI2000 GUI and can be used to change how experiments behave.<br />
Parameters can either be loaded from a file:<br />
<pre><br />
//path is relative to the Operator's working directory, that is, the /prog directory of the BCI2000 installation<br />
bci.LoadParameters("path/to/parameterfile.prm");<br />
</pre><br />
or added individually:<br />
<pre><br />
//Parameter in the ParamArea section within the Application tab, with default value 0 <br />
bci.AddParameter("Application:ParamArea", "Param", "0");<br />
//Parameter in the ParamArea section within the Application tab, with default value "Green" <br />
bci.AddParameter("Application:ParamArea", "Param2", "Green");<br />
//Parameter in the ParamArea2 section within the Application tab, with default value 0 and range 0-10<br />
bci.AddParameter("Application:ParamArea", "Param3", "0", "0", "10");<br />
</pre><br />
<br />
Events are values logged by BCI2000 alongside the signal data. They have a temporal resolution equivalent to the sample rate, and can be set and read throughout data collection.<br />
Events are unsigned integers with a bit width between 1 and 32:<br />
<pre><br />
//An event called "condition" representing a boolean value with possible values 0 and 1. Will be zero by default.<br />
bci.AddEvent("condition", 1);<br />
//An 32-bit event with default value 100, and range 0 to 2^32 - 1.<br />
bci.AddEvent("value1", 32, 100);<br />
</pre><br />
<br />
====Starting BCI2000 Modules====<br />
BCI2000 modules are started using the <code>StartModules()</code> method, given a dictionary of module names and argument lists. For example, to open SignalGenerator, DummySignalProcessing, and DummyApplication with keyboard and mouse logging:<br />
<pre><br />
bci.StartupModules(new Dictionary<string, IEnumerable<string>?>()<br />
{<br />
{"SignalGenerator", new List<string>() {"LogKeyboard=1", "LogMouse=1"}},<br />
{"DummySignalProcessing", null},<br />
{"DummyApplication", null}<br />
});<br />
</pre><br />
<br />
====Setting Parameters and Visualizing Values====<br />
If using BCI2000RemoteNET as a substitute for BCI2000Shell for setting up the basic environment, this would usually be where you continue using BCI2000 through its own GUI.<br />
<br />
At this point parameters can be set via <code>SetParameter</code>, for example, setting up experiment parameters:<br />
<pre><br />
bci.SetParameter("DataDirectory", "../data/theDirectory");<br />
bci.SetParameter("SubjectName", "APatient");<br />
bci.SetParameter("SubjectSession", "004");<br />
</pre><br />
<br />
You can also set values such as events to be shown in a graph view. <br />
For example, since we set the source module to start with mouse logging enabled, we can view the values of the mouse position events.<br />
<pre><br />
bci.Visualize("MousePosX");<br />
bci.Visualize("MousePosY");<br />
</pre><br />
We can also visualize the events we added earlier.<br />
<pre><br />
bci.Visualize("condition");<br />
bci.Visualize("value1");<br />
</pre><br />
<br />
====Collecting Data====<br />
Start collecting data with the <code>Start()</code> method. This will implicitly call <code>SetConfig()</code>, but it can be called separately as well.<br />
<pre><br />
bci.Start();<br />
</pre><br />
If you instead want to start BCI2000 through the GUI, and wait for it in this program, you can instead wait for BCI2000 to be in the <code>Running</code> state.<br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Running);<br />
</pre><br />
<br />
During a run you can interact with BCI2000 by setting event variables:<br />
<pre><br />
bci.SetEvent("value1", 400);<br />
</pre><br />
<br />
You can also pulse events, setting their value for one sample duration before setting them back.<br />
<pre><br />
bci.PulseEvent("condition", 1);<br />
</pre><br />
<br />
You can also get values from BCI2000. As we set the source module to log the mouse position earlier, we can retrieve its value via <code>GetEvent()</code>.<br />
<pre><br />
uint mousePositionX = bci.GetEvent("MousePosX");<br />
uint mousePositionY = bci.GetEvent("MousePosY");<br />
</pre><br />
<br />
You can also retrieve the value of the hardware signal. <br />
<pre><br />
//Get value of element 2 of channel 1 of signal<br />
double signal11 = bci.GetSignal(1, 2);X");<br />
</pre><br />
<br />
====Stopping BCI2000====<br />
When you are finished collecting data, stop BCI2000 with the <code>BCI2000Connection.Stop()</code> method.<br />
<pre><br />
bci.connection.Stop();<br />
</pre><br />
<br />
You can also shut down BCI2000.<br />
<pre><br />
bci.connection.Quit();<br />
</pre><br />
<br />
If you instead want to stop BCI2000 via the GUI, you can wait for the system to be in the <code>Suspended</code> state. <br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Connected);<br />
</pre><br />
<br />
Or if you want to poll the system state repeatedly (in a loop, for example);<br />
<pre> <br />
bool loop = true;<br />
while (loop) {<br />
...<br />
if (bci.GetSystemState() == BCI2000Remote.SystemState.Suspended) {<br />
loop = false;<br />
}<br />
}<br />
</pre><br />
<br />
==Examples==<br />
Embedding BCI2000RemoteNET within another program is largely covered above, so this section focuses on alternative usecases.<br />
<br />
====Using BCI2000RemoteNET as a substitute for BCI2000Shell====<br />
BCI2000RemoteNET can be used as a replacement for BCI2000Shell when starting up BCI2000, if you need more advanced language capabilities than what the operator scripting language can provide.<br />
<br />
This is the existing startup script for the Stimulus Presentation task with the software Signal Generator.<br />
<pre>/batch/StimulusPresentation_SignalGenerator.bat</pre><br />
<pre><br />
#! ../prog/BCI2000Shell<br />
@cls & ..\prog\BCI2000Shell %0 %* #! && exit /b 0 || exit /b 1\n<br />
Change directory $BCI2000LAUNCHDIR<br />
Show window; Set title ${Extract file base $0}<br />
Reset system<br />
Startup system localhost<br />
Start executable SignalGenerator --local --LogKeyboard=1 --SpinningWheel=1 --ShowDisplayStatistics=1<br />
Start executable P3SignalProcessing --local<br />
Start executable StimulusPresentation --local<br />
Wait for Connected<br />
Load parameterfile "../parms/examples/StimulusPresentation_SignalGenerator.prm"<br />
</pre><br />
<br />
This is the equivalent C# code using BCI2000RemoteNET:<br />
<pre>/batch/StimulusPresentation_SignalGenerator.cs</pre><br />
<pre><br />
using BCI2000RemoteNET;<br />
using System.RuntimeInformation.InteropServices;<br />
BCI2000Remote bci = new(new BCI2000Connection());<br />
bool isWindows = RuntimeInformation.IsOSPlatform(OSPlatform.Windows);<br />
bci.connection.StartOperator("../prog/Operator" + isWindows ? ".exe" : ""); //Add file extension if on windows <br />
bci.connection.Connect();<br />
bci.LoadParameters("../parms/examples/StimulusPresentation_SignalGenerator.prm");<br />
bci.StartupModules(new Dictionary<string, IEnumerable<string>?> {<br />
{"SignalGenerator", new() {"LogKeyboard=1", "SpinningWheel=1", "ShowDisplayStatistics=1"}},<br />
{"P3SignalProcessing", null},<br />
{"StimulusPresentation", null}<br />
});<br />
</pre> <br />
<br />
C# startup scripts have access to all of the constructs of the C# language, so different actions can be taken depending on conditions such as the operating system, as seen in the above script, or take other input such as command line options.<br />
Note that this will need to be part of a C# project, created via <code>dotnet new console</code> with its accompanied <code>.csproj</code> file.<br />
<br />
An alternative would be to instead use a PowerShell or F# script, which can then be run via <code>pwsh</code> or <code>dotnet fsi</code>. This is the equivalent F# code:<br />
<pre>/batch/StimulusPresentation_SignalGenerator.fsx</pre><br />
<pre><br />
#r "../BCI2000RemoteNET.dll"<br />
open BCI2000RemoteNET<br />
open System.Runtime.InteropServices<br />
let bci = new BCI2000Remote(new BCI2000Connection()) in<br />
let isWindows = RuntimeInformation.IsOSPlatform(OSPlatform.Windows) in<br />
let operatorPath = "../../bci2000/prog/Operator" + if isWindows then ".exe" else "" in<br />
bci.connection.StartOperator operatorPath;<br />
bci.connection.Connect ();<br />
bci.LoadParameters "../parms/examples/StimulusPresentation_SignalGenerator.prm";<br />
bci.StartupModules <| Map [<br />
("SignalGenerator", ["LogKeyboard=1"; "SpinningWheel=1"; "ShowDisplayStatistics=1"]);<br />
("P3SignalProcessing", null);<br />
("StimulusPresentation", null);<br />
]<br />
</pre><br />
This can be run directly:<br />
<code>dotnet fsi StimulusPresentation_SignalGenerator.fsx</code><br />
<br />
==Note On Security==<br />
The BCI2000 command line interface can be used to run arbitrary system shell commands. It is also entirely unsecured and unencrypted. Anyone who has access to it effectively has full access to the computer on which it runs. This is not a problem if running locally, and is generally not a problem if running on a firewalled local network. However, due to the unsecured nature of the interface, running BCI2000 across the internet is highly discouraged. That is, if you set BCI2000 to listen at an address of an external network interface, or to listen at all connections by passing the address <code>0.0.0.0</code>, make sure that port 3999 (or whichever port BCI2000 is listening on), is not forwarded beyond the local network by your router. Support for securely connecting to BCI2000 is planned for the future.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:BCI2000RemoteNET&diff=11352Contributions:BCI2000RemoteNET2024-05-24T20:53:34Z<p>Tytbutler: Fixed start up modules documentation</p>
<hr />
<div>==Synopsis==<br />
BCI2000RemoteNET is a library for controlling BCI2000 from .NET programs such as Unity. With C# top-level declarations, it can also be used as a replacement for [[User Reference:BCI2000Shell]] with the added step of compilation via [https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/ <code>csc</code>]. <br />
<br />
==Operation==<br />
<br />
BCI2000RemoteNET communicates with the BCI2000 Operator via [[User Reference:Operator Module Scripting|operator module scripting commands]], which are sent as text over TCP to a running Operator. It also provides functionality for starting the Operator directly, so it can control the Operator entirely from startup to shutdown. <br />
<br />
BCI2000RemoteNET consists of two classes, <code>BCI2000Connection</code>, which provides the basic functionality necessary for starting and communicating with BCI2000, and <code>BCI2000Remote</code>, which provides a set of methods for controlling a BCI2000 experiment, such as interacting with parameters and events, as well as starting modules and experiments.<br />
<br />
BCI2000RemoteNET comes in two versions, targeting .NET 8.0 and .NET Standard 2.1. This is due to compatibility with programs such as Unity, which require .NET Standard binaries. There is little difference in functionality between the two versions, other than the behavior of the <code>Execute()</code> method, whose differences are described below.<br />
<br />
==Documentation==<br />
Documentation for the classes can be found here:<br />
<br />
====.NET 8.0====<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
====.NET Standard 2.1====<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
==Installation==<br />
Acquire the latest binary from [https://github.com/neurotechcenter/BCI2000RemoteNET GitHub], or build from source from the source code on GitHub or in the main BCI2000 Subversion repository (Keep in mind that the version in the Subversion repository will likely be behind the version on GitHub.)<br />
<br />
==Usage==<br />
====Starting the operator====<br />
If you plan on starting the operator separately, skip this step, but make sure to start the operator with its <code>--Telnet</code> option set.<br />
<br />
In order to start the operator, call the <code>BCI2000Connection.StartOperator</code> method with the path to your BCI2000 Operator executable.<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
conn.StartOperator("Path/To/BCI2000/prog/Operator.exe");<br />
</pre><br />
<br />
By default, this will start an operator listening on <code>127.0.0.1:3999</code>. You can also set the Operator to listen on another port:<br />
<pre><br />
conn.StartOperator("path", port: 51101);<br />
</pre><br />
<br />
Or if you wish to accept connections from other computers you can set BCI2000 to listen on all addresses:<br />
<pre><br />
conn.StartOperator("path", address: "0.0.0.0");<br />
</pre><br />
<br />
Or listen on a specific network interface:<br />
<pre><br />
conn.StartOperator("path", address: "10.11.198.2");<br />
</pre><br />
<br />
<br />
====Connecting to the operator====<br />
Connect to the operator with the <code>BCI2000Connection.Connect()</code> method. If you started a local operator with default settings, then you can call <code>Connect</code> with its default parameters, which will connect to the operator at <code>127.0.0.1:3999</code>. If you are connecting to an operator on another machine, say at IP address <code>11.11.11.11</code>,or one listening on a port other than 3999, call <code>Connect()</code> with its optional parameters.<br />
Please see the [[#Note On Security]] for an important caveat of setting a non-default parameter here.<br />
<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
<br />
//Connect to operator on the same machine on the default port.<br />
conn.Connect();<br />
<br />
//Connect to operator at address 11.11.11.11:3999<br />
conn.Connect(address: "11.11.11.11");<br />
<br />
</pre><br />
<br />
====Adding parameters and events====<br />
At this point you can add parameters and events to BCI2000. <br />
Parameters are values which can be changed in the BCI2000 GUI and can be used to change how experiments behave.<br />
Parameters can either be loaded from a file:<br />
<pre><br />
//path is relative to the Operator's working directory, that is, the /prog directory of the BCI2000 installation<br />
bci.LoadParameters("path/to/parameterfile.prm");<br />
</pre><br />
or added individually:<br />
<pre><br />
//Parameter in the ParamArea section within the Application tab, with default value 0 <br />
bci.AddParameter("Application:ParamArea", "Param", "0");<br />
//Parameter in the ParamArea section within the Application tab, with default value "Green" <br />
bci.AddParameter("Application:ParamArea", "Param2", "Green");<br />
//Parameter in the ParamArea2 section within the Application tab, with default value 0 and range 0-10<br />
bci.AddParameter("Application:ParamArea", "Param3", "0", "0", "10");<br />
</pre><br />
<br />
Events are values logged by BCI2000 alongside the signal data. They have a temporal resolution equivalent to the sample rate, and can be set and read throughout data collection.<br />
Events are unsigned integers with a bit width between 1 and 32:<br />
<pre><br />
//An event called "condition" representing a boolean value with possible values 0 and 1. Will be zero by default.<br />
bci.AddEvent("condition", 1);<br />
//An 32-bit event with default value 100, and range 0 to 2^32 - 1.<br />
bci.AddEvent("value1", 32, 100);<br />
</pre><br />
<br />
====Starting BCI2000 Modules====<br />
BCI2000 modules are started using the <code>StartModules()</code> method, given a dictionary of module names and argument lists. For example, to open SignalGenerator, DummySignalProcessing, and DummyApplication with keyboard and mouse logging:<br />
<pre><br />
bci.StartupModules(new Dictionary<string, IEnumerable<string>?>()<br />
{<br />
{"SignalGenerator", new List<string>() {"LogKeyboard=1", "LogMouse=1"}},<br />
{"DummySignalProcessing", null},<br />
{"DummyApplication", null}<br />
});<br />
</pre><br />
<br />
====Setting Parameters and Visualizing Values====<br />
If using BCI2000RemoteNET as a substitute for BCI2000Shell for setting up the basic environment, this would usually be where you continue using BCI2000 through its own GUI.<br />
<br />
At this point parameters can be set via <code>SetParameter</code>, for example, setting up experiment parameters:<br />
<pre><br />
bci.SetParameter("DataDirectory", "../data/theDirectory");<br />
bci.SetParameter("SubjectName", "APatient");<br />
bci.SetParameter("SubjectSession", "004");<br />
</pre><br />
<br />
You can also set values such as events to be shown in a graph view. <br />
For example, since we set the source module to start with mouse logging enabled, we can view the values of the mouse position events.<br />
<pre><br />
bci.Visualize("MousePosX");<br />
bci.Visualize("MousePosY");<br />
</pre><br />
We can also visualize the events we added earlier.<br />
<pre><br />
bci.Visualize("condition");<br />
bci.Visualize("value1");<br />
</pre><br />
<br />
====Collecting Data====<br />
Start collecting data with the <code>Start()</code> method. This will implicitly call <code>SetConfig()</code>, but it can be called separately as well.<br />
<pre><br />
bci.Start();<br />
</pre><br />
If you instead want to start BCI2000 through the GUI, and wait for it in this program, you can instead wait for BCI2000 to be in the <code>Running</code> state.<br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Running);<br />
</pre><br />
<br />
During a run you can interact with BCI2000 by setting event variables:<br />
<pre><br />
bci.SetEvent("value1", 400);<br />
</pre><br />
<br />
You can also pulse events, setting their value for one sample duration before setting them back.<br />
<pre><br />
bci.PulseEvent("condition", 1);<br />
</pre><br />
<br />
You can also get values from BCI2000. As we set the source module to log the mouse position earlier, we can retrieve its value via <code>GetEvent()</code>.<br />
<pre><br />
uint mousePositionX = bci.GetEvent("MousePosX");<br />
uint mousePositionY = bci.GetEvent("MousePosY");<br />
</pre><br />
<br />
You can also retrieve the value of the hardware signal. <br />
<pre><br />
//Get value of element 2 of channel 1 of signal<br />
double signal11 = bci.GetSignal(1, 2);X");<br />
</pre><br />
<br />
====Stopping BCI2000====<br />
When you are finished collecting data, stop BCI2000 with the <code>BCI2000Connection.Stop()</code> method.<br />
<pre><br />
bci.connection.Stop();<br />
</pre><br />
<br />
You can also shut down BCI2000.<br />
<pre><br />
bci.connection.Quit();<br />
</pre><br />
<br />
If you instead want to stop BCI2000 via the GUI, you can wait for the system to be in the <code>Suspended</code> state. <br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Connected);<br />
</pre><br />
<br />
Or if you want to poll the system state repeatedly (in a loop, for example);<br />
<pre> <br />
bool loop = true;<br />
while (loop) {<br />
...<br />
if (bci.GetSystemState() == BCI2000Remote.SystemState.Suspended) {<br />
loop = false;<br />
}<br />
}<br />
</pre><br />
<br />
==Examples==<br />
Embedding BCI2000RemoteNET within another program is largely covered above, so this section focuses on alternative usecases.<br />
<br />
====Using BCI2000RemoteNET as a substitute for BCI2000Shell====<br />
BCI2000RemoteNET can be used as a replacement for BCI2000Shell when starting up BCI2000, if you need more advanced language capabilities than what the operator scripting language can provide.<br />
<br />
This is the existing startup script for the Stimulus Presentation task with the software Signal Generator.<br />
<pre>/batch/StimulusPresentation_SignalGenerator.bat</pre><br />
<pre><br />
#! ../prog/BCI2000Shell<br />
@cls & ..\prog\BCI2000Shell %0 %* #! && exit /b 0 || exit /b 1\n<br />
Change directory $BCI2000LAUNCHDIR<br />
Show window; Set title ${Extract file base $0}<br />
Reset system<br />
Startup system localhost<br />
Start executable SignalGenerator --local --LogKeyboard=1 --SpinningWheel=1 --ShowDisplayStatistics=1<br />
Start executable P3SignalProcessing --local<br />
Start executable StimulusPresentation --local<br />
Wait for Connected<br />
Load parameterfile "../parms/examples/StimulusPresentation_SignalGenerator.prm"<br />
</pre><br />
<br />
This is the equivalent C# code using BCI2000RemoteNET:<br />
<pre>/batch/StimulusPresentation_SignalGenerator.cs</pre><br />
<pre><br />
using BCI2000RemoteNET;<br />
using System.RuntimeInformation.InteropServices;<br />
BCI2000Remote bci = new(new BCI2000Connection());<br />
bool isWindows = RuntimeInformation.IsOSPlatform(OSPlatform.Windows);<br />
bci.connection.StartOperator("../prog/Operator" + isWindows ? ".exe" : ""); //Add file extension if on windows <br />
bci.connection.Connect();<br />
bci.LoadParameters("../parms/examples/StimulusPresentation_SignalGenerator.prm");<br />
bci.StartupModules(new Dictionary<string, IEnumerable<string>?> {<br />
{"SignalGenerator", new() {"LogKeyboard=1", "SpinningWheel=1", "ShowDisplayStatistics=1"}},<br />
{"P3SignalProcessing", null},<br />
{"StimulusPresentation", null}<br />
});<br />
</pre> <br />
<br />
C# startup scripts have access to all of the constructs of the C# language, so different actions can be taken depending on conditions such as the operating system, as seen in the above script, or take other input such as command line options.<br />
Note that this will need to be part of a C# project, created via <code>dotnet new console</code> with its accompanied <code>.csproj</code> file.<br />
<br />
An alternative would be to instead use a PowerShell or F# script, which can then be run via <code>pwsh</code> or <code>dotnet fsi</code>. This is the equivalent F# code:<br />
<pre>/batch/StimulusPresentation_SignalGenerator.fsx</pre><br />
<pre><br />
#r "../BCI2000RemoteNET.dll"<br />
open BCI2000RemoteNET<br />
open System.Runtime.InteropServices<br />
let bci = new BCI2000Remote(new BCI2000Connection()) in<br />
let isWindows = RuntimeInformation.IsOSPlatform(OSPlatform.Windows) in<br />
let operatorPath = "../../bci2000/prog/Operator" + if isWindows then ".exe" else "" in<br />
bci.connection.StartOperator operatorPath;<br />
bci.connection.Connect ();<br />
bci.LoadParameters "../parms/examples/StimulusPresentation_SignalGenerator.prm";<br />
bci.StartupModules <| Map [<br />
("SignalGenerator", ["LogKeyboard=1"; "SpinningWheel=1"; "ShowDisplayStatistics=1"]);<br />
("P3SignalProcessing", null);<br />
("StimulusPresentation", null);<br />
]<br />
</pre><br />
This can be run directly:<br />
<code>dotnet fsi StimulusPresentation_SignalGenerator.fsx</code><br />
<br />
==Note On Security==<br />
The BCI2000 command line interface can be used to run arbitrary system shell commands. It is also entirely unsecured and unencrypted. Anyone who has access to it effectively has full access to the computer on which it runs. This is not a problem if running locally, and is generally not a problem if running on a firewalled local network. However, due to the unsecured nature of the interface, running BCI2000 across the internet is highly discouraged. That is, if you set BCI2000 to listen at an address of an external network interface, or to listen at all connections by passing the address <code>0.0.0.0</code>, make sure that port 3999 (or whichever port BCI2000 is listening on), is not forwarded beyond the local network by your router. Support for securely connecting to BCI2000 is planned for the future.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:BCI2000RemoteNET&diff=11337Contributions:BCI2000RemoteNET2024-05-21T14:31:16Z<p>Tytbutler: Change wording of future plans</p>
<hr />
<div>==Synopsis==<br />
BCI2000RemoteNET is a library for controlling BCI2000 from .NET programs such as Unity. With C# top-level declarations, it can also be used as a replacement for [[User Reference:BCI2000Shell]] with the added step of compilation via [https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/ <code>csc</code>]. <br />
<br />
==Operation==<br />
<br />
BCI2000RemoteNET communicates with the BCI2000 Operator via [[User Reference:Operator Module Scripting|operator module scripting commands]], which are sent as text over TCP to a running Operator. It also provides functionality for starting the Operator directly, so it can control the Operator entirely from startup to shutdown. <br />
<br />
BCI2000RemoteNET consists of two classes, <code>BCI2000Connection</code>, which provides the basic functionality necessary for starting and communicating with BCI2000, and <code>BCI2000Remote</code>, which provides a set of methods for controlling a BCI2000 experiment, such as interacting with parameters and events, as well as starting modules and experiments.<br />
<br />
BCI2000RemoteNET comes in two versions, targeting .NET 8.0 and .NET Standard 2.1. This is due to compatibility with programs such as Unity, which require .NET Standard binaries. There is little difference in functionality between the two versions, other than the behavior of the <code>Execute()</code> method, whose differences are described below.<br />
<br />
==Documentation==<br />
Documentation for the classes can be found here:<br />
<br />
====.NET 8.0====<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
====.NET Standard 2.1====<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
==Installation==<br />
Acquire the latest binary from [https://github.com/neurotechcenter/BCI2000RemoteNET GitHub], or build from source from the source code on GitHub or in the main BCI2000 Subversion repository (Keep in mind that the version in the Subversion repository will likely be behind the version on GitHub.)<br />
<br />
==Usage==<br />
====Starting the operator====<br />
If you plan on starting the operator separately, skip this step, but make sure to start the operator with its <code>--Telnet</code> option set.<br />
<br />
In order to start the operator, call the <code>BCI2000Connection.StartOperator</code> method with the path to your BCI2000 Operator executable.<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
conn.StartOperator("Path/To/BCI2000/prog/Operator.exe");<br />
</pre><br />
<br />
By default, this will start an operator listening on <code>127.0.0.1:3999</code>. You can also set the Operator to listen on another port:<br />
<pre><br />
conn.StartOperator("path", port: 51101);<br />
</pre><br />
<br />
Or if you wish to accept connections from other computers you can set BCI2000 to listen on all addresses:<br />
<pre><br />
conn.StartOperator("path", address: "0.0.0.0");<br />
</pre><br />
<br />
Or listen on a specific network interface:<br />
<pre><br />
conn.StartOperator("path", address: "10.11.198.2");<br />
</pre><br />
<br />
<br />
====Connecting to the operator====<br />
Connect to the operator with the <code>BCI2000Connection.Connect()</code> method. If you started a local operator with default settings, then you can call <code>Connect</code> with its default parameters, which will connect to the operator at <code>127.0.0.1:3999</code>. If you are connecting to an operator on another machine, say at IP address <code>11.11.11.11</code>,or one listening on a port other than 3999, call <code>Connect()</code> with its optional parameters.<br />
Please see the [[#Note On Security]] for an important caveat of setting a non-default parameter here.<br />
<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
<br />
//Connect to operator on the same machine on the default port.<br />
conn.Connect();<br />
<br />
//Connect to operator at address 11.11.11.11:3999<br />
conn.Connect(address: "11.11.11.11");<br />
<br />
</pre><br />
<br />
====Adding parameters and events====<br />
At this point you can add parameters and events to BCI2000. <br />
Parameters are values which can be changed in the BCI2000 GUI and can be used to change how experiments behave.<br />
Parameters can either be loaded from a file:<br />
<pre><br />
//path is relative to the Operator's working directory, that is, the /prog directory of the BCI2000 installation<br />
bci.LoadParameters("path/to/parameterfile.prm");<br />
</pre><br />
or added individually:<br />
<pre><br />
//Parameter in the ParamArea section within the Application tab, with default value 0 <br />
bci.AddParameter("Application:ParamArea", "Param", "0");<br />
//Parameter in the ParamArea section within the Application tab, with default value "Green" <br />
bci.AddParameter("Application:ParamArea", "Param2", "Green");<br />
//Parameter in the ParamArea2 section within the Application tab, with default value 0 and range 0-10<br />
bci.AddParameter("Application:ParamArea", "Param3", "0", "0", "10");<br />
</pre><br />
<br />
Events are values logged by BCI2000 alongside the signal data. They have a temporal resolution equivalent to the sample rate, and can be set and read throughout data collection.<br />
Events are unsigned integers with a bit width between 1 and 32:<br />
<pre><br />
//An event called "condition" representing a boolean value with possible values 0 and 1. Will be zero by default.<br />
bci.AddEvent("condition", 1);<br />
//An 32-bit event with default value 100, and range 0 to 2^32 - 1.<br />
bci.AddEvent("value1", 32, 100);<br />
</pre><br />
<br />
====Starting BCI2000 Modules====<br />
BCI2000 modules are started using the <code>StartModules()</code> method, given a dictionary of module names and argument lists. For example, to open SignalGenerator, DummySignalProcessing, and DummyApplication with keyboard and mouse logging:<br />
<pre><br />
bci.StartupModules(new Dictionary<string, List<string>?>()<br />
{<br />
{"SignalGenerator", new List<string>() {"LogKeyboard=1", "LogMouse=1"}},<br />
{"DummySignalProcessing", null},<br />
{"DummyApplication", null}<br />
});<br />
</pre><br />
<br />
====Setting Parameters and Visualizing Values====<br />
If using BCI2000RemoteNET as a substitute for BCI2000Shell for setting up the basic environment, this would usually be where you continue using BCI2000 through its own GUI.<br />
<br />
At this point parameters can be set via <code>SetParameter</code>, for example, setting up experiment parameters:<br />
<pre><br />
bci.SetParameter("DataDirectory", "../data/theDirectory");<br />
bci.SetParameter("SubjectName", "APatient");<br />
bci.SetParameter("SubjectSession", "004");<br />
</pre><br />
<br />
You can also set values such as events to be shown in a graph view. <br />
For example, since we set the source module to start with mouse logging enabled, we can view the values of the mouse position events.<br />
<pre><br />
bci.Visualize("MousePosX");<br />
bci.Visualize("MousePosY");<br />
</pre><br />
We can also visualize the events we added earlier.<br />
<pre><br />
bci.Visualize("condition");<br />
bci.Visualize("value1");<br />
</pre><br />
<br />
====Collecting Data====<br />
Start collecting data with the <code>Start()</code> method. This will implicitly call <code>SetConfig()</code>, but it can be called separately as well.<br />
<pre><br />
bci.Start();<br />
</pre><br />
If you instead want to start BCI2000 through the GUI, and wait for it in this program, you can instead wait for BCI2000 to be in the <code>Running</code> state.<br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Running);<br />
</pre><br />
<br />
During a run you can interact with BCI2000 by setting event variables:<br />
<pre><br />
bci.SetEvent("value1", 400);<br />
</pre><br />
<br />
You can also pulse events, setting their value for one sample duration before setting them back.<br />
<pre><br />
bci.PulseEvent("condition", 1);<br />
</pre><br />
<br />
You can also get values from BCI2000. As we set the source module to log the mouse position earlier, we can retrieve its value via <code>GetEvent()</code>.<br />
<pre><br />
uint mousePositionX = bci.GetEvent("MousePosX");<br />
uint mousePositionY = bci.GetEvent("MousePosY");<br />
</pre><br />
<br />
You can also retrieve the value of the hardware signal. <br />
<pre><br />
//Get value of element 2 of channel 1 of signal<br />
double signal11 = bci.GetSignal(1, 2);X");<br />
</pre><br />
<br />
====Stopping BCI2000====<br />
When you are finished collecting data, stop BCI2000 with the <code>BCI2000Connection.Stop()</code> method.<br />
<pre><br />
bci.connection.Stop();<br />
</pre><br />
<br />
You can also shut down BCI2000.<br />
<pre><br />
bci.connection.Quit();<br />
</pre><br />
<br />
If you instead want to stop BCI2000 via the GUI, you can wait for the system to be in the <code>Suspended</code> state. <br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Connected);<br />
</pre><br />
<br />
Or if you want to poll the system state repeatedly (in a loop, for example);<br />
<pre> <br />
bool loop = true;<br />
while (loop) {<br />
...<br />
if (bci.GetSystemState() == BCI2000Remote.SystemState.Suspended) {<br />
loop = false;<br />
}<br />
}<br />
</pre><br />
<br />
==Examples==<br />
Embedding BCI2000RemoteNET within another program is largely covered above, so this section focuses on alternative usecases.<br />
<br />
====Using BCI2000RemoteNET as a substitute for BCI2000Shell====<br />
BCI2000RemoteNET can be used as a replacement for BCI2000Shell when starting up BCI2000, if you need more advanced language capabilities than what the operator scripting language can provide.<br />
<br />
This is the existing startup script for the Stimulus Presentation task with the software Signal Generator.<br />
<pre>/batch/StimulusPresentation_SignalGenerator.bat</pre><br />
<pre><br />
#! ../prog/BCI2000Shell<br />
@cls & ..\prog\BCI2000Shell %0 %* #! && exit /b 0 || exit /b 1\n<br />
Change directory $BCI2000LAUNCHDIR<br />
Show window; Set title ${Extract file base $0}<br />
Reset system<br />
Startup system localhost<br />
Start executable SignalGenerator --local --LogKeyboard=1 --SpinningWheel=1 --ShowDisplayStatistics=1<br />
Start executable P3SignalProcessing --local<br />
Start executable StimulusPresentation --local<br />
Wait for Connected<br />
Load parameterfile "../parms/examples/StimulusPresentation_SignalGenerator.prm"<br />
</pre><br />
<br />
This is the equivalent C# code using BCI2000RemoteNET:<br />
<pre>/batch/StimulusPresentation_SignalGenerator.cs</pre><br />
<pre><br />
using BCI2000RemoteNET;<br />
using System.RuntimeInformation.InteropServices;<br />
BCI2000Remote bci = new(new BCI2000Connection());<br />
bool isWindows = RuntimeInformation.IsOSPlatform(OSPlatform.Windows);<br />
bci.connection.StartOperator("../prog/Operator" + isWindows ? ".exe" : ""); //Add file extension if on windows <br />
bci.connection.Connect();<br />
bci.LoadParameters("../parms/examples/StimulusPresentation_SignalGenerator.prm");<br />
bci.StartupModules(new() {<br />
{"SignalGenerator", new() {"LogKeyboard=1", "SpinningWheel=1", "ShowDisplayStatistics=1"}},<br />
{"P3SignalProcessing", null},<br />
{"StimulusPresentation", null}<br />
});<br />
</pre> <br />
<br />
C# startup scripts have access to all of the constructs of the C# language, so different actions can be taken depending on conditions such as the operating system, as seen in the above script, or take other input such as command line options.<br />
Note that this will need to be part of a C# project, created via <code>dotnet new console</code> with its accompanied <code>.csproj</code> file.<br />
<br />
An alternative would be to instead use a PowerShell or F# script, which can then be run via <code>pwsh</code> or <code>dotnet fsi</code>. This is the equivalent F# code:<br />
<pre>/batch/StimulusPresentation_SignalGenerator.fsx</pre><br />
<pre><br />
#r "../BCI2000RemoteNET.dll"<br />
open BCI2000RemoteNET<br />
open System.Runtime.InteropServices<br />
let bci = new BCI2000Remote(new BCI2000Connection()) in<br />
let isWindows = RuntimeInformation.IsOSPlatform(OSPlatform.Windows) in<br />
let operatorPath = "../../bci2000/prog/Operator" + if isWindows then ".exe" else "" in<br />
bci.connection.StartOperator operatorPath;<br />
bci.connection.Connect ();<br />
bci.LoadParameters "../parms/examples/StimulusPresentation_SignalGenerator.prm";<br />
bci.StartupModules <| Map [<br />
("SignalGenerator", ["LogKeyboard=1"; "SpinningWheel=1"; "ShowDisplayStatistics=1"]);<br />
("P3SignalProcessing", null);<br />
("StimulusPresentation", null);<br />
]<br />
</pre><br />
This can be run directly:<br />
<code>dotnet fsi StimulusPresentation_SignalGenerator.fsx</code><br />
<br />
==Note On Security==<br />
The BCI2000 command line interface can be used to run arbitrary system shell commands. It is also entirely unsecured and unencrypted. Anyone who has access to it effectively has full access to the computer on which it runs. This is not a problem if running locally, and is generally not a problem if running on a firewalled local network. However, due to the unsecured nature of the interface, running BCI2000 across the internet is highly discouraged. That is, if you set BCI2000 to listen at an address of an external network interface, or to listen at all connections by passing the address <code>0.0.0.0</code>, make sure that port 3999 (or whichever port BCI2000 is listening on), is not forwarded beyond the local network by your router. Support for securely connecting to BCI2000 is planned for the future.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:BCI2000RemoteNET&diff=11336Contributions:BCI2000RemoteNET2024-05-17T21:21:53Z<p>Tytbutler: added F# example</p>
<hr />
<div>==Synopsis==<br />
BCI2000RemoteNET is a library for controlling BCI2000 from .NET programs such as Unity. With C# top-level declarations, it can also be used as a replacement for [[User Reference:BCI2000Shell]] with the added step of compilation via [https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/ <code>csc</code>]. <br />
<br />
==Operation==<br />
<br />
BCI2000RemoteNET communicates with the BCI2000 Operator via [[User Reference:Operator Module Scripting|operator module scripting commands]], which are sent as text over TCP to a running Operator. It also provides functionality for starting the Operator directly, so it can control the Operator entirely from startup to shutdown. <br />
<br />
BCI2000RemoteNET consists of two classes, <code>BCI2000Connection</code>, which provides the basic functionality necessary for starting and communicating with BCI2000, and <code>BCI2000Remote</code>, which provides a set of methods for controlling a BCI2000 experiment, such as interacting with parameters and events, as well as starting modules and experiments.<br />
<br />
BCI2000RemoteNET comes in two versions, targeting .NET 8.0 and .NET Standard 2.1. This is due to compatibility with programs such as Unity, which require .NET Standard binaries. There is little difference in functionality between the two versions, other than the behavior of the <code>Execute()</code> method, whose differences are described below.<br />
<br />
==Documentation==<br />
Documentation for the classes can be found here:<br />
<br />
====.NET 8.0====<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
====.NET Standard 2.1====<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
==Installation==<br />
Acquire the latest binary from [https://github.com/neurotechcenter/BCI2000RemoteNET GitHub], or build from source from the source code on GitHub or in the main BCI2000 Subversion repository (Keep in mind that the version in the Subversion repository will likely be behind the version on GitHub.)<br />
<br />
==Usage==<br />
====Starting the operator====<br />
If you plan on starting the operator separately, skip this step, but make sure to start the operator with its <code>--Telnet</code> option set.<br />
<br />
In order to start the operator, call the <code>BCI2000Connection.StartOperator</code> method with the path to your BCI2000 Operator executable.<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
conn.StartOperator("Path/To/BCI2000/prog/Operator.exe");<br />
</pre><br />
<br />
By default, this will start an operator listening on <code>127.0.0.1:3999</code>. You can also set the Operator to listen on another port:<br />
<pre><br />
conn.StartOperator("path", port: 51101);<br />
</pre><br />
<br />
Or if you wish to accept connections from other computers you can set BCI2000 to listen on all addresses:<br />
<pre><br />
conn.StartOperator("path", address: "0.0.0.0");<br />
</pre><br />
<br />
Or listen on a specific network interface:<br />
<pre><br />
conn.StartOperator("path", address: "10.11.198.2");<br />
</pre><br />
<br />
<br />
====Connecting to the operator====<br />
Connect to the operator with the <code>BCI2000Connection.Connect()</code> method. If you started a local operator with default settings, then you can call <code>Connect</code> with its default parameters, which will connect to the operator at <code>127.0.0.1:3999</code>. If you are connecting to an operator on another machine, say at IP address <code>11.11.11.11</code>,or one listening on a port other than 3999, call <code>Connect()</code> with its optional parameters.<br />
Please see the [[#Note On Security]] for an important caveat of setting a non-default parameter here.<br />
<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
<br />
//Connect to operator on the same machine on the default port.<br />
conn.Connect();<br />
<br />
//Connect to operator at address 11.11.11.11:3999<br />
conn.Connect(address: "11.11.11.11");<br />
<br />
</pre><br />
<br />
====Adding parameters and events====<br />
At this point you can add parameters and events to BCI2000. <br />
Parameters are values which can be changed in the BCI2000 GUI and can be used to change how experiments behave.<br />
Parameters can either be loaded from a file:<br />
<pre><br />
//path is relative to the Operator's working directory, that is, the /prog directory of the BCI2000 installation<br />
bci.LoadParameters("path/to/parameterfile.prm");<br />
</pre><br />
or added individually:<br />
<pre><br />
//Parameter in the ParamArea section within the Application tab, with default value 0 <br />
bci.AddParameter("Application:ParamArea", "Param", "0");<br />
//Parameter in the ParamArea section within the Application tab, with default value "Green" <br />
bci.AddParameter("Application:ParamArea", "Param2", "Green");<br />
//Parameter in the ParamArea2 section within the Application tab, with default value 0 and range 0-10<br />
bci.AddParameter("Application:ParamArea", "Param3", "0", "0", "10");<br />
</pre><br />
<br />
Events are values logged by BCI2000 alongside the signal data. They have a temporal resolution equivalent to the sample rate, and can be set and read throughout data collection.<br />
Events are unsigned integers with a bit width between 1 and 32:<br />
<pre><br />
//An event called "condition" representing a boolean value with possible values 0 and 1. Will be zero by default.<br />
bci.AddEvent("condition", 1);<br />
//An 32-bit event with default value 100, and range 0 to 2^32 - 1.<br />
bci.AddEvent("value1", 32, 100);<br />
</pre><br />
<br />
====Starting BCI2000 Modules====<br />
BCI2000 modules are started using the <code>StartModules()</code> method, given a dictionary of module names and argument lists. For example, to open SignalGenerator, DummySignalProcessing, and DummyApplication with keyboard and mouse logging:<br />
<pre><br />
bci.StartupModules(new Dictionary<string, List<string>?>()<br />
{<br />
{"SignalGenerator", new List<string>() {"LogKeyboard=1", "LogMouse=1"}},<br />
{"DummySignalProcessing", null},<br />
{"DummyApplication", null}<br />
});<br />
</pre><br />
<br />
====Setting Parameters and Visualizing Values====<br />
If using BCI2000RemoteNET as a substitute for BCI2000Shell for setting up the basic environment, this would usually be where you continue using BCI2000 through its own GUI.<br />
<br />
At this point parameters can be set via <code>SetParameter</code>, for example, setting up experiment parameters:<br />
<pre><br />
bci.SetParameter("DataDirectory", "../data/theDirectory");<br />
bci.SetParameter("SubjectName", "APatient");<br />
bci.SetParameter("SubjectSession", "004");<br />
</pre><br />
<br />
You can also set values such as events to be shown in a graph view. <br />
For example, since we set the source module to start with mouse logging enabled, we can view the values of the mouse position events.<br />
<pre><br />
bci.Visualize("MousePosX");<br />
bci.Visualize("MousePosY");<br />
</pre><br />
We can also visualize the events we added earlier.<br />
<pre><br />
bci.Visualize("condition");<br />
bci.Visualize("value1");<br />
</pre><br />
<br />
====Collecting Data====<br />
Start collecting data with the <code>Start()</code> method. This will implicitly call <code>SetConfig()</code>, but it can be called separately as well.<br />
<pre><br />
bci.Start();<br />
</pre><br />
If you instead want to start BCI2000 through the GUI, and wait for it in this program, you can instead wait for BCI2000 to be in the <code>Running</code> state.<br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Running);<br />
</pre><br />
<br />
During a run you can interact with BCI2000 by setting event variables:<br />
<pre><br />
bci.SetEvent("value1", 400);<br />
</pre><br />
<br />
You can also pulse events, setting their value for one sample duration before setting them back.<br />
<pre><br />
bci.PulseEvent("condition", 1);<br />
</pre><br />
<br />
You can also get values from BCI2000. As we set the source module to log the mouse position earlier, we can retrieve its value via <code>GetEvent()</code>.<br />
<pre><br />
uint mousePositionX = bci.GetEvent("MousePosX");<br />
uint mousePositionY = bci.GetEvent("MousePosY");<br />
</pre><br />
<br />
You can also retrieve the value of the hardware signal. <br />
<pre><br />
//Get value of element 2 of channel 1 of signal<br />
double signal11 = bci.GetSignal(1, 2);X");<br />
</pre><br />
<br />
====Stopping BCI2000====<br />
When you are finished collecting data, stop BCI2000 with the <code>BCI2000Connection.Stop()</code> method.<br />
<pre><br />
bci.connection.Stop();<br />
</pre><br />
<br />
You can also shut down BCI2000.<br />
<pre><br />
bci.connection.Quit();<br />
</pre><br />
<br />
If you instead want to stop BCI2000 via the GUI, you can wait for the system to be in the <code>Suspended</code> state. <br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Connected);<br />
</pre><br />
<br />
Or if you want to poll the system state repeatedly (in a loop, for example);<br />
<pre> <br />
bool loop = true;<br />
while (loop) {<br />
...<br />
if (bci.GetSystemState() == BCI2000Remote.SystemState.Suspended) {<br />
loop = false;<br />
}<br />
}<br />
</pre><br />
<br />
==Examples==<br />
Embedding BCI2000RemoteNET within another program is largely covered above, so this section focuses on alternative usecases.<br />
<br />
====Using BCI2000RemoteNET as a substitute for BCI2000Shell====<br />
BCI2000RemoteNET can be used as a replacement for BCI2000Shell when starting up BCI2000, if you need more advanced language capabilities than what the operator scripting language can provide.<br />
<br />
This is the existing startup script for the Stimulus Presentation task with the software Signal Generator.<br />
<pre>/batch/StimulusPresentation_SignalGenerator.bat</pre><br />
<pre><br />
#! ../prog/BCI2000Shell<br />
@cls & ..\prog\BCI2000Shell %0 %* #! && exit /b 0 || exit /b 1\n<br />
Change directory $BCI2000LAUNCHDIR<br />
Show window; Set title ${Extract file base $0}<br />
Reset system<br />
Startup system localhost<br />
Start executable SignalGenerator --local --LogKeyboard=1 --SpinningWheel=1 --ShowDisplayStatistics=1<br />
Start executable P3SignalProcessing --local<br />
Start executable StimulusPresentation --local<br />
Wait for Connected<br />
Load parameterfile "../parms/examples/StimulusPresentation_SignalGenerator.prm"<br />
</pre><br />
<br />
This is the equivalent C# code using BCI2000RemoteNET:<br />
<pre>/batch/StimulusPresentation_SignalGenerator.cs</pre><br />
<pre><br />
using BCI2000RemoteNET;<br />
using System.RuntimeInformation.InteropServices;<br />
BCI2000Remote bci = new(new BCI2000Connection());<br />
bool isWindows = RuntimeInformation.IsOSPlatform(OSPlatform.Windows);<br />
bci.connection.StartOperator("../prog/Operator" + isWindows ? ".exe" : ""); //Add file extension if on windows <br />
bci.connection.Connect();<br />
bci.LoadParameters("../parms/examples/StimulusPresentation_SignalGenerator.prm");<br />
bci.StartupModules(new() {<br />
{"SignalGenerator", new() {"LogKeyboard=1", "SpinningWheel=1", "ShowDisplayStatistics=1"}},<br />
{"P3SignalProcessing", null},<br />
{"StimulusPresentation", null}<br />
});<br />
</pre> <br />
<br />
C# startup scripts have access to all of the constructs of the C# language, so different actions can be taken depending on conditions such as the operating system, as seen in the above script, or take other input such as command line options.<br />
Note that this will need to be part of a C# project, created via <code>dotnet new console</code> with its accompanied <code>.csproj</code> file.<br />
<br />
An alternative would be to instead use a PowerShell or F# script, which can then be run via <code>pwsh</code> or <code>dotnet fsi</code>. This is the equivalent F# code:<br />
<pre>/batch/StimulusPresentation_SignalGenerator.fsx</pre><br />
<pre><br />
#r "../BCI2000RemoteNET.dll"<br />
open BCI2000RemoteNET<br />
open System.Runtime.InteropServices<br />
let bci = new BCI2000Remote(new BCI2000Connection()) in<br />
let isWindows = RuntimeInformation.IsOSPlatform(OSPlatform.Windows) in<br />
let operatorPath = "../../bci2000/prog/Operator" + if isWindows then ".exe" else "" in<br />
bci.connection.StartOperator operatorPath;<br />
bci.connection.Connect ();<br />
bci.LoadParameters "../parms/examples/StimulusPresentation_SignalGenerator.prm";<br />
bci.StartupModules <| Map [<br />
("SignalGenerator", ["LogKeyboard=1"; "SpinningWheel=1"; "ShowDisplayStatistics=1"]);<br />
("P3SignalProcessing", null);<br />
("StimulusPresentation", null);<br />
]<br />
</pre><br />
This can be run directly:<br />
<code>dotnet fsi StimulusPresentation_SignalGenerator.fsx</code><br />
<br />
==Note On Security==<br />
The BCI2000 command line interface can be used to run arbitrary system shell commands. It is also entirely unsecured and unencrypted. Anyone who has access to it effectively has full access to the computer on which it runs. This is not a problem if running locally, and is generally not a problem if running on a firewalled local network. However, due to the unsecured nature of the interface, running BCI2000 across the internet is highly discouraged. That is, if you set BCI2000 to listen at an address of an external network interface, or to listen at all connections by passing the address <code>0.0.0.0</code>, make sure that port 3999 (or whichever port BCI2000 is listening on), is not forwarded beyond the local network by your router. Support for interfacing with BCI2000 over TLS is planned, so that safe connection can be made over the internet.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:BCI2000RemoteNET&diff=11335Contributions:BCI2000RemoteNET2024-05-17T19:47:29Z<p>Tytbutler: Fixed spacing</p>
<hr />
<div>==Synopsis==<br />
BCI2000RemoteNET is a library for controlling BCI2000 from .NET programs such as Unity. With C# top-level declarations, it can also be used as a replacement for [[User Reference:BCI2000Shell]] with the added step of compilation via [https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/ <code>csc</code>]. <br />
<br />
==Operation==<br />
<br />
BCI2000RemoteNET communicates with the BCI2000 Operator via [[User Reference:Operator Module Scripting|operator module scripting commands]], which are sent as text over TCP to a running Operator. It also provides functionality for starting the Operator directly, so it can control the Operator entirely from startup to shutdown. <br />
<br />
BCI2000RemoteNET consists of two classes, <code>BCI2000Connection</code>, which provides the basic functionality necessary for starting and communicating with BCI2000, and <code>BCI2000Remote</code>, which provides a set of methods for controlling a BCI2000 experiment, such as interacting with parameters and events, as well as starting modules and experiments.<br />
<br />
BCI2000RemoteNET comes in two versions, targeting .NET 8.0 and .NET Standard 2.1. This is due to compatibility with programs such as Unity, which require .NET Standard binaries. There is little difference in functionality between the two versions, other than the behavior of the <code>Execute()</code> method, whose differences are described below.<br />
<br />
==Documentation==<br />
Documentation for the classes can be found here:<br />
<br />
====.NET 8.0====<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
====.NET Standard 2.1====<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
==Installation==<br />
Acquire the latest binary from [https://github.com/neurotechcenter/BCI2000RemoteNET GitHub], or build from source from the source code on GitHub or in the main BCI2000 Subversion repository (Keep in mind that the version in the Subversion repository will likely be behind the version on GitHub.)<br />
<br />
==Usage==<br />
====Starting the operator====<br />
If you plan on starting the operator separately, skip this step, but make sure to start the operator with its <code>--Telnet</code> option set.<br />
<br />
In order to start the operator, call the <code>BCI2000Connection.StartOperator</code> method with the path to your BCI2000 Operator executable.<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
conn.StartOperator("Path/To/BCI2000/prog/Operator.exe");<br />
</pre><br />
<br />
By default, this will start an operator listening on <code>127.0.0.1:3999</code>. You can also set the Operator to listen on another port:<br />
<pre><br />
conn.StartOperator("path", port: 51101);<br />
</pre><br />
<br />
Or if you wish to accept connections from other computers you can set BCI2000 to listen on all addresses:<br />
<pre><br />
conn.StartOperator("path", address: "0.0.0.0");<br />
</pre><br />
<br />
Or listen on a specific network interface:<br />
<pre><br />
conn.StartOperator("path", address: "10.11.198.2");<br />
</pre><br />
<br />
<br />
====Connecting to the operator====<br />
Connect to the operator with the <code>BCI2000Connection.Connect()</code> method. If you started a local operator with default settings, then you can call <code>Connect</code> with its default parameters, which will connect to the operator at <code>127.0.0.1:3999</code>. If you are connecting to an operator on another machine, say at IP address <code>11.11.11.11</code>,or one listening on a port other than 3999, call <code>Connect()</code> with its optional parameters.<br />
Please see the [[#Note On Security]] for an important caveat of setting a non-default parameter here.<br />
<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
<br />
//Connect to operator on the same machine on the default port.<br />
conn.Connect();<br />
<br />
//Connect to operator at address 11.11.11.11:3999<br />
conn.Connect(address: "11.11.11.11");<br />
<br />
</pre><br />
<br />
====Adding parameters and events====<br />
At this point you can add parameters and events to BCI2000. <br />
Parameters are values which can be changed in the BCI2000 GUI and can be used to change how experiments behave.<br />
Parameters can either be loaded from a file:<br />
<pre><br />
//path is relative to the Operator's working directory, that is, the /prog directory of the BCI2000 installation<br />
bci.LoadParameters("path/to/parameterfile.prm");<br />
</pre><br />
or added individually:<br />
<pre><br />
//Parameter in the ParamArea section within the Application tab, with default value 0 <br />
bci.AddParameter("Application:ParamArea", "Param", "0");<br />
//Parameter in the ParamArea section within the Application tab, with default value "Green" <br />
bci.AddParameter("Application:ParamArea", "Param2", "Green");<br />
//Parameter in the ParamArea2 section within the Application tab, with default value 0 and range 0-10<br />
bci.AddParameter("Application:ParamArea", "Param3", "0", "0", "10");<br />
</pre><br />
<br />
Events are values logged by BCI2000 alongside the signal data. They have a temporal resolution equivalent to the sample rate, and can be set and read throughout data collection.<br />
Events are unsigned integers with a bit width between 1 and 32:<br />
<pre><br />
//An event called "condition" representing a boolean value with possible values 0 and 1. Will be zero by default.<br />
bci.AddEvent("condition", 1);<br />
//An 32-bit event with default value 100, and range 0 to 2^32 - 1.<br />
bci.AddEvent("value1", 32, 100);<br />
</pre><br />
<br />
====Starting BCI2000 Modules====<br />
BCI2000 modules are started using the <code>StartModules()</code> method, given a dictionary of module names and argument lists. For example, to open SignalGenerator, DummySignalProcessing, and DummyApplication with keyboard and mouse logging:<br />
<pre><br />
bci.StartupModules(new Dictionary<string, List<string>?>()<br />
{<br />
{"SignalGenerator", new List<string>() {"LogKeyboard=1", "LogMouse=1"}},<br />
{"DummySignalProcessing", null},<br />
{"DummyApplication", null}<br />
});<br />
</pre><br />
<br />
====Setting Parameters and Visualizing Values====<br />
If using BCI2000RemoteNET as a substitute for BCI2000Shell for setting up the basic environment, this would usually be where you continue using BCI2000 through its own GUI.<br />
<br />
At this point parameters can be set via <code>SetParameter</code>, for example, setting up experiment parameters:<br />
<pre><br />
bci.SetParameter("DataDirectory", "../data/theDirectory");<br />
bci.SetParameter("SubjectName", "APatient");<br />
bci.SetParameter("SubjectSession", "004");<br />
</pre><br />
<br />
You can also set values such as events to be shown in a graph view. <br />
For example, since we set the source module to start with mouse logging enabled, we can view the values of the mouse position events.<br />
<pre><br />
bci.Visualize("MousePosX");<br />
bci.Visualize("MousePosY");<br />
</pre><br />
We can also visualize the events we added earlier.<br />
<pre><br />
bci.Visualize("condition");<br />
bci.Visualize("value1");<br />
</pre><br />
<br />
====Collecting Data====<br />
Start collecting data with the <code>Start()</code> method. This will implicitly call <code>SetConfig()</code>, but it can be called separately as well.<br />
<pre><br />
bci.Start();<br />
</pre><br />
If you instead want to start BCI2000 through the GUI, and wait for it in this program, you can instead wait for BCI2000 to be in the <code>Running</code> state.<br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Running);<br />
</pre><br />
<br />
During a run you can interact with BCI2000 by setting event variables:<br />
<pre><br />
bci.SetEvent("value1", 400);<br />
</pre><br />
<br />
You can also pulse events, setting their value for one sample duration before setting them back.<br />
<pre><br />
bci.PulseEvent("condition", 1);<br />
</pre><br />
<br />
You can also get values from BCI2000. As we set the source module to log the mouse position earlier, we can retrieve its value via <code>GetEvent()</code>.<br />
<pre><br />
uint mousePositionX = bci.GetEvent("MousePosX");<br />
uint mousePositionY = bci.GetEvent("MousePosY");<br />
</pre><br />
<br />
You can also retrieve the value of the hardware signal. <br />
<pre><br />
//Get value of element 2 of channel 1 of signal<br />
double signal11 = bci.GetSignal(1, 2);X");<br />
</pre><br />
<br />
====Stopping BCI2000====<br />
When you are finished collecting data, stop BCI2000 with the <code>BCI2000Connection.Stop()</code> method.<br />
<pre><br />
bci.connection.Stop();<br />
</pre><br />
<br />
You can also shut down BCI2000.<br />
<pre><br />
bci.connection.Quit();<br />
</pre><br />
<br />
If you instead want to stop BCI2000 via the GUI, you can wait for the system to be in the <code>Suspended</code> state. <br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Connected);<br />
</pre><br />
<br />
Or if you want to poll the system state repeatedly (in a loop, for example);<br />
<pre> <br />
bool loop = true;<br />
while (loop) {<br />
...<br />
if (bci.GetSystemState() == BCI2000Remote.SystemState.Suspended) {<br />
loop = false;<br />
}<br />
}<br />
</pre><br />
<br />
==Examples==<br />
Embedding BCI2000RemoteNET within another program is largely covered above, so this section focuses on alternative usecases.<br />
<br />
====Using BCI2000RemoteNET as a substitute for BCI2000Shell====<br />
BCI2000RemoteNET can be used as a replacement for BCI2000Shell when starting up BCI2000, if you need more advanced language capabilities than what the operator scripting language can provide.<br />
<br />
This is the existing startup script for the Stimulus Presentation task with the software Signal Generator.<br />
<pre>/batch/StimulusPresentation_SignalGenerator.bat</pre><br />
<pre><br />
#! ../prog/BCI2000Shell<br />
@cls & ..\prog\BCI2000Shell %0 %* #! && exit /b 0 || exit /b 1\n<br />
Change directory $BCI2000LAUNCHDIR<br />
Show window; Set title ${Extract file base $0}<br />
Reset system<br />
Startup system localhost<br />
Start executable SignalGenerator --local --LogKeyboard=1 --SpinningWheel=1 --ShowDisplayStatistics=1<br />
Start executable P3SignalProcessing --local<br />
Start executable StimulusPresentation --local<br />
Wait for Connected<br />
Load parameterfile "../parms/examples/StimulusPresentation_SignalGenerator.prm"<br />
</pre><br />
<br />
This is the equivalent C# code using BCI2000RemoteNET:<br />
<pre>/batch/StimulusPresentation_SignalGenerator.cs</pre><br />
<pre><br />
using BCI2000RemoteNET;<br />
using System.RuntimeInformation.InteropServices;<br />
BCI2000Remote bci = new(new BCI2000Connection());<br />
bool isWindows = RuntimeInformation.IsOSPlatform(OSPlatform.Windows);<br />
bci.connection.StartOperator("../prog/Operator" + isWindows ? ".exe" : ""); //Add file extension if on windows <br />
bci.connection.Connect();<br />
bci.LoadParameters("../parms/examples/StimulusPresentation_SignalGenerator.prm");<br />
bci.StartupModules(new() {<br />
{"SignalGenerator", new() {"LogKeyboard=1", "SpinningWheel=1", "ShowDisplayStatistics=1"}},<br />
{"P3SignalProcessing", null}<br />
{"StimulusPresentation", null}<br />
});<br />
</pre> <br />
<br />
C# startup scripts have access to all of the constructs of the C# language, so different actions can be taken depending on conditions such as the operating system, as seen in the above script, or take other input such as command line options.<br />
<br />
This startup script can then be compiled to a .NET executable:<br />
Windows:<br />
<br />
<code>csc.exe /r:"path/to/BCI2000RemoteNET.dll" StimulusPresentation_SignalGenerator.cs</code><br />
<br />
Non-Windows:<br />
<br />
</code>csc /r:"path/to/BCI2000RemoteNET.dll" StimulusPresentation_SignalGenerator.cs</code><br />
<br />
The resulting executable can be run directly on Windows:<br />
<br />
<code>./StimulusPresentation_SignalGenerator.exe</code><br />
<br />
or via Mono on other platforms:<br />
<br />
<code>mono ./StimulusPresentation_SignalGenerator.exe</code><br />
<br />
==Note On Security==<br />
The BCI2000 command line interface can be used to run arbitrary system shell commands. It is also entirely unsecured and unencrypted. Anyone who has access to it effectively has full access to the computer on which it runs. This is not a problem if running locally, and is generally not a problem if running on a firewalled local network. However, due to the unsecured nature of the interface, running BCI2000 across the internet is highly discouraged. That is, if you set BCI2000 to listen at an address of an external network interface, or to listen at all connections by passing the address <code>0.0.0.0</code>, make sure that port 3999 (or whichever port BCI2000 is listening on), is not forwarded beyond the local network by your router. Support for interfacing with BCI2000 over TLS is planned, so that safe connection can be made over the internet.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:BCI2000RemoteNET&diff=11334Contributions:BCI2000RemoteNET2024-05-17T19:46:59Z<p>Tytbutler: Added example</p>
<hr />
<div>==Synopsis==<br />
BCI2000RemoteNET is a library for controlling BCI2000 from .NET programs such as Unity. With C# top-level declarations, it can also be used as a replacement for [[User Reference:BCI2000Shell]] with the added step of compilation via [https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/ <code>csc</code>]. <br />
<br />
==Operation==<br />
<br />
BCI2000RemoteNET communicates with the BCI2000 Operator via [[User Reference:Operator Module Scripting|operator module scripting commands]], which are sent as text over TCP to a running Operator. It also provides functionality for starting the Operator directly, so it can control the Operator entirely from startup to shutdown. <br />
<br />
BCI2000RemoteNET consists of two classes, <code>BCI2000Connection</code>, which provides the basic functionality necessary for starting and communicating with BCI2000, and <code>BCI2000Remote</code>, which provides a set of methods for controlling a BCI2000 experiment, such as interacting with parameters and events, as well as starting modules and experiments.<br />
<br />
BCI2000RemoteNET comes in two versions, targeting .NET 8.0 and .NET Standard 2.1. This is due to compatibility with programs such as Unity, which require .NET Standard binaries. There is little difference in functionality between the two versions, other than the behavior of the <code>Execute()</code> method, whose differences are described below.<br />
<br />
==Documentation==<br />
Documentation for the classes can be found here:<br />
<br />
====.NET 8.0====<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
====.NET Standard 2.1====<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
==Installation==<br />
Acquire the latest binary from [https://github.com/neurotechcenter/BCI2000RemoteNET GitHub], or build from source from the source code on GitHub or in the main BCI2000 Subversion repository (Keep in mind that the version in the Subversion repository will likely be behind the version on GitHub.)<br />
<br />
==Usage==<br />
====Starting the operator====<br />
If you plan on starting the operator separately, skip this step, but make sure to start the operator with its <code>--Telnet</code> option set.<br />
<br />
In order to start the operator, call the <code>BCI2000Connection.StartOperator</code> method with the path to your BCI2000 Operator executable.<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
conn.StartOperator("Path/To/BCI2000/prog/Operator.exe");<br />
</pre><br />
<br />
By default, this will start an operator listening on <code>127.0.0.1:3999</code>. You can also set the Operator to listen on another port:<br />
<pre><br />
conn.StartOperator("path", port: 51101);<br />
</pre><br />
<br />
Or if you wish to accept connections from other computers you can set BCI2000 to listen on all addresses:<br />
<pre><br />
conn.StartOperator("path", address: "0.0.0.0");<br />
</pre><br />
<br />
Or listen on a specific network interface:<br />
<pre><br />
conn.StartOperator("path", address: "10.11.198.2");<br />
</pre><br />
<br />
<br />
====Connecting to the operator====<br />
Connect to the operator with the <code>BCI2000Connection.Connect()</code> method. If you started a local operator with default settings, then you can call <code>Connect</code> with its default parameters, which will connect to the operator at <code>127.0.0.1:3999</code>. If you are connecting to an operator on another machine, say at IP address <code>11.11.11.11</code>,or one listening on a port other than 3999, call <code>Connect()</code> with its optional parameters.<br />
Please see the [[#Note On Security]] for an important caveat of setting a non-default parameter here.<br />
<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
<br />
//Connect to operator on the same machine on the default port.<br />
conn.Connect();<br />
<br />
//Connect to operator at address 11.11.11.11:3999<br />
conn.Connect(address: "11.11.11.11");<br />
<br />
</pre><br />
<br />
====Adding parameters and events====<br />
At this point you can add parameters and events to BCI2000. <br />
Parameters are values which can be changed in the BCI2000 GUI and can be used to change how experiments behave.<br />
Parameters can either be loaded from a file:<br />
<pre><br />
//path is relative to the Operator's working directory, that is, the /prog directory of the BCI2000 installation<br />
bci.LoadParameters("path/to/parameterfile.prm");<br />
</pre><br />
or added individually:<br />
<pre><br />
//Parameter in the ParamArea section within the Application tab, with default value 0 <br />
bci.AddParameter("Application:ParamArea", "Param", "0");<br />
//Parameter in the ParamArea section within the Application tab, with default value "Green" <br />
bci.AddParameter("Application:ParamArea", "Param2", "Green");<br />
//Parameter in the ParamArea2 section within the Application tab, with default value 0 and range 0-10<br />
bci.AddParameter("Application:ParamArea", "Param3", "0", "0", "10");<br />
</pre><br />
<br />
Events are values logged by BCI2000 alongside the signal data. They have a temporal resolution equivalent to the sample rate, and can be set and read throughout data collection.<br />
Events are unsigned integers with a bit width between 1 and 32:<br />
<pre><br />
//An event called "condition" representing a boolean value with possible values 0 and 1. Will be zero by default.<br />
bci.AddEvent("condition", 1);<br />
//An 32-bit event with default value 100, and range 0 to 2^32 - 1.<br />
bci.AddEvent("value1", 32, 100);<br />
</pre><br />
<br />
====Starting BCI2000 Modules====<br />
BCI2000 modules are started using the <code>StartModules()</code> method, given a dictionary of module names and argument lists. For example, to open SignalGenerator, DummySignalProcessing, and DummyApplication with keyboard and mouse logging:<br />
<pre><br />
bci.StartupModules(new Dictionary<string, List<string>?>()<br />
{<br />
{"SignalGenerator", new List<string>() {"LogKeyboard=1", "LogMouse=1"}},<br />
{"DummySignalProcessing", null},<br />
{"DummyApplication", null}<br />
});<br />
</pre><br />
<br />
====Setting Parameters and Visualizing Values====<br />
If using BCI2000RemoteNET as a substitute for BCI2000Shell for setting up the basic environment, this would usually be where you continue using BCI2000 through its own GUI.<br />
<br />
At this point parameters can be set via <code>SetParameter</code>, for example, setting up experiment parameters:<br />
<pre><br />
bci.SetParameter("DataDirectory", "../data/theDirectory");<br />
bci.SetParameter("SubjectName", "APatient");<br />
bci.SetParameter("SubjectSession", "004");<br />
</pre><br />
<br />
You can also set values such as events to be shown in a graph view. <br />
For example, since we set the source module to start with mouse logging enabled, we can view the values of the mouse position events.<br />
<pre><br />
bci.Visualize("MousePosX");<br />
bci.Visualize("MousePosY");<br />
</pre><br />
We can also visualize the events we added earlier.<br />
<pre><br />
bci.Visualize("condition");<br />
bci.Visualize("value1");<br />
</pre><br />
<br />
====Collecting Data====<br />
Start collecting data with the <code>Start()</code> method. This will implicitly call <code>SetConfig()</code>, but it can be called separately as well.<br />
<pre><br />
bci.Start();<br />
</pre><br />
If you instead want to start BCI2000 through the GUI, and wait for it in this program, you can instead wait for BCI2000 to be in the <code>Running</code> state.<br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Running);<br />
</pre><br />
<br />
During a run you can interact with BCI2000 by setting event variables:<br />
<pre><br />
bci.SetEvent("value1", 400);<br />
</pre><br />
<br />
You can also pulse events, setting their value for one sample duration before setting them back.<br />
<pre><br />
bci.PulseEvent("condition", 1);<br />
</pre><br />
<br />
You can also get values from BCI2000. As we set the source module to log the mouse position earlier, we can retrieve its value via <code>GetEvent()</code>.<br />
<pre><br />
uint mousePositionX = bci.GetEvent("MousePosX");<br />
uint mousePositionY = bci.GetEvent("MousePosY");<br />
</pre><br />
<br />
You can also retrieve the value of the hardware signal. <br />
<pre><br />
//Get value of element 2 of channel 1 of signal<br />
double signal11 = bci.GetSignal(1, 2);X");<br />
</pre><br />
<br />
====Stopping BCI2000====<br />
When you are finished collecting data, stop BCI2000 with the <code>BCI2000Connection.Stop()</code> method.<br />
<pre><br />
bci.connection.Stop();<br />
</pre><br />
<br />
You can also shut down BCI2000.<br />
<pre><br />
bci.connection.Quit();<br />
</pre><br />
<br />
If you instead want to stop BCI2000 via the GUI, you can wait for the system to be in the <code>Suspended</code> state. <br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Connected);<br />
</pre><br />
<br />
Or if you want to poll the system state repeatedly (in a loop, for example);<br />
<pre> <br />
bool loop = true;<br />
while (loop) {<br />
...<br />
if (bci.GetSystemState() == BCI2000Remote.SystemState.Suspended) {<br />
loop = false;<br />
}<br />
}<br />
</pre><br />
<br />
==Examples==<br />
Embedding BCI2000RemoteNET within another program is largely covered above, so this section focuses on alternative usecases.<br />
<br />
====Using BCI2000RemoteNET as a substitute for BCI2000Shell====<br />
BCI2000RemoteNET can be used as a replacement for BCI2000Shell when starting up BCI2000, if you need more advanced language capabilities than what the operator scripting language can provide.<br />
<br />
This is the existing startup script for the Stimulus Presentation task with the software Signal Generator.<br />
<pre>/batch/StimulusPresentation_SignalGenerator.bat</pre><br />
<pre><br />
#! ../prog/BCI2000Shell<br />
@cls & ..\prog\BCI2000Shell %0 %* #! && exit /b 0 || exit /b 1\n<br />
Change directory $BCI2000LAUNCHDIR<br />
Show window; Set title ${Extract file base $0}<br />
Reset system<br />
Startup system localhost<br />
Start executable SignalGenerator --local --LogKeyboard=1 --SpinningWheel=1 --ShowDisplayStatistics=1<br />
Start executable P3SignalProcessing --local<br />
Start executable StimulusPresentation --local<br />
Wait for Connected<br />
Load parameterfile "../parms/examples/StimulusPresentation_SignalGenerator.prm"<br />
</pre><br />
<br />
This is the equivalent C# code using BCI2000RemoteNET:<br />
<pre>/batch/StimulusPresentation_SignalGenerator.cs</pre><br />
<pre><br />
using BCI2000RemoteNET;<br />
using System.RuntimeInformation.InteropServices;<br />
BCI2000Remote bci = new(new BCI2000Connection());<br />
bool isWindows = RuntimeInformation.IsOSPlatform(OSPlatform.Windows);<br />
bci.connection.StartOperator("../prog/Operator" + isWindows ? ".exe" : ""); //Add file extension if on windows <br />
bci.connection.Connect();<br />
bci.LoadParameters("../parms/examples/StimulusPresentation_SignalGenerator.prm");<br />
bci.StartupModules(new() {<br />
{"SignalGenerator", new() {"LogKeyboard=1", "SpinningWheel=1", "ShowDisplayStatistics=1"}},<br />
{"P3SignalProcessing", null}<br />
{"StimulusPresentation", null}<br />
});<br />
</pre> <br />
<br />
C# startup scripts have access to all of the constructs of the C# language, so different actions can be taken depending on conditions such as the operating system, as seen in the above script, or take other input such as command line options.<br />
<br />
This startup script can then be compiled to a .NET executable:<br />
Windows:<br />
<code>csc.exe /r:"path/to/BCI2000RemoteNET.dll" StimulusPresentation_SignalGenerator.cs</code><br />
Non-Windows:<br />
</code>csc /r:"path/to/BCI2000RemoteNET.dll" StimulusPresentation_SignalGenerator.cs</code><br />
<br />
The resulting executable can be run directly on Windows:<br />
<code>./StimulusPresentation_SignalGenerator.exe</code><br />
or via Mono on other platforms:<br />
<code>mono ./StimulusPresentation_SignalGenerator.exe</code><br />
<br />
==Note On Security==<br />
The BCI2000 command line interface can be used to run arbitrary system shell commands. It is also entirely unsecured and unencrypted. Anyone who has access to it effectively has full access to the computer on which it runs. This is not a problem if running locally, and is generally not a problem if running on a firewalled local network. However, due to the unsecured nature of the interface, running BCI2000 across the internet is highly discouraged. That is, if you set BCI2000 to listen at an address of an external network interface, or to listen at all connections by passing the address <code>0.0.0.0</code>, make sure that port 3999 (or whichever port BCI2000 is listening on), is not forwarded beyond the local network by your router. Support for interfacing with BCI2000 over TLS is planned, so that safe connection can be made over the internet.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:BCI2000RemoteNET&diff=11333Contributions:BCI2000RemoteNET2024-05-17T19:13:09Z<p>Tytbutler: Fixed formatting</p>
<hr />
<div>==Synopsis==<br />
BCI2000RemoteNET is a library for controlling BCI2000 from .NET programs such as Unity. With C# top-level declarations, it can also be used as a replacement for [[User Reference:BCI2000Shell]] with the added step of compilation via [https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/ <code>csc</code>]. <br />
<br />
==Operation==<br />
<br />
BCI2000RemoteNET communicates with the BCI2000 Operator via [[User Reference:Operator Module Scripting|operator module scripting commands]], which are sent as text over TCP to a running Operator. It also provides functionality for starting the Operator directly, so it can control the Operator entirely from startup to shutdown. <br />
<br />
BCI2000RemoteNET consists of two classes, <code>BCI2000Connection</code>, which provides the basic functionality necessary for starting and communicating with BCI2000, and <code>BCI2000Remote</code>, which provides a set of methods for controlling a BCI2000 experiment, such as interacting with parameters and events, as well as starting modules and experiments.<br />
<br />
BCI2000RemoteNET comes in two versions, targeting .NET 8.0 and .NET Standard 2.1. This is due to compatibility with programs such as Unity, which require .NET Standard binaries. There is little difference in functionality between the two versions, other than the behavior of the <code>Execute()</code> method, whose differences are described below.<br />
<br />
==Documentation==<br />
Documentation for the classes can be found here:<br />
<br />
====.NET 8.0====<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
====.NET Standard 2.1====<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
<br />
[https://bci2000.org/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
==Installation==<br />
Acquire the latest binary from [https://github.com/neurotechcenter/BCI2000RemoteNET GitHub], or build from source from the source code on GitHub or in the main BCI2000 Subversion repository (Keep in mind that the version in the Subversion repository will likely be behind the version on GitHub.)<br />
<br />
==Usage==<br />
====Starting the operator====<br />
If you plan on starting the operator separately, skip this step, but make sure to start the operator with its <code>--Telnet</code> option set.<br />
<br />
In order to start the operator, call the <code>BCI2000Connection.StartOperator</code> method with the path to your BCI2000 Operator executable.<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
conn.StartOperator("Path/To/BCI2000/prog/Operator.exe");<br />
</pre><br />
<br />
By default, this will start an operator listening on <code>127.0.0.1:3999</code>. You can also set the Operator to listen on another port:<br />
<pre><br />
conn.StartOperator("path", port: 51101);<br />
</pre><br />
<br />
Or if you wish to accept connections from other computers you can set BCI2000 to listen on all addresses:<br />
<pre><br />
conn.StartOperator("path", address: "0.0.0.0");<br />
</pre><br />
<br />
Or listen on a specific network interface:<br />
<pre><br />
conn.StartOperator("path", address: "10.11.198.2");<br />
</pre><br />
<br />
<br />
====Connecting to the operator====<br />
Connect to the operator with the <code>BCI2000Connection.Connect()</code> method. If you started a local operator with default settings, then you can call <code>Connect</code> with its default parameters, which will connect to the operator at <code>127.0.0.1:3999</code>. If you are connecting to an operator on another machine, say at IP address <code>11.11.11.11</code>,or one listening on a port other than 3999, call <code>Connect()</code> with its optional parameters.<br />
Please see the [[#Note On Security]] for an important caveat of setting a non-default parameter here.<br />
<br />
<pre><br />
BCI2000Connection conn = new BCI2000Connection();<br />
<br />
//Connect to operator on the same machine on the default port.<br />
conn.Connect();<br />
<br />
//Connect to operator at address 11.11.11.11:3999<br />
conn.Connect(address: "11.11.11.11");<br />
<br />
</pre><br />
<br />
====Adding parameters and events====<br />
At this point you can add parameters and events to BCI2000. <br />
Parameters are values which can be changed in the BCI2000 GUI and can be used to change how experiments behave.<br />
Parameters can either be loaded from a file:<br />
<pre><br />
//path is relative to the Operator's working directory, that is, the /prog directory of the BCI2000 installation<br />
bci.LoadParameters("path/to/parameterfile.prm");<br />
</pre><br />
or added individually:<br />
<pre><br />
//Parameter in the ParamArea section within the Application tab, with default value 0 <br />
bci.AddParameter("Application:ParamArea", "Param", "0");<br />
//Parameter in the ParamArea section within the Application tab, with default value "Green" <br />
bci.AddParameter("Application:ParamArea", "Param2", "Green");<br />
//Parameter in the ParamArea2 section within the Application tab, with default value 0 and range 0-10<br />
bci.AddParameter("Application:ParamArea", "Param3", "0", "0", "10");<br />
</pre><br />
<br />
Events are values logged by BCI2000 alongside the signal data. They have a temporal resolution equivalent to the sample rate, and can be set and read throughout data collection.<br />
Events are unsigned integers with a bit width between 1 and 32:<br />
<pre><br />
//An event called "condition" representing a boolean value with possible values 0 and 1. Will be zero by default.<br />
bci.AddEvent("condition", 1);<br />
//An 32-bit event with default value 100, and range 0 to 2^32 - 1.<br />
bci.AddEvent("value1", 32, 100);<br />
</pre><br />
<br />
====Starting BCI2000 Modules====<br />
BCI2000 modules are started using the <code>StartModules()</code> method, given a dictionary of module names and argument lists. For example, to open SignalGenerator, DummySignalProcessing, and DummyApplication with keyboard and mouse logging:<br />
<pre><br />
bci.StartupModules(new Dictionary<string, List<string>?>()<br />
{<br />
{"SignalGenerator", new List<string>() {"LogKeyboard=1", "LogMouse=1"}},<br />
{"DummySignalProcessing", null},<br />
{"DummyApplication", null}<br />
});<br />
</pre><br />
<br />
====Setting Parameters and Visualizing Values====<br />
If using BCI2000RemoteNET as a substitute for BCI2000Shell for setting up the basic environment, this would usually be where you continue using BCI2000 through its own GUI.<br />
<br />
At this point parameters can be set via <code>SetParameter</code>, for example, setting up experiment parameters:<br />
<pre><br />
bci.SetParameter("DataDirectory", "../data/theDirectory");<br />
bci.SetParameter("SubjectName", "APatient");<br />
bci.SetParameter("SubjectSession", "004");<br />
</pre><br />
<br />
You can also set values such as events to be shown in a graph view. <br />
For example, since we set the source module to start with mouse logging enabled, we can view the values of the mouse position events.<br />
<pre><br />
bci.Visualize("MousePosX");<br />
bci.Visualize("MousePosY");<br />
</pre><br />
We can also visualize the events we added earlier.<br />
<pre><br />
bci.Visualize("condition");<br />
bci.Visualize("value1");<br />
</pre><br />
<br />
====Collecting Data====<br />
Start collecting data with the <code>Start()</code> method. This will implicitly call <code>SetConfig()</code>, but it can be called separately as well.<br />
<pre><br />
bci.Start();<br />
</pre><br />
If you instead want to start BCI2000 through the GUI, and wait for it in this program, you can instead wait for BCI2000 to be in the <code>Running</code> state.<br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Running);<br />
</pre><br />
<br />
During a run you can interact with BCI2000 by setting event variables:<br />
<pre><br />
bci.SetEvent("value1", 400);<br />
</pre><br />
<br />
You can also pulse events, setting their value for one sample duration before setting them back.<br />
<pre><br />
bci.PulseEvent("condition", 1);<br />
</pre><br />
<br />
You can also get values from BCI2000. As we set the source module to log the mouse position earlier, we can retrieve its value via <code>GetEvent()</code>.<br />
<pre><br />
uint mousePositionX = bci.GetEvent("MousePosX");<br />
uint mousePositionY = bci.GetEvent("MousePosY");<br />
</pre><br />
<br />
You can also retrieve the value of the hardware signal. <br />
<pre><br />
//Get value of element 2 of channel 1 of signal<br />
double signal11 = bci.GetSignal(1, 2);X");<br />
</pre><br />
<br />
====Stopping BCI2000====<br />
When you are finished collecting data, stop BCI2000 with the <code>BCI2000Connection.Stop()</code> method.<br />
<pre><br />
bci.connection.Stop();<br />
</pre><br />
<br />
You can also shut down BCI2000.<br />
<pre><br />
bci.connection.Quit();<br />
</pre><br />
<br />
If you instead want to stop BCI2000 via the GUI, you can wait for the system to be in the <code>Suspended</code> state. <br />
<pre><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Connected);<br />
</pre><br />
<br />
Or if you want to poll the system state repeatedly (in a loop, for example);<br />
<pre> <br />
bool loop = true;<br />
while (loop) {<br />
...<br />
if (bci.GetSystemState() == BCI2000Remote.SystemState.Suspended) {<br />
loop = false;<br />
}<br />
}<br />
</pre><br />
<br />
==Note On Security==<br />
The BCI2000 command line interface can be used to run arbitrary system shell commands. It is also entirely unsecured and unencrypted. Anyone who has access to it effectively has full access to the computer on which it runs. This is not a problem if running locally, and is generally not a problem if running on a firewalled local network. However, due to the unsecured nature of the interface, running BCI2000 across the internet is highly discouraged. That is, if you set BCI2000 to listen at an address of an external network interface, or to listen at all connections by passing the address <code>0.0.0.0</code>, make sure that port 3999 (or whichever port BCI2000 is listening on), is not forwarded beyond the local network by your router. Support for interfacing with BCI2000 over TLS is planned, so that safe connection can be made over the internet.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:BCI2000RemoteNET&diff=11332Contributions:BCI2000RemoteNET2024-05-17T19:03:17Z<p>Tytbutler: New version</p>
<hr />
<div>==Synopsis==<br />
BCI2000RemoteNET is a library for controlling BCI2000 from .NET programs such as Unity. With C# top-level declarations, it can also be used as a replacement for [[User Reference:BCI2000Shell]] with the added step of compilation via [https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/ <code>csc</code>]. <br />
<br />
==Operation==<br />
<br />
BCI2000RemoteNET communicates with the BCI2000 Operator via [[User Reference:Operator Module Scripting|operator module scripting commands]], which are sent as text over TCP to a running Operator. It also provides functionality for starting the Operator directly, so it can control the Operator entirely from startup to shutdown. <br />
<br />
BCI2000RemoteNET consists of two classes, <code>BCI2000Connection</code>, which provides the basic functionality necessary for starting and communicating with BCI2000, and <code>BCI2000Remote</code>, which provides a set of methods for controlling a BCI2000 experiment, such as interacting with parameters and events, as well as starting modules and experiments.<br />
<br />
BCI2000RemoteNET comes in two versions, targeting .NET 8.0 and .NET Standard 2.1. This is due to compatibility with programs such as Unity, which require .NET Standard binaries. There is little difference in functionality between the two versions, other than the behavior of the <code>Execute()</code> method, whose differences are described below.<br />
<br />
==Documentation==<br />
Documentation for the classes can be found here:<br />
<br />
====.NET 8.0====<br />
[{{hostname}}/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
[{{hostname}}/BCI2000RemoteNET/net8/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
====.NET Standard 2.1====<br />
[{{hostname}}/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Connection.html BCI2000Connection]<br />
[{{hostname}}/BCI2000RemoteNET/netstandard2/classBCI2000RemoteNET_1_1BCI2000Remote.html BCI2000Remote]<br />
<br />
==Installation==<br />
Acquire the latest binary from [https://github.com/neurotechcenter/BCI2000RemoteNET GitHub], or build from source from the source code on GitHub or in the main BCI2000 Subversion repository (Keep in mind that the version in the Subversion repository will likely be behind the version on GitHub.)<br />
<br />
==Usage==<br />
====Starting the operator====<br />
If you plan on starting the operator separately, skip this step, but make sure to start the operator with its <code>--Telnet</code> option set.<br />
<br />
In order to start the operator, call the <code>BCI2000Connection.StartOperator</code> method with the path to your BCI2000 Operator executable.<br />
<code><br />
BCI2000Connection conn = new BCI2000Connection();<br />
conn.StartOperator("Path/To/BCI2000/prog/Operator.exe");<br />
</code><br />
<br />
By default, this will start an operator listening on <code>127.0.0.1:3999</code>. You can also set the Operator to listen on another port:<br />
<code><br />
conn.StartOperator("path", port: 51101);<br />
</code><br />
<br />
Or if you wish to accept connections from other computers you can set BCI2000 to listen on all addresses:<br />
<code><br />
conn.StartOperator("path", address: "0.0.0.0");<br />
</code><br />
<br />
Or listen on a specific network interface:<br />
<code><br />
conn.StartOperator("path", address: "10.11.198.2");<br />
</code><br />
<br />
<br />
====Connecting to the operator====<br />
Connect to the operator with the <code>BCI2000Connection.Connect()</code> method. If you started a local operator with default settings, then you can call <code>Connect</code> with its default parameters, which will connect to the operator at <code>127.0.0.1:3999</code>. If you are connecting to an operator on another machine, say at IP address <code>11.11.11.11</code>,or one listening on a port other than 3999, call <code>Connect()</code> with its optional parameters.<br />
Please see the [[#Note On Security]] for an important caveat of setting a non-default parameter here.<br />
<br />
<code><br />
BCI2000Connection conn = new BCI2000Connection();<br />
<br />
//Connect to operator on the same machine on the default port.<br />
conn.Connect();<br />
<br />
//Connect to operator at address 11.11.11.11:3999<br />
conn.Connect(address: "11.11.11.11");<br />
<br />
</code><br />
<br />
====Adding parameters and events====<br />
At this point you can add parameters and events to BCI2000. <br />
Parameters are values which can be changed in the BCI2000 GUI and can be used to change how experiments behave.<br />
Parameters can either be loaded from a file:<br />
<code><br />
//path is relative to the Operator's working directory, that is, the /prog directory of the BCI2000 installation<br />
bci.LoadParameters("path/to/parameterfile.prm");<br />
</code><br />
or added individually:<br />
<code><br />
//Parameter in the ParamArea section within the Application tab, with default value 0 <br />
bci.AddParameter("Application:ParamArea", "Param", "0");<br />
//Parameter in the ParamArea section within the Application tab, with default value "Green" <br />
bci.AddParameter("Application:ParamArea", "Param2", "Green");<br />
//Parameter in the ParamArea2 section within the Application tab, with default value 0 and range 0-10<br />
bci.AddParameter("Application:ParamArea", "Param3", "0", "0", "10");<br />
</code><br />
<br />
Events are values logged by BCI2000 alongside the signal data. They have a temporal resolution equivalent to the sample rate, and can be set and read throughout data collection.<br />
Events are unsigned integers with a bit width between 1 and 32:<br />
<code><br />
//An event called "condition" representing a boolean value with possible values 0 and 1. Will be zero by default.<br />
bci.AddEvent("condition", 1);<br />
//An 32-bit event with default value 100, and range 0 to 2^32 - 1.<br />
bci.AddEvent("value1", 32, 100);<br />
</code><br />
<br />
====Starting BCI2000 Modules====<br />
BCI2000 modules are started using the <code>StartModules()</code> method, given a dictionary of module names and argument lists. For example, to open SignalGenerator, DummySignalProcessing, and DummyApplication with keyboard and mouse logging:<br />
<code><br />
bci.StartupModules(new Dictionary<string, List<string>?>()<br />
{<br />
{"SignalGenerator", new List<string>() {"LogKeyboard=1", "LogMouse=1"}},<br />
{"DummySignalProcessing", null},<br />
{"DummyApplication", null}<br />
});<br />
</code><br />
<br />
====Setting Parameters and Visualizing Values====<br />
If using BCI2000RemoteNET as a substitute for BCI2000Shell for setting up the basic environment, this would usually be where you continue using BCI2000 through its own GUI.<br />
<br />
At this point parameters can be set via <code>SetParameter</code>, for example, setting up experiment parameters:<br />
<code><br />
bci.SetParameter("DataDirectory", "../data/theDirectory");<br />
bci.SetParameter("SubjectName", "APatient");<br />
bci.SetParameter("SubjectSession", "004");<br />
</code><br />
<br />
You can also set values such as events to be shown in a graph view. <br />
For example, since we set the source module to start with mouse logging enabled, we can view the values of the mouse position events.<br />
<code><br />
bci.Visualize("MousePosX");<br />
bci.Visualize("MousePosY");<br />
</code><br />
We can also visualize the events we added earlier.<br />
<code><br />
bci.Visualize("condition");<br />
bci.Visualize("value1");<br />
</code><br />
<br />
====Collecting Data====<br />
Start collecting data with the <code>Start()</code> method. This will implicitly call <code>SetConfig()</code>, but it can be called separately as well.<br />
<code><br />
bci.Start();<br />
</code><br />
If you instead want to start BCI2000 through the GUI, and wait for it in this program, you can instead wait for BCI2000 to be in the <code>Running</code> state.<br />
<code><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Running);<br />
</code><br />
<br />
During a run you can interact with BCI2000 by setting event variables:<br />
<code><br />
bci.SetEvent("value1", 400);<br />
</code><br />
<br />
You can also pulse events, setting their value for one sample duration before setting them back.<br />
<code><br />
bci.PulseEvent("condition", 1);<br />
</code><br />
<br />
You can also get values from BCI2000. As we set the source module to log the mouse position earlier, we can retrieve its value via <code>GetEvent()</code>.<br />
<code><br />
uint mousePositionX = bci.GetEvent("MousePosX");<br />
uint mousePositionY = bci.GetEvent("MousePosY");<br />
</code><br />
<br />
You can also retrieve the value of the hardware signal. <br />
<code><br />
//Get value of element 2 of channel 1 of signal<br />
double signal11 = bci.GetSignal(1, 2);X");<br />
</code><br />
<br />
====Stopping BCI2000====<br />
When you are finished collecting data, stop BCI2000 with the <code>BCI2000Connection.Stop()</code> method.<br />
<code><br />
bci.connection.Stop();<br />
</code><br />
<br />
You can also shut down BCI2000.<br />
<code><br />
bci.connection.Quit();<br />
</code><br />
<br />
If you instead want to stop BCI2000 via the GUI, you can wait for the system to be in the <code>Suspended</code> state. <br />
<code><br />
bci.WaitForSystemState(BCI2000Remote.SystemState.Connected);<br />
</code><br />
<br />
Or if you want to poll the system state repeatedly (in a loop, for example);<br />
<code><br />
bool loop = true;<br />
while (loop) {<br />
...<br />
<br />
if (bci.GetSystemState() == BCI2000Remote.SystemState.Suspended) {<br />
loop = false;<br />
}<br />
}<br />
</code><br />
<br />
==Note On Security==<br />
The BCI2000 command line interface can be used to run arbitrary system shell commands. It is also entirely unsecured and unencrypted. Anyone who has access to it effectively has full access to the computer on which it runs. This is not a problem if running locally, and is generally not a problem if running on a firewalled local network. However, due to the unsecured nature of the interface, running BCI2000 across the internet is highly discouraged. That is, if you set BCI2000 to listen at an address of an external network interface, or to listen at all connections by passing the address <code>0.0.0.0</code>, make sure that port 3999 (or whichever port BCI2000 is listening on), is not forwarded beyond the local network by your router. Support for interfacing with BCI2000 over TLS is planned, so that safe connection can be made over the internet.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:UnityBCI2000&diff=11256Contributions:UnityBCI20002024-04-16T17:34:23Z<p>Tytbutler: Initial writing of the new UnityBCI2000 page</p>
<hr />
<div>==Synopsis==<br />
UnityBCI2000 is an extension for the Unity game/3D application development platform that enables control of and communication with the BCI2000 brain-computer interface research platform. It consists of a .NET library for communication with the BCI2000 operator and a Unity package which provides integration with Unity itself.<br />
<br />
==Prerequisites==<br />
Alongside UnityBCI2000, install Unity per the instructions at [https://unity.com/download the Unity website], and the [BCI2000 setup tutorial https://www.bci2000.org/mediawiki/index.php/Programming_Howto:Install_Prerequisites].<br />
<br />
<br />
<br />
==Documentation==<br />
[https://bci2000.org/BCI2000Unity/classUnityBCI2000.html Interface documentation]</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:BCI2000Unity_OUTDATED&diff=11255Contributions:BCI2000Unity OUTDATED2024-04-16T17:14:43Z<p>Tytbutler: Delisted old version of the UnityBCI2000 page. New version located at Contributions:UnityBCI2000</p>
<hr />
<div>__NOINDEX__<br />
<br />
==Introduction==<br />
<br />
Unity is a cross-platform game engine with support for desktop, mobile, console, and virtual reality platforms. It is both easy for beginners to use and is popular for low-cost game development. This is a Unity package which integrates BCI2000.<br />
<br />
==Prerequisites==<br />
<br />
UnityBCI2000 depends on the BCI2000RemoteNET library, located at<br />
[https://github.com/neurotechcenter/BCI2000RemoteNET Github] or [https://www.nuget.org/packages/BCI2000RemoteNET NuGet]).<br />
Keep in mind that at the moment both BCI2000RemoteNET and BCI2000Unity are not fully released, and are still in development, so features and API structure are subject to change at any time, and bugs are to be expected.<br />
<br />
==Usage==<br />
<br />
Add the `UnityBCI2000.cs` script to one `GameObject`. This is the central script which communicates with BCI2000. <br />
Add the `BCI2000StateSender` to any object which you want to monitor with BCI2000. <br />
Before starting, you must set the operator and modules to start up, by specifying the fields<br />
`OperatorPath` and `Module[1-3]`. All other properties have default settings and will function without change. <br />
Alternatively, if you leave `OperatorPath` blank, `BCI2000Remote` will attempt to connect to an operator at<br />
`TelnetIp:TelnetPort`. This is useful for if you already have an operator open that you want to use. <br />
If you also have modules started within a running BCI2000 instance, set `DontStartModules` to `true`, this will preserve<br />
your running modules.<br />
<br />
===Using built-in variables===<br />
<br />
`BCI2000StateSender` has some variables built in. To use these, just select their check boxes in the inspector.<br />
<br />
===Adding custom variables===<br />
<br />
To add custom variables, add a script to the same object as a `BCI2000StateSender`, which inherits from `CustomVariableBase`. <br />
Then, add the `CustomVariableBase` to the "Custom Variable Supplier" field of the `BCI2000StateSender`.<br />
Then, add `CustomVariable`s to the list `customVariables` within the `CustomVariableBase`. There are some included<br />
templates and snippets which show the syntax for adding custom variables.<br />
<br />
===Custom Variables===<br />
<br />
A custom variable has four fields. These are its name, value, scale, and type. <br />
Its name is a string which holds its name. <br />
Its value is a `Func<float>` delegate which returns a float, which will be sent to BCI2000, after being multiplied by its scale. <br />
Its type is a member of the enum `UnityBCI2000.StateType`, which represents the format of the number being sent to BCI2000.<br />
<br />
===Custom Variable Class Example===<br />
<br />
Template<br />
<br />
public class <ClassName> : CustomVariableBase<br />
{<br />
public override void AddCustomVariables()<br />
{<br />
customVariables.Add(new CustomSetVariable( //Copy this for more set variables<br />
"[Name]",<br />
new Func<float>(() => [Code which returns variable to send]),<br />
[Scale],<br />
UnityBCI2000.StateType.[Type]<br />
));<br />
<br />
customVariables.Add(new CustomGetVariable( //Copy this for more get variables<br />
"[Name]", <br />
new Action<int> ((int i) => [Code which uses i])<br />
));<br />
<br />
}<br />
}<br />
<br />
Example<br />
<br />
public class CustomVariableSupplier1 : CustomVariableBase<br />
{<br />
public override void AddCustomVariables() <br />
{<br />
customVariables.Add(new CustomSetVariable(<br />
"Custom variable 1",<br />
new Func<float>(() => {return 65 / 5;}),<br />
100,<br />
UnityBCI2000.StateType.SignedInt16<br />
));<br />
customVariables.Add(new CustomSetVariable(<br />
"Custom variable 2: Frame count",<br />
new Func<float>(() => Time.frameCount),<br />
1,<br />
UnityBCI2000.StateType.UnsignedInt32<br />
));<br />
customVariables.Add(new CustomGetVariable( <br />
"StateName", <br />
new Action<int> ((int i) => {score = i})<br />
));<br />
}<br />
}<br />
<br />
===Number Formats===<br />
<br />
The available formats are found in the enum `UnityBCI2000.StateType`. As they are being accessed outside of `UnityBCI2000`, <br />
they will always be preceded by "UnityBCI2000.".<br />
<br />
The formats are `Boolean`, `UnsignedInt16`, `UnsignedInt32`, `SignedInt16`, and `SignedInt32`. <br />
These are available formats because BCI2000 takes state values in the form of unsigned integers with a bit width of powers of 2 between 1 and 32. <br />
Boolean is the same as an unsigned int of bit width 1. <br />
Signed numbers will generate a second state within BCI2000 of bit width 1, which holds their sign. If they are negative, their sign will be 1,<br />
and if they are positive, their sign will be 0. Use signed numbers if your value will ever be negative.<br />
<br />
===Other scripting===<br />
<br />
Try to avoid calling any of the methods directly. UnityBCI2000 should ideally be able to run and control BCI2000 without any intervention.<br />
<br />
==Properties==<br />
<br />
===UnityBCI2000===<br />
<br />
`Timeout`<br />
The timeout, in milliseconds, for sending and receiving commands, default 1000.<br />
<br />
`TelnetIP`<br />
The IP at which to connect to the Operator, default 127.0.0.1<br />
Note: Don't use "localhost" when setting this, as this causes errors due to ambiguity in name resolution.<br />
<br />
`TelnetPort`<br />
The port to connect to the Operator, default 3999.<br />
<br />
`OperatorPath`<br />
The path to the Operator module to start up when there is no running operator at the IP and port specified, will always connect on localhost, at the previously given port.<br />
<br />
`LogFile`<br />
The path to the file to write the log. This is overwritten on `Connect()`, default "logFile.txt", in the application's working directory.<br />
<br />
`LogStates`<br />
Whether or not to log commands to set a state, as well as the received Prompt if the command produces no errors, default false.<br />
<br />
`LogPrompts`<br />
Whether or not to log any Prompt, in which case only received output and errors will be logged, default false.<br />
<br />
===BCI2000StateSender===<br />
<br />
`UnityBCI2000 object`<br />
The object which has the attached `UnityBCI2000` script.<br />
<br />
`Custom Variable Supplier`<br />
The component which inherits from `CustomVariableBase` which supplies custom variables.<br />
<br />
Global and screen coordinates and their scales.<br />
<br />
`Camera`<br />
The camera to use for finding screen position.<br />
<br />
`Is on screen`<br />
Is the object on screen.<br />
<br />
<br />
`Velocity`<br />
The velocity of the object in any direction.<br />
<br />
`Custom Variables`<br />
Lists the names of any added custom variables.<br />
<br />
==Other Notes==<br />
<br />
`StateVariable` is a class which holds values necessary for sending states to BCI2000. <br />
They are stored in two places, a central list within `UnityBCI2000` which is only used for checking if a state already exists,<br />
and within the `BCI2000StateSender` which 'owns' the state, where they are stored within objects called `SendStateVariable`,<br />
which update the state with a new value every frame. This is done so that one state can be changed by mutiple `BCI2000StateSender`s,<br />
through the use of multiple `SendStateVariables` created using the `AddSendExistingState()` method. <br />
<br />
BCI2000Remote will write its output to a log file that is, by default, located at logFile.txt in the working directory of your Unity application.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:UnityBCI2000&diff=11112Contributions:UnityBCI20002024-02-19T22:12:50Z<p>Tytbutler: Full tutorial soon, added class documentation</p>
<hr />
<div>==Synopsis==<br />
UnityBCI2000 is a tool for integration of Unity applications with BCI2000.<br />
<br />
==Tutorial==<br />
[https://bci2000.org/BCI2000Unity/classUnityBCI2000.html Class documentation]</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:UnityBCI2000&diff=10582Contributions:UnityBCI20002023-08-02T15:37:16Z<p>Tytbutler: </p>
<hr />
<div>==Synopsis==<br />
UnityBCI2000 is a tool for integration of Unity applications with BCI2000.<br />
<br />
==Tutorial==<br />
For information on how to use Unity itself, see the Unity [https://docs.unity3d.com/Manual/index.html manual]. This tutorial assumes knowledge of how to use Unity.<br />
More in-depth detail on how UnityBCI2000 works is provided in the README.md file, as well as HTML documentation in the docs directory.<br />
<br />
First, download UnityBCI2000 from [https://github.com/neurotechcenter/UnityBCI2000 GitHub]. As of now, UnityBCI2000 is not a full Unity package, but it works the same. Place the files UnityBCI2000.cs and BCI2000RemoteNET.dll within the Assets folder of your Unity project.<br />
<br />
Add the UnityBCI2000 script as a component to an empty GameObject. This will serve as the connection to BCI2000 within your project.<br />
<br />
Specify the location of the BCI2000 executable, the BCI2000 modules you want to start along with their startup arguments, and any parameter files you want to load.<br />
<br />
Connection to BCI2000 is done by calling UnityBCI2000's methods from other scripts. Within the script object from which you want to control BCI2000, add the UnityBCI2000 component as a member variable using Unity's GameObject.Find and GameObject.GetComponent methods.<br />
For example, if you have UnityBCI2000 attached to a GameObject called "BCI2K", your script would look like this:<br />
<tt><br />
class ObjScript : MonoBehaviour {<br />
private UnityBCI2000 bci = GameObject.Find("BCI2K").GetComponent<UnityBCI2000>();<br />
public void Start(){}<br />
public void Update(){}<br />
}<br />
</tt><br />
<br />
Events and States can be added to BCI2000 within the Start() methods of your scripts. If you wanted to add an Event called "X" and a State called "Y", your script would look like this:<br />
<br />
<tt><br />
class ObjScript : MonoBehaviour {<br />
private UnityBCI2000 bci = GameObject.Find("BCI2K").GetComponent<UnityBCI2000>();<br />
public void Start(){<br />
bci.AddEvent("M");<br />
bci.AddState("N");<br />
}<br />
public void Update(){}<br />
}<br />
</tt><br />
<br />
Events and States are accessed through a few methods of UnityBCI2000 called from the Update() method. In order to access their values, use the GetEvent and GetState methods.<br />
<br />
In order to set their values, call SetEvent, PulseEvent, or SetState. For events, SetEvent sets the value of an Event like a state, and PulseEvent sets the value of an Event for a single sample before returning it to its previous value, for use if you want to record an instantaneous event happening. <br />
A script which interacts with events:<br />
<br />
<tt><br />
class ObjScript : MonoBehaviour {<br />
private UnityBCI2000 bci = GameObject.Find("BCI2K").GetComponent<UnityBCI2000>();<br />
public void Start(){<br />
bci.AddEvent("M");<br />
bci.AddState("N");<br />
}<br />
public void Update(){<br />
int x = bci.GetEvent("MousePosX");<br />
if (condition) {<br />
bci.PulseEvent("thingHappened", 1);<br />
}<br />
bci.SetEvent("Y", (int) transform.position.y);<br />
}<br />
}<br />
</tt></div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:UnityBCI2000&diff=9207Contributions:UnityBCI20002021-10-06T03:49:03Z<p>Tytbutler: </p>
<hr />
<div>==Synopsis==<br />
UnityBCI2000 is a tool for integration of Unity applications with BCI2000.<br />
<br />
==Tutorial==<br />
For information on how to use Unity itself, see the Unity [https://docs.unity3d.com/Manual/index.html manual]. This tutorial assumes knowledge of how to use Unity. It is recommended to know how GameObjects and Components work.<br />
More in-depth detail on how UnityBCI2000 works is provided in the README.md file.<br />
<br />
<br />
<br />
First, download UnityBCI2000 from [https://github.com/neurotechcenter/UnityBCI2000 GitHub]. As of now, UnityBCI2000 is not a full Unity package, but it works the same. Place the C# files from the Runtime folder, as well as BCI2000RemoteNET.dll, within the Assets directory of your Unity project.<br />
<br />
Create an empty GameObject and add the script UnityBCI2000 as a Component. This will serve as the central connection to the BCI2000 Operator. As of now, it is not possible to use multiple scenes with one BCI2000 connection.<br />
<br />
1. Add a UnityBCI2000.cs to the GameObject as a Script Component. <br />
<br />
2.Specify the path to the operator using the Operator Path field, as well as the names of the modules to start up alongside it. <br />
<br />
If you have an instance of the operator already running, specify the IP and port it is listening on using the Telnet Ip and Telnet Port fields instead.<br />
<br />
You can also set a custom log file location, as well as tell the program to log sent states and received prompts. '''NOTE: There is a known issue with writing to the log file, this is remedied by changing the name of the file to write to. This is an issue with BCI2000RemoteNET, and will be fixed in upcoming updates.'''<br />
<br />
3. Now, add a Script component of the script BCI2000StateSender to the object which you want to take data from. <br />
<br />
4. Drag the BCI2000 GameObject from step 1 into the UnityBCI2000Object field of the BCI2000StateSender.<br />
<br />
BCI2000StateSender comes with some predefined states to send, as well as values to scale them by. These are the global and screen coordinates, as well as whether the object is on screen.<br />
<br />
===Adding Custom Variables===<br />
Due to the way Unity works, adding custom variables must be done from a custom script, unique to each GameObject, if the GameObjects are not identical. Unfortunately, this means that some knowledge of C# programming is required, but templates for a CustomVariableSupplier script are provided within the README.md file.<br />
<br />
There are two types of custom variables: custom set variables, which set a state in BCI2000 to some value, and custom get variables, which retrieve the value of a state variable from BCI2000.<br />
<br />
Custom set variables contain the name of the state to write to, a Func<int> delegate(a piece of code represented by a method or lambda expression which returns the value to send to BCI2000), a scale factor to scale the variable by, in order to avoid truncation due to the fact that BCI2000 state variables are only unsigned integers, and a type.<br />
Types are defined by the enum UnityBCI2000.StateType, which currently holds 5 values, which are signed integers of bit widths 16 and 32, as well as boolean, which is an unsigned integer of bit width 1. Signed numbers will be represented in BCI2000 by two state variables: The magnitude of the number and its sign, which is 0 for positive and 1 for negative.<br />
<br />
Custom get variables contain the name of the state to read from, as well as an Action<int> delegate(a piece of code which takes an int as a parameter), which will receive the value from BCI2000.<br />
For reference on delegates see the [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/delegates/ C# Programming Guide].<br />
Note: UnityBCI2000 uses reflection in order to reduce the amount of boilerplate code needed to implement a custom state variable, as well as simplify the process of adding and indexing of custom state variables.<br />
<br />
Template for adding custom variables:<br />
<tt><br />
public class <ClassName> : CustomVariableBase<br />
{<br />
public override void AddCustomVariables()<br />
{<br />
customVariables.Add(new CustomSetVariable( //Copy this for more set variables<br />
"[Name]",<br />
new Func<float>(() => [Code which returns variable to send]),<br />
[Scale],<br />
UnityBCI2000.StateType.[Type]<br />
));<br />
<br />
customVariables.Add(new CustomGetVariable( //Copy this for more get variables<br />
"[Name]", <br />
new Action<int> ((int i) => [Code which uses i])<br />
));<br />
<br />
}<br />
}<br />
</tt><br />
<br />
Example of a custom variable provider script:<br />
<tt><br />
public class CustomVariableSupplier1 : CustomVariableBase<br />
{<br />
public override void AddCustomVariables() <br />
{<br />
customVariables.Add(new CustomSetVariable( <br />
"Custom variable 1",<br />
new Func<float>(() => {return 65 / 5;}),<br />
100,<br />
UnityBCI2000.StateType.SignedInt16<br />
));<br />
<br />
customVariables.Add(new CustomSetVariable(<br />
"Custom variable 2: Frame count",<br />
new Func<float>(() => Time.frameCount),<br />
1,<br />
UnityBCI2000.StateType.UnsignedInt32<br />
));<br />
<br />
customVariables.Add(new CustomGetVariable( <br />
"StateName", <br />
new Action<int> ((int i) => {score = i})<br />
));<br />
}<br />
}<br />
</tt><br />
<br />
<br />
1. Add a new C# script to the object which you want to take data from.<br />
<br />
2. Edit the script to change the inherited class to be CustomVariableBase instead of MonoBehavior.<br />
<br />
3. Implement the AddCustomVariables method, and have it add Custom Variables to the customVariables List, by calling customVariables.Add. <br />
<br />
4. Drag this new script into the Custom Variable Supplier field of the BCI2000StateSender Component.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:UnityBCI2000&diff=9206Contributions:UnityBCI20002021-10-06T03:47:55Z<p>Tytbutler: </p>
<hr />
<div>==Synopsis==<br />
UnityBCI2000 is a tool for integration of Unity applications with BCI2000.<br />
<br />
==Tutorial==<br />
For information on how to use Unity itself, see the Unity [https://docs.unity3d.com/Manual/index.html manual]. This tutorial assumes knowledge of how to use Unity. It is recommended to know how GameObjects and Components work.<br />
More in-depth detail on how UnityBCI2000 works is provided in the README.md file.<br />
<br />
<br />
<br />
First, download UnityBCI2000 from [https://github.com/neurotechcenter/UnityBCI2000 GitHub]. As of now, UnityBCI2000 is not a full Unity package, but it works the same. Place the C# files from the Runtime folder, as well as BCI2000RemoteNET.dll, within the Assets directory of your Unity project.<br />
<br />
Create an empty GameObject and add the script UnityBCI2000 as a Component. This will serve as the central connection to the BCI2000 Operator. As of now, it is not possible to use multiple scenes with one BCI2000 connection.<br />
<br />
1. Add a UnityBCI2000.cs to the GameObject as a Script Component. <br />
2.Specify the path to the operator using the Operator Path field, as well as the names of the modules to start up alongside it. <br />
-If you have an instance of the operator already running, specify the IP and port it is listening on using the Telnet Ip and Telnet Port fields instead.<br />
<br />
-You can also set a custom log file location, as well as tell the program to log sent states and received prompts. '''NOTE: There is a known issue with writing to the log file, this is remedied by changing the name of the file to write to. This is an issue with BCI2000RemoteNET, and will be fixed in upcoming updates.'''<br />
<br />
3. Now, add a Script component of the script BCI2000StateSender to the object which you want to take data from. <br />
4. Drag the BCI2000 GameObject from step 1 into the UnityBCI2000Object field of the BCI2000StateSender.<br />
-BCI2000StateSender comes with some predefined states to send, as well as values to scale them by. These are the global and screen coordinates, as well as whether the object is on screen.<br />
<br />
===Adding Custom Variables===<br />
Due to the way Unity works, adding custom variables must be done from a custom script, unique to each GameObject, if the GameObjects are not identical. Unfortunately, this means that some knowledge of C# programming is required, but templates for a CustomVariableSupplier script are provided within the README.md file.<br />
<br />
There are two types of custom variables: custom set variables, which set a state in BCI2000 to some value, and custom get variables, which retrieve the value of a state variable from BCI2000.<br />
<br />
Custom set variables contain the name of the state to write to, a Func<int> delegate(a piece of code represented by a method or lambda expression which returns the value to send to BCI2000), a scale factor to scale the variable by, in order to avoid truncation due to the fact that BCI2000 state variables are only unsigned integers, and a type.<br />
Types are defined by the enum UnityBCI2000.StateType, which currently holds 5 values, which are signed integers of bit widths 16 and 32, as well as boolean, which is an unsigned integer of bit width 1. Signed numbers will be represented in BCI2000 by two state variables: The magnitude of the number and its sign, which is 0 for positive and 1 for negative.<br />
<br />
Custom get variables contain the name of the state to read from, as well as an Action<int> delegate(a piece of code which takes an int as a parameter), which will receive the value from BCI2000.<br />
For reference on delegates see the [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/delegates/ C# Programming Guide].<br />
Note: UnityBCI2000 uses reflection in order to reduce the amount of boilerplate code needed to implement a custom state variable, as well as simplify the process of adding and indexing of custom state variables.<br />
<br />
Template for adding custom variables:<br />
<tt><br />
public class <ClassName> : CustomVariableBase<br />
{<br />
public override void AddCustomVariables()<br />
{<br />
customVariables.Add(new CustomSetVariable( //Copy this for more set variables<br />
"[Name]",<br />
new Func<float>(() => [Code which returns variable to send]),<br />
[Scale],<br />
UnityBCI2000.StateType.[Type]<br />
));<br />
<br />
customVariables.Add(new CustomGetVariable( //Copy this for more get variables<br />
"[Name]", <br />
new Action<int> ((int i) => [Code which uses i])<br />
));<br />
<br />
}<br />
}<br />
</tt><br />
<br />
Example of a custom variable provider script:<br />
<tt><br />
public class CustomVariableSupplier1 : CustomVariableBase<br />
{<br />
public override void AddCustomVariables() <br />
{<br />
customVariables.Add(new CustomSetVariable( <br />
"Custom variable 1",<br />
new Func<float>(() => {return 65 / 5;}),<br />
100,<br />
UnityBCI2000.StateType.SignedInt16<br />
));<br />
<br />
customVariables.Add(new CustomSetVariable(<br />
"Custom variable 2: Frame count",<br />
new Func<float>(() => Time.frameCount),<br />
1,<br />
UnityBCI2000.StateType.UnsignedInt32<br />
));<br />
<br />
customVariables.Add(new CustomGetVariable( <br />
"StateName", <br />
new Action<int> ((int i) => {score = i})<br />
));<br />
}<br />
}<br />
</tt><br />
<br />
<br />
1. Add a new C# script to the object which you want to take data from.<br />
<br />
2. Edit the script to change the inherited class to be CustomVariableBase instead of MonoBehavior.<br />
<br />
3. Implement the AddCustomVariables method, and have it add Custom Variables to the customVariables List, by calling customVariables.Add. <br />
<br />
4. Drag this new script into the Custom Variable Supplier field of the BCI2000StateSender Component.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:UnityBCI2000&diff=9205Contributions:UnityBCI20002021-10-06T03:46:49Z<p>Tytbutler: </p>
<hr />
<div>==Synopsis==<br />
UnityBCI2000 is a tool for integration of Unity applications with BCI2000.<br />
<br />
==Tutorial==<br />
For information on how to use Unity itself, see the Unity [https://docs.unity3d.com/Manual/index.html manual]. This tutorial assumes knowledge of how to use Unity. It is recommended to know how GameObjects and Components work.<br />
More in-depth detail on how UnityBCI2000 works is provided in the README.md file.<br />
<br />
<br />
<br />
First, download UnityBCI2000 from [https://github.com/neurotechcenter/UnityBCI2000 GitHub]. As of now, UnityBCI2000 is not a full Unity package, but it works the same. Place the C# files from the Runtime folder, as well as BCI2000RemoteNET.dll, within the Assets directory of your Unity project.<br />
<br />
Create an empty GameObject and add the script UnityBCI2000 as a Component. This will serve as the central connection to the BCI2000 Operator. As of now, it is not possible to use multiple scenes with one BCI2000 connection.<br />
<br />
1. Add a UnityBCI2000.cs to the GameObject as a Script Component. <br />
2.Specify the path to the operator using the Operator Path field, as well as the names of the modules to start up alongside it. <br />
-If you have an instance of the operator already running, specify the IP and port it is listening on using the Telnet Ip and Telnet Port fields instead.<br />
<br />
-You can also set a custom log file location, as well as tell the program to log sent states and received prompts. '''NOTE: There is a known issue with writing to the log file, this is remedied by changing the name of the file to write to. This is an issue with BCI2000RemoteNET, and will be fixed in upcoming updates.'''<br />
<br />
3. Now, add a Script component of the script BCI2000StateSender to the object which you want to take data from. <br />
4. Drag the BCI2000 GameObject from step 1 into the UnityBCI2000Object field of the BCI2000StateSender.<br />
-BCI2000StateSender comes with some predefined states to send, as well as values to scale them by. These are the global and screen coordinates, as well as whether the object is on screen.<br />
<br />
===Adding Custom Variables===<br />
Due to the way Unity works, adding custom variables must be done from a custom script, unique to each GameObject, if the GameObjects are not identical. Unfortunately, this means that some knowledge of C# programming is required, but templates for a CustomVariableSupplier script are provided within the README.md file.<br />
<br />
There are two types of custom variables: custom set variables, which set a state in BCI2000 to some value, and custom get variables, which retrieve the value of a state variable from BCI2000.<br />
<br />
Custom set variables contain the name of the state to write to, a Func<int> delegate(a piece of code represented by a method or lambda expression which returns the value to send to BCI2000), a scale factor to scale the variable by, in order to avoid truncation due to the fact that BCI2000 state variables are only unsigned integers, and a type.<br />
Types are defined by the enum UnityBCI2000.StateType, which currently holds 5 values, which are signed integers of bit widths 16 and 32, as well as boolean, which is an unsigned integer of bit width 1. Signed numbers will be represented in BCI2000 by two state variables: The magnitude of the number and its sign, which is 0 for positive and 1 for negative.<br />
<br />
Custom get variables contain the name of the state to read from, as well as an Action<int> delegate(a piece of code which takes an int as a parameter), which will receive the value from BCI2000.<br />
For reference on delegates see the [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/delegates/ C# Programming Guide].<br />
Note: UnityBCI2000 uses reflection in order to reduce the amount of boilerplate code needed to implement a custom state variable, as well as simplify the process of adding and indexing of custom state variables.<br />
<br />
Template for adding custom variables:<br />
<tt><br />
public class <ClassName> : CustomVariableBase<br />
{<br />
public override void AddCustomVariables()<br />
{<br />
customVariables.Add(new CustomSetVariable( //Copy this for more set variables<br />
"[Name]",<br />
new Func<float>(() => [Code which returns variable to send]),<br />
[Scale],<br />
UnityBCI2000.StateType.[Type]<br />
));<br />
<br />
customVariables.Add(new CustomGetVariable( //Copy this for more get variables<br />
"[Name]", <br />
new Action<int> ((int i) => [Code which uses i])<br />
));<br />
<br />
}<br />
}<br />
</tt><br />
<br />
Example of a custom variable provider script:<br />
<tt><br />
public class CustomVariableSupplier1 : CustomVariableBase<br />
{<br />
public override void AddCustomVariables() <br />
{<br />
customVariables.Add(new CustomSetVariable( <br />
"Custom variable 1",<br />
new Func<float>(() => {return 65 / 5;}),<br />
100,<br />
UnityBCI2000.StateType.SignedInt16<br />
));<br />
<br />
customVariables.Add(new CustomSetVariable(<br />
"Custom variable 2: Frame count",<br />
new Func<float>(() => Time.frameCount),<br />
1,<br />
UnityBCI2000.StateType.UnsignedInt32<br />
));<br />
<br />
customVariables.Add(new CustomGetVariable( <br />
"StateName", <br />
new Action<int> ((int i) => {score = i})<br />
));<br />
}<br />
}<br />
</tt><br />
<br />
<br />
1. Add a new C# script to the object which you want to take data from.<br />
2. Edit the script to change the inherited class to be CustomVariableBase instead of MonoBehavior.<br />
3. Implement the AddCustomVariables method, and have it add Custom Variables to the customVariables List, by calling customVariables.Add.<br />
4. Drag this new script into the Custom Variable Supplier field of the BCI2000StateSender Component.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:UnityBCI2000&diff=9204Contributions:UnityBCI20002021-10-06T02:46:24Z<p>Tytbutler: </p>
<hr />
<div>==Synopsis==<br />
UnityBCI2000 is a tool for integration of Unity applications with BCI2000.<br />
<br />
==Tutorial==<br />
For information on how to use Unity itself, see the Unity [https://docs.unity3d.com/Manual/index.html manual]. This tutorial assumes knowledge of how to use Unity. It is recommended to know how GameObjects and Components work.<br />
<br />
<br />
<br />
First, download UnityBCI2000 from [https://github.com/neurotechcenter/UnityBCI2000 GitHub]. As of now, UnityBCI2000 is not a full Unity package, but it works the same. Place the C# files from the Runtime folder, as well as BCI2000RemoteNET.dll, within the Assets directory of your Unity project.<br />
<br />
Create an empty GameObject and add the script UnityBCI2000 as a Component. This will serve as the central connection to the BCI2000 Operator. As of now, it is not possible to use multiple scenes with one BCI2000 connection.<br />
<br />
Add a UnityBCI2000.cs to the GameObject as a Script Component. Specify the path to the operator using the Operator Path field, as well as the names of the modules to start up alongside it. If you have an instance of the operator already running, specify the IP and port it is listening on using the Telnet Ip and Telnet Port fields instead.<br />
<br />
You can also set a custom log file location, as well as tell the program to log sent states and received prompts.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:BCI2000RemoteNET&diff=9197Contributions:BCI2000RemoteNET2021-09-28T01:33:18Z<p>Tytbutler: </p>
<hr />
<div>==Synopsis==<br />
BCI2000RemoteNET is an implementation of [[Programming_Reference:BCI2000Remote_Class|BCI2000Remote]] as a .NET Standard assembly, for use within .NET languages such as C#, as well as associated applications such as Unity (See [[Contributions:UnityBCI2000|UnityBCI2000]]). Similarly to BCI2000Remote, it sends [[User_Reference:Operator_Module_Scripting|Operator Scripting Commands]] over TCP to a running [[User_Reference:Operator_Module|Operator Module]], or starts up BCI2000 on its own. It does not depends on the BCI2000 Framework, but requires a .NET environment (.NET Framework, .NET Core, Mono) to run.<br />
<br />
==Description==<br />
BCI2000RemoteNET contains a class, BCI2000Remote, which handles connection and communication with the Operator.<br />
To start, instantiate a BCI2000Remote object, set the operator path if starting a new Operator, and call the Connect() method.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:BCI2000RemoteNET&diff=9196Contributions:BCI2000RemoteNET2021-09-28T01:23:01Z<p>Tytbutler: Created page with "==Synopsis== BCI2000RemoteNET is an implementation of BCI2000Remote as a .NET Standard assembly, for use within .NET languages su..."</p>
<hr />
<div>==Synopsis==<br />
BCI2000RemoteNET is an implementation of [[Programming_Reference:BCI2000Remote_Class|BCI2000Remote]] as a .NET Standard assembly, for use within .NET languages such as C#, as well as associated applications such as Unity (See [[Contributions:UnityBCI2000|UnityBCI2000]]). Similarly to BCI2000Remote, it sends [[User_Reference:Operator_Module_Scripting|Operator Scripting Commands]] over TCP to a running [[User_Reference:Operator_Module|Operator Module]], or starts up BCI2000 on its own.</div>Tytbutlerhttps://www.bci2000.org/mediawiki/index.php?title=Contributions:UnityBCI2000&diff=9195Contributions:UnityBCI20002021-09-28T01:19:50Z<p>Tytbutler: Created page with "==Synopsis== UnityBCI2000 is a tool for integration of Unity applications with BCI2000."</p>
<hr />
<div>==Synopsis==<br />
UnityBCI2000 is a tool for integration of Unity applications with BCI2000.</div>Tytbutler