BCI2000 Wiki - User contributions [en]

Contributions:RipplePyADC

2024-05-23T19:46:55Z

Dmehta: /* Known Issues */

==Introduction==
RipplePyADC is a source module that allows for utilization of the Ripple Grapevine and other Ripple devices within BCI2000 through BCPy2000.

==Video Overview==

==Versioning==

===Authors===
* Dhruva Mehta (mehta@neurotechcenter.org)

===Version History===
* 9/22/2023 Initial Creation and Setup

===Source Code Revisions===
*Initial development:
*Tested under:
*Known to compile under:
*Broken since: --

===Known Issues===

Stimulation has not been implemented yet.

There may be some block timing issues only visually due to how data is being acquired in BCPy2000. In practice, the data acquired is valid.

Some data streams may not be available depending on the device and the front-end used.

==Using the RipplePyADC==

To use the Ripple Python ADC, you will need to have a Ripple device that works with Trellis and Ripple's Python API. You will also need a computer set up with both BCI2000 and BCPy2000, which we will go over later.

===Initial Setup===

For the initial setup of your device, please follow the Ripple user manual for your specific device.

====Trellis====

Trellis is a user interface program that has been included with your device. Please use Trellis to test your connection with the device, such as stimulating and recording, as a means of debugging any connection issues or errors.

====Python API====

Ripple has developed a Python interface to Trellis and the Grapevine Neural Interface Processor (NIP) called Xipppy, which is being used in this source module. If there is a functionality that is not implemented, please first check the Python API to see if Ripple has it implemented themselves. If it is missing from this source module but implemented in their API, please contact us to update the source module.

==How to set up with BCPy2000==

Now we will set up the research PC. First, follow the BCPy2000 installation guide found '''[[BCPy2000|here]]''' to install BCPy2000 and compile the solution on your PC.

===Creating a Batch File===

Creating a batch file with BCPy2000 is very straightforward. If you followed the guide, you will already have a few python batch files in the batch folder of your BCI2000 installation since you copied them over from your BCPy2000 installation. If you don't already have a batch file related to Ripple Python, you can create one by copying the template batch file, and editing it. All you need to do is change the values of
start executable PythonSource --local --PythonSrcClassFile=BciSource.py --PythonSrcShell=0 --PythonSrcLog=Srclogger.txt

start executable PythonSignalProcessing --local --PythonSigClassFile=BciSignalProcessing.py --PythonSigShell=0 --PythonSigLog=Siglogger.txt

start executable PythonApplication --local --PythonAppClassFile=BciApplication.py --PythonAppShell=0 --PythonAppLog=Applogger.txt
to
start executable PythonSource --local --PythonSrcClassFile=ripple/ripplePC.py --PythonSrcShell=0 --PythonSrcLog=aaaaa.txt

start executable DummySignalProcessing --local

start executable DummyApplication --local

Here, you can also manually change the logger files for use with debugging.

===Installing the Python Module===

To actually be able to use the Ripple's Python API with BCPy2000, it needs to be installed with your BCPy installation. First download and unzip the whl files provided by Ripple. Depending on your operating system, right-click and copy the path to the whl file. For reference, I used version 0.16.19 on Python 3.8.

<gallery mode="packed" heights=500px>
File:Ripple_whl_path.png|Copying the path
</gallery>

Now, open command prompt and navigate to the folder containing your BCPy2000 installation. Now, run the command
python -m pip install "YOUR_PATH_HERE"
where "YOUR_PATH_HERE" is your path in quotations.

<gallery mode="packed" heights=300px>
File:Ripple_api_install.png|Installing the module
</gallery>

After installing, you should be good to test the source module!

===Debugging===

Before debugging with BCPy2000, please use Trellis to make sure a proper connection is established. Once you have done that, there are a few methods to test the functionality of both the source module and the underlying Python API.

First we will test the Python API. The following is a simple script to test connecting to a device in both UDP and TCP:

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import xipppy as xp
from time import sleep

def connectToProcessor():

# Close connection
xp._close()
sleep(0.001)
# Connect to processor (Try UDP then TCP).
try:
xp._open()
except:
try:
xp._open(use_tcp=True)
except:
print("Failed to connect to processor.")
else:
print("Connected over TCP")
else:
print("Connected over UDP")

sleep(0.001)

if __name__ == '__main__':
connectToProcessor()
xp._close()

The following script can be used to test data acquisition:

import xipppy
import numpy as np
import time

if __name__ == '__main__':
with xipppy.open(use_tcp=true):
i = 0
data_arrays = []
while i < 10:
ts = xipppy.time()
time.sleep(1)
array = xipppy.cont_hires(100, [0], ts)
data_arrays.append(array)
i += 1
print(data_arrays)

Most of the time, the error will be:
xipppy.exception.XippPyException: Library already open or failed to initialize
It is hard to pinpoint exactly what caused the error in this case, and even Ripple's documentation states that this error lacks any additional information.
You can also manually edit the python source module and utilize print statements or write to a file within the program. The source module will print out to the designated logger file that was named in the batch file.

==Running the Source Module==

===Initial Parameters===
Now that you have installed the source module, you can begin testing to make sure that data is being acquired. Before you test the source module, you can make sure that a signal is being passed through by using the Trellis application provided by Ripple. This will eliminate any doubt about whether data is actually being acquired in the first place, since you will be able to see a signal generated in Trellis.

Next, double click on the batch file to start the source module. Here you will be able to configure parameters and even save them as a file to load in for future experiment runs.

First, you can decide the number of source channels. This is going to be the same as the number of electrodes that you would like a signal to be acquired and visualized from.

Next, you can choose the number of samples to be acquired per acquisition block with the sample block size.

Next, you must decide which data acquisition function you would like to choose. The six options are raw, lfp, hifreq, hires, emg, and status. The specifics of these data streams are covered in the Ripple manual. The important thing to note is that the choices for macro and micro are both "raw". Macro and micro depends on which front-end you are using.

Next, we must check that the sampling rate matches the sampling rate of the data acquisition function you choose. The frequencies are listed in the Parameters section of this wiki. It is important that they match otherwise you will get errors on data acquisition.

The final thing to change would be which specific electrodes to acquire data from, via the specific channel parameter. Here, you set put the electrodes in a 0-indexed list (electrode 1 is 0, electrode 2 is 1, etc.). The length of this list must match the number of source channels you put earlier. Otherwise, this list will be overwritten during preflight.

You can also change other parameters as detailed in the parameter guide.

<gallery mode="packed" heights=500px>
File:Ripple_Source_Parameters.png|Source Parameters
</gallery>

===Stimulation===

If you would like to use stimulation with your Ripple device, there is a separate parameter tab where you can create stimulation segments, sequences, triggers, and trains. This is still currently under development.

<gallery mode="packed" heights=500px>
File:Ripple_Stimulation_Parameters.png|Stimulation Parameters
</gallery>

==Parameters==

===SourceCh===
The total number of digitized and stored channels.

===SampleBlockSize===
Samples per channel per digitized block.
Together with the sampling rate, this parameter determines how often per second data are collected, processed, and feedback is updated. For example, at 1000 Hz sampling and a SampleBlockSize of 20, the system (e.g., source signal display, signal processing, and stimulus presentation) will be updated 50 times per second.

===SamplingRate===
The sample rate of the system. '''It is important that this parameter matches the sampling rate of the data acquisition function that you want to use. Otherwise, the two frequencies will be out of sync and you will eventually get either an error or a flat line in the signal visualizer.'''

===SourceChOffset===
Offset for each channel.

===SourceChGain===
Gain for each channel.

===ChannelNames===
Names of each channel.

===ReferenceCh===
This list defines what channels will be used as reference. This list is uploaded to the device and set in hardware, effecting the raw bio-signal data that is recorded by BCI2000. If you do not want to effect the raw bio-signal data that is recorded, you can use the [https://www.bci2000.org/mediawiki/index.php/User_Reference:SpatialFilter spatial filter]. If this parameter is set to auto, no reference channels are used.

===DataStream===
The type of data stream you would like to use for acquisition. There are six types of data streams you can use, each with different frequencies:

{| class="wikitable" style="margin-right:auto; margin-left:10px; text-align:center;"
|+ Data Streams
|-
! Stream !! Frequency (kHz)
|-
| macro || 15
|-
| lfp || 1
|-
| hires || 2
|-
| hifreq || 15
|-
| emg || 15
|-
| status || 2
|-
| micro || 30
|}

Before trying to use a specific data stream, test to make sure you can acquire data from Trellis with it. If you don't see a signal in Trellis, you will not be able to see data in BcPy2000 either.

===SpecificCh===
Here, you can choose which channels you want to actually acquire data from, just put the number of the channel you would like in a corresponding list section. Channel numbers start with 0. You can choose any number of channels by readjusting the list matrix size. Numbers do not need to be in ascending order, however the channels will appear in order they are put in the list from top to bottom. '''Make sure that the number of specific channels matches the SourceCh parameter.''' Otherwise, you will get thrown an error and the electrode list will automatically be changed to match the value of SourchCh.

==Device Parameters==

==See also==
[[User Reference:Filters]], [[Contributions:ADCs]]

[[Category:Contributions]][[Category:Data Acquisition]]

Contributions:RipplePyADC

2024-05-23T19:45:22Z

Dmehta: /* DataStream */

==Introduction==
RipplePyADC is a source module that allows for utilization of the Ripple Grapevine and other Ripple devices within BCI2000 through BCPy2000.

==Video Overview==

==Versioning==

===Authors===
* Dhruva Mehta (mehta@neurotechcenter.org)

===Version History===
* 9/22/2023 Initial Creation and Setup

===Source Code Revisions===
*Initial development:
*Tested under:
*Known to compile under:
*Broken since: --

===Known Issues===

==Using the RipplePyADC==

To use the Ripple Python ADC, you will need to have a Ripple device that works with Trellis and Ripple's Python API. You will also need a computer set up with both BCI2000 and BCPy2000, which we will go over later.

===Initial Setup===

For the initial setup of your device, please follow the Ripple user manual for your specific device.

====Trellis====

Trellis is a user interface program that has been included with your device. Please use Trellis to test your connection with the device, such as stimulating and recording, as a means of debugging any connection issues or errors.

====Python API====

Ripple has developed a Python interface to Trellis and the Grapevine Neural Interface Processor (NIP) called Xipppy, which is being used in this source module. If there is a functionality that is not implemented, please first check the Python API to see if Ripple has it implemented themselves. If it is missing from this source module but implemented in their API, please contact us to update the source module.

==How to set up with BCPy2000==

Now we will set up the research PC. First, follow the BCPy2000 installation guide found '''[[BCPy2000|here]]''' to install BCPy2000 and compile the solution on your PC.

===Creating a Batch File===

Creating a batch file with BCPy2000 is very straightforward. If you followed the guide, you will already have a few python batch files in the batch folder of your BCI2000 installation since you copied them over from your BCPy2000 installation. If you don't already have a batch file related to Ripple Python, you can create one by copying the template batch file, and editing it. All you need to do is change the values of
start executable PythonSource --local --PythonSrcClassFile=BciSource.py --PythonSrcShell=0 --PythonSrcLog=Srclogger.txt

start executable PythonSignalProcessing --local --PythonSigClassFile=BciSignalProcessing.py --PythonSigShell=0 --PythonSigLog=Siglogger.txt

start executable PythonApplication --local --PythonAppClassFile=BciApplication.py --PythonAppShell=0 --PythonAppLog=Applogger.txt
to
start executable PythonSource --local --PythonSrcClassFile=ripple/ripplePC.py --PythonSrcShell=0 --PythonSrcLog=aaaaa.txt

start executable DummySignalProcessing --local

start executable DummyApplication --local

Here, you can also manually change the logger files for use with debugging.

===Installing the Python Module===

To actually be able to use the Ripple's Python API with BCPy2000, it needs to be installed with your BCPy installation. First download and unzip the whl files provided by Ripple. Depending on your operating system, right-click and copy the path to the whl file. For reference, I used version 0.16.19 on Python 3.8.

<gallery mode="packed" heights=500px>
File:Ripple_whl_path.png|Copying the path
</gallery>

Now, open command prompt and navigate to the folder containing your BCPy2000 installation. Now, run the command
python -m pip install "YOUR_PATH_HERE"
where "YOUR_PATH_HERE" is your path in quotations.

<gallery mode="packed" heights=300px>
File:Ripple_api_install.png|Installing the module
</gallery>

After installing, you should be good to test the source module!

===Debugging===

Before debugging with BCPy2000, please use Trellis to make sure a proper connection is established. Once you have done that, there are a few methods to test the functionality of both the source module and the underlying Python API.

First we will test the Python API. The following is a simple script to test connecting to a device in both UDP and TCP:

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import xipppy as xp
from time import sleep

def connectToProcessor():

# Close connection
xp._close()
sleep(0.001)
# Connect to processor (Try UDP then TCP).
try:
xp._open()
except:
try:
xp._open(use_tcp=True)
except:
print("Failed to connect to processor.")
else:
print("Connected over TCP")
else:
print("Connected over UDP")

sleep(0.001)

if __name__ == '__main__':
connectToProcessor()
xp._close()

The following script can be used to test data acquisition:

import xipppy
import numpy as np
import time

if __name__ == '__main__':
with xipppy.open(use_tcp=true):
i = 0
data_arrays = []
while i < 10:
ts = xipppy.time()
time.sleep(1)
array = xipppy.cont_hires(100, [0], ts)
data_arrays.append(array)
i += 1
print(data_arrays)

Most of the time, the error will be:
xipppy.exception.XippPyException: Library already open or failed to initialize
It is hard to pinpoint exactly what caused the error in this case, and even Ripple's documentation states that this error lacks any additional information.
You can also manually edit the python source module and utilize print statements or write to a file within the program. The source module will print out to the designated logger file that was named in the batch file.

==Running the Source Module==

===Initial Parameters===
Now that you have installed the source module, you can begin testing to make sure that data is being acquired. Before you test the source module, you can make sure that a signal is being passed through by using the Trellis application provided by Ripple. This will eliminate any doubt about whether data is actually being acquired in the first place, since you will be able to see a signal generated in Trellis.

Next, double click on the batch file to start the source module. Here you will be able to configure parameters and even save them as a file to load in for future experiment runs.

First, you can decide the number of source channels. This is going to be the same as the number of electrodes that you would like a signal to be acquired and visualized from.

Next, you can choose the number of samples to be acquired per acquisition block with the sample block size.

Next, you must decide which data acquisition function you would like to choose. The six options are raw, lfp, hifreq, hires, emg, and status. The specifics of these data streams are covered in the Ripple manual. The important thing to note is that the choices for macro and micro are both "raw". Macro and micro depends on which front-end you are using.

Next, we must check that the sampling rate matches the sampling rate of the data acquisition function you choose. The frequencies are listed in the Parameters section of this wiki. It is important that they match otherwise you will get errors on data acquisition.

The final thing to change would be which specific electrodes to acquire data from, via the specific channel parameter. Here, you set put the electrodes in a 0-indexed list (electrode 1 is 0, electrode 2 is 1, etc.). The length of this list must match the number of source channels you put earlier. Otherwise, this list will be overwritten during preflight.

You can also change other parameters as detailed in the parameter guide.

<gallery mode="packed" heights=500px>
File:Ripple_Source_Parameters.png|Source Parameters
</gallery>

===Stimulation===

If you would like to use stimulation with your Ripple device, there is a separate parameter tab where you can create stimulation segments, sequences, triggers, and trains. This is still currently under development.

<gallery mode="packed" heights=500px>
File:Ripple_Stimulation_Parameters.png|Stimulation Parameters
</gallery>

==Parameters==

===SourceCh===
The total number of digitized and stored channels.

===SampleBlockSize===
Samples per channel per digitized block.
Together with the sampling rate, this parameter determines how often per second data are collected, processed, and feedback is updated. For example, at 1000 Hz sampling and a SampleBlockSize of 20, the system (e.g., source signal display, signal processing, and stimulus presentation) will be updated 50 times per second.

===SamplingRate===
The sample rate of the system. '''It is important that this parameter matches the sampling rate of the data acquisition function that you want to use. Otherwise, the two frequencies will be out of sync and you will eventually get either an error or a flat line in the signal visualizer.'''

===SourceChOffset===
Offset for each channel.

===SourceChGain===
Gain for each channel.

===ChannelNames===
Names of each channel.

===ReferenceCh===
This list defines what channels will be used as reference. This list is uploaded to the device and set in hardware, effecting the raw bio-signal data that is recorded by BCI2000. If you do not want to effect the raw bio-signal data that is recorded, you can use the [https://www.bci2000.org/mediawiki/index.php/User_Reference:SpatialFilter spatial filter]. If this parameter is set to auto, no reference channels are used.

===DataStream===
The type of data stream you would like to use for acquisition. There are six types of data streams you can use, each with different frequencies:

{| class="wikitable" style="margin-right:auto; margin-left:10px; text-align:center;"
|+ Data Streams
|-
! Stream !! Frequency (kHz)
|-
| macro || 15
|-
| lfp || 1
|-
| hires || 2
|-
| hifreq || 15
|-
| emg || 15
|-
| status || 2
|-
| micro || 30
|}

Before trying to use a specific data stream, test to make sure you can acquire data from Trellis with it. If you don't see a signal in Trellis, you will not be able to see data in BcPy2000 either.

===SpecificCh===
Here, you can choose which channels you want to actually acquire data from, just put the number of the channel you would like in a corresponding list section. Channel numbers start with 0. You can choose any number of channels by readjusting the list matrix size. Numbers do not need to be in ascending order, however the channels will appear in order they are put in the list from top to bottom. '''Make sure that the number of specific channels matches the SourceCh parameter.''' Otherwise, you will get thrown an error and the electrode list will automatically be changed to match the value of SourchCh.

==Device Parameters==

==See also==
[[User Reference:Filters]], [[Contributions:ADCs]]

[[Category:Contributions]][[Category:Data Acquisition]]

Contributions:eegoRTADC

2024-05-23T19:44:22Z

Dmehta: /* Parameters */

==Introduction==
eegoRTADC is a source module that allows for utilization of the eego product family from ANT neuro and its associated SDK within BCI2000. For more information on the eego product family, please visit [https://www.ant-neuro.com/products/eego_product_family this site]

==Video Overview==

==Versioning==

===Authors===
* Dhruva Mehta (mehta@neurotechcenter.org)

===Version History===
* 5/23/2024 Initial testing done with Version 1.3.30.57172 of the eego SDK and the eego MyLab amplifier (EE-225)

===Source Code Revisions===
*Initial development:
*Tested under:
*Known to compile under:
*Broken since: --

===Known Issues===

There is currently an issue where trying to access the amplifier's information results in "need an initialized sdk context". During testing, the amplifier wouldn't power on after some time, thus, this is most likely due to an issue with the amplifier not being powered on properly. The amplifier is able to be recognized via USB after drivers are installed properly. When drivers are not installed properly, there is an error stating "amplifier list empty".

===Initial Setup===

For the initial setup of your device, please follow the SDK manual provided by ANT neuro for more detail. This wiki guide will give a brief overview of the steps needed to work with BCI2000.

First, follow the BCI2000 installation guide found [[Programming_Howto:Building_and_Customizing_BCI2000|here]] to install BCI2000 and compile the solution on your PC.

Next, we will set up the device. This guide will go over setting up the device on a Windows system. If you use Linux, please refer to the manual.

When you first plug in the device into the computer via USB, you must first go to Device Manager and find the listed device under "Other Devices". Right Click on the device and then choose "Update Drivers". Then click "Browse my computer for drivers". Navigate to the location of the SDK provided to you by ANT Neuro on your computer. Then, the drivers will be located in "SDK_ROOT/windows/driver". Click "Next" and "Close". Your device should now be listed under "Medical Imagining Solutions" as "eego amplifier".

==Parameters==
===Source Tab===
====Signal Properties====
*'''SourceCh''' - This parameter should be "auto", as it is determined by the amplifier. Can also be set by user if specific channel only is desired.

*'''SampleBlockSize''' - Cannot be set nor retrieved by the SDK. Automatically is set at 32.

*'''SamplingRate''' - Depending on the amplifier being used, there are specific sampling rates allowed. If the sampling rate is different, and error will be thrown. Valid values are among: 500, 512, 1000, 1024, 2000, 2048, 4000, 4096, 8000, 8192, 16000, and 16384.

*'''ChannelNames''' - Can be manually written by user, but 'auto' is simpler.

*'''SourceChOffset''' - Use 'auto'.

*'''SourceChGain''' - Use 'auto'.

Contributions:eegoRTADC

2024-05-23T17:34:51Z

Dmehta:

==Introduction==
eegoRTADC is a source module that allows for utilization of the eego product family from ANT neuro and its associated SDK within BCI2000. For more information on the eego product family, please visit [https://www.ant-neuro.com/products/eego_product_family this site]

==Video Overview==

==Versioning==

===Authors===
* Dhruva Mehta (mehta@neurotechcenter.org)

===Version History===
* 5/23/2024 Initial testing done with Version 1.3.30.57172 of the eego SDK and the eego MyLab amplifier (EE-225)

===Source Code Revisions===
*Initial development:
*Tested under:
*Known to compile under:
*Broken since: --

===Known Issues===

There is currently an issue where trying to access the amplifier's information results in "need an initialized sdk context". During testing, the amplifier wouldn't power on after some time, thus, this is most likely due to an issue with the amplifier not being powered on properly. The amplifier is able to be recognized via USB after drivers are installed properly. When drivers are not installed properly, there is an error stating "amplifier list empty".

===Initial Setup===

For the initial setup of your device, please follow the SDK manual provided by ANT neuro for more detail. This wiki guide will give a brief overview of the steps needed to work with BCI2000.

First, follow the BCI2000 installation guide found [[Programming_Howto:Building_and_Customizing_BCI2000|here]] to install BCI2000 and compile the solution on your PC.

Next, we will set up the device. This guide will go over setting up the device on a Windows system. If you use Linux, please refer to the manual.

When you first plug in the device into the computer via USB, you must first go to Device Manager and find the listed device under "Other Devices". Right Click on the device and then choose "Update Drivers". Then click "Browse my computer for drivers". Navigate to the location of the SDK provided to you by ANT Neuro on your computer. Then, the drivers will be located in "SDK_ROOT/windows/driver". Click "Next" and "Close". Your device should now be listed under "Medical Imagining Solutions" as "eego amplifier".

==Parameters==
===Source Tab===
====Signal Properties====
*'''SourceCh''' - This parameter should be "auto", as it is determined by the size of the "RecordingChIDs" parameter.

*'''SampleBlockSize''' - Number of samples that are transmitted at a time.

*'''SamplingRate''' - Some channels on the Neuro Omega are recorded at different sampling rates, so this parameter is dictated by the configuration of the clinical system and must be manually entered accordingly. Information on how to check the sampling rate of a given channel is coming soon.

*'''ChannelNames''' - This should be set to auto, as the names of the channels will be automatically acquired from the Neuro Omega.

*'''SourceChOffset''' - Use 'auto', or needs to be the length of number of channels in RecordingChIDs.

*'''SourceChGain''' - Use 'auto', or needs to be the length of number of channels in RecordingChIDs.

*'''RecordingChIDs''' - This parameter should be a list of channel IDs corresponding to the channels you want to record from. Each of these channels must have the same sampling rate.

Contributions:eegoRTADC

2024-05-23T17:26:58Z

Dmehta:

Contributions:eegoRTADC

2024-05-23T16:39:02Z

Dmehta: /* Initial Setup */

2023-12-12T18:18:22Z

Dmehta: