BCI2000 Wiki - User contributions [en]

CortecExperience

2026-05-15T16:51:56Z

Nluczak:

=Introduction Video of CorTec Brain Interchange with BCI2000=
<youtube alignment="center" dimensions="900">https://youtu.be/TMZPQPhRnn8</youtube>

=Getting Started with Cortec BIC in BCI2000=

#[[Programming Howto:Building and Customizing BCI2000|Install BCI2000]]
#*Here you will learn how to configure and compile BCI2000 on your own computer.

#[[CortecADC]]
#*This article steps you through all the available configuration options and information stored with using BCI2000 with the Brain Interchange.

#[[Contributions:XsensMTwLogger]]
#*This article shows how to combine any BCI2000 source module the XsensMTw device to capture motion simultaneously with electrophysiological signals.

=Canine Surgical Procedure=
This article presents a brief introduction to surgical protocols for the implantation of the CorTec Brain Interchange. The main objective is to introduce the essential surgical considerations for implanting this device in different animal models.

Download the [https://bci2000.org/downloads/doc/Canine_Cortec_Surgical_Protocol.pdf surgical protocol here].

Download the updated [https://wustl.box.com/s/hq5rgw4mnb70nd6f07jkk50u2o70n46s surgical protocol here].

=Preliminary experience with the CorTec BrainInterchange device in a canine modele=
This article describes initial work toward an ecosystem for adaptive neuromodulation in humans by documenting the experience of implanting CorTec's BrainInterchange (BIC) device in a beagle canine and using the BCI2000 environment to interact with the BIC device. It begins with laying out the substantial opportunity presented by a useful, easy-to-use, and widely available hardware/software ecosystem in the current landscape of the field of adaptive neuromodulation, and then describes experience with implantation, software integration, and post-surgical validation of recording of brain signals and implant parameters. Initial experience suggests that the hardware capabilities of the BIC device are fully supported by BCI2000, and that the BIC/BCI2000 device can record and process brain signals during free behavior. With further development and validation, the BIC/BCI2000 ecosystem could become an important tool for research into new adaptive neuromodulation protocols in humans.

Schalk G, Worrell S, Mivalt F, Belsten A, Kim I, Morris JM, Hermes D, Klassen BT, Staff NP, Messina S, Kaufmann T, Rickert J, Brunner P, Worrell GA, Miller KJ. Toward a fully implantable ecosystem for adaptive neuromodulation in humans: Preliminary experience with the CorTec BrainInterchange device in a canine model. Front Neurosci. 2022 Dec 19;16:932782. doi: 10.3389/fnins.2022.932782. PMID: 36601593; PMCID: PMC9806357.

Download the [https://bci2000.org/downloads/doc/Preliminary_experience_with_the_CorTec_BrainInterchange_device_in_a_canine_model.pdf article here].

=Data Sharing=
This data recorded is freely available on DANDI and OpenNeuro.

Download the [https://dandiarchive.org/dandiset/000571?pos=1 canine data from DANDI].

Download the [https://openneuro.org/datasets/ds004624/versions/1.0.1 canine data from OpenNeuro].

=Closed-loop Stimulation=
With BCI2000, it is possible to stimulate with the Brain Interchange based on processed signals from Brain Interchange recordings! BCI2000's infrastructure was created for closed-loop control, as it processes the recorded activity and can directly use the results to affect the task or stimulation.

'''See the [[Closed-Loop Stimulation]] page for more information!'''

<youtube alignment="center" dimensions="900">https://youtu.be/YIM_YmoHRR8</youtube>

To start out, we can review how to conduct a closed-loop brain-computer interface task. This has a very similar pipeline to closed-loop stimulation so it is a good place to start. Review the [[User Tutorial:Mu Rhythm BCI Tutorial|Mu Rhythm tutorial]] for in-depth instructions on how to set it up.

Now that we have the closed-loop task control reviewed, we can move on to closed-loop stimulation. Since CortecADC is a source module, stimulation is conducted in the source module (review the [[User Reference:Filters|Filters]] page for BCI2000 overview). This means we have to carry-over the results from the past signal processing pipeline to the next block. This can be done with States, which stream through all the modules of BCI2000 in a closed-loop fashion. Since Cortec stimulation is controlled with Expressions, a State that was changed due to the processed signal will trigger stimulation. For example, you can use EarlyOffsetExpression available in the [[User Tutorial:StimulusPresentation|StimulusPresentation]] Application module to change stimuli due to a processed signal. You would set up the stimulation to be triggered once the new stimulus is reached, due to EarlyOffsetExpression becoming true.

=Synchronize Inertial Measurement Units with the CorTec Brain Interchange=
<youtube alignment="center" dimensions="900">https://youtu.be/-SOUX5J1vJE</youtube>

[[Category:Video]]

Contributions:CortecADC

2026-05-14T22:15:06Z

Nluczak:

[[File:CorTec_BrainInterchange.png|400px|thumb|right|CorTec Brain Interchange Implant]]
CortecADC is a source module that allows for intra-cranial recording and stimulating over 32 channels via a fully implantable device. It is intended for long-term measurement of neural activity and electrical stimulation of brain tissue. See the [https://www.cortec-neuro.com/solutions/complete-system/ CorTec site] for more information.
'''See the [[CortecExperience]] page for user tutorials and a broad overview!''' After viewing the [[CortecExperience]] page, refer to this page for detailed instructions.
==Versioning==
===Authors===
* Nicholas Luczak (luczak@neurotechcenter.org)
* William Engelhardt (engelhardt@neurotechcenter.org)
* Alexander Belsten (belsten@neurotechcenter.org)
* Markus Adamek (adamek@neurotechcenter.org)
* Christian Stolle (christian.stolle@cortec-neuro.com)
===Source Code Revisions===
*Initial development: 6266
*Tested under: 9282
*Known to compile under: 9282
*Broken since: --
===BCI2000 Version History===
{|class="wikitable" style="text-align: center;"
! Date !! Revision !! Note !! Contributor
|-
!11/29/2018
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R5829
|Initial untested version
|Adamek
|-
!04/19/2021
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R6271
|First working version
|Belsten
|-
!07/22/2021
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R6339
|Changed ''ImplantLostSample'' from a BCI2000 state to a stream, so it can record individual sample loss (instead of over the whole block)
|Belsten
|-
!01/01/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7133
|Updated API to version 1.0.200.
|Engelhardt
|-
!03/08/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7251
|Stimulation functionality added
|Engelhardt
|-
!05/19/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7367
|Impedance measurement enabled
|Engelhardt
|-
!10/26/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7679
|Stimulation latency vastly improved
|Engelhardt
|-
!02/20/2024
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7847
|Version 1.0.230 added. Can change between versions in CMakeLists.txt file
|Stolle
|-
!08/09/2024
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R8313
|Version 1.0.238 added
|Stolle
|-
!01/17/2025
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7679
|Interpolation filter added to interpolate lost samples
|Engelhardt
|-
!06/25/2025
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R8915
|All listener states were changed to events
|Engelhardt
|-
!04/13/2026
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R9351
|Refactored stimulation to be more in line with Cortec and BCI2000 standards.
|Nicholas Luczak
|-
|}
===Cortec API Version History===
Cortec is continually updating their devices with new API versions. In BCI2000, we currently support versions 1.0.200, 1.0.230, and 1.0.238. Each Brain Interchange Communication unit (BIC) is only compatible with one API version. To find your compatible version, connect the USB drive that comes with your BIC. Look under:
# '''Software folder''': Each executable has the API version. E.g., <code>Bicapi_setup_1.0.200-bicapi-setup-1.0.200-rev35926.exe</code>
# '''Manuals foder''': ''Appendix1_BIC_Application_Software_Short_Manual.pdf''. On page 3, in Table 1, the third row contains the compatible version.
Here are some differences between the versions. As the device is always improving, the newest version will have the most features.
{|class="wikitable" style="text-align: center;"
! Features !! 1.0.200 !! 1.0.230 !! 1.0.238 !! 1.0.260
|-
!Matlab API
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!C/C++ API
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Stimulation modes
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!ASIC Noise Detection Mode
|style="color:red"|✘
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Monopolar stimulation (Ch → GND)
|style="color:red"|✘
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Measure GND impedances
|style="color:red"|✘
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Self-tests
|style="color:red"|✘
|style="color:red"|✘
|style="color:red"|✘
|style="color:green"|✔
|-
!Low noise recording
|style="color:red"|✘
|style="color:red"|✘
|style="color:red"|✘
|style="color:green"|✔
|-
|}
===Known Issues===
* Lost samples - The <code>ImplantLostSamples</code> state records what samples are lost, and their locations. Lost samples are replaced with the previous valid sample for all channels. In offline analysis, be sure to remove these samples and replace them with interpolates.
* The Brain Interchange Communication Unit has been seen to work with certain USB inputs, and not with others. If you are experiencing connection issues, try using a different USB port.
==Installation==
# Install BCI2000
# Insert the Cortec USB drive that comes with the Brain Interchange (BIC) device. Under ''Software'', run the ''Bicapi_setup...'' executable
# Run a batch file with CortecADC as your Signal Source!
# If you receive an error, and it states your API version is incorrect, you need to change it. Locate the ''CMakeLists.txt'' under <code>BCI2000/src/private/SignalSource/Cortec</code>. You must change Line 12, where it states <code>set(BICAPI_VERSION 200)</code>. Change 200 to 230 or 238, depending on your device (see [[#Cortec Version History | details above]]).
==Source Parameters==
These parameters can be found in the "Source" tab of the BCI2000 config window.
[[File:CortecSourceParameters.jpg|600px|thumb|center|upright=2.5|Figure 1. The default source parameters for the CortecADC]]
===SourceCh===
The total number of digitized and stored channels. In the current implementation, this parameter cannot be edited, and will default to how many channels are available from the implant.
===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. This parameter cannot be edited, and will default to the sampling rate available from the implant.
In case you are experiencing problems by higher sampling rates (e.g., data loss, jerky display, etc.), increase the SampleBlockSize so that you are updating the system less frequently (usually, updating the system 20-30 times per second is sufficient for most applications), and increase Visualize->VisualizeSourceDecimation. This parameter will decrease the number of samples per second that are actually drawn in the Source display.
===SourceChOffset===
Offset for each channel.
===SourceChGain===
Gain for each channel.
===ChannelNames===
Names of each channel.
===LogCortecBinaryFiles===
Enable or disable binary logging of raw CorTec communication data.
When enabled, a binary log file is written to the BCI2000 session directory with the name:
<code>YYYYMMDD_HHMMSS_CortecAdcLog.bin</code>
This file contains raw communication packets between the Brain Interchange Communication unit and the implant and is primarily useful for low-level debugging and support from CorTec.
Default value: <code>1</code> (enabled)
Disable this parameter if binary logs are not needed or disk space usage is a concern.
===LogStimulationEvents===
Enable logging of stimulation configuration and execution events to the Operator Log.
When enabled, detailed information about stimulation functions, trigger evaluation, and stimulation execution will be printed using <code>bciout</code> messages.
This is useful for debugging stimulation timing and verifying correct parameter interpretation.
Default value: <code>0</code> (disabled)
===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. It is strongly recommended to use at least one reference channel.
===AmplificationFactor===
Amplification factor that is applied to the recorded data on the implant. The choices are 39.5, 45.5, 51.5, 57.5 db.
===UseGround===
Enable to use the ground electrode while measuring. This setting can be overwritten during stimulation, depending if the ground electrode is being used or not. For example, if you have enabled this parameter but don't have <code>0</code> in your <code>Destination ch</code> list in the StimulationTriggers parameter, when you are stimulating you will not be using the ground electrode. Once stimulation is done, this parameter's settings are used again.
===SaveInfoFile===
Enable to save a text file, named the same as the data file run. It will contain the timestamp, amplification factor used in the run, and reference channels used. If the Impedance is measured, the impedance values will be saved to this file regardless of if this parameter is enabled.
===LogPacketErrors===
Enable to save the packet loss errors to the System Log. Helpful for debugging, however can get overwhelming if there are a lot of lost samples. The System Log can be programmatically saved by appending <code>--SystemLogFile=SOME_FILE.TXT</code> to the <code>Startup system localhost</code> line in your batch file.
==Stimulation Parameters==
The figure below summarizes the BCI2000 stimulation paradigm used by CortecADC. A BCI2000 expression (typically based on <code>StimulusCode</code>) acts as a '''Stimulation Trigger'''. When a trigger evaluates true, one or more '''Stimulation Commands''' are executed. Each Stimulation Command is composed of one or more '''Stimulation Functions''' (with optional bursts, pauses, and repetitions), and every Stimulation Function is defined by a '''Stimulation Pulse''' with pulse amplitude, pulse duration, and dead-zone parameters. Use this figure as a mental model for interpreting the <code>StimulationPulses</code> and <code>StimulationTriggers</code> parameters described below.
[[File:StimDefinition_BCI2000.png|1000px|thumb|center|upright=2.5|Figure 2. Summary of the BCI2000 stimulation paradigm. A BCI2000 trigger expression (top, based on StimulusCode) launches a Stimulation Command (red, left), which is built from repeating Stimulation Functions, optional bursts, and pauses. Each Stimulation Function is defined by a Stimulation Pulse (blue, right), parameterized by Pulse Amplitude, Pulse Duration, Dead Zone 0, and Dead Zone 1.]]
These parameters can be found in the "Stimulation" tab of the BCI2000 config window.
<gallery mode="packed" widths=300px heights=300px>
File:CortecADC_stimulation_parm.PNG
File:CortecADC_stimulationpulses_parm.PNG
File:CortecADC_stimulationtriggers_parm1.PNG
</gallery>

===EnableStimulation===
This parameter enables/disables stimulation.
===StimulationMode===
The BIC has 3 stimulation modes. Each one has limitations. Here is a brief summary of how to use each one:
#Volatile Commands: The most flexible mode, allowing stimulation commands to be defined with virtually no size constraints. However, the stimulation configuration must be uploaded immediately before execution, which introduces additional latency. Furthermore, the configuration is cleared after each command, resulting in increased latency for repeated executions. This mode is best suited for iterating across multiple stimulation configurations and designing complex stimulation paradigms.
[[File:VolatileCommand.png|1000px|thumb|center|upright=2.5|Figure 3. Figure demonstrating volatile command functionality]]
#Persistent Command: This preloading mode enables uploading up to 16 stimulation functions to the device and executing them in a predefined order (the list of FunctionID(s) in StimulationTriggers must be the same). The stimulation command remains in memory after execution and can be repeated, making it best suited for delivering continuous or continuously repeated stimulation.
#Persistent Functions: This preloading mode enables uploading up to 16 stimulation functions to the device and executing them individually by calling the stimulation function ID. The device executes only one stimulation function (the indexed one) without repetition. This mode is best suited for rapidly iterating over subsets of stimulation pulses in single-pulse stimulation settings.
[[File:PersistantFunction.png|1000px|thumb|center|upright=2.5|Figure 4. Figure demonstrating Persistant Function functionality]]

There cannot be any train settings (Train frequency and Train repetitions), so the StimulationTriggers must not have those rows. Also, StimulationTriggers must not have more than 16 columns, as that is the highest number of configurations that can be stored on the device.
Persistent Command and Functions modes have a lower latency because the stimulation is pre-uploaded. All modes are available to give you the highest amount of flexiblity with the BIC. [[#Stimulation Latency|See below for more details on latency.]]
===MeasureImpedance===
When enabled, the impedances of the used electrodes are printed when you set the configuration. All electrodes that are being recorded will conduct the impedance measurement. The impedances are shown to the user and also saved in the data directory.
===StimulationPulses===
This parameter defines stimulation ''functions''. Each column defines a stimulation waveform and electrode configuration.
Each function consists of:
* Pulse waveform parameters
* Electrode mapping
* Repetition behavior
Rows are defined as follows:
====FunctionID====
Integer identifier for this stimulation function. This ID is referenced in the <code>StimulationTriggers</code> parameter.
====Pulse Amplitude====
Amplitude of the stimulation pulse in µA.
Valid range:
0 to 6120 µA
====Pulse Duration====
Duration of the main pulse in µs.
Valid range:
10 to 2550 µs
====Dead Zone 0====
Pause between main pulse and counter pulse.
====Dead Zone 1====
Pause after pulse delivery.
====Anode(s)====
Embedded list specifying source electrodes.
Example:
<code>{ list 1 18 19 }</code>
====Cathode(s)====
Embedded list specifying return electrodes.
Use <code>0</code> to reference ground.
====Pulse Repetition====
Number of times the pulse is repeated within a function.
Range:
1 to 255
====Burst Repetition====
Number of times the function is repeated.
Range:
1 to 255
===StimulationTriggers===
Defines when stimulation functions are executed.
Each column contains:
====Trigger====
A valid BCI2000 expression.
When this expression evaluates to true, the associated stimulation function(s) are executed.
====FunctionID(s)====
List of FunctionIDs that should execute when the trigger evaluates true.
Example:
<code>
StimulusCode==1 { list 1 3 }
</code>
This means:
Execute FunctionID 1 followed by FunctionID 3 whenever the trigger becomes true.
Note:
Electrode configuration and repetition settings are defined in <code>StimulationPulses</code>, not here.
==Device Parameters==
===DeviceInfo===
This parameter cannot be edited and is automatically populated with information returned from the device, such as device type, device ID, and the firmware version.
===StateInfo===
This parameter cannot be edited and is automatically populated with information regarding state units and their multiplier. The device provides information such as humidity, temperature, control value, etc., which are recorded in BCI2000 states (see state information on this page for a complete enumeration of states). The device provides these values with floats, but BCI2000 states can only be integers. The multipliers defined in this parameter are used to increase the amount of precision in the state values. To approximately recover the original float values with the units defined in this parameter, divide each state by its corresponding multiplier.
==States==
The states encode auxiliary information returned from the Cortec implant. The device provides this data in floating point numbers, however BCI2000 can only record integers to it's states. To maintain some precision, these floats are multiplied by constants, then recorded to the states as integers. To approximately recover the original data, divide the state by its corresponding constant. Constants are shown in the following table.
{| class="wikitable" style="text-align:right;"
|- style="font-weight:bold;"
! State
! style="text-align:center;" | Constant
|-
| ImplantVoltage
| style="text-align:center;" | 1000
|-
| ImplantHumidity
| style="text-align:center;" | 100
|-
| ImplantControlValue
| style="text-align:center;" | 100
|-
| ImplantPrimaryCoilCurrent
| style="text-align:center;" | 1000
|-
| ImplantTemperature
| style="text-align:center;" | 100
|}
===ImplantLostSample===
The communication protocol the device uses does not re-send lost data. This state annotates what samples were lost in the bio-signal data. Currently, lost samples are made up by duplicating the previous sample.
===ImplantVoltage===
16 bit state that changes when new supply voltage value is received from the implant. After dividing the integer state value by the the voltage multiplier defined in the StateInfo parameter, the units are in volts.
===ImplantHumidity===
16 bit state that changes when new humidity value is received from the implant. Units in %rh.
===ImplantControlValue===
16 bit state that changes when new current control value is received from the external unit. The power of the implant is controlled by the external unit. The control value provides a measure of how good the coupling between the two coils is and how much more power can be provided if necessary.
The value is between 0.0 and 100.0 percent, where 0.0 translates to no power and 100.0 translates to maximum power applied.
===ImplantPrimaryCoilCurrent===
16 bit state that change when new primary coil current value is received from the external unit. The primary coil refers to the coil inside the head piece of the external unit. Units are mA.
===ImplantTemperature===
16 bit state that changes when new temperature value is received from the implant. Units are degrees Celsius.
===ImplantStimulation===
Binary state that changes when the device reports that it is stimulating.
===ImplantStimulationBursts===
Updates when the device reports that stimulation functions have finished. Should increment during a stimulation train.
===ImplantRfQuality===
8 bit state that reports the antenna quality as reported from the rf-link in dBm. '''''To obtain the original value, subtract by 128 (2^8)'''''.
===RequestedStimulation===
Binary state that records when a stimulation trigger expression evaluates true. State remains true for the duration triggered stimulation. This is useful for determining the latency between when stimulation is requested and when it is actually applied. This is done by computing the difference in time between the rising edges of ''ImplantStimulation'' and ''RequestedStimulation'' states.
===PauseStimulation===
Binary state that pauses stimulation execution without stopping data recording.
When this state is set to <code>1</code>, trigger expressions are ignored and no stimulation will be delivered.
When set to <code>0</code>, stimulation resumes normally.
This allows temporary suspension of stimulation during a recording session without restarting the system.
==Stimulation Logging==
When <code>LogStimulationEvents</code> is enabled, stimulation activity will be written to the Operator Log.
Logged information includes:
* Stimulation mode
* Function definitions
* Trigger matches
* Stimulation execution events
This information is useful for:
* Debugging stimulation timing
* Verifying correct function configuration
* Investigating unexpected stimulation behavior
==[[User_Reference:StimulationConfigurationIntegrativeTool_(SCIT)|SCIT]]==
To help out with creating the BCI2000 parameters, a GUI has been made which should make it easy to translate your stimulation specifications into BCI2000 parameter files. The GUI also visualizes the stimulation from three different perspectives, making it easy to tell if your parameters are really what you want. There is a [[User_Reference:StimulationConfigurationIntegrativeTool_(SCIT)|Stimulation Configuration tool user reference]] which will further tell you how to use this tool.
<gallery mode="packed" widths=500px heights=500px>
File:CortecGUIimg.png|The Cortec GUI which creates BCI2000 parameters from stimulation specifications.
</gallery>
==Stimulation Latency==
<gallery mode="packed" widths=500px heights=500px>
File:StimulationModesLatencyCortec.png|Stimulation Latencies for the specified Stimulation Modes.
</gallery>
Tests were conducted for 100 pulses, with an ISI of 10 seconds.
Stimulation latency numbers:
*Persistent functions: '''13 ± 1 ms'''
*Persistent commands: '''11 ± 1 ms'''
*Volatile commands: '''60 ± 30 ms'''. Split into the 2 groups, the lower one is '''48 ± 3 ms''' and the higher one is '''174 ± 3 ms'''
As explained above, volatile commands are uploaded right before stimulation, which leads to the increased latency and jitter.
==Template Parameter Files==
The following <code>.prm</code> files are '''stimulation parameter fragments''' — they contain only the Stimulation section (<code>EnableStimulation</code>, <code>StimulationMode</code>, <code>MeasureImpedance</code>, <code>LogStimulationEvents=1</code>, <code>StimulationPulses</code>, <code>StimulationTriggers</code>). Load one on top of an existing CortecADC configuration in the BCI2000 config window to swap in a stimulation paradigm without overwriting your source/storage/visualization settings.
===Volatile Commands (StimulationMode = 0)===
* [https://bci2000.org/downloads/doc/complex_stim.prm complex_stim.prm] — '''Complex multi-function stimulation paradigm.''' 20-function StimulationPulses matrix mixing pause and stim functions, monopolar (cathode=0/ground) and multi-electrode anode/cathode lists, amplitudes 50–300µA, durations 50–500µs, and reps up to 255 × 100. Two triggers: <code>StimulusCode==1</code> runs functions [1, 2] with CommandRepetition=5; <code>StimulusCode==2</code> runs functions [3…20] once. Useful for exercising the volatile-mode flexibility on a long, structured command.
* [https://bci2000.org/downloads/doc/stim_100Hz_1min.prm stim_100Hz_1min.prm] — '''1-minute 100 Hz volatile stim train, three electrode targets.''' Three "100Hz" stimulation functions (FunctionID 1/2/3) all 250–150µA, 200µs, 100 pulses × 60 bursts (≈1 min at 100 Hz each). Triggers labeled '''ANT''', '''HPC''', and '''Cortical1''' map <code>StimulusCode==1/2/3</code> to those functions, so the same 100 Hz / 1 min train can be steered to anterior thalamus, hippocampus, or cortical electrodes.
===Persistent Command (StimulationMode = 1)===
* [https://bci2000.org/downloads/doc/persistant_100Hz_1function.prm persistant_100Hz_1function.prm] — '''Single-function 100 Hz preloaded persistent command.''' One stimulation function "100Hz" (250µA, 200µs, anode 1 / cathode 2, 200 pulses × 30 bursts ≈ 1 min of 100 Hz). One trigger "Sequence1" on <code>StimulusCode==1</code>, CommandRepetition=1. Demonstrates the simplest persistent-command setup: preload once, fire on cue.
* [https://bci2000.org/downloads/doc/stim_1Hz_1min.prm stim_1Hz_1min.prm] — '''1 Hz × 1 min persistent-command train.''' Two functions, "1Hz" and "pause": a 250µA / 250µs single pulse (anode 1 / cathode 2) and a ~990 ms pause (IsPause=1, duration 990,000µs). One trigger "1Hz" on <code>StimulusCode==1</code> runs [1Hz, pause] with CommandRepetition=60 → 60 pulses spaced ~1 s apart = 1 Hz for 1 minute.
* [https://bci2000.org/downloads/doc/stim_5Hz_1min.prm stim_5Hz_1min.prm] — '''5 Hz × 1 min persistent-command train.''' Same structure as the 1 Hz file but with a ~190 ms pause (190,000µs); trigger on <code>StimulusCode==1</code> with CommandRepetition=300 → 300 pulses at ~200 ms spacing = 5 Hz for 1 minute.
===Persistent Functions (StimulationMode = 2)===
* [https://bci2000.org/downloads/doc/persistant_function_single_pulse.prm persistant_function_single_pulse.prm] — '''Four indexed single-pulse persistent functions.''' Functions SinglePulse1–4 vary independently in amplitude (250 / 375 / 250 / 125 µA), pulse duration (250 / 250 / 200 / 500 µs), and electrode pair (10/11, 1/2, 3/5, 7/8). Triggers map <code>StimulusCode==1…4</code> directly to FunctionID 1…4 so each StimulusCode value fires a different preloaded single pulse — ideal for rapid iteration over a small set of distinct pulses.
* [https://bci2000.org/downloads/doc/singlePulse.prm singlePulse.prm] — '''16 indexed single-pulse persistent functions, one per bipolar pair.''' 16-function StimulationPulses matrix of 250µA / 250µs single pulses across electrode pairs 1/2 … 15/16, plus an 8-vs-8 final function. Triggers map <code>StimulusCode==1…16</code> 1:1 onto FunctionID 1…16 (CommandRepetition=1) so each StimulusCode value fires a single pulse on its corresponding pair.
===Matrix Parameter Files (.bmt)===
<code>.bmt</code> files are BCI2000 matrix parameter exports. Load one into a matrix parameter (e.g., <code>StimulationPulses</code>). These templates only populate the corresponding matrix; everything else in the configuration (StimulationMode, triggers, ReferenceCh, etc.) is unaffected, so they can be reused across any stimulation mode.
* [https://bci2000.org/downloads/doc/SinglePulse_withPause.bmt SinglePulse_withPause.bmt] — StimulationPulses matrix with four functions in sequence: a 1 s leading pause, a 250µA / 250µs single pulse on anode 1 / cathode 2, a 250µA / 250µs single pulse on anode 3 / cathode 5, and a 2.5 s inter-stimulation pause. Demonstrates how to interleave pause functions with stimulation in a single command.
* [https://bci2000.org/downloads/doc/100Hz.bmt 100Hz.bmt] — StimulationPulses matrix with three functions: a 250µA / 200µs 100 Hz train (anode 1 / cathode 2, 100 pulses × 60 bursts), a 1 s pause (amplitude 0, dead zone 1 = 1,000,000µs), and a second 150µA / 200µs 100 Hz train (anodes 3,4 / cathodes 5,6, 100 pulses × 60 bursts). Use for two-train protocols separated by a fixed pause.
==µZeus==
In order to use the new µZeus headpiece simply change the BICVERSION number on line 12 of the CMakeList.txt located in the project folder to use version 274 of the API. ie.,
<code>set(BICAPI_VERSION 274)</code>
==See also==
[[User Reference:Filters]], [[Contributions:ADCs]]
[[Category:Contributions]][[Category:Data Acquisition]]

Contributions:CortecADC

2026-05-14T22:06:45Z

Nluczak:

[[File:CorTec_BrainInterchange.png|400px|thumb|right|CorTec Brain Interchange Implant]]
CortecADC is a source module that allows for intra-cranial recording and stimulating over 32 channels via a fully implantable device. It is intended for long-term measurement of neural activity and electrical stimulation of brain tissue. See the [https://www.cortec-neuro.com/solutions/complete-system/ CorTec site] for more information.
'''See the [[CortecExperience]] page for user tutorials and a broad overview!''' After viewing the [[CortecExperience]] page, refer to this page for detailed instructions.
==Versioning==
===Authors===
* Nicholas Luczak (luczak@neurotechcenter.org)
* William Engelhardt (engelhardt@neurotechcenter.org)
* Alexander Belsten (belsten@neurotechcenter.org)
* Markus Adamek (adamek@neurotechcenter.org)
* Christian Stolle (christian.stolle@cortec-neuro.com)
===Source Code Revisions===
*Initial development: 6266
*Tested under: 9282
*Known to compile under: 9282
*Broken since: --
===BCI2000 Version History===
{|class="wikitable" style="text-align: center;"
! Date !! Revision !! Note !! Contributor
|-
!11/29/2018
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R5829
|Initial untested version
|Adamek
|-
!04/19/2021
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R6271
|First working version
|Belsten
|-
!07/22/2021
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R6339
|Changed ''ImplantLostSample'' from a BCI2000 state to a stream, so it can record individual sample loss (instead of over the whole block)
|Belsten
|-
!01/01/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7133
|Updated API to version 1.0.200.
|Engelhardt
|-
!03/08/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7251
|Stimulation functionality added
|Engelhardt
|-
!05/19/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7367
|Impedance measurement enabled
|Engelhardt
|-
!10/26/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7679
|Stimulation latency vastly improved
|Engelhardt
|-
!02/20/2024
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7847
|Version 1.0.230 added. Can change between versions in CMakeLists.txt file
|Stolle
|-
!08/09/2024
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R8313
|Version 1.0.238 added
|Stolle
|-
!01/17/2025
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7679
|Interpolation filter added to interpolate lost samples
|Engelhardt
|-
!06/25/2025
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R8915
|All listener states were changed to events
|Engelhardt
|-
!04/13/2026
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R9xxx
|Refactored stimulation to be more in line with Cortec and BCI2000 standards.
|Nicholas Luczak
|-
|}
===Cortec API Version History===
Cortec is continually updating their devices with new API versions. In BCI2000, we currently support versions 1.0.200, 1.0.230, and 1.0.238. Each Brain Interchange Communication unit (BIC) is only compatible with one API version. To find your compatible version, connect the USB drive that comes with your BIC. Look under:
# '''Software folder''': Each executable has the API version. E.g., <code>Bicapi_setup_1.0.200-bicapi-setup-1.0.200-rev35926.exe</code>
# '''Manuals foder''': ''Appendix1_BIC_Application_Software_Short_Manual.pdf''. On page 3, in Table 1, the third row contains the compatible version.
Here are some differences between the versions. As the device is always improving, the newest version will have the most features.
{|class="wikitable" style="text-align: center;"
! Features !! 1.0.200 !! 1.0.230 !! 1.0.238 !! 1.0.260
|-
!Matlab API
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!C/C++ API
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Stimulation modes
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!ASIC Noise Detection Mode
|style="color:red"|✘
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Monopolar stimulation (Ch → GND)
|style="color:red"|✘
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Measure GND impedances
|style="color:red"|✘
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Self-tests
|style="color:red"|✘
|style="color:red"|✘
|style="color:red"|✘
|style="color:green"|✔
|-
!Low noise recording
|style="color:red"|✘
|style="color:red"|✘
|style="color:red"|✘
|style="color:green"|✔
|-
|}
===Known Issues===
* Lost samples - The <code>ImplantLostSamples</code> state records what samples are lost, and their locations. Lost samples are replaced with the previous valid sample for all channels. In offline analysis, be sure to remove these samples and replace them with interpolates.
* The Brain Interchange Communication Unit has been seen to work with certain USB inputs, and not with others. If you are experiencing connection issues, try using a different USB port.
==Installation==
# Install BCI2000
# Insert the Cortec USB drive that comes with the Brain Interchange (BIC) device. Under ''Software'', run the ''Bicapi_setup...'' executable
# Run a batch file with CortecADC as your Signal Source!
# If you receive an error, and it states your API version is incorrect, you need to change it. Locate the ''CMakeLists.txt'' under <code>BCI2000/src/private/SignalSource/Cortec</code>. You must change Line 12, where it states <code>set(BICAPI_VERSION 200)</code>. Change 200 to 230 or 238, depending on your device (see [[#Cortec Version History | details above]]).
==Source Parameters==
These parameters can be found in the "Source" tab of the BCI2000 config window.
[[File:CortecSourceParameters.jpg|600px|thumb|center|upright=2.5|Figure 1. The default source parameters for the CortecADC]]
===SourceCh===
The total number of digitized and stored channels. In the current implementation, this parameter cannot be edited, and will default to how many channels are available from the implant.
===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. This parameter cannot be edited, and will default to the sampling rate available from the implant.
In case you are experiencing problems by higher sampling rates (e.g., data loss, jerky display, etc.), increase the SampleBlockSize so that you are updating the system less frequently (usually, updating the system 20-30 times per second is sufficient for most applications), and increase Visualize->VisualizeSourceDecimation. This parameter will decrease the number of samples per second that are actually drawn in the Source display.
===SourceChOffset===
Offset for each channel.
===SourceChGain===
Gain for each channel.
===ChannelNames===
Names of each channel.
===LogCortecBinaryFiles===
Enable or disable binary logging of raw CorTec communication data.
When enabled, a binary log file is written to the BCI2000 session directory with the name:
<code>YYYYMMDD_HHMMSS_CortecAdcLog.bin</code>
This file contains raw communication packets between the Brain Interchange Communication unit and the implant and is primarily useful for low-level debugging and support from CorTec.
Default value: <code>1</code> (enabled)
Disable this parameter if binary logs are not needed or disk space usage is a concern.
===LogStimulationEvents===
Enable logging of stimulation configuration and execution events to the Operator Log.
When enabled, detailed information about stimulation functions, trigger evaluation, and stimulation execution will be printed using <code>bciout</code> messages.
This is useful for debugging stimulation timing and verifying correct parameter interpretation.
Default value: <code>0</code> (disabled)
===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. It is strongly recommended to use at least one reference channel.
===AmplificationFactor===
Amplification factor that is applied to the recorded data on the implant. The choices are 39.5, 45.5, 51.5, 57.5 db.
===UseGround===
Enable to use the ground electrode while measuring. This setting can be overwritten during stimulation, depending if the ground electrode is being used or not. For example, if you have enabled this parameter but don't have <code>0</code> in your <code>Destination ch</code> list in the StimulationTriggers parameter, when you are stimulating you will not be using the ground electrode. Once stimulation is done, this parameter's settings are used again.
===SaveInfoFile===
Enable to save a text file, named the same as the data file run. It will contain the timestamp, amplification factor used in the run, and reference channels used. If the Impedance is measured, the impedance values will be saved to this file regardless of if this parameter is enabled.
===LogPacketErrors===
Enable to save the packet loss errors to the System Log. Helpful for debugging, however can get overwhelming if there are a lot of lost samples. The System Log can be programmatically saved by appending <code>--SystemLogFile=SOME_FILE.TXT</code> to the <code>Startup system localhost</code> line in your batch file.
==Stimulation Parameters==
The figure below summarizes the BCI2000 stimulation paradigm used by CortecADC. A BCI2000 expression (typically based on <code>StimulusCode</code>) acts as a '''Stimulation Trigger'''. When a trigger evaluates true, one or more '''Stimulation Commands''' are executed. Each Stimulation Command is composed of one or more '''Stimulation Functions''' (with optional bursts, pauses, and repetitions), and every Stimulation Function is defined by a '''Stimulation Pulse''' with pulse amplitude, pulse duration, and dead-zone parameters. Use this figure as a mental model for interpreting the <code>StimulationPulses</code> and <code>StimulationTriggers</code> parameters described below.
[[File:StimDefinition_BCI2000.png|1000px|thumb|center|upright=2.5|Figure 2. Summary of the BCI2000 stimulation paradigm. A BCI2000 trigger expression (top, based on StimulusCode) launches a Stimulation Command (red, left), which is built from repeating Stimulation Functions, optional bursts, and pauses. Each Stimulation Function is defined by a Stimulation Pulse (blue, right), parameterized by Pulse Amplitude, Pulse Duration, Dead Zone 0, and Dead Zone 1.]]
These parameters can be found in the "Stimulation" tab of the BCI2000 config window.
<gallery mode="packed" widths=300px heights=300px>
File:CortecADC_stimulation_parm.PNG
File:CortecADC_stimulationpulses_parm.PNG
File:CortecADC_stimulationtriggers_parm1.PNG
</gallery>

===EnableStimulation===
This parameter enables/disables stimulation.
===StimulationMode===
The BIC has 3 stimulation modes. Each one has limitations. Here is a brief summary of how to use each one:
#Volatile Commands: The most flexible mode, allowing stimulation commands to be defined with virtually no size constraints. However, the stimulation configuration must be uploaded immediately before execution, which introduces additional latency. Furthermore, the configuration is cleared after each command, resulting in increased latency for repeated executions. This mode is best suited for iterating across multiple stimulation configurations and designing complex stimulation paradigms.
[[File:VolatileCommand.png|1000px|thumb|center|upright=2.5|Figure 3. Figure demonstrating volatile command functionality]]
#Persistent Command: This preloading mode enables uploading up to 16 stimulation functions to the device and executing them in a predefined order (the list of FunctionID(s) in StimulationTriggers must be the same). The stimulation command remains in memory after execution and can be repeated, making it best suited for delivering continuous or continuously repeated stimulation.
#Persistent Functions: This preloading mode enables uploading up to 16 stimulation functions to the device and executing them individually by calling the stimulation function ID. The device executes only one stimulation function (the indexed one) without repetition. This mode is best suited for rapidly iterating over subsets of stimulation pulses in single-pulse stimulation settings.
[[File:PersistantFunction.png|1000px|thumb|center|upright=2.5|Figure 4. Figure demonstrating Persistant Function functionality]]

There cannot be any train settings (Train frequency and Train repetitions), so the StimulationTriggers must not have those rows. Also, StimulationTriggers must not have more than 16 columns, as that is the highest number of configurations that can be stored on the device.
Persistent Command and Functions modes have a lower latency because the stimulation is pre-uploaded. All modes are available to give you the highest amount of flexiblity with the BIC. [[#Stimulation Latency|See below for more details on latency.]]
===MeasureImpedance===
When enabled, the impedances of the used electrodes are printed when you set the configuration. All electrodes that are being recorded will conduct the impedance measurement. The impedances are shown to the user and also saved in the data directory.
===StimulationPulses===
This parameter defines stimulation ''functions''. Each column defines a stimulation waveform and electrode configuration.
Each function consists of:
* Pulse waveform parameters
* Electrode mapping
* Repetition behavior
Rows are defined as follows:
====FunctionID====
Integer identifier for this stimulation function. This ID is referenced in the <code>StimulationTriggers</code> parameter.
====Pulse Amplitude====
Amplitude of the stimulation pulse in µA.
Valid range:
0 to 6120 µA
====Pulse Duration====
Duration of the main pulse in µs.
Valid range:
10 to 2550 µs
====Dead Zone 0====
Pause between main pulse and counter pulse.
====Dead Zone 1====
Pause after pulse delivery.
====Anode(s)====
Embedded list specifying source electrodes.
Example:
<code>{ list 1 18 19 }</code>
====Cathode(s)====
Embedded list specifying return electrodes.
Use <code>0</code> to reference ground.
====Pulse Repetition====
Number of times the pulse is repeated within a function.
Range:
1 to 255
====Burst Repetition====
Number of times the function is repeated.
Range:
1 to 255
===StimulationTriggers===
Defines when stimulation functions are executed.
Each column contains:
====Trigger====
A valid BCI2000 expression.
When this expression evaluates to true, the associated stimulation function(s) are executed.
====FunctionID(s)====
List of FunctionIDs that should execute when the trigger evaluates true.
Example:
<code>
StimulusCode==1 { list 1 3 }
</code>
This means:
Execute FunctionID 1 followed by FunctionID 3 whenever the trigger becomes true.
Note:
Electrode configuration and repetition settings are defined in <code>StimulationPulses</code>, not here.
==Device Parameters==
===DeviceInfo===
This parameter cannot be edited and is automatically populated with information returned from the device, such as device type, device ID, and the firmware version.
===StateInfo===
This parameter cannot be edited and is automatically populated with information regarding state units and their multiplier. The device provides information such as humidity, temperature, control value, etc., which are recorded in BCI2000 states (see state information on this page for a complete enumeration of states). The device provides these values with floats, but BCI2000 states can only be integers. The multipliers defined in this parameter are used to increase the amount of precision in the state values. To approximately recover the original float values with the units defined in this parameter, divide each state by its corresponding multiplier.
==States==
The states encode auxiliary information returned from the Cortec implant. The device provides this data in floating point numbers, however BCI2000 can only record integers to it's states. To maintain some precision, these floats are multiplied by constants, then recorded to the states as integers. To approximately recover the original data, divide the state by its corresponding constant. Constants are shown in the following table.
{| class="wikitable" style="text-align:right;"
|- style="font-weight:bold;"
! State
! style="text-align:center;" | Constant
|-
| ImplantVoltage
| style="text-align:center;" | 1000
|-
| ImplantHumidity
| style="text-align:center;" | 100
|-
| ImplantControlValue
| style="text-align:center;" | 100
|-
| ImplantPrimaryCoilCurrent
| style="text-align:center;" | 1000
|-
| ImplantTemperature
| style="text-align:center;" | 100
|}
===ImplantLostSample===
The communication protocol the device uses does not re-send lost data. This state annotates what samples were lost in the bio-signal data. Currently, lost samples are made up by duplicating the previous sample.
===ImplantVoltage===
16 bit state that changes when new supply voltage value is received from the implant. After dividing the integer state value by the the voltage multiplier defined in the StateInfo parameter, the units are in volts.
===ImplantHumidity===
16 bit state that changes when new humidity value is received from the implant. Units in %rh.
===ImplantControlValue===
16 bit state that changes when new current control value is received from the external unit. The power of the implant is controlled by the external unit. The control value provides a measure of how good the coupling between the two coils is and how much more power can be provided if necessary.
The value is between 0.0 and 100.0 percent, where 0.0 translates to no power and 100.0 translates to maximum power applied.
===ImplantPrimaryCoilCurrent===
16 bit state that change when new primary coil current value is received from the external unit. The primary coil refers to the coil inside the head piece of the external unit. Units are mA.
===ImplantTemperature===
16 bit state that changes when new temperature value is received from the implant. Units are degrees Celsius.
===ImplantStimulation===
Binary state that changes when the device reports that it is stimulating.
===ImplantStimulationBursts===
Updates when the device reports that stimulation functions have finished. Should increment during a stimulation train.
===ImplantRfQuality===
8 bit state that reports the antenna quality as reported from the rf-link in dBm. '''''To obtain the original value, subtract by 128 (2^8)'''''.
===RequestedStimulation===
Binary state that records when a stimulation trigger expression evaluates true. State remains true for the duration triggered stimulation. This is useful for determining the latency between when stimulation is requested and when it is actually applied. This is done by computing the difference in time between the rising edges of ''ImplantStimulation'' and ''RequestedStimulation'' states.
===PauseStimulation===
Binary state that pauses stimulation execution without stopping data recording.
When this state is set to <code>1</code>, trigger expressions are ignored and no stimulation will be delivered.
When set to <code>0</code>, stimulation resumes normally.
This allows temporary suspension of stimulation during a recording session without restarting the system.
==Stimulation Logging==
When <code>LogStimulationEvents</code> is enabled, stimulation activity will be written to the Operator Log.
Logged information includes:
* Stimulation mode
* Function definitions
* Trigger matches
* Stimulation execution events
This information is useful for:
* Debugging stimulation timing
* Verifying correct function configuration
* Investigating unexpected stimulation behavior
==[[User_Reference:StimulationConfigurationIntegrativeTool_(SCIT)|SCIT]]==
To help out with creating the BCI2000 parameters, a GUI has been made which should make it easy to translate your stimulation specifications into BCI2000 parameter files. The GUI also visualizes the stimulation from three different perspectives, making it easy to tell if your parameters are really what you want. There is a [[User_Reference:StimulationConfigurationIntegrativeTool_(SCIT)|Stimulation Configuration tool user reference]] which will further tell you how to use this tool.
<gallery mode="packed" widths=500px heights=500px>
File:CortecGUIimg.png|The Cortec GUI which creates BCI2000 parameters from stimulation specifications.
</gallery>
==Stimulation Latency==
<gallery mode="packed" widths=500px heights=500px>
File:StimulationModesLatencyCortec.png|Stimulation Latencies for the specified Stimulation Modes.
</gallery>
Tests were conducted for 100 pulses, with an ISI of 10 seconds.
Stimulation latency numbers:
*Persistent functions: '''13 ± 1 ms'''
*Persistent commands: '''11 ± 1 ms'''
*Volatile commands: '''60 ± 30 ms'''. Split into the 2 groups, the lower one is '''48 ± 3 ms''' and the higher one is '''174 ± 3 ms'''
As explained above, volatile commands are uploaded right before stimulation, which leads to the increased latency and jitter.
==Template Parameter Files==
The following <code>.prm</code> files are '''stimulation parameter fragments''' — they contain only the Stimulation section (<code>EnableStimulation</code>, <code>StimulationMode</code>, <code>MeasureImpedance</code>, <code>LogStimulationEvents=1</code>, <code>StimulationPulses</code>, <code>StimulationTriggers</code>). Load one on top of an existing CortecADC configuration in the BCI2000 config window to swap in a stimulation paradigm without overwriting your source/storage/visualization settings.
===Volatile Commands (StimulationMode = 0)===
* [https://bci2000.org/downloads/doc/complex_stim.prm complex_stim.prm] — '''Complex multi-function stimulation paradigm.''' 20-function StimulationPulses matrix mixing pause and stim functions, monopolar (cathode=0/ground) and multi-electrode anode/cathode lists, amplitudes 50–300µA, durations 50–500µs, and reps up to 255 × 100. Two triggers: <code>StimulusCode==1</code> runs functions [1, 2] with CommandRepetition=5; <code>StimulusCode==2</code> runs functions [3…20] once. Useful for exercising the volatile-mode flexibility on a long, structured command.
* [https://bci2000.org/downloads/doc/stim_100Hz_1min.prm stim_100Hz_1min.prm] — '''1-minute 100 Hz volatile stim train, three electrode targets.''' Three "100Hz" stimulation functions (FunctionID 1/2/3) all 250–150µA, 200µs, 100 pulses × 60 bursts (≈1 min at 100 Hz each). Triggers labeled '''ANT''', '''HPC''', and '''Cortical1''' map <code>StimulusCode==1/2/3</code> to those functions, so the same 100 Hz / 1 min train can be steered to anterior thalamus, hippocampus, or cortical electrodes.
===Persistent Command (StimulationMode = 1)===
* [https://bci2000.org/downloads/doc/persistant_100Hz_1function.prm persistant_100Hz_1function.prm] — '''Single-function 100 Hz preloaded persistent command.''' One stimulation function "100Hz" (250µA, 200µs, anode 1 / cathode 2, 200 pulses × 30 bursts ≈ 1 min of 100 Hz). One trigger "Sequence1" on <code>StimulusCode==1</code>, CommandRepetition=1. Demonstrates the simplest persistent-command setup: preload once, fire on cue.
* [https://bci2000.org/downloads/doc/stim_1Hz_1min.prm stim_1Hz_1min.prm] — '''1 Hz × 1 min persistent-command train.''' Two functions, "1Hz" and "pause": a 250µA / 250µs single pulse (anode 1 / cathode 2) and a ~990 ms pause (IsPause=1, duration 990,000µs). One trigger "1Hz" on <code>StimulusCode==1</code> runs [1Hz, pause] with CommandRepetition=60 → 60 pulses spaced ~1 s apart = 1 Hz for 1 minute.
* [https://bci2000.org/downloads/doc/stim_5Hz_1min.prm stim_5Hz_1min.prm] — '''5 Hz × 1 min persistent-command train.''' Same structure as the 1 Hz file but with a ~190 ms pause (190,000µs); trigger on <code>StimulusCode==1</code> with CommandRepetition=300 → 300 pulses at ~200 ms spacing = 5 Hz for 1 minute.
===Persistent Functions (StimulationMode = 2)===
* [https://bci2000.org/downloads/doc/persistant_function_single_pulse.prm persistant_function_single_pulse.prm] — '''Four indexed single-pulse persistent functions.''' Functions SinglePulse1–4 vary independently in amplitude (250 / 375 / 250 / 125 µA), pulse duration (250 / 250 / 200 / 500 µs), and electrode pair (10/11, 1/2, 3/5, 7/8). Triggers map <code>StimulusCode==1…4</code> directly to FunctionID 1…4 so each StimulusCode value fires a different preloaded single pulse — ideal for rapid iteration over a small set of distinct pulses.
* [https://bci2000.org/downloads/doc/singlePulse.prm singlePulse.prm] — '''16 indexed single-pulse persistent functions, one per bipolar pair.''' 16-function StimulationPulses matrix of 250µA / 250µs single pulses across electrode pairs 1/2 … 15/16, plus an 8-vs-8 final function. Triggers map <code>StimulusCode==1…16</code> 1:1 onto FunctionID 1…16 (CommandRepetition=1) so each StimulusCode value fires a single pulse on its corresponding pair.
===Matrix Parameter Files (.bmt)===
<code>.bmt</code> files are BCI2000 matrix parameter exports. Load one into a matrix parameter (e.g., <code>StimulationPulses</code>). These templates only populate the corresponding matrix; everything else in the configuration (StimulationMode, triggers, ReferenceCh, etc.) is unaffected, so they can be reused across any stimulation mode.
* [https://bci2000.org/downloads/doc/SinglePulse_withPause.bmt SinglePulse_withPause.bmt] — StimulationPulses matrix with four functions in sequence: a 1 s leading pause, a 250µA / 250µs single pulse on anode 1 / cathode 2, a 250µA / 250µs single pulse on anode 3 / cathode 5, and a 2.5 s inter-stimulation pause. Demonstrates how to interleave pause functions with stimulation in a single command.
* [https://bci2000.org/downloads/doc/100Hz.bmt 100Hz.bmt] — StimulationPulses matrix with three functions: a 250µA / 200µs 100 Hz train (anode 1 / cathode 2, 100 pulses × 60 bursts), a 1 s pause (amplitude 0, dead zone 1 = 1,000,000µs), and a second 150µA / 200µs 100 Hz train (anodes 3,4 / cathodes 5,6, 100 pulses × 60 bursts). Use for two-train protocols separated by a fixed pause.
==µZeus==
In order to use the new µZeus headpiece simply change the BICVERSION number on line 12 of the CMakeList.txt located in the project folder to use version 274 of the API. ie.,
<code>set(BICAPI_VERSION 274)</code>
==See also==
[[User Reference:Filters]], [[Contributions:ADCs]]
[[Category:Contributions]][[Category:Data Acquisition]]

CortecExperience

2026-05-14T21:12:15Z

Nluczak: /* Canine Surgical Procedure */

=Introduction Video of CorTec Brain Interchange with BCI2000=
<youtube alignment="center" dimensions="900">https://youtu.be/TMZPQPhRnn8</youtube>

=Getting Started with Cortec BIC in BCI2000=

#[[Programming Howto:Building and Customizing BCI2000|Install BCI2000]]
#*Here you will learn how to configure and compile BCI2000 on your own computer.

#[[CortecADC]]
#*This article steps you through all the available configuration options and information stored with using BCI2000 with the Brain Interchange.

#[[Contributions:XsensMTwLogger]]
#*This article shows how to combine any BCI2000 source module the XsensMTw device to capture motion simultaneously with electrophysiological signals.

=Canine Surgical Procedure=
This article presents a brief introduction to surgical protocols for the implantation of the CorTec Brain Interchange. The main objective is to introduce the essential surgical considerations for implanting this device in different animal models.

Download the [https://bci2000.org/downloads/doc/Canine_Cortec_Surgical_Protocol.pdf surgical protocol here].

Download the updated [https://bci2000.org/downloads/doc/Animal_Surgical_Protocol_CorTec_May2026.pdf surgical protocol here].

=Preliminary experience with the CorTec BrainInterchange device in a canine modele=
This article describes initial work toward an ecosystem for adaptive neuromodulation in humans by documenting the experience of implanting CorTec's BrainInterchange (BIC) device in a beagle canine and using the BCI2000 environment to interact with the BIC device. It begins with laying out the substantial opportunity presented by a useful, easy-to-use, and widely available hardware/software ecosystem in the current landscape of the field of adaptive neuromodulation, and then describes experience with implantation, software integration, and post-surgical validation of recording of brain signals and implant parameters. Initial experience suggests that the hardware capabilities of the BIC device are fully supported by BCI2000, and that the BIC/BCI2000 device can record and process brain signals during free behavior. With further development and validation, the BIC/BCI2000 ecosystem could become an important tool for research into new adaptive neuromodulation protocols in humans.

Schalk G, Worrell S, Mivalt F, Belsten A, Kim I, Morris JM, Hermes D, Klassen BT, Staff NP, Messina S, Kaufmann T, Rickert J, Brunner P, Worrell GA, Miller KJ. Toward a fully implantable ecosystem for adaptive neuromodulation in humans: Preliminary experience with the CorTec BrainInterchange device in a canine model. Front Neurosci. 2022 Dec 19;16:932782. doi: 10.3389/fnins.2022.932782. PMID: 36601593; PMCID: PMC9806357.

Download the [https://bci2000.org/downloads/doc/Preliminary_experience_with_the_CorTec_BrainInterchange_device_in_a_canine_model.pdf article here].

=Data Sharing=
This data recorded is freely available on DANDI and OpenNeuro.

Download the [https://dandiarchive.org/dandiset/000571?pos=1 canine data from DANDI].

Download the [https://openneuro.org/datasets/ds004624/versions/1.0.1 canine data from OpenNeuro].

=Closed-loop Stimulation=
With BCI2000, it is possible to stimulate with the Brain Interchange based on processed signals from Brain Interchange recordings! BCI2000's infrastructure was created for closed-loop control, as it processes the recorded activity and can directly use the results to affect the task or stimulation.

'''See the [[Closed-Loop Stimulation]] page for more information!'''

<youtube alignment="center" dimensions="900">https://youtu.be/YIM_YmoHRR8</youtube>

To start out, we can review how to conduct a closed-loop brain-computer interface task. This has a very similar pipeline to closed-loop stimulation so it is a good place to start. Review the [[User Tutorial:Mu Rhythm BCI Tutorial|Mu Rhythm tutorial]] for in-depth instructions on how to set it up.

Now that we have the closed-loop task control reviewed, we can move on to closed-loop stimulation. Since CortecADC is a source module, stimulation is conducted in the source module (review the [[User Reference:Filters|Filters]] page for BCI2000 overview). This means we have to carry-over the results from the past signal processing pipeline to the next block. This can be done with States, which stream through all the modules of BCI2000 in a closed-loop fashion. Since Cortec stimulation is controlled with Expressions, a State that was changed due to the processed signal will trigger stimulation. For example, you can use EarlyOffsetExpression available in the [[User Tutorial:StimulusPresentation|StimulusPresentation]] Application module to change stimuli due to a processed signal. You would set up the stimulation to be triggered once the new stimulus is reached, due to EarlyOffsetExpression becoming true.

=Synchronize Inertial Measurement Units with the CorTec Brain Interchange=
<youtube alignment="center" dimensions="900">https://youtu.be/-SOUX5J1vJE</youtube>

[[Category:Video]]

File:StimDefinition BCI2000.png

2026-05-14T21:05:37Z

Nluczak:

Contributions:CortecADC

2026-05-14T21:05:01Z

Nluczak:

[[File:CorTec_BrainInterchange.png|400px|thumb|right|CorTec Brain Interchange Implant]]
CortecADC is a source module that allows for intra-cranial recording and stimulating over 32 channels via a fully implantable device. It is intended for long-term measurement of neural activity and electrical stimulation of brain tissue. See the [https://www.cortec-neuro.com/solutions/complete-system/ CorTec site] for more information.
'''See the [[CortecExperience]] page for user tutorials and a broad overview!''' After viewing the [[CortecExperience]] page, refer to this page for detailed instructions.
==Versioning==
===Authors===
* Nicholas Luczak (luczak@neurotechcenter.org)
* William Engelhardt (engelhardt@neurotechcenter.org)
* Alexander Belsten (belsten@neurotechcenter.org)
* Markus Adamek (adamek@neurotechcenter.org)
* Christian Stolle (christian.stolle@cortec-neuro.com)
===Source Code Revisions===
*Initial development: 6266
*Tested under: 9282
*Known to compile under: 9282
*Broken since: --
===BCI2000 Version History===
{|class="wikitable" style="text-align: center;"
! Date !! Revision !! Note !! Contributor
|-
!11/29/2018
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R5829
|Initial untested version
|Adamek
|-
!04/19/2021
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R6271
|First working version
|Belsten
|-
!07/22/2021
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R6339
|Changed ''ImplantLostSample'' from a BCI2000 state to a stream, so it can record individual sample loss (instead of over the whole block)
|Belsten
|-
!01/01/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7133
|Updated API to version 1.0.200.
|Engelhardt
|-
!03/08/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7251
|Stimulation functionality added
|Engelhardt
|-
!05/19/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7367
|Impedance measurement enabled
|Engelhardt
|-
!10/26/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7679
|Stimulation latency vastly improved
|Engelhardt
|-
!02/20/2024
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7847
|Version 1.0.230 added. Can change between versions in CMakeLists.txt file
|Stolle
|-
!08/09/2024
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R8313
|Version 1.0.238 added
|Stolle
|-
!01/17/2025
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7679
|Interpolation filter added to interpolate lost samples
|Engelhardt
|-
!06/25/2025
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R8915
|All listener states were changed to events
|Engelhardt
|-
!04/13/2026
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R9xxx
|Refactored stimulation to be more in line with Cortec and BCI2000 standards.
|Nicholas Luczak
|-
|}
===Cortec API Version History===
Cortec is continually updating their devices with new API versions. In BCI2000, we currently support versions 1.0.200, 1.0.230, and 1.0.238. Each Brain Interchange Communication unit (BIC) is only compatible with one API version. To find your compatible version, connect the USB drive that comes with your BIC. Look under:
# '''Software folder''': Each executable has the API version. E.g., <code>Bicapi_setup_1.0.200-bicapi-setup-1.0.200-rev35926.exe</code>
# '''Manuals foder''': ''Appendix1_BIC_Application_Software_Short_Manual.pdf''. On page 3, in Table 1, the third row contains the compatible version.
Here are some differences between the versions. As the device is always improving, the newest version will have the most features.
{|class="wikitable" style="text-align: center;"
! Features !! 1.0.200 !! 1.0.230 !! 1.0.238 !! 1.0.260
|-
!Matlab API
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!C/C++ API
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Stimulation modes
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!ASIC Noise Detection Mode
|style="color:red"|✘
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Monopolar stimulation (Ch → GND)
|style="color:red"|✘
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Measure GND impedances
|style="color:red"|✘
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Self-tests
|style="color:red"|✘
|style="color:red"|✘
|style="color:red"|✘
|style="color:green"|✔
|-
!Low noise recording
|style="color:red"|✘
|style="color:red"|✘
|style="color:red"|✘
|style="color:green"|✔
|-
|}
===Known Issues===
* Lost samples - The <code>ImplantLostSamples</code> state records what samples are lost, and their locations. Lost samples are replaced with the previous valid sample for all channels. In offline analysis, be sure to remove these samples and replace them with interpolates.
* The Brain Interchange Communication Unit has been seen to work with certain USB inputs, and not with others. If you are experiencing connection issues, try using a different USB port.
==Installation==
# Install BCI2000
# Insert the Cortec USB drive that comes with the Brain Interchange (BIC) device. Under ''Software'', run the ''Bicapi_setup...'' executable
# Run a batch file with CortecADC as your Signal Source!
# If you receive an error, and it states your API version is incorrect, you need to change it. Locate the ''CMakeLists.txt'' under <code>BCI2000/src/private/SignalSource/Cortec</code>. You must change Line 12, where it states <code>set(BICAPI_VERSION 200)</code>. Change 200 to 230 or 238, depending on your device (see [[#Cortec Version History | details above]]).
==Source Parameters==
These parameters can be found in the "Source" tab of the BCI2000 config window.
[[File:CortecSourceParameters.jpg|600px|thumb|center|upright=2.5|Figure 1. The default source parameters for the CortecADC]]
===SourceCh===
The total number of digitized and stored channels. In the current implementation, this parameter cannot be edited, and will default to how many channels are available from the implant.
===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. This parameter cannot be edited, and will default to the sampling rate available from the implant.
In case you are experiencing problems by higher sampling rates (e.g., data loss, jerky display, etc.), increase the SampleBlockSize so that you are updating the system less frequently (usually, updating the system 20-30 times per second is sufficient for most applications), and increase Visualize->VisualizeSourceDecimation. This parameter will decrease the number of samples per second that are actually drawn in the Source display.
===SourceChOffset===
Offset for each channel.
===SourceChGain===
Gain for each channel.
===ChannelNames===
Names of each channel.
===LogCortecBinaryFiles===
Enable or disable binary logging of raw CorTec communication data.
When enabled, a binary log file is written to the BCI2000 session directory with the name:
<code>YYYYMMDD_HHMMSS_CortecAdcLog.bin</code>
This file contains raw communication packets between the Brain Interchange Communication unit and the implant and is primarily useful for low-level debugging and support from CorTec.
Default value: <code>1</code> (enabled)
Disable this parameter if binary logs are not needed or disk space usage is a concern.
===LogStimulationEvents===
Enable logging of stimulation configuration and execution events to the Operator Log.
When enabled, detailed information about stimulation functions, trigger evaluation, and stimulation execution will be printed using <code>bciout</code> messages.
This is useful for debugging stimulation timing and verifying correct parameter interpretation.
Default value: <code>0</code> (disabled)
===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. It is strongly recommended to use at least one reference channel.
===AmplificationFactor===
Amplification factor that is applied to the recorded data on the implant. The choices are 39.5, 45.5, 51.5, 57.5 db.
===UseGround===
Enable to use the ground electrode while measuring. This setting can be overwritten during stimulation, depending if the ground electrode is being used or not. For example, if you have enabled this parameter but don't have <code>0</code> in your <code>Destination ch</code> list in the StimulationTriggers parameter, when you are stimulating you will not be using the ground electrode. Once stimulation is done, this parameter's settings are used again.
===SaveInfoFile===
Enable to save a text file, named the same as the data file run. It will contain the timestamp, amplification factor used in the run, and reference channels used. If the Impedance is measured, the impedance values will be saved to this file regardless of if this parameter is enabled.
===LogPacketErrors===
Enable to save the packet loss errors to the System Log. Helpful for debugging, however can get overwhelming if there are a lot of lost samples. The System Log can be programmatically saved by appending <code>--SystemLogFile=SOME_FILE.TXT</code> to the <code>Startup system localhost</code> line in your batch file.
==Stimulation Parameters==
The figure below summarizes the BCI2000 stimulation paradigm used by CortecADC. A BCI2000 expression (typically based on <code>StimulusCode</code>) acts as a '''Stimulation Trigger'''. When a trigger evaluates true, one or more '''Stimulation Commands''' are executed. Each Stimulation Command is composed of one or more '''Stimulation Functions''' (with optional bursts, pauses, and repetitions), and every Stimulation Function is defined by a '''Stimulation Pulse''' with pulse amplitude, pulse duration, and dead-zone parameters. Use this figure as a mental model for interpreting the <code>StimulationPulses</code> and <code>StimulationTriggers</code> parameters described below.
[[File:StimDefinition_BCI2000.png|1000px|thumb|center|upright=2.5|Figure 2. Summary of the BCI2000 stimulation paradigm. A BCI2000 trigger expression (top, based on StimulusCode) launches a Stimulation Command (red, left), which is built from repeating Stimulation Functions, optional bursts, and pauses. Each Stimulation Function is defined by a Stimulation Pulse (blue, right), parameterized by Pulse Amplitude, Pulse Duration, Dead Zone 0, and Dead Zone 1.]]
These parameters can be found in the "Stimulation" tab of the BCI2000 config window.
<gallery mode="packed" widths=300px heights=300px>
File:CortecADC_stimulation_parm.PNG
File:CortecADC_stimulationpulses_parm.PNG
File:CortecADC_stimulationtriggers_parm1.PNG
</gallery>

===EnableStimulation===
This parameter enables/disables stimulation.
===StimulationMode===
The BIC has 3 stimulation modes. Each one has limitations. Here is a brief summary of how to use each one:
#Volatile Commands: The most flexible mode, allowing stimulation commands to be defined with virtually no size constraints. However, the stimulation configuration must be uploaded immediately before execution, which introduces additional latency. Furthermore, the configuration is cleared after each command, resulting in increased latency for repeated executions. This mode is best suited for iterating across multiple stimulation configurations and designing complex stimulation paradigms.
[[File:VolatileCommand.png|1000px|thumb|center|upright=2.5|Figure 3. Figure demonstrating volatile command functionality]]
#Persistent Command: This preloading mode enables uploading up to 16 stimulation functions to the device and executing them in a predefined order (the list of FunctionID(s) in StimulationTriggers must be the same). The stimulation command remains in memory after execution and can be repeated, making it best suited for delivering continuous or continuously repeated stimulation.
#Persistent Functions: This preloading mode enables uploading up to 16 stimulation functions to the device and executing them individually by calling the stimulation function ID. The device executes only one stimulation function (the indexed one) without repetition. This mode is best suited for rapidly iterating over subsets of stimulation pulses in single-pulse stimulation settings.
[[File:PersistantFunction.png|1000px|thumb|center|upright=2.5|Figure 4. Figure demonstrating Persistant Function functionality]]

There cannot be any train settings (Train frequency and Train repetitions), so the StimulationTriggers must not have those rows. Also, StimulationTriggers must not have more than 16 columns, as that is the highest number of configurations that can be stored on the device.
Persistent Command and Functions modes have a lower latency because the stimulation is pre-uploaded. All modes are available to give you the highest amount of flexiblity with the BIC. [[#Stimulation Latency|See below for more details on latency.]]
===MeasureImpedance===
When enabled, the impedances of the used electrodes are printed when you set the configuration. All electrodes that are being recorded will conduct the impedance measurement. The impedances are shown to the user and also saved in the data directory.
===StimulationPulses===
This parameter defines stimulation ''functions''. Each column defines a stimulation waveform and electrode configuration.
Each function consists of:
* Pulse waveform parameters
* Electrode mapping
* Repetition behavior
Rows are defined as follows:
====FunctionID====
Integer identifier for this stimulation function. This ID is referenced in the <code>StimulationTriggers</code> parameter.
====Pulse Amplitude====
Amplitude of the stimulation pulse in µA.
Valid range:
0 to 6120 µA
====Pulse Duration====
Duration of the main pulse in µs.
Valid range:
10 to 2550 µs
====Dead Zone 0====
Pause between main pulse and counter pulse.
====Dead Zone 1====
Pause after pulse delivery.
====Anode(s)====
Embedded list specifying source electrodes.
Example:
<code>{ list 1 18 19 }</code>
====Cathode(s)====
Embedded list specifying return electrodes.
Use <code>0</code> to reference ground.
====Pulse Repetition====
Number of times the pulse is repeated within a function.
Range:
1 to 255
====Burst Repetition====
Number of times the function is repeated.
Range:
1 to 255
===StimulationTriggers===
Defines when stimulation functions are executed.
Each column contains:
====Trigger====
A valid BCI2000 expression.
When this expression evaluates to true, the associated stimulation function(s) are executed.
====FunctionID(s)====
List of FunctionIDs that should execute when the trigger evaluates true.
Example:
<code>
StimulusCode==1 { list 1 3 }
</code>
This means:
Execute FunctionID 1 followed by FunctionID 3 whenever the trigger becomes true.
Note:
Electrode configuration and repetition settings are defined in <code>StimulationPulses</code>, not here.
==Device Parameters==
===DeviceInfo===
This parameter cannot be edited and is automatically populated with information returned from the device, such as device type, device ID, and the firmware version.
===StateInfo===
This parameter cannot be edited and is automatically populated with information regarding state units and their multiplier. The device provides information such as humidity, temperature, control value, etc., which are recorded in BCI2000 states (see state information on this page for a complete enumeration of states). The device provides these values with floats, but BCI2000 states can only be integers. The multipliers defined in this parameter are used to increase the amount of precision in the state values. To approximately recover the original float values with the units defined in this parameter, divide each state by its corresponding multiplier.
==States==
The states encode auxiliary information returned from the Cortec implant. The device provides this data in floating point numbers, however BCI2000 can only record integers to it's states. To maintain some precision, these floats are multiplied by constants, then recorded to the states as integers. To approximately recover the original data, divide the state by its corresponding constant. Constants are shown in the following table.
{| class="wikitable" style="text-align:right;"
|- style="font-weight:bold;"
! State
! style="text-align:center;" | Constant
|-
| ImplantVoltage
| style="text-align:center;" | 1000
|-
| ImplantHumidity
| style="text-align:center;" | 100
|-
| ImplantControlValue
| style="text-align:center;" | 100
|-
| ImplantPrimaryCoilCurrent
| style="text-align:center;" | 1000
|-
| ImplantTemperature
| style="text-align:center;" | 100
|}
===ImplantLostSample===
The communication protocol the device uses does not re-send lost data. This state annotates what samples were lost in the bio-signal data. Currently, lost samples are made up by duplicating the previous sample.
===ImplantVoltage===
16 bit state that changes when new supply voltage value is received from the implant. After dividing the integer state value by the the voltage multiplier defined in the StateInfo parameter, the units are in volts.
===ImplantHumidity===
16 bit state that changes when new humidity value is received from the implant. Units in %rh.
===ImplantControlValue===
16 bit state that changes when new current control value is received from the external unit. The power of the implant is controlled by the external unit. The control value provides a measure of how good the coupling between the two coils is and how much more power can be provided if necessary.
The value is between 0.0 and 100.0 percent, where 0.0 translates to no power and 100.0 translates to maximum power applied.
===ImplantPrimaryCoilCurrent===
16 bit state that change when new primary coil current value is received from the external unit. The primary coil refers to the coil inside the head piece of the external unit. Units are mA.
===ImplantTemperature===
16 bit state that changes when new temperature value is received from the implant. Units are degrees Celsius.
===ImplantStimulation===
Binary state that changes when the device reports that it is stimulating.
===ImplantStimulationBursts===
Updates when the device reports that stimulation functions have finished. Should increment during a stimulation train.
===ImplantRfQuality===
8 bit state that reports the antenna quality as reported from the rf-link in dBm. '''''To obtain the original value, subtract by 128 (2^8)'''''.
===RequestedStimulation===
Binary state that records when a stimulation trigger expression evaluates true. State remains true for the duration triggered stimulation. This is useful for determining the latency between when stimulation is requested and when it is actually applied. This is done by computing the difference in time between the rising edges of ''ImplantStimulation'' and ''RequestedStimulation'' states.
===PauseStimulation===
Binary state that pauses stimulation execution without stopping data recording.
When this state is set to <code>1</code>, trigger expressions are ignored and no stimulation will be delivered.
When set to <code>0</code>, stimulation resumes normally.
This allows temporary suspension of stimulation during a recording session without restarting the system.
==Stimulation Logging==
When <code>LogStimulationEvents</code> is enabled, stimulation activity will be written to the Operator Log.
Logged information includes:
* Stimulation mode
* Function definitions
* Trigger matches
* Stimulation execution events
This information is useful for:
* Debugging stimulation timing
* Verifying correct function configuration
* Investigating unexpected stimulation behavior
==[[User_Reference:StimulationConfigurationIntegrativeTool_(SCIT)|SCIT]]==
To help out with creating the BCI2000 parameters, a GUI has been made which should make it easy to translate your stimulation specifications into BCI2000 parameter files. The GUI also visualizes the stimulation from three different perspectives, making it easy to tell if your parameters are really what you want. There is a [[User_Reference:StimulationConfigurationIntegrativeTool_(SCIT)|Stimulation Configuration tool user reference]] which will further tell you how to use this tool.
<gallery mode="packed" widths=500px heights=500px>
File:CortecGUIimg.png|The Cortec GUI which creates BCI2000 parameters from stimulation specifications.
</gallery>
==Stimulation Latency==
<gallery mode="packed" widths=500px heights=500px>
File:StimulationModesLatencyCortec.png|Stimulation Latencies for the specified Stimulation Modes.
</gallery>
Tests were conducted for 100 pulses, with an ISI of 10 seconds.
Stimulation latency numbers:
*Persistent functions: '''13 ± 1 ms'''
*Persistent commands: '''11 ± 1 ms'''
*Volatile commands: '''60 ± 30 ms'''. Split into the 2 groups, the lower one is '''48 ± 3 ms''' and the higher one is '''174 ± 3 ms'''
As explained above, volatile commands are uploaded right before stimulation, which leads to the increased latency and jitter.
==Template Parameter Files==

Template parameter files are provided for each stimulation mode to make it easier to get started:
* '''Volatile Commands''' — ''(link pending)''
* '''Persistent Command''' — ''(link pending)''
* '''Persistent Functions''' — ''(link pending)''
==µZeus==
In order to use the new µZeus headpiece simply change the BICVERSION number on line 12 of the CMakeList.txt located in the project folder to use version 274 of the API. ie.,
<code>set(BICAPI_VERSION 274)</code>
==See also==
[[User Reference:Filters]], [[Contributions:ADCs]]
[[Category:Contributions]][[Category:Data Acquisition]]

File:CortecADC stimulationtriggers parm1.PNG

2026-05-14T20:58:22Z

Nluczak: Nluczak uploaded a new version of File:CortecADC stimulationtriggers parm1.PNG

File:CortecADC stimulationpulses parm.PNG

2026-05-14T20:57:56Z

Nluczak: Nluczak uploaded a new version of File:CortecADC stimulationpulses parm.PNG

File:CortecADC stimulation parm.PNG

2026-05-14T20:57:30Z

Nluczak: Nluczak uploaded a new version of File:CortecADC stimulation parm.PNG

File:VolatileCommand.png

2026-05-14T20:51:14Z

Nluczak: Nluczak uploaded a new version of File:VolatileCommand.png

Contributions:BlackrockGemini

2026-04-20T20:34:50Z

Nluczak:

==Synopsis==
The BlackrockGemini signal source module acquires data from Blackrock Microsystems Gemini acquisition hardware over Ethernet, using the Cerebus SDK ([https://github.com/dashesy/CereLink cbsdk]). All channel configuration — enabled channels, per-channel sampling rate, gain, and label — is set in Blackrock's Central application and imported into BCI2000 automatically at <code>SetConfig</code> time.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/BlackrockGemini

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com), Jürgen Mellinger (mellinger@neurotechcenter.org), Nicholas Luczak (luczak@neurotechcenter.org)

===Source Code Revisions===
*Initial development: 8061
*Tested under: 9216
*Known to compile under: 9216
*Broken since: N/A

==System Setup==

===Network Configuration===
The module talks to the Gemini Hub over UDP and is sensitive to packet loss. Connect the BCI2000 machine and the Gemini Hub to a '''single''' commercial-grade switch, or use a crossover cable directly between the two. Do not place a second switch, or a consumer-grade router, in between.

Configure the BCI2000 machine's network interface as follows:
* '''IP address:''' <code>192.168.137.XXX</code>, where <code>XXX</code> is below 128, not 10, and ideally below 16. Make sure no other computer on the switch uses the same address.
* '''Subnet mask:''' <code>255.255.255.0</code>
* '''Default gateway:''' blank

To verify connectivity, open a command prompt and run:
ping 192.168.137.128
That is the Gemini Hub's default address. If the hub responds, the module should be able to reach it.

===Configuring Channels in Central===
All amplifier-side configuration is done in Blackrock's Central software. The Gemini Hub always digitises at 30 kHz; each channel can be independently enabled for continuous streaming at 500 Hz, 1 kHz, 2 kHz, 10 kHz, or 30 kHz. The hub decimates non-30 kHz streams (with antialiasing) before transmission.

A sample group may mix neural-amplifier channels and analog-input channels (sync pulses, eye-tracker outputs, photodiode signals, and so on). Any channel enabled for continuous streaming at the SamplingRate selected in BCI2000 will appear in the signal, regardless of the bank it lives on. Within the signal, channels are grouped by Blackrock instrument id (neural-amp channels first, analog inputs next), and within each instrument they appear in the order reported by Central.

==Parameters==
All parameters live under '''Source -- Signal Properties'''.

===SamplingRate===
Selects the sample group to record from. Valid values are 500 Hz, 1000 Hz, 2000 Hz, 10000 Hz, and 30000 Hz. When <code>SetConfig</code> is pressed, the module collects every channel currently enabled at this rate in Central and configures BCI2000 to acquire them.

===SampleBlockSize===
Samples per block per channel. Set to <code>auto</code> to pick a default that clocks BCI2000 at approximately 50 Hz:

int gGroupRates[] = { 0, 500, 1000, 2000, 10000, 30000 }; // samples per second
int gBlockSizes[] = { 0, 10, 20, 40, 200, 600 }; // samples per block (~50 Hz)

Any positive integer is accepted. Clocking BCI2000 faster than 50 Hz is [http://www.youtube.com/watch?v=2FM3Em7FIOc generally a bad idea].

===SourceCh===
Total number of channels. Set to <code>auto</code>; the module fills this in from the Central configuration at <code>SetConfig</code> time.

===ChannelNames===
Channel labels. Populated automatically from the Channel Label column in Central. Use <code>auto</code>.

===SourceChOffset / SourceChGain===
Per-channel offset and gain. Populated automatically from each channel's <code>cbSCALING</code> limits reported by cbsdk. Use <code>auto</code>.

==States==

===NSPSyncState===
A two-bit state used internally by the module's start-of-run state machine. Not intended for downstream analysis.

===BlackrockSourceTimeHigh / BlackrockSourceTimeLow===
The upper and lower 32 bits of the 64-bit per-sample timestamp produced by the Gemini Hub. Concatenate as
timestamp_ns = (BlackrockSourceTimeHigh << 32) | BlackrockSourceTimeLow
to obtain nanoseconds since the Unix epoch (1970-01-01 UTC, 1 ns resolution).

Under the hood, these states are populated by reserving the final two rows of the source signal and labelling them <code>@BlackrockSourceTimeHigh</code> and <code>@BlackrockSourceTimeLow</code>; the <code>@</code> prefix instructs BCI2000 to route those samples into the corresponding state rather than leave them in the signal.

==Implementation Notes==
This section is intended for programmers extending, porting, or debugging the module.

===Class Overview===
<code>BlackrockADC</code> derives from <code>BufferedADC</code>. Acquisition is callback-driven:

* <code>OnStartAcquisition()</code> opens the cbsdk connection and registers <code>DataCallback</code> with <code>cbSdkRegisterCallback(CBSDKCALLBACK_CONTINUOUS)</code>. Every incoming <code>cbPKT_GROUP</code> is dispatched to <code>OnData()</code> on a cbsdk thread.
* <code>OnData()</code> assembles one composite sample per timestep and pushes it into <code>mDataPacketBuffers</code>. When enough samples are queued for a full block, it signals <code>mDataAvailable</code>.
* <code>DoAcquire()</code>, running on BCI2000's source thread, blocks on <code>mDataAvailable</code> and drains a block's worth of composite samples into the output signal.
* <code>mDataMutex</code> (a <code>std::recursive_mutex</code>) protects the per-instrument queues, the composite buffers, and the layout vectors.

===Per-timestep Packet Pairing===
On Gemini, each timestep is broadcast as '''one <code>cbPKT_GROUP</code> per instrument''' — for example, one for the front-end amplifier and a second for the AINP board. The <code>cbpkt_header.time</code> field in these packets is a per-packet send time, not a shared sample time, so channels cannot be paired across instruments by matching timestamps.

The module pairs them '''by arrival order''' instead:
# Each instrument has its own FIFO in <code>mInstrumentQueues</code>.
# <code>OnData()</code> pushes every packet into the FIFO for its <code>cbpkt_header.instrument</code>.
# While every FIFO is non-empty, the fronts are popped and concatenated into one composite frame in <code>mDataPacketBuffers</code>, with each instrument's samples written at its reserved <code>baseOffset</code> inside the frame.
# A '''resync guard''' flushes every FIFO if any one of them exceeds <code>kMaxInstrumentQueueDepth</code> (8192 packets). This re-aligns pairing from a clean state if an instrument falls far behind.

===Channel Discovery===
<code>GetChannelConfig()</code> deliberately does '''not''' use <code>cbSdkGetSampleGroupList()</code>. On Gemini, that API reports only front-end channels in the requested sample group; AINP channels configured for the same rate stream as <code>cbPKT_GROUP</code> packets under a different <code>cbpkt_header.instrument</code> and are omitted from the list.

Instead, the module probes every channel id from 1 through <code>cbNUM_ANALOG_CHANS</code> with <code>cbSdkGetChannelConfig()</code>, filters by <code>chanInfo.smpgroup == iGroup</code>, groups the survivors by <code>chanInfo.cbpkt_header.instrument</code>, and emits them in ascending instrument-id order. As a side effect, this yields the instrument id used to route each channel's packets in <code>OnData()</code>.

===Build===
The CMake target is Windows-only. It links against the prebuilt Cerebus SDK in <code>lib/x64/cbsdkx64.lib</code> (x64) or <code>lib/x86/cbsdk.lib</code> (x86). The headers <code>cbsdk.h</code> and <code>cbhwlib.h</code> ship in <code>include/</code>. Batch files are copied to <code>prog/batch</code>, and the <code>BlackrockGemini.prm</code> fragment to <code>parms/fragments/amplifiers</code>, by <code>BCI2000_ADD_SIGNAL_SOURCE_MODULE</code>.

The module has been built and run against both the official Blackrock cbsdk release and the open-source [https://github.com/dashesy/CereLink CereLink] fork; either is compatible.

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

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

Contributions:BlackrockGemini

2026-04-20T16:31:23Z

Nluczak: Updated to reflect on changes to gemini

==Synopsis==
The Blackrock Gemini acquisition module enables signal acquisition from Blackrock Microsystems Gemini acquisition hardware through the "cbsdk" C++ API.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/BlackrockGemini

==Versioning==
===Author===
Griffin Milsap (griffin.milsap@gmail.com), Jürgen Mellinger (mellinger@neurotechcenter.org)
===Source Code Revisions===
*Initial development: 4365/8061
*Tested under: 8522
*Known to compile under: 8522
*Broken since: N/A

==Functional Description==
The BlackrockGemini source module is used for acquiring recordings from Blackrock Gemini systems using CBSDK as provided through official Blackrock channels, or through CereLink (https://github.com/dashesy/CereLink). This documentation explains the parameterization and specifics on how to set up the system.

===System Setup===
Building the BlackrockGemini module should copy .bat files for standard experiments into the batch directory.

Ensure your machine is connected to a switch or router that the Gemini Hub is also connected to. This module communicates to the Gemini Hub using UDP, and is susceptible to packet loss. Ensure you have a commercial grade switch to avoid dropping packets. You can also use a crossover cable to connect directly to the Gemini Hub, but this prevents other computers from receiving data from the Gemini Hub.

You will also need to change your interface's network configuration:
* IP address: 192.168.137.XXX where XXX is less than 128. This number needs to be below 16 and not 10. Ensure no other computers have this same address on this switch.
* Subnet Mask: 255.255.255.0
* Default Gateway: <Blank>
To test your network configuration, open a terminal or command prompt and type '''ping 192.168.137.128'''. This is the Gemini Hub's default network address. If you can ping the Gemini Hub, you should be able to run the module.

==Parameters==
Blackrock systems are very configurable, and it appears to make little sense to reproduce each individual setting as a BCI2000 parameter.
Rather, you will configure the recording setup using the Blackrock "Central" software, and BCI2000 will auto-configure to match the SampleGroup dictated by the SamplingRate parameter. Gemini Hubs always acquire data at 30Khz, but channels can be added to a SampleGroup which is downsampled (with antialiasing) in real-time by the Gemini Hub before being streamed over ethernet to receivers. You can add channels to these channel groups in the Central software by enabling continuous streaming on individual channels, and selecting the sampling rate.

The following parameters are available for configuring the BlackrockGemini source module. You will find these parameters in the Source -- Signal Properties section.
===SamplingRate===
In standard use, this is one of two parameters you need to play with. This is where you select the sample group you want BCI2000 to record from. Valid sampling rates are 500 Hz, 1000 Hz, 2000 Hz, 10000 Hz, and 30000 Hz. When the SetConfig button is pressed, BCI2000 will collect all channels that are members of that SampleGroup and configure to acquire from those channels.

The sample group can mix neural channels and analog input channels (such as sync, eye-tracking, or photodiode signals). Any channel you have enabled for continuous streaming in Central at the selected rate will be picked up, regardless of which bank it lives on. In the BCI2000 signal, neural channels are listed first, followed by the analog input channels, in the order shown by Central.

===SampleBlockSize===
There are a bunch of default SampleBlockSizes for the different SamplingRates, which you will get if you use 'auto' as the value of this parameter. They are roughly set to clock BCI2000 at about 50 Hz. Depending on the processing you're doing, you may want to lengthen the block size. Any number of samples is valid here: even 1. You may want to not do that, however. Clocking the system above 50 Hz [http://www.youtube.com/watch?v=2FM3Em7FIOc is a bad choice]. The default block size for different sample groups is as follows:

int gGroupRates[] = { 0, 500, 1000, 2000, 10000, 30000 }; // samples per second
int gBlockSizes[] = { 0, 10, 20, 40, 200, 600 }; // samples per block (50 Hz)

===ChannelNames===
These will be pulled from the Channel Label property set in the Central Software. Use 'auto' to configure this parameter.

===SourceChOffset/SourceChGain===
Again, these are populated automatically. Use 'auto' to configure this parameter.

===NSPInstances===
This parameter determines how many NSPs you intend to record from. This is the other parameter that you might want to play with, but only if you have more than one NSP. Using more than 2 NSPs is untested.

===DigitalOutput===
This parameter specifies a matrix of expressions that will be evaluated once per SampleBlock to set the digital output channels. Each row of this matrix defines an expression for one digital output. If that expression evaluates true for that block, the associated digital output will be set high, and vice versa for false. See [[User Reference:Expression Syntax]] for help with BCI2000 Expressions. An example matrix is provided below.

Instance Output Expression
1 1 StimulusCode!=0 // Will set output 1 on NSP1 high whenever a stimulus is on screen
2 3 KeyDown!=0 // Will set output 3 on NSP2 high whenever a key is pressed.

==States==
===BlackrockTimeStampHigh===
The higher 32 bits of the 64-bit per-sample timestamp sent by the Gemini Hub.
===BlackrockTimeStampLow===
The lower 32 bits of the 64-bit per-sample timestamp sent by the Gemini Hub.
The time stamp itself represents the amount of time since the UNIX epoch (1.1.1970), with a resolution of 1ns (one nanosecond, 1e-9 seconds).

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

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

File:CortecADC stimulationtriggers parm1.PNG

2026-04-13T19:16:54Z

Nluczak: Nluczak uploaded a new version of File:CortecADC stimulationtriggers parm1.PNG

File:CortecADC stimulationpulses parm.PNG

2026-04-13T19:16:17Z

Nluczak: Nluczak uploaded a new version of File:CortecADC stimulationpulses parm.PNG

File:CortecADC stimulation parm.PNG

2026-04-13T19:14:36Z

Nluczak: Nluczak uploaded a new version of File:CortecADC stimulation parm.PNG

Contributions:CortecADC

2026-04-13T19:08:57Z

Nluczak:

[[File:CorTec_BrainInterchange.png|400px|thumb|right|CorTec Brain Interchange Implant]]

CortecADC is a source module that allows for intra-cranial recording and stimulating over 32 channels via a fully implantable device. It is intended for long-term measurement of neural activity and electrical stimulation of brain tissue. See the [https://www.cortec-neuro.com/solutions/complete-system/ CorTec site] for more information.

'''See the [[CortecExperience]] page for user tutorials and a broad overview!''' After viewing the [[CortecExperience]] page, refer to this page for detailed instructions.

==Versioning==

===Authors===
* Nicholas Luczak (luczak@neurotechcenter.org)
* William Engelhardt (engelhardt@neurotechcenter.org)
* Alexander Belsten (belsten@neurotechcenter.org)
* Markus Adamek (adamek@neurotechcenter.org)
* Christian Stolle (christian.stolle@cortec-neuro.com)

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

===BCI2000 Version History===
{|class="wikitable" style="text-align: center;"
! Date !! Revision !! Note !! Contributor
|-
!11/29/2018
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R5829
|Initial untested version
|Adamek
|-
!04/19/2021
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R6271
|First working version
|Belsten
|-
!07/22/2021
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R6339
|Changed ''ImplantLostSample'' from a BCI2000 state to a stream, so it can record individual sample loss (instead of over the whole block)
|Belsten
|-
!01/01/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7133
|Updated API to version 1.0.200.
|Engelhardt
|-
!03/08/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7251
|Stimulation functionality added
|Engelhardt
|-
!05/19/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7367
|Impedance measurement enabled
|Engelhardt
|-
!10/26/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7679
|Stimulation latency vastly improved
|Engelhardt
|-
!02/20/2024
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7847
|Version 1.0.230 added. Can change between versions in CMakeLists.txt file
|Stolle
|-
!08/09/2024
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R8313
|Version 1.0.238 added
|Stolle
|-
!01/17/2025
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7679
|Interpolation filter added to interpolate lost samples
|Engelhardt
|-
!06/25/2025
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R8915
|All listener states were changed to events
|Engelhardt
|-
!04/13/2026
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R9xxx
|Refactored stimulation to be more in line with Cortec and BCI2000 standards.
|Nicholas Luczak
|-
|}

===Cortec API Version History===
Cortec is continually updating their devices with new API versions. In BCI2000, we currently support versions 1.0.200, 1.0.230, and 1.0.238. Each Brain Interchange Communication unit (BIC) is only compatible with one API version. To find your compatible version, connect the USB drive that comes with your BIC. Look under:
# '''Software folder''': Each executable has the API version. E.g., <code>Bicapi_setup_1.0.200-bicapi-setup-1.0.200-rev35926.exe</code>
# '''Manuals foder''': ''Appendix1_BIC_Application_Software_Short_Manual.pdf''. On page 3, in Table 1, the third row contains the compatible version.

Here are some differences between the versions. As the device is always improving, the newest version will have the most features.

{|class="wikitable" style="text-align: center;"
! Features !! 1.0.200 !! 1.0.230 !! 1.0.238 !! 1.0.260

|-
!Matlab API
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!C/C++ API
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Stimulation modes
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!ASIC Noise Detection Mode
|style="color:red"|✘
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Monopolar stimulation (Ch → GND)
|style="color:red"|✘
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Measure GND impedances
|style="color:red"|✘
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Self-tests
|style="color:red"|✘
|style="color:red"|✘
|style="color:red"|✘
|style="color:green"|✔
|-
!Low noise recording
|style="color:red"|✘
|style="color:red"|✘
|style="color:red"|✘
|style="color:green"|✔
|-
|}

===Known Issues===
* Lost samples - The <code>ImplantLostSamples</code> state records what samples are lost, and their locations. Lost samples are replaced with the previous valid sample for all channels. In offline analysis, be sure to remove these samples and replace them with interpolates.
* The Brain Interchange Communication Unit has been seen to work with certain USB inputs, and not with others. If you are experiencing connection issues, try using a different USB port.

==Installation==
# Install BCI2000
# Insert the Cortec USB drive that comes with the Brain Interchange (BIC) device. Under ''Software'', run the ''Bicapi_setup...'' executable
# Run a batch file with CortecADC as your Signal Source!
# If you receive an error, and it states your API version is incorrect, you need to change it. Locate the ''CMakeLists.txt'' under <code>BCI2000/src/private/SignalSource/Cortec</code>. You must change Line 12, where it states <code>set(BICAPI_VERSION 200)</code>. Change 200 to 230 or 238, depending on your device (see [[#Cortec Version History | details above]]).

==Source Parameters==
These parameters can be found in the "Source" tab of the BCI2000 config window.
[[File:CortecSourceParameters.jpg|600px|thumb|center|upright=2.5|Figure 1. The default source parameters for the CortecADC]]
===SourceCh===
The total number of digitized and stored channels. In the current implementation, this parameter cannot be edited, and will default to how many channels are available from the implant.

===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. This parameter cannot be edited, and will default to the sampling rate available from the implant.
In case you are experiencing problems by higher sampling rates (e.g., data loss, jerky display, etc.), increase the SampleBlockSize so that you are updating the system less frequently (usually, updating the system 20-30 times per second is sufficient for most applications), and increase Visualize->VisualizeSourceDecimation. This parameter will decrease the number of samples per second that are actually drawn in the Source display.

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

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

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

===LogCortecBinaryFiles===
Enable or disable binary logging of raw CorTec communication data.

When enabled, a binary log file is written to the BCI2000 session directory with the name:

<code>YYYYMMDD_HHMMSS_CortecAdcLog.bin</code>

This file contains raw communication packets between the Brain Interchange Communication unit and the implant and is primarily useful for low-level debugging and support from CorTec.

Default value: <code>1</code> (enabled)

Disable this parameter if binary logs are not needed or disk space usage is a concern.

===LogStimulationEvents===
Enable logging of stimulation configuration and execution events to the Operator Log.

When enabled, detailed information about stimulation functions, trigger evaluation, and stimulation execution will be printed using <code>bciout</code> messages.

This is useful for debugging stimulation timing and verifying correct parameter interpretation.

Default value: <code>0</code> (disabled)

===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. It is strongly recommended to use at least one reference channel.

===AmplificationFactor===
Amplification factor that is applied to the recorded data on the implant. The choices are 39.5, 45.5, 51.5, 57.5 db.

===UseGround===
Enable to use the ground electrode while measuring. This setting can be overwritten during stimulation, depending if the ground electrode is being used or not. For example, if you have enabled this parameter but don't have <code>0</code> in your <code>Destination ch</code> list in the StimulationTriggers parameter, when you are stimulating you will not be using the ground electrode. Once stimulation is done, this parameter's settings are used again.

===SaveInfoFile===
Enable to save a text file, named the same as the data file run. It will contain the timestamp, amplification factor used in the run, and reference channels used. If the Impedance is measured, the impedance values will be saved to this file regardless of if this parameter is enabled.

===LogPacketErrors===
Enable to save the packet loss errors to the System Log. Helpful for debugging, however can get overwhelming if there are a lot of lost samples. The System Log can be programmatically saved by appending <code>--SystemLogFile=SOME_FILE.TXT</code> to the <code>Startup system localhost</code> line in your batch file.

==Stimulation Parameters==
These parameters can be found in the "Stimulation" tab of the BCI2000 config window.
<gallery mode="packed" widths=300px heights=300px>
File:CortecADC_stimulation_parm.PNG
File:CortecADC_stimulationpulses_parm.PNG
File:CortecADC_stimulationtriggers_parm1.PNG
</gallery>

===EnableStimulation===
This parameter enables/disables stimulation.

===StimulationMode===
The BIC has 3 stimulation modes. Each one has limitations. Here is a brief summary of how to use each one:
#Volatile Commands: The most flexible mode. The limitation is that the stimulation configuration is uploaded right before starting the stimulation, which increases the latency of the stimulation. This mode is best used in single pulse stimulation or stimulation burst applications. Can cause issues in longer stimulation trains due to the latency introduced by uploading commands repeatedly.
[[File:VolatileCommand.png|1000px|thumb|center|upright=2.5|Figure 1. Figure demonstrating volatile command functionality]]
#Persistent Command: There can only be one stimulation configuration (one column in StimulationPulses), which includes burst settings. You cannot change the source and destination channels without uploading a new command. This mode is useful for implementing stimulation trains, otherwise similar but less flexible when compared to volatile commands.
[[File:PersistantCommand.png|1000px|thumb|center|upright=2.5|Figure 2. Figure demonstrating Persistant Command functionality]]

#Persistent Functions: This function allows you to preload multiple stimulation configurations allowing for the user to define different source and destination channels. The device executes only one of the stim configrations, and without repetition. This is best used for rapidly iterating over subsets of stimulation pulses in single-pulse stimulation settings.
[[File:PersistantFunction.png|1000px|thumb|center|upright=2.5|Figure 3. Figure demonstrating Persistant Function functionality]]
There cannot be any train settings (Train frequency and Train repetitions), so the StimulationTriggers must not have those rows. Also, StimulationTriggers must not have more than 16 columns, as that is the highest number of configurations that can be stored on the device.

Persistent Command and Functions modes have a lower latency because the stimulation is pre-uploaded. All modes are available to give you the highest amount of flexiblity with the BIC. [[#Stimulation Latency|See below for more details on latency.]]

===MeasureImpedance===
When enabled, the impedances of the used electrodes are printed when you set the configuration. All electrodes that are being recorded will conduct the impedance measurement. The impedances are shown to the user and also saved in the data directory.

===StimulationPulses===
This parameter defines stimulation ''functions''. Each column defines a stimulation waveform and electrode configuration.

Each function consists of:

* Pulse waveform parameters
* Electrode mapping
* Repetition behavior

Rows are defined as follows:

====FunctionID====
Integer identifier for this stimulation function. This ID is referenced in the <code>StimulationTriggers</code> parameter.

====Pulse Amplitude====
Amplitude of the stimulation pulse in µA.

Valid range:
0 to 6120 µA

====Pulse Duration====
Duration of the main pulse in µs.

Valid range:
10 to 2550 µs

====Dead Zone 0====
Pause between main pulse and counter pulse.

====Dead Zone 1====
Pause after pulse delivery.

====Anode(s)====
Embedded list specifying source electrodes.

Example:

<code>{ list 1 18 19 }</code>

====Cathode(s)====
Embedded list specifying return electrodes.

Use <code>0</code> to reference ground.

====Pulse Repetition====
Number of times the pulse is repeated within a function.

Range:
1 to 255

====Burst Repetition====
Number of times the function is repeated.

Range:
1 to 255

===StimulationTriggers===
Defines when stimulation functions are executed.

Each column contains:

====Trigger====
A valid BCI2000 expression.

When this expression evaluates to true, the associated stimulation function(s) are executed.

====FunctionID(s)====
List of FunctionIDs that should execute when the trigger evaluates true.

Example:

<code>
StimulusCode==1 { list 1 3 }
</code>

This means:

Execute FunctionID 1 followed by FunctionID 3 whenever the trigger becomes true.

Note:
Electrode configuration and repetition settings are defined in <code>StimulationPulses</code>, not here.

==Device Parameters==

===DeviceInfo===
This parameter cannot be edited and is automatically populated with information returned from the device, such as device type, device ID, and the firmware version.

===StateInfo===
This parameter cannot be edited and is automatically populated with information regarding state units and their multiplier. The device provides information such as humidity, temperature, control value, etc., which are recorded in BCI2000 states (see state information on this page for a complete enumeration of states). The device provides these values with floats, but BCI2000 states can only be integers. The multipliers defined in this parameter are used to increase the amount of precision in the state values. To approximately recover the original float values with the units defined in this parameter, divide each state by its corresponding multiplier.

==States==
The states encode auxiliary information returned from the Cortec implant. The device provides this data in floating point numbers, however BCI2000 can only record integers to it's states. To maintain some precision, these floats are multiplied by constants, then recorded to the states as integers. To approximately recover the original data, divide the state by its corresponding constant. Constants are shown in the following table.
{| class="wikitable" style="text-align:right;"
|- style="font-weight:bold;"
! State
! style="text-align:center;" | Constant
|-
| ImplantVoltage
| style="text-align:center;" | 1000
|-
| ImplantHumidity
| style="text-align:center;" | 100
|-
| ImplantControlValue
| style="text-align:center;" | 100
|-
| ImplantPrimaryCoilCurrent
| style="text-align:center;" | 1000
|-
| ImplantTemperature
| style="text-align:center;" | 100
|}
===ImplantLostSample===
The communication protocol the device uses does not re-send lost data. This state annotates what samples were lost in the bio-signal data. Currently, lost samples are made up by duplicating the previous sample.

===ImplantVoltage===
16 bit state that changes when new supply voltage value is received from the implant. After dividing the integer state value by the the voltage multiplier defined in the StateInfo parameter, the units are in volts.

===ImplantHumidity===
16 bit state that changes when new humidity value is received from the implant. Units in %rh.

===ImplantControlValue===
16 bit state that changes when new current control value is received from the external unit. The power of the implant is controlled by the external unit. The control value provides a measure of how good the coupling between the two coils is and how much more power can be provided if necessary.
The value is between 0.0 and 100.0 percent, where 0.0 translates to no power and 100.0 translates to maximum power applied.

===ImplantPrimaryCoilCurrent===
16 bit state that change when new primary coil current value is received from the external unit. The primary coil refers to the coil inside the head piece of the external unit. Units are mA.

===ImplantTemperature===
16 bit state that changes when new temperature value is received from the implant. Units are degrees Celsius.

===ImplantStimulation===
Binary state that changes when the device reports that it is stimulating.

===ImplantStimulationBursts===
Updates when the device reports that stimulation functions have finished. Should increment during a stimulation train.

===ImplantRfQuality===
8 bit state that reports the antenna quality as reported from the rf-link in dBm. '''''To obtain the original value, subtract by 128 (2^8)'''''.

===RequestedStimulation===
Binary state that records when a stimulation trigger expression evaluates true. State remains true for the duration triggered stimulation. This is useful for determining the latency between when stimulation is requested and when it is actually applied. This is done by computing the difference in time between the rising edges of ''ImplantStimulation'' and ''RequestedStimulation'' states.

===PauseStimulation===
Binary state that pauses stimulation execution without stopping data recording.

When this state is set to <code>1</code>, trigger expressions are ignored and no stimulation will be delivered.

When set to <code>0</code>, stimulation resumes normally.

This allows temporary suspension of stimulation during a recording session without restarting the system.

==Stimulation Logging==
When <code>LogStimulationEvents</code> is enabled, stimulation activity will be written to the Operator Log.

Logged information includes:

* Stimulation mode
* Function definitions
* Trigger matches
* Stimulation execution events

This information is useful for:

* Debugging stimulation timing
* Verifying correct function configuration
* Investigating unexpected stimulation behavior

==[[User_Reference:StimulationConfigurationIntegrativeTool_(SCIT)|SCIT]]==
To help out with creating the BCI2000 parameters, a GUI has been made which should make it easy to translate your stimulation specifications into BCI2000 parameter files. The GUI also visualizes the stimulation from three different perspectives, making it easy to tell if your parameters are really what you want. There is a [[User_Reference:StimulationConfigurationIntegrativeTool_(SCIT)|Stimulation Configuration tool user reference]] which will further tell you how to use this tool.

<gallery mode="packed" widths=500px heights=500px>
File:CortecGUIimg.png|The Cortec GUI which creates BCI2000 parameters from stimulation specifications.
</gallery>

==Stimulation Latency==
<gallery mode="packed" widths=500px heights=500px>
File:StimulationModesLatencyCortec.png|Stimulation Latencies for the specified Stimulation Modes.
</gallery>
Tests were conducted for 100 pulses, with an ISI of 10 seconds.

Stimulation latency numbers:
*Persistent functions: '''13 ± 1 ms'''
*Persistent commands: '''11 ± 1 ms'''
*Volatile commands: '''60 ± 30 ms'''. Split into the 2 groups, the lower one is '''48 ± 3 ms''' and the higher one is '''174 ± 3 ms'''

As explained above, volatile commands are uploaded right before stimulation, which leads to the increased latency and jitter.
==µZeus==
In order to use the new µZeus headpiece simply change the BICVERSION number on line 12 of the CMakeList.txt located in the project folder to use version 274 of the API. ie.,

<code>set(BICAPI_VERSION 274)</code>

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

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

Contributions:AmpServerProADC

2026-03-18T13:43:39Z

Nluczak: /* Source Code Revisions */

==Synopsis==
The ''AmpServerProADC'' component implements the client side of EGI's TCP/IP-based Amp Server Pro (ASP) protocol. Thus, it may be used to interface BCI2000 with an EGI amplifier. Amplifiers that record data and administer transcranial direct current stimulation (GTEN devices) are supported.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/AmpServerPro

==Versioning==
===Author===
Joshua Fialkoff, (c) 2008 Wadsworth Center, New York State Department of Health. (V1)

Alex Belsten (belsten@neurotechcenter.org), NCAN. (V2)

===Version History===
* V1.00 - 06/11/2008 - First working version
* V2.00 - 05/10/2020 - Added support for GTEN devices and packet format 2
===Source Code Revisions===
*Initial development: 1998
*Tested under: 9297
*Known to compile under: 9297
*Stimulation broken since: 7273 - Race condition in AmpServerProADC allows stimulation to start before train upload completes, causing “train not uploaded” errors and SignalSource crashes.

==Video Overview==
<youtube alignment="center">https://www.youtube.com/watch?v=wW-xEy9e5ps&list=PL6LrR5Nj3cAxOxKHNsnqyKfLDGikpi8Qi&index=7</youtube>

==Using the AmpServerPro Source Module==
For using the AmpServerPro source module, you will need to obtain a license for the AmpServerPro SDK. Without such a license, you may be able to connect to the machine running the EGI software, but it will not send any real-time data when asked to. In order to obtain an AmpServerPro SDK license, you will need to contact EGI at http://www.egi.com.

==Setting Up the Hardware==
The EGI system comes with many hardware and cables, so connecting everything in a step-by-step manner is helpful for getting everything connected correctly. There are a few steps to this process. First, make sure you have all of the necessary cables and hardware. These items can be seen in the two images below (Fig. 1 and Fig. 2).
<gallery mode="packed" widths=300px heights=300px>
File:EGI-cables.jpeg|Figure 1: The necessary cables.
File:EGI-boxes.jpg|Figure 2: EGI hardware.
</gallery>
In addition to the hardware shown in Fig. 1 and 2, you will need the EGI iMac that comes with the amplifier and a research PC. This PC must be running Windows and needs an ethernet port or an adapter that connects to an ethernet cable.
Once sure that all of the necessary hardware/cables are present, it is time to connect all the hardware. For your reference, the general architecture is shown in the figure below.
<gallery mode="packed" widths=300px heights=300px>
File:EGI-power_and_network.png|Figure 3: General hardware architecture.
</gallery>
===Setting up the Power Supplies===
The transformer is the first piece of hardware to set up. It provides isolated power to the EGI amplifier, switch box, and EGI iMac. Each of these devices connects to the plugs on the back of the transformer, as shown in Fig. 4.
<gallery mode="packed" widths=300px heights=300px>
File:EGI-transformer_connections.jpeg|Figure 4: Three different types of plugs on the back of the transformer.
</gallery>

Verify that the transformer is off and use plug type 3 in Fig. 4 to plug into a standard wall socket. Now, connect the EGI iMac to plug type 2. Next, you will need two cables of type 1 (IEC plug cable). Connect one to the amplifier power supply and the other to the switch box. Keep the transformer off for now. Lastly, you will need to use the amplifier power cable to connect the amplifier power supply to the amplifier.

===Setting up the Network Cables===
Next, the network cables need to be connected. Fig. 5 and 6 serve as a reference through this process.
<gallery class="center" mode="nolines" widths=500px heights=500px>
File:EGI-back-of-amp.jpeg|Figure 5: Connections to back of amplifier.
File:EGI-switch-box.jpeg|Figure 6: Network connections to switch box.
</gallery>
Start by connecting the orange fiber optic cable to the back of the amplifier and then connect the other end to the front of the switch box. Then, connect one of the network cables to the EGI iMac and connect the other end to any one of the eight ports on the switch box. Lastly, connect the other network cable to your research PC and then to the switch box. Now that everything is connected, the transformer and amplifier power supply can be turned on. Next, boot up the EGI iMac. Navigate to the browser and enter the amplifier's IPv4 address into the address bar. You can find the IPv4 address of your amplifier by launching Net Station Acquisition on the EGI iMac and expanding the ''sharing'' tab. All of the EGI amplifiers have an IPv4 address of the form <code>10.10.10.X</code> where <code>X</code> is some integer between 0 and 256. You should now see the amplifier's web page, similar to the one shown in Fig. 7. If you cannot see this web page, verify that all network connections are secure and the amplifier is powered on.
<gallery class="center" mode="nolines" widths=600px heights=600px>
File:EGI-amp_webserver.jpg|Figure 7: Amplifier webpage that is accessible from amplifier's IPv4 address.
</gallery>

==Configuring and Setting Up BCI2000 on the Research PC==
Now it is time to set up the research PC. First, install BCI2000 (a guide to do this can be found at [[Programming_Howto:Building_and_Customizing_BCI2000]]) and make sure the <code>BUILD_CONTRIB</code> option is enabled in CMake before compiling.

The research PC's IP address must be configured to allow the amplifier and Net Station to recognize it. On the research PC, configure the IP (IPv4) for a manual IP address (<code>10.10.10.Y</code> where <code>Y</code> is any digits other than the last two digits used by the amp); with the manual IPv4 address configured, set the subnet mask to 255.255.255.0. Once this has been completed, open a browser on the research PC and enter the amplifier's IPv4 address into the address bar. If the research PC's IP address is set correctly, the page will populate with information about the amplifier shown in Fig. 7. If the web page fails to load, then the PC's IPv4 address may not have been set correctly, or the research PC has a firewall that is blocking the amplifier. Verify that the research IPv4 address is correct and firewalls have been disabled.

===Starting Amp Server Pro===
Amp Server Pro is capable of working with many amplifiers concurrently. To begin using Amp Server Pro with BCI2000, ensure that at least one amplifier is connected to the server. If no amplifier is connected, the Amp Server software emulates an amplifier. If you choose to use the emulated amplifier, you should expect to see a smooth sine wave signal for all channels. To start the amp server simply navigate to the Amp Server Pro directory and double click the file named "<tt>Amp Server</tt>".

===Creating a BCI2000 Batch File===
Although it is not necessary, it is convenient to create a batch file to run BCI2000 with the Amp Server Pro module. To create the batch file, start out with a copy of a suitable batch file in <tt>BCI2000/batch/</tt>, and open it in a text editor.

Towards the end of the file, you will see a sequence of lines beginning with
start executable

These lines are responsible for starting up source, signal processing, and application module, in that sequence. To use the AmpServerPro module, you will need to replace the executable name in the first entry, e.g.
start executable SignalGenerator --local
becomes
start executable AmpServerPro --local

For more information, see [[Contributions:How_to_use_a_Contributed_Source_Module#Creating_batch_files|this page]].

===Using Amp Server Pro with BCI2000===
Once you have started the Amp Server and compiled the Amp Server Pro module, you can begin collecting data with BCI2000 by following the steps below.
# Double click <tt>BCI2000/batch/CursorTask_AmpServerPro.bat</tt> - the batch file that was created in the previous section - to start BCI2000.
# Click the "Configure" button.
# Set the appropriate parameters. The Amp Server Pro module is initialized with a number of parameters that can be configured from the "Source" tab. A summary and description of these parameters can be found below.
# Click "Set Config".
# Click "Start" to begin your experiment.

==Parameters==
===SourceCh===
Enter the number of channels that have electrodes connected (32, 64, 128, or 256).
Make sure that '''SourceChOffset''' and '''SourceChGain''' are set to "auto" or you may get an error message about a mismatching number of entries.

===BlockSize===
This parameter should always be set to ''auto''. If the amp uses packet format 1, then the block size is fixed at 40 samples per block. If the amp uses packet format 2 then the block size specified by ''SampleBlockSize'' will be used. The packet format will be displayed in the operator window of BCI2000 after clicking 'Set Config' and successful connection to amp.

===ServerIP===
The IP address of the amplifier (e.g. <code>10.10.10.51</code>)

===CommandPort===
The port number of the port used for command layer communication. Unless you have explicitly set the port number via Amp Server's configuration, the default of 9877 should be correct.

===NotificationPort===
The port number of the port used for notification layer communication. Unless you have explicitly set the port number via Amp Server's configuration, the default of 9878 should be correct.

===StreamPort===
The port number of the port used for data streaming. Unless you have explicitly set the port number via Amp Server's configuration, the default of 9879 should be correct.

===AmplifierID===
Amp Server Pro is capable of managing many amplifiers concurrently. BCI2000, however, operates with a single amplifier. If only a single amplifier is connected, you may enter the value "auto" here and allow BCI2000 to automatically determine the Amplifier ID. If multiple amplifiers are connected, however, you must enter a valid ID from 0 to N-1, where N is the number of amplifiers connected.

==Packet Format 2 Parameter==
===SampleBlockSize===
If the connected amp uses packet format 2, then the user can configure the number of samples per block using this parameter.

==GTEN Parameters==
The GTEN parameters are only used when using a GTEN device. If the connected amp cannot perform stimulation, disable ''RunTranscranialStim''.

===RunTranscranialStim===
Enables stimulation. If stimulation is enabled, the following parameters are used.

===ModulationPlanFile===
The modulation plan file contains all of the information about the stimulation train. This file is created on the Net Station iMac with the EGI program Reciprocity. Reciprocity allows the user to configure all of the parameters of the stimulation train such as electrode location, waveform amplitude, duration, etc. See EGI's GTEN manual for information related to Reciprocity use.

Once the train is designed in Reciprocity, save the .mcb plan file and note its location. Copy the .mcb file and transfer it to the research PC. Launch BCI2000 and click the browse button for the ''ModulationPlanFile'' parameter. On windows, the .mcb file will now be a folder. Navigate to this folder and inside, there will be multiple files and two other folders. Select the file called 'plan.mcf' as the ''ModulationPlanFile''. Select ONLY the 'plan.mcf' file as the BCI2000 parameter value, but also DO NOT change any of the other contents of the .mcb folder.

===StimulationExpression===
Expression that triggers stimulation. For more info on expressions, see [[User Reference:Expression Syntax]].
===AbortExpression===
Expression that aborts stimulation. If this is never triggered, the stimulation will continue until the <code>duration_ms</code>, specified in the uploaded Modulation Plan, runs to its full duration.
==States==
===GTENStimulationTriggered===
This binary state is set to 1 when stimulation is triggered.
===GTENTrainRunning===
This state is one byte in size and contains information sent back from the amplifier about stimulation. If bit 2 is low (XXXX X0XX) then current is being injected by the amp. If bit 4 is low (XXX0 XXXX) then a new block in the neuromodulation train has just begun.
===EGIDigitalInputStream===
This state is 16 bits and records the digital inputs on the back of the amplifier as seen in Fig. 5.
===DigitalInput1-4===
These 4 binary states are 1 when there is a digital input, or 0 in the absence of one. This information is parsed from the EGIDigitalInputStream, but separated for user convenience.

==Certification Results==
The AmpServerPro certification was performed to give a better understanding of the restraints that must be placed on the system when using this device. Certification success criteria was determined internally and without rigor, and reflects our experience with psychophysical experiments and the performance we expect to need for the system. More information about certification testing can be found on the [[User Reference:BCI2000Certification|certification wiki page]].

===PC Specifications===
*Lenovo Thinkpad E580 (https://www.lenovo.com/us/en/laptops/thinkpad/thinkpad-e-series/ThinkPad-E580/p/22TP2TEE580)
*Processor: Intel(R) Core(TM) i5-7200U CPU @ 2.50GHz 2.7GHz
*Installed Ram: 8.00 GB
*Graphics Card: Intel(R) HD Graphics 620
*System Type: 64-bit operating system, x64-based processor
*BCI2000 compiled with MSVC2019 and Qt 5.15.2

===Certification Tests Performed===
Certification testing varied block size (50, 100 ms), and task (P3Spell (7x7 grid), P3Spell (1x1 grid), CursorTask, CursorTaskLow, and StimulusPresentation), and tested audio and video latency, for a total of 12 performed tasks. The audio latency and video latency are partitioned into separate windows, as we tested them in different runs.

===Success Criteria and Overall Results===
{|border="1"
|Name
|Actual Latency
|Success Criteria
|Result
|-
|Timestamp Latency Mean
|509µs
|1 ms
|passed
|-
|Timestamp Latency STD
|2.02ms
|1 ms
|failed
|-
|Processing Latency Mean
|44.7ms
|20 ms
|failed
|-
|Processing Latency STD
|20.3ms
|10 ms
|failed
|-
|Video Latency Mean
|73.1ms
|65 ms
|failed
|-
|Video Latency STD
|17.7ms
|20 ms
|passed
|-
|Audio Latency Mean
|62.9ms
|65 ms
|passed
|-
|Audio Latency STD
|3.33ms
|20 ms
|passed
|}

===Stimulation Latency===
The Stimulation Latency for the EGI system seems to be dependent on the stimulation width and ISI width. When the '''stimulation width plus the ISI width is less than 8 seconds''', it has a large latency and can also miss stimulation (see Figure 8).

<gallery mode="packed" widths=450px heights=450px>
File:EGILatency 2sStim.png|Figure 8: The jitter of the stimulation latency, showing a large mean and variation of latency for ISI's less than 6 seconds.
File:EGILatencyHist.png | Figure 9: The latency of the EGI system. Run for 100 trials, with a 2s stimulation width and an 8s ISI width. The block size was 40 ms with a sampling rate of 1 kHz.
</gallery>

The stimulation latency seems to be inconsistent, however for large enough ISI widths, it is usually around 1.1 seconds. For the trial shown in Figure 9, the average latency was 1,159 ± 5 ms.



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

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

Contributions:AmpServerProADC

2026-03-18T13:43:28Z

Nluczak: /* Versioning */

==Synopsis==
The ''AmpServerProADC'' component implements the client side of EGI's TCP/IP-based Amp Server Pro (ASP) protocol. Thus, it may be used to interface BCI2000 with an EGI amplifier. Amplifiers that record data and administer transcranial direct current stimulation (GTEN devices) are supported.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/AmpServerPro

==Versioning==
===Author===
Joshua Fialkoff, (c) 2008 Wadsworth Center, New York State Department of Health. (V1)

Alex Belsten (belsten@neurotechcenter.org), NCAN. (V2)

===Version History===
* V1.00 - 06/11/2008 - First working version
* V2.00 - 05/10/2020 - Added support for GTEN devices and packet format 2
===Source Code Revisions===
*Initial development: 1998
*Tested under: 9297
*Known to compile under: 9297
*Stimulation broken since: 7273
Race condition in AmpServerProADC allows stimulation to start before train upload completes, causing “train not uploaded” errors and SignalSource crashes.

==Video Overview==
<youtube alignment="center">https://www.youtube.com/watch?v=wW-xEy9e5ps&list=PL6LrR5Nj3cAxOxKHNsnqyKfLDGikpi8Qi&index=7</youtube>

==Using the AmpServerPro Source Module==
For using the AmpServerPro source module, you will need to obtain a license for the AmpServerPro SDK. Without such a license, you may be able to connect to the machine running the EGI software, but it will not send any real-time data when asked to. In order to obtain an AmpServerPro SDK license, you will need to contact EGI at http://www.egi.com.

==Setting Up the Hardware==
The EGI system comes with many hardware and cables, so connecting everything in a step-by-step manner is helpful for getting everything connected correctly. There are a few steps to this process. First, make sure you have all of the necessary cables and hardware. These items can be seen in the two images below (Fig. 1 and Fig. 2).
<gallery mode="packed" widths=300px heights=300px>
File:EGI-cables.jpeg|Figure 1: The necessary cables.
File:EGI-boxes.jpg|Figure 2: EGI hardware.
</gallery>
In addition to the hardware shown in Fig. 1 and 2, you will need the EGI iMac that comes with the amplifier and a research PC. This PC must be running Windows and needs an ethernet port or an adapter that connects to an ethernet cable.
Once sure that all of the necessary hardware/cables are present, it is time to connect all the hardware. For your reference, the general architecture is shown in the figure below.
<gallery mode="packed" widths=300px heights=300px>
File:EGI-power_and_network.png|Figure 3: General hardware architecture.
</gallery>
===Setting up the Power Supplies===
The transformer is the first piece of hardware to set up. It provides isolated power to the EGI amplifier, switch box, and EGI iMac. Each of these devices connects to the plugs on the back of the transformer, as shown in Fig. 4.
<gallery mode="packed" widths=300px heights=300px>
File:EGI-transformer_connections.jpeg|Figure 4: Three different types of plugs on the back of the transformer.
</gallery>

Verify that the transformer is off and use plug type 3 in Fig. 4 to plug into a standard wall socket. Now, connect the EGI iMac to plug type 2. Next, you will need two cables of type 1 (IEC plug cable). Connect one to the amplifier power supply and the other to the switch box. Keep the transformer off for now. Lastly, you will need to use the amplifier power cable to connect the amplifier power supply to the amplifier.

===Setting up the Network Cables===
Next, the network cables need to be connected. Fig. 5 and 6 serve as a reference through this process.
<gallery class="center" mode="nolines" widths=500px heights=500px>
File:EGI-back-of-amp.jpeg|Figure 5: Connections to back of amplifier.
File:EGI-switch-box.jpeg|Figure 6: Network connections to switch box.
</gallery>
Start by connecting the orange fiber optic cable to the back of the amplifier and then connect the other end to the front of the switch box. Then, connect one of the network cables to the EGI iMac and connect the other end to any one of the eight ports on the switch box. Lastly, connect the other network cable to your research PC and then to the switch box. Now that everything is connected, the transformer and amplifier power supply can be turned on. Next, boot up the EGI iMac. Navigate to the browser and enter the amplifier's IPv4 address into the address bar. You can find the IPv4 address of your amplifier by launching Net Station Acquisition on the EGI iMac and expanding the ''sharing'' tab. All of the EGI amplifiers have an IPv4 address of the form <code>10.10.10.X</code> where <code>X</code> is some integer between 0 and 256. You should now see the amplifier's web page, similar to the one shown in Fig. 7. If you cannot see this web page, verify that all network connections are secure and the amplifier is powered on.
<gallery class="center" mode="nolines" widths=600px heights=600px>
File:EGI-amp_webserver.jpg|Figure 7: Amplifier webpage that is accessible from amplifier's IPv4 address.
</gallery>

==Configuring and Setting Up BCI2000 on the Research PC==
Now it is time to set up the research PC. First, install BCI2000 (a guide to do this can be found at [[Programming_Howto:Building_and_Customizing_BCI2000]]) and make sure the <code>BUILD_CONTRIB</code> option is enabled in CMake before compiling.

The research PC's IP address must be configured to allow the amplifier and Net Station to recognize it. On the research PC, configure the IP (IPv4) for a manual IP address (<code>10.10.10.Y</code> where <code>Y</code> is any digits other than the last two digits used by the amp); with the manual IPv4 address configured, set the subnet mask to 255.255.255.0. Once this has been completed, open a browser on the research PC and enter the amplifier's IPv4 address into the address bar. If the research PC's IP address is set correctly, the page will populate with information about the amplifier shown in Fig. 7. If the web page fails to load, then the PC's IPv4 address may not have been set correctly, or the research PC has a firewall that is blocking the amplifier. Verify that the research IPv4 address is correct and firewalls have been disabled.

===Starting Amp Server Pro===
Amp Server Pro is capable of working with many amplifiers concurrently. To begin using Amp Server Pro with BCI2000, ensure that at least one amplifier is connected to the server. If no amplifier is connected, the Amp Server software emulates an amplifier. If you choose to use the emulated amplifier, you should expect to see a smooth sine wave signal for all channels. To start the amp server simply navigate to the Amp Server Pro directory and double click the file named "<tt>Amp Server</tt>".

===Creating a BCI2000 Batch File===
Although it is not necessary, it is convenient to create a batch file to run BCI2000 with the Amp Server Pro module. To create the batch file, start out with a copy of a suitable batch file in <tt>BCI2000/batch/</tt>, and open it in a text editor.

Towards the end of the file, you will see a sequence of lines beginning with
start executable

These lines are responsible for starting up source, signal processing, and application module, in that sequence. To use the AmpServerPro module, you will need to replace the executable name in the first entry, e.g.
start executable SignalGenerator --local
becomes
start executable AmpServerPro --local

For more information, see [[Contributions:How_to_use_a_Contributed_Source_Module#Creating_batch_files|this page]].

===Using Amp Server Pro with BCI2000===
Once you have started the Amp Server and compiled the Amp Server Pro module, you can begin collecting data with BCI2000 by following the steps below.
# Double click <tt>BCI2000/batch/CursorTask_AmpServerPro.bat</tt> - the batch file that was created in the previous section - to start BCI2000.
# Click the "Configure" button.
# Set the appropriate parameters. The Amp Server Pro module is initialized with a number of parameters that can be configured from the "Source" tab. A summary and description of these parameters can be found below.
# Click "Set Config".
# Click "Start" to begin your experiment.

==Parameters==
===SourceCh===
Enter the number of channels that have electrodes connected (32, 64, 128, or 256).
Make sure that '''SourceChOffset''' and '''SourceChGain''' are set to "auto" or you may get an error message about a mismatching number of entries.

===BlockSize===
This parameter should always be set to ''auto''. If the amp uses packet format 1, then the block size is fixed at 40 samples per block. If the amp uses packet format 2 then the block size specified by ''SampleBlockSize'' will be used. The packet format will be displayed in the operator window of BCI2000 after clicking 'Set Config' and successful connection to amp.

===ServerIP===
The IP address of the amplifier (e.g. <code>10.10.10.51</code>)

===CommandPort===
The port number of the port used for command layer communication. Unless you have explicitly set the port number via Amp Server's configuration, the default of 9877 should be correct.

===NotificationPort===
The port number of the port used for notification layer communication. Unless you have explicitly set the port number via Amp Server's configuration, the default of 9878 should be correct.

===StreamPort===
The port number of the port used for data streaming. Unless you have explicitly set the port number via Amp Server's configuration, the default of 9879 should be correct.

===AmplifierID===
Amp Server Pro is capable of managing many amplifiers concurrently. BCI2000, however, operates with a single amplifier. If only a single amplifier is connected, you may enter the value "auto" here and allow BCI2000 to automatically determine the Amplifier ID. If multiple amplifiers are connected, however, you must enter a valid ID from 0 to N-1, where N is the number of amplifiers connected.

==Packet Format 2 Parameter==
===SampleBlockSize===
If the connected amp uses packet format 2, then the user can configure the number of samples per block using this parameter.

==GTEN Parameters==
The GTEN parameters are only used when using a GTEN device. If the connected amp cannot perform stimulation, disable ''RunTranscranialStim''.

===RunTranscranialStim===
Enables stimulation. If stimulation is enabled, the following parameters are used.

===ModulationPlanFile===
The modulation plan file contains all of the information about the stimulation train. This file is created on the Net Station iMac with the EGI program Reciprocity. Reciprocity allows the user to configure all of the parameters of the stimulation train such as electrode location, waveform amplitude, duration, etc. See EGI's GTEN manual for information related to Reciprocity use.

Once the train is designed in Reciprocity, save the .mcb plan file and note its location. Copy the .mcb file and transfer it to the research PC. Launch BCI2000 and click the browse button for the ''ModulationPlanFile'' parameter. On windows, the .mcb file will now be a folder. Navigate to this folder and inside, there will be multiple files and two other folders. Select the file called 'plan.mcf' as the ''ModulationPlanFile''. Select ONLY the 'plan.mcf' file as the BCI2000 parameter value, but also DO NOT change any of the other contents of the .mcb folder.

===StimulationExpression===
Expression that triggers stimulation. For more info on expressions, see [[User Reference:Expression Syntax]].
===AbortExpression===
Expression that aborts stimulation. If this is never triggered, the stimulation will continue until the <code>duration_ms</code>, specified in the uploaded Modulation Plan, runs to its full duration.
==States==
===GTENStimulationTriggered===
This binary state is set to 1 when stimulation is triggered.
===GTENTrainRunning===
This state is one byte in size and contains information sent back from the amplifier about stimulation. If bit 2 is low (XXXX X0XX) then current is being injected by the amp. If bit 4 is low (XXX0 XXXX) then a new block in the neuromodulation train has just begun.
===EGIDigitalInputStream===
This state is 16 bits and records the digital inputs on the back of the amplifier as seen in Fig. 5.
===DigitalInput1-4===
These 4 binary states are 1 when there is a digital input, or 0 in the absence of one. This information is parsed from the EGIDigitalInputStream, but separated for user convenience.

==Certification Results==
The AmpServerPro certification was performed to give a better understanding of the restraints that must be placed on the system when using this device. Certification success criteria was determined internally and without rigor, and reflects our experience with psychophysical experiments and the performance we expect to need for the system. More information about certification testing can be found on the [[User Reference:BCI2000Certification|certification wiki page]].

===PC Specifications===
*Lenovo Thinkpad E580 (https://www.lenovo.com/us/en/laptops/thinkpad/thinkpad-e-series/ThinkPad-E580/p/22TP2TEE580)
*Processor: Intel(R) Core(TM) i5-7200U CPU @ 2.50GHz 2.7GHz
*Installed Ram: 8.00 GB
*Graphics Card: Intel(R) HD Graphics 620
*System Type: 64-bit operating system, x64-based processor
*BCI2000 compiled with MSVC2019 and Qt 5.15.2

===Certification Tests Performed===
Certification testing varied block size (50, 100 ms), and task (P3Spell (7x7 grid), P3Spell (1x1 grid), CursorTask, CursorTaskLow, and StimulusPresentation), and tested audio and video latency, for a total of 12 performed tasks. The audio latency and video latency are partitioned into separate windows, as we tested them in different runs.

===Success Criteria and Overall Results===
{|border="1"
|Name
|Actual Latency
|Success Criteria
|Result
|-
|Timestamp Latency Mean
|509µs
|1 ms
|passed
|-
|Timestamp Latency STD
|2.02ms
|1 ms
|failed
|-
|Processing Latency Mean
|44.7ms
|20 ms
|failed
|-
|Processing Latency STD
|20.3ms
|10 ms
|failed
|-
|Video Latency Mean
|73.1ms
|65 ms
|failed
|-
|Video Latency STD
|17.7ms
|20 ms
|passed
|-
|Audio Latency Mean
|62.9ms
|65 ms
|passed
|-
|Audio Latency STD
|3.33ms
|20 ms
|passed
|}

===Stimulation Latency===
The Stimulation Latency for the EGI system seems to be dependent on the stimulation width and ISI width. When the '''stimulation width plus the ISI width is less than 8 seconds''', it has a large latency and can also miss stimulation (see Figure 8).

<gallery mode="packed" widths=450px heights=450px>
File:EGILatency 2sStim.png|Figure 8: The jitter of the stimulation latency, showing a large mean and variation of latency for ISI's less than 6 seconds.
File:EGILatencyHist.png | Figure 9: The latency of the EGI system. Run for 100 trials, with a 2s stimulation width and an 8s ISI width. The block size was 40 ms with a sampling rate of 1 kHz.
</gallery>

The stimulation latency seems to be inconsistent, however for large enough ISI widths, it is usually around 1.1 seconds. For the trial shown in Figure 9, the average latency was 1,159 ± 5 ms.



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

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

User Reference:gNautilus

2026-02-25T14:00:13Z

Nluczak:

==Synopsis==
The g.Nautilus is a biopotential amplifier with wireless transmission technology with either wet or dry electrodes. It reads in up to 32 signal channels and 8 trigger channels.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/core/SignalSource/g.NautilusSource

==Versioning==
===Author===
Kristopher Kaleb Goering (kaleb.goering@gmail.com) University of Kansas

===Source Code Revisions===
*Initial development: 4928
*Tested under: 9282
*Known to compile under: 9282
*Broken since: N/A

==Functional Description==
The g.Nautilus is a wireless headset by g.tec, and is the first in their product line to use g.NEEDaccess exclusively for realtime access. This documentation explains the parameterization and specifics on how to set up the system.

Install g.NEEDaccess_Sever. Ensure the device is charged and connected to the base station (refer to the included documentation for help with this). Start BCI2000 with the gNautilusSource module.

==Parameters==
===SourceCh===
represents the total number of channels to be logged from the source module.
===SampleBlockSize===
should be set equal to the size of the sample block pulled from the device.

'''NOTE:''' 25 and up found to work best during testing for 250Hz
===SampleRate===
determines the rate at which the device samples data.

'''NOTE:''' Only the following sample rates are currently supported by the API: 250Hz and 500Hz.
===ChannelNames===
is a convenience parameter. Name channels here and they can be referenced by these names later.
===SourceChOffset===
should be set to a list of "0"s -- one 0 for each channel as indicated by SourceCh, separated by spaces.
===SourceChGain===
should be set to a list of "1"s -- one 0 for each channel as indicated by SourceCh, separated by spaces.
===DeviceIDMaster===
is the serial number identifier of the master g.Nautilus device. This serial can be found on the physical device and is typically in a "'''NB-20XX.XX.XX'''" format. This parameter can also be set to "'''auto'''" if there is only one g.Nautilus device connected to the machine.
===DeviceIDs===
is a list of device serials (typically in "'''NB-20XX.XX.XX'''" format) which corresponds to the devices to record channels from. One of these serials must be specified as the master device in the "DeviceIDMaster" parameter. This parameter can also be set to "'''auto'''" if there is only one g.Nautilus device connected to the machine. 

'''NOTE:''' Device slaving has not been tested. 
===RefChList===
is a list of channels which can act as "Reference" channels for each device. If left blank, no channel will be used as a reference, and the raw signal will be recorded in the output. 

'''NOTE:''' If specifying reference channels, there must be one reference channel per device specified in "DeviceIDs" in the same order. 
===SourceChList===
===FilterEnabled===
===FilterHighPass===
===FilterLowPass===
===FilterModelOrder===
===FilterType===
===NotchEnabled===
===NotchHighPass===
===NotchLowPass===
===NotchModelOrder===
===NotchType===
===SourceBufferSize===
===EnableAccelerationData===
is a toggle button to enable acceleration data and store them in synchronous states AccelerationX1, AcceleratioY1, and AccelerationZ1.

'''NOTE''' To record acceleration data, at least one analog channel must also be recorded. 
===EnableCounterInput===
is a toggle button to enable the counter data and store it in the synchronous state Counter1.

'''NOTE''' To record counter data, at least one analog channel must also be recorded. 
===EnableLinkQuality===
is a toggle button to enable the link quality data and store it in the synchronous state LinkQuality1.

'''NOTE''' To record link quality data, at least one analog channel must also be recorded. 
===EnableBatteryLevel===
is a toggle button to enable the battery level data and store it in the synchronous state Battery1.

'''NOTE''' To record battery level data, at least one analog channel must also be recorded. 
===EnableDigitalInputs===
is a toggle button to enable both digital input ports and store them in synchronous states DigitalInput1 - DigitalInput8.

'''NOTE''' To record digital input, at least one analog channel must also be recorded. 
===EnableValidationIndicator===
is a toggle button to enable validation data and store it in the synchronous state Validation1.

'''NOTE''' To record validation data, at least one analog channel must also be recorded. 

==States==
===Acceleration===
Acceleration is stored in three separate states with the axis labeled, i.e. the acceleration on the x-axis is stored in AccelerationX1.
The g.Nautilus records the acceleration between -6g and 6g. It is then translated into a value between 0 and 65535 with the equation

<math>\lfloor((acceleration + 6) / 12) * 65535\rfloor</math>

Thus if the acceleration was 0 then the state would have the value 32767.

===Counter===
Counter is a value that is constantly increasing in value and then repeats starting at 0. It is stored in Counter1.

===Link Quality===
Link quality is a value between 0 and 100. It is stored in LinkQuality1. When link quality falls bellow 10% the first time, BCI2000 will give a warning.

===Battery Level===
Battery level is a value between 0 and 100. It is stored in Battery1. When battery falls bellow 10%, BCI2000 will give a warning and again when it falls below 5%.

===Digital Input===
Digital input port is on the Base Station. The value is between 0 and 255 and then separated into to a binary number which is then saved in a state with the corresponding number of the bit, i.e. bit 5 is stored in DigitalInput5.

[[File:gNautilusDigitalInput.jpg]]

===Validation Indicator===
Validation indicator is a value of 0 or 1. It is stored in Validation1. If it is 0, then the data may not be valid. If it is 1, the data is valid.

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

[[Category:Data Acquisition]]

File:PersistantFunction.png

2026-02-25T13:57:15Z

Nluczak:

File:PersistantCommand.png

2026-02-25T13:56:14Z

Nluczak:

File:VolatileCommand.png

2026-02-25T13:55:11Z

Nluczak:

Contributions:CortecADC

2026-02-25T13:54:35Z

Nluczak:

[[File:CorTec_BrainInterchange.png|400px|thumb|right|CorTec Brain Interchange Implant]]

CortecADC is a source module that allows for intra-cranial recording and stimulating over 32 channels via a fully implantable device. It is intended for long-term measurement of neural activity and electrical stimulation of brain tissue. See the [https://www.cortec-neuro.com/solutions/complete-system/ CorTec site] for more information.

'''See the [[CortecExperience]] page for user tutorials and a broad overview!''' After viewing the [[CortecExperience]] page, refer to this page for detailed instructions.

==Versioning==

===Authors===
* William Engelhardt (engelhardt@neurotechcenter.org)
* Alexander Belsten (belsten@neurotechcenter.org)
* Markus Adamek (adamek@neurotechcenter.org)
* Christian Stolle (christian.stolle@cortec-neuro.com)

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

===BCI2000 Version History===
{|class="wikitable" style="text-align: center;"
! Date !! Revision !! Note !! Contributor
|-
!11/29/2018
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R5829
|Initial untested version
|Adamek
|-
!04/19/2021
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R6271
|First working version
|Belsten
|-
!07/22/2021
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R6339
|Changed ''ImplantLostSample'' from a BCI2000 state to a stream, so it can record individual sample loss (instead of over the whole block)
|Belsten
|-
!01/01/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7133
|Updated API to version 1.0.200.
|Engelhardt
|-
!03/08/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7251
|Stimulation functionality added
|Engelhardt
|-
!05/19/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7367
|Impedance measurement enabled
|Engelhardt
|-
!10/26/2023
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7679
|Stimulation latency vastly improved
|Engelhardt
|-
!02/20/2024
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7847
|Version 1.0.230 added. Can change between versions in CMakeLists.txt file
|Stolle
|-
!08/09/2024
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R8313
|Version 1.0.238 added
|Stolle
|-
!01/17/2025
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R7679
|Interpolation filter added to interpolate lost samples
|Engelhardt
|-
!06/25/2025
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|R8915
|All listener states were changed to events
|Engelhardt
|-
|}

===Cortec API Version History===
Cortec is continually updating their devices with new API versions. In BCI2000, we currently support versions 1.0.200, 1.0.230, and 1.0.238. Each Brain Interchange Communication unit (BIC) is only compatible with one API version. To find your compatible version, connect the USB drive that comes with your BIC. Look under:
# '''Software folder''': Each executable has the API version. E.g., <code>Bicapi_setup_1.0.200-bicapi-setup-1.0.200-rev35926.exe</code>
# '''Manuals foder''': ''Appendix1_BIC_Application_Software_Short_Manual.pdf''. On page 3, in Table 1, the third row contains the compatible version.

Here are some differences between the versions. As the device is always improving, the newest version will have the most features.

{|class="wikitable" style="text-align: center;"
! Features !! 1.0.200 !! 1.0.230 !! 1.0.238 !! 1.0.260

|-
!Matlab API
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!C/C++ API
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Stimulation modes
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!ASIC Noise Detection Mode
|style="color:red"|✘
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Monopolar stimulation (Ch → GND)
|style="color:red"|✘
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Measure GND impedances
|style="color:red"|✘
|style="color:green"|✔
|style="color:green"|✔
|style="color:green"|✔
|-
!Self-tests
|style="color:red"|✘
|style="color:red"|✘
|style="color:red"|✘
|style="color:green"|✔
|-
!Low noise recording
|style="color:red"|✘
|style="color:red"|✘
|style="color:red"|✘
|style="color:green"|✔
|-
|}

===Known Issues===
* Lost samples - The <code>ImplantLostSamples</code> state records what samples are lost, and their locations. Lost samples are replaced with the previous valid sample for all channels. In offline analysis, be sure to remove these samples and replace them with interpolates.
* The Brain Interchange Communication Unit has been seen to work with certain USB inputs, and not with others. If you are experiencing connection issues, try using a different USB port.

==Installation==
# Install BCI2000
# Insert the Cortec USB drive that comes with the Brain Interchange (BIC) device. Under ''Software'', run the ''Bicapi_setup...'' executable
# Run a batch file with CortecADC as your Signal Source!
# If you receive an error, and it states your API version is incorrect, you need to change it. Locate the ''CMakeLists.txt'' under <code>BCI2000/src/private/SignalSource/Cortec</code>. You must change Line 12, where it states <code>set(BICAPI_VERSION 200)</code>. Change 200 to 230 or 238, depending on your device (see [[#Cortec Version History | details above]]).

==Source Parameters==
These parameters can be found in the "Source" tab of the BCI2000 config window.
[[File:CortecSourceParameters.jpg|600px|thumb|center|upright=2.5|Figure 1. The default source parameters for the CortecADC]]
===SourceCh===
The total number of digitized and stored channels. In the current implementation, this parameter cannot be edited, and will default to how many channels are available from the implant.

===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. This parameter cannot be edited, and will default to the sampling rate available from the implant.
In case you are experiencing problems by higher sampling rates (e.g., data loss, jerky display, etc.), increase the SampleBlockSize so that you are updating the system less frequently (usually, updating the system 20-30 times per second is sufficient for most applications), and increase Visualize->VisualizeSourceDecimation. This parameter will decrease the number of samples per second that are actually drawn in the Source display.

===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. It is strongly recommended to use at least one reference channel.

===AmplificationFactor===
Amplification factor that is applied to the recorded data on the implant. The choices are 39.5, 45.5, 51.5, 57.5 db.

===UseGround===
Enable to use the ground electrode while measuring. This setting can be overwritten during stimulation, depending if the ground electrode is being used or not. For example, if you have enabled this parameter but don't have <code>0</code> in your <code>Destination ch</code> list in the StimulationTriggers parameter, when you are stimulating you will not be using the ground electrode. Once stimulation is done, this parameter's settings are used again.

===SaveInfoFile===
Enable to save a text file, named the same as the data file run. It will contain the timestamp, amplification factor used in the run, and reference channels used. If the Impedance is measured, the impedance values will be saved to this file regardless of if this parameter is enabled.

===LogPacketErrors===
Enable to save the packet loss errors to the System Log. Helpful for debugging, however can get overwhelming if there are a lot of lost samples. The System Log can be programmatically saved by appending <code>--SystemLogFile=SOME_FILE.TXT</code> to the <code>Startup system localhost</code> line in your batch file.

==Stimulation Parameters==
These parameters can be found in the "Stimulation" tab of the BCI2000 config window.
<gallery mode="packed" widths=300px heights=300px>
File:CortecADC_stimulation_parm.PNG
File:CortecADC_stimulationpulses_parm.PNG
File:CortecADC_stimulationtriggers_parm1.PNG
</gallery>

===EnableStimulation===
This parameter enables/disables stimulation.

===StimulationMode===
The BIC has 3 stimulation modes. Each one has limitations. Here is a brief summary of how to use each one:
#Volatile Commands: The most flexible mode. The limitation is that the stimulation configuration is uploaded right before starting the stimulation, which increases the latency of the stimulation. This mode is best used in single pulse stimulation or stimulation burst applications. Can cause issues in longer stimulation trains due to the latency introduced by uploading commands repeatedly.
[[File:VolatileCommand.png|1000px|thumb|center|upright=2.5|Figure 1. Figure demonstrating volatile command functionality]]
#Persistent Command: There can only be one stimulation configuration (one column in StimulationPulses), which includes burst settings. You cannot change the source and destination channels without uploading a new command. This mode is useful for implementing stimulation trains, otherwise similar but less flexible when compared to volatile commands.
[[File:PersistantCommand.png|1000px|thumb|center|upright=2.5|Figure 2. Figure demonstrating Persistant Command functionality]]

#Persistent Functions: This function allows you to preload multiple stimulation configurations allowing for the user to define different source and destination channels. The device executes only one of the stim configrations, and without repetition. This is best used for rapidly iterating over subsets of stimulation pulses in single-pulse stimulation settings.
[[File:PersistantFunction.png|1000px|thumb|center|upright=2.5|Figure 3. Figure demonstrating Persistant Function functionality]]
There cannot be any train settings (Train frequency and Train repetitions), so the StimulationTriggers must not have those rows. Also, StimulationTriggers must not have more than 16 columns, as that is the highest number of configurations that can be stored on the device.

Persistent Command and Functions modes have a lower latency because the stimulation is pre-uploaded. All modes are available to give you the highest amount of flexiblity with the BIC. [[#Stimulation Latency|See below for more details on latency.]]

===MeasureImpedance===
When enabled, the impedances of the used electrodes are printed when you set the configuration. All electrodes that are being recorded will conduct the impedance measurement. The impedances are shown to the user and also saved in the data directory.

===StimulationPulses===
This parameter defines the shape of the charge balanced stimulation pulses, as described in Fig 1. The pulses are defined in one column of this parameter matrix, and it is possible to define an arbitrary number of pulses, each of which are associated with a user defined integer called a ''PulseID''. The rows are labeled and there are some limitations to the magnitudes and durations which are elaborated on in the subsequent section.
[[File:CortecADC_pulse_def.png|600px|thumb|center|upright=2.5|Figure 1. Pulse definition]]
====PulseID====
This must be an integer greater than or equal to zero. This ID will be used in the ''StimulationTriggers'' parameter.

====Pulse Amplitude====
The pulse amplitude defines the amplitude of the main pulse in units of µA. The counter pulse will have a negative amplitude that is one-quarter of the magnitude of the main pulse.

The valid values of this parameter are in the range 0 to 6120 µA. The granularity changes for smaller amplitudes as follows:
* amplitude <= 3060 µA: step size of 12
* amplitude > 3060 µA: step size of 24
This leads to a set of acceptable values that looks like: [0, 12, ..., 3048, 3060, 3084, ... 6096, 6120]
You can define this parameter not to be one of the acceptable values in this range, but it will be rounded to the nearest valid value, and other parameters will be varied to maintain charge balance.

====Pulse Duration====
The pulse duration defines the duration of the main pulse in µs. The counter pulse will have a duration that is four times longer than the main pulse duration. Pulse duration values are set in steps of 10 µs. The acceptable range is between 10 and 2550 µs. Again, if the provided value is not a multiple of 10, it will be rounded to the nearest valid value, and other parameters will be modified to maintain charge balance.

====Dead Zone 0====
Holds the duration of the pause between main and counter pulse in µs. Values can be set in steps of 10 µs. The acceptable range is between 10 and 2550 µs. The same duration dead zone will also occur after the counter pulse.

====Dead Zone 1====
Holds the duration of the pause after the pulse was delivered. Values can be set in steps of 80 µs. The acceptable range goes from 10 to 20400 µs. Note that the steps are starting from 0 while the minimum value is 10 µs. This leads to a set of acceptable values that looks like: [10, 80, 160, 240, ... , 20400] µs.

===StimulationTriggers===
This parameter defines when stimulation is applied, what pulse is used, how many pulses are applied, and the source and destination locations of the stimulation. These parameters are defined in the rows of this matrix with labels
====Trigger====
This must be a [https://www.bci2000.org/mediawiki/index.php/User_Reference:Expression_Syntax BCI2000 expression]. When this expression evaluates true during the run, the stimulation is applied.
====PulseID====
The second row should contain a valid PulseID that is to be used.
====Source Ch====
The third row is an embedded list that defines the source electrodes.
====Destination Ch====
The fourth row is also an embedded list that defines the destination electrodes. Specify <code>0</code> to include the ground electrode as the destination channel.
====Pulse Repetition====
The fifth row defines how many times that pulse is repeated. The max is 255. In between each repeated pulse there is a 10 µs delay.
====Train Frequency (optional)====
The sixth row defines the frequency of the train. This is implemented by determining the amount of downtime after the pulses are done, in a resolution of microseconds. So if your desired frequency produces a desired wait time with a resolution of less than a microsecond, this will be rounded to the nearest microsecond.
====Train Repetition (optional)====
The seventh row defines how many times the entire train is repeated, at the frequency set by the previous row.
[[File:Cotec Stimulation Train.png|1000px|thumb|center|upright=2.5|Figure 1. Stimulation train definition]]

''Note'': If a train is not desired, you can either set Train Frequency and Repetition to 0, or delete those 2 rows.

===Hardware limitations===
{|style="text-align: center;"
! !! Minimum !! Maximum
|-
!Pulse Amplitude (µA)
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|0
|6,120
|-
!Pulse Duration (µs)
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|10
|2,550
|-
!Dead Zone 0 (µs)
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|10
|2,550
|-
!Dead Zone 1 (µs)
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|10
|20,400
|-
!Pulse Repetitions
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|1
|255
|-
!Train Repetitions
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|0
|65,535
|-
!Pulse Frequency (Hz)
|style="border-left: solid 1px grey; border-right: solid 1px grey;"|43.57
|200
|-
!Train Frequency (Hz)
|style="border-left: solid 1px grey; border-right: solid 1px grey;"| ~0.02
|Pulse Frequency
|-
!Compliance Voltage (V)
|style="border-left: solid 1px grey; border-right: solid 1px grey;"| -11
|5
|-
|}

==Device Parameters==

===DeviceInfo===
This parameter cannot be edited and is automatically populated with information returned from the device, such as device type, device ID, and the firmware version.

===StateInfo===
This parameter cannot be edited and is automatically populated with information regarding state units and their multiplier. The device provides information such as humidity, temperature, control value, etc., which are recorded in BCI2000 states (see state information on this page for a complete enumeration of states). The device provides these values with floats, but BCI2000 states can only be integers. The multipliers defined in this parameter are used to increase the amount of precision in the state values. To approximately recover the original float values with the units defined in this parameter, divide each state by its corresponding multiplier.

==States==
The states encode auxiliary information returned from the Cortec implant. The device provides this data in floating point numbers, however BCI2000 can only record integers to it's states. To maintain some precision, these floats are multiplied by constants, then recorded to the states as integers. To approximately recover the original data, divide the state by its corresponding constant. Constants are shown in the following table.
{| class="wikitable" style="text-align:right;"
|- style="font-weight:bold;"
! State
! style="text-align:center;" | Constant
|-
| ImplantVoltage
| style="text-align:center;" | 1000
|-
| ImplantHumidity
| style="text-align:center;" | 100
|-
| ImplantControlValue
| style="text-align:center;" | 100
|-
| ImplantPrimaryCoilCurrent
| style="text-align:center;" | 1000
|-
| ImplantTemperature
| style="text-align:center;" | 100
|}
===ImplantLostSample===
The communication protocol the device uses does not re-send lost data. This state annotates what samples were lost in the bio-signal data. Currently, lost samples are made up by duplicating the previous sample.

===ImplantVoltage===
16 bit state that changes when new supply voltage value is received from the implant. After dividing the integer state value by the the voltage multiplier defined in the StateInfo parameter, the units are in volts.

===ImplantHumidity===
16 bit state that changes when new humidity value is received from the implant. Units in %rh.

===ImplantControlValue===
16 bit state that changes when new current control value is received from the external unit. The power of the implant is controlled by the external unit. The control value provides a measure of how good the coupling between the two coils is and how much more power can be provided if necessary.
The value is between 0.0 and 100.0 percent, where 0.0 translates to no power and 100.0 translates to maximum power applied.

===ImplantPrimaryCoilCurrent===
16 bit state that change when new primary coil current value is received from the external unit. The primary coil refers to the coil inside the head piece of the external unit. Units are mA.

===ImplantTemperature===
16 bit state that changes when new temperature value is received from the implant. Units are degrees Celsius.

===ImplantStimulation===
Binary state that changes when the device reports that it is stimulating.

===ImplantStimulationBursts===
Updates when the device reports that stimulation functions have finished. Should increment during a stimulation train.

===ImplantRfQuality===
8 bit state that reports the antenna quality as reported from the rf-link in dBm. '''''To obtain the original value, subtract by 128 (2^8)'''''.

===RequestedStimulation===
Binary state that records when a stimulation trigger expression evaluates true. State remains true for the duration triggered stimulation. This is useful for determining the latency between when stimulation is requested and when it is actually applied. This is done by computing the difference in time between the rising edges of ''ImplantStimulation'' and ''RequestedStimulation'' states.

==[[User_Reference:StimulationConfigurationIntegrativeTool_(SCIT)|SCIT]]==
To help out with creating the BCI2000 parameters, a GUI has been made which should make it easy to translate your stimulation specifications into BCI2000 parameter files. The GUI also visualizes the stimulation from three different perspectives, making it easy to tell if your parameters are really what you want. There is a [[User_Reference:StimulationConfigurationIntegrativeTool_(SCIT)|Stimulation Configuration tool user reference]] which will further tell you how to use this tool.

<gallery mode="packed" widths=500px heights=500px>
File:CortecGUIimg.png|The Cortec GUI which creates BCI2000 parameters from stimulation specifications.
</gallery>

==Stimulation Latency==
<gallery mode="packed" widths=500px heights=500px>
File:StimulationModesLatencyCortec.png|Stimulation Latencies for the specified Stimulation Modes.
</gallery>
Tests were conducted for 100 pulses, with an ISI of 10 seconds.

Stimulation latency numbers:
*Persistent functions: '''13 ± 1 ms'''
*Persistent commands: '''11 ± 1 ms'''
*Volatile commands: '''60 ± 30 ms'''. Split into the 2 groups, the lower one is '''48 ± 3 ms''' and the higher one is '''174 ± 3 ms'''

As explained above, volatile commands are uploaded right before stimulation, which leads to the increased latency and jitter.
==µZeus==
In order to use the new µZeus headpiece simply change the BICVERSION number on line 12 of the CMakeList.txt located in the project folder to use version 274 of the API. ie.,

<code>set(BICAPI_VERSION 274)</code>

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

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

Contributions:RippleADC

2025-12-20T00:33:38Z

Nluczak:

[[File:RippleDeviceImage.webp|400px|thumb|right|Ripple Neural Interface Processor]]

RippleADC is a source module that allows for neural recording and stimulation using Ripple's Grapevine Neural Interface Processor. It supports high-channel-count recording and precise electrical stimulation capabilities. See the [https://rippleneuro.com/ Ripple site] for more information.

==[https://scribehow.com/page/Using_a_Ripple_device_with_BCI2000__fqrBfPskSSGBQPLttTlx2A Detailed installation instructions]==

==Versioning==

===Authors===
* Nicholas Luczak (luczak@neurotechcenter org)

* Luciano Branco (lrfbranco@gmail com)

===Version History===
* 04/29/2025 - Initial version
* 06/10/2025 - Added stimulation support
* 11/15/2025 - Added Luciano's Tool, added new important states, and improved Stimulation matrix configuration

===Source Code Revisions===
* Initial development: 8600
* Tested under: 9072
* Known to compile under: 9072
* Broken since: --
==Dependencies==
Other than BCI2000, all you should need is the [https://rippleneuro.com/trellis-eeg-software/ Trellis software that comes with your Ripple device]
==Source Parameters==
These parameters can be found in the "Source" tab of the BCI2000 config window.
[[File:Ripple_Source_Parameters.png|600px|thumb|center|upright=2.5|Figure 1. The default source parameters for the RippleADC]]

===SourceCh===
The total number of digitized and stored channels. This can be set manually or left as "auto" to detect all available 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.

===SamplingRate===
The sample rate of the system. Supported rates are:
* 30,000 Hz (RAW)
* 15,000 Hz (HiFreq)
* 2,000 Hz (HiRes/EMG)
* 1,000 Hz (LFP)

===SourceChOffset===
Offset for each channel in raw A/D units.

===SourceChGain===
Gain for each channel in physical units per raw A/D unit (typically µV).

===ChannelNames===
Names of each channel in the format "FrontendName_ChannelNumber".

===SourceChList===
List of channels to actually transmit (subset of available channels).

==Stimulation Parameters==
These parameters can be found in the "Stimulation" tab and in both the BCI2000 config window and the Ripple Stimulation Tool. Parameters are checked and will throw a warning if they exceed device's safety limits or capabilities in both BCI2000 and the Ripple Stimulation Tool.
[[File:RippleStimulationParameters.png|600px|thumb|center|upright=2.5|Figure 2. Stimulation parameters for the RippleADC]]

===StimEnable===
Enable/disable stimulation functionality (0 or 1).

===Step Size===

This parameter defines the amplitude resolution of the stimulator in µA.
It indicates the granularity with which the stimulation amplitude may be adjusted. The allowed values depend on the hardware and are typically fixed by the front-end.

===Frequency===

This parameter defines the frequency of stimulation pulses in Hz.
It specifies how many biphasic pulses occur per second during stimulation. Controls the pulse rate within a stimulation train. Higher frequencies produce temporally denser stimulation.
Unit: Hz

===Amplitude===

This parameter defines the stimulation amplitude in mA.
It sets the magnitude of the delivered current for each pulse in the stimulation train. Primary determinant of stimulation intensity.
Unit: mA
===Duration===

This parameter defines the total duration of the stimulation train in seconds.
It specifies how long stimulation continues once triggered.
Unit: s

===Burst Length===

This parameter defines the length of each stimulation burst in seconds.
If burst-mode stimulation is used, pulses are grouped into bursts separated by silent periods.

Unit: s
Significance: Controls how long each burst remains active before an interburst pause occurs.

===Interburst Length===

This parameter defines the silent interval between bursts in milliseconds. Sets the recovery or idle period between active bursts; used to generate patterned or duty-cycled stimulation.

Unit: ms

===Pulse Width===

This parameter defines the width of each stimulation phase in microseconds (µs).
It corresponds to the duration of the main pulse phase. Affects charge delivery per pulse.
Unit: µs

===Interpulse Width===

This parameter defines the interval of time between pulses in microseconds. Controls how tightly pulses are packed in time; together with Pulse Width and Frequency, shapes the temporal profile of stimulation.
Unit: µs
===Gap Until Next===

This parameter defines the delay between this stimulation block and the next block in seconds.
Unit: s
Significance: Used in multi-step or sequential stimulation programs to introduce timing gaps before the next configured stimulation event.

===StimulationTriggers===
This parameter defines when stimulation is applied, what pulse is used, how many pulses are applied, and the source and destination locations of the stimulation. These parameters are defined in the rows of this matrix with labels
====Triggers====
This must be a [https://www.bci2000.org/mediawiki/index.php/User_Reference:Expression_Syntax BCI2000 expression]. When this expression evaluates true during the run, the stimulation is applied.

==Device Parameters==

===DeviceInfo===
This parameter cannot be edited and is automatically populated with information returned from the device, including:
* Processor type
* Firmware version
* Network address
* Available front ends

===ConnectionSettings===
Advanced TCP/IP connection settings for the Grapevine processor.

==States==
The states encode auxiliary information about the system status and stimulation events.

===Timestamp===
16-bit state containing the processor timestamp for each sample block.

===StimulusCode===
16-bit state that records the amplitude of active stimulation.

===StimulusType===
16-bit state that indicates stimulation status.

===ConnectionStatus===
8-bit state reporting the network connection quality.

==Technical Details==

===Supported Front Ends===
{| class="wikitable"
! Front End Type !! Channels !! Supported Sampling Rates
|-
| Stimulation || 32 || HiRes (2kHz), HiFreq (15kHz)
|-
| Raw || 32 || LFP (1kHz), HiRes (2kHz), Raw (30kHz)
|}

===Stimulation Waveforms===
Pulse parameters are converted to Ripple's stimulation command format as described in XippStimCmd.h.

[[File:RippleStimulationWaveform.png|800px|thumb|center|Figure 3. Example monophasic stimulation waveform]]

===Network Protocol===
The module uses Ripple's xipplib library to communicate with the Grapevine processor over TCP/IP. All data is transmitted in real-time with timestamps for synchronization.

==Stimulation How-to==
We have implemented and are distributing two different methods of stimulation through the Ripple device. One is a native implementation within BCI2000. The more capable method of driving stimulation is through a tool made using Matlab. This tool was created by Luciano Branco at the Mayo Clinic. This tool is distributed with BCI2000 and should be accessible through our SVN under src/contrib/SignalSource/RippleADC/cnel_stim. The tool allows you to create a wide range of stimulation configurations while visualising it and driving the stimulation in tandem with BCI2000 so that all of the relevant information is recorded.
===Native BCI2000===
In order to use stimulation through BCI2000, you simply need to go into the configuration window after launching a batch file with the RippleADC as your source. There, all you need to do is go to the Source tab, then scroll down until you see the stimulation section, then click the checkbox to enable stimulation and configure your stimulation parameters. These stimulation parameters will allow you to specify step size, frequency, amplitude, duration, burst length, interburst length, pulse width, interpulse width, and the gap until the next stimulation (if you're setting things up for multiple blocks of stimulation). The final relevant parameter is the StimulationTriggers parameter which allows you to define a trigger for your different configured stimulation patterns. For example, one could use a state such as stimulusCode to trigger stimulation based on when a stimulus is presented, or one could use some signal as a threshold for stimulation.
A step by step tutorial with screenshots can be found here:
[https://scribehow.com/viewer/Macro_Raw__DSjk-3QJRxe7EQVS8cSx4A Stimulation instructions]
===Matlab GUI tool===
This tool, developed by Luciano Branco at the Mayo Clinic is a much more advanced tool for driving stimulation which allows you to inspect your stimulation trains visually and also drive stimulation. The parameters for stimulation are identical to those within BCI2000

[[File:RippleStimulationParameters.png|800px|thumb|center|Image of settings possible to configure Ripple cnelStim tool]]

After configuring your various stimulation configurations you can inspect each train of stimulations.
[[File:RippleStimulationWaveform.png|800px|thumb|center|Image of example monophasic waveform]]

Once you are happy with your different waveforms and have confirmed that they are appropriate you can proceed to the Control Panel which allows you to define if you want to do bipolar stimulation, whether you want to drive stimulation from the cathode first, and other extra features. Once you are happy with the configuration and you have BCI2000 running you're ready to start stimulation. You can either drive the cnelStim tool by simply clicking the "Start Stimulation" button, or you can configure it to drive stimulation using a BCI2000 state which is pulled from BCI2000 using BCI2000Remote.
[[File:RippleControlPanel.png|800px|thumb|center|Image of example monophasic waveform]]

====Ripple GUI Configuration Files====
In order to easily configure and save complex stimulation parameters within the Matlab GUI tool, a CSV can be used to save and load desired stimulation parameters. You can find different example files [https://wustl.box.com/s/hl25jzr4ay5chhfmsw3g8ud219jn8m1l here.]
[[File:RippleCSV.png|800px|thumb|center|Image of an example CSV file for monophasic stimulation]]
==See also==
[[User Reference:Filters]], [[Contributions:ADCs]]
[[Category:Contributions]][[Category:Data Acquisition]]

Contributions:RipplePyADC

2025-12-19T19:57:39Z

Nluczak:

[[Image:RippleDeviceImage.webp|thumb|Example Ripple set-up|450px]]
= '''THIS IS OUT OF DATE, PLEASE USE THIS '''[[Contributions:RippleADC|C++ IMPLEMENTATION]]''' =
==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. Xipppy is provided by Ripple, please contact them to obtain the API. 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]]

File:Make-done-RPI.png

2025-12-19T16:44:26Z

Nluczak:

RaspberryPi

2025-12-19T16:19:12Z

Nluczak:

= Raspberry Pi (Linux) Build Dependencies (BCI2000 GUI build) =

This section documents system packages needed to compile BCI2000 on a Raspberry Pi with GUI components enabled (e.g., ''OperatorQt'', ''StimulusPresentation'', ''BCI2000Viewer'').
== Raspberry Pi Performance ==
These instructions were created using a Raspberry Pi 3 model B running Debian GNU/Linux 13 (trixie).
While Running the signal generator, DummySignalProcessing, and Stimulus Presentation we observed a power draw of between 2.2 and 4.2 Watts.
== Dependencies observed during build troubleshooting ==

During compilation, missing headers/libraries were resolved by installing the following packages:

'''libdrm-dev''' — Direct Rendering Manager development files (graphics stack)

'''libxcb-dev''' / '''libxcb1-dev''' — XCB (X11) client library development files

'''libxcb-cursor-dev''' — XCB cursor support (required by Qt/X11)

== Recommended minimal install command (GUI build) ==

The following is a practical minimal set for a Raspberry Pi OS / Debian-like system when building BCI2000 with Qt GUI components:

<syntaxhighlight lang="bash">sudo apt update && sudo apt install -y \
build-essential \
cmake \
qtbase5-dev \
qt5-qmake \
qtbase5-dev-tools \
libdrm-dev \
libxcb1-dev \
libxcb-dev \
libxcb-cursor-dev \
libx11-dev \
libxext-dev \
libxrender-dev \
libxi-dev \
libxrandr-dev
</syntaxhighlight>

Notes:

Qt on Linux typically depends on X11/XCB libraries, so missing XCB/DRM packages commonly block Qt GUI builds.

If you are doing a headless build (no GUI), you may be able to omit Qt and X11/XCB packages.

== Verify GUI dependency availability ==

To confirm the GUI-related packages are installed:

<syntaxhighlight lang="bash"> dpkg -l | egrep "libdrm-dev|libxcb|qtbase5-dev|cmake" </syntaxhighlight>

= Running the CMake GUI on Raspberry Pi (cmake-gui) =

The CMake GUI executable is '''cmake-gui''', provided by Debian’s '''cmake-qt-gui''' package.
Debian Packages
+1

== 1) Install the CMake GUI package ==

On Raspberry Pi OS / Debian Bookworm-like systems:

<syntaxhighlight lang="bash"> sudo apt update && sudo apt install -y cmake-qt-gui </syntaxhighlight>

This installs the '''cmake-gui''' executable.
Debian Packages
+1

== 2) Run cmake-gui on the Pi desktop ==

If your Pi is running a desktop environment and you are logged in locally:

<syntaxhighlight lang="bash"> cmake-gui </syntaxhighlight>

If launched from a terminal within the Pi desktop, it should open normally.

==Configure BCI2000 for Compilation==

===Run the CMake GUI===
Double-click "Configure.sh.cmd" in your BCI2000 build directory.

[[File:Cmake-init-RPI.png|700px]]

===Tell CMake which Qt installation to use===
Click "AddEntry" in the CMake window (Note that checking off "Advanced" in CMake is optional and does not impact compilation) and enter the path to a Qt directory.

Use CMAKE_PREFIX_PATH as the name for the new entry. Be aware that the entry's name is case sensitive.

[[File:Cmake-add-cache-RPI.png|700px]]

===Configuration===
In the CMake window, click "Configure" and choose a generator that is consistent with your compiler. This tutorial will be using Unix Makefiles.

Then click "Done" to perform the configuration step.

[[File:Cmake-generators-RPI.png|700px]]

You will see a list of targets scrolling by, and a number of new entries in the variable list at the top of the window, marked in red.

===Choose Build Options===
Make sure the "Grouped" checkbox is checked, and configure the build by customizing values in the "BUILD" group, "EXTENSIONS" group, and "USE" group.

[[File:Cmake-done-RPI.png|700px]]

===Generate Makefiles===
Then, click "Generate" to create build files. When CMake displays its "Generating done" message, your BCI2000 build directory will now contain a Makefile (or a project file for your compiler of choice), as well as a number of additional CMake-generated files.

[[File:Cmake-configured-RPI.png|700px]]

==Compile BCI2000==
===Open Terminal===
Open a new terminal window and navigate to your BCI2000 build directory.

[[File:terminal-bulid-directory-RPI.png|700px]]

===Build Executables===
Run:
make -j4
from your BCI2000 build directory. Once this is finished your BCI2000 prog directory will contain a number of executables, one for each module, plus a few helper executables. Not everything works the same or, in some cases, at all on non-windows platforms. See [[Non-Windows Functionality]] for more information.

[[File:Make-done-RPI.png|700px]]

The build process is now complete. Run
make -j4
again to recompile. Or
make <target>
to recompile only a specific target.

[[Category:Howto]]

RaspberryPi

2025-12-19T16:13:29Z

Nluczak:

= Raspberry Pi (Linux) Build Dependencies (BCI2000 GUI build) =

This section documents system packages needed to compile BCI2000 on a Raspberry Pi with GUI components enabled (e.g., ''OperatorQt'', ''StimulusPresentation'', ''BCI2000Viewer'').
== Raspberry Pi Performance ==
While Running the signal generator, DummySignalProcessing, and Stimulus Presentation we observed a power draw of between 2.2 and 4.2 Watts.
== Dependencies observed during build troubleshooting ==

During compilation, missing headers/libraries were resolved by installing the following packages:

'''libdrm-dev''' — Direct Rendering Manager development files (graphics stack)

'''libxcb-dev''' / '''libxcb1-dev''' — XCB (X11) client library development files

'''libxcb-cursor-dev''' — XCB cursor support (required by Qt/X11)

== Recommended minimal install command (GUI build) ==

The following is a practical minimal set for a Raspberry Pi OS / Debian-like system when building BCI2000 with Qt GUI components:

<syntaxhighlight lang="bash"> sudo apt update sudo apt install -y \ build-essential \ cmake \ qtbase5-dev \ qt5-qmake \ qtbase5-dev-tools \ libdrm-dev \ libxcb1-dev \ libxcb-dev \ libxcb-cursor-dev \ libx11-dev \ libxext-dev \ libxrender-dev \ libxi-dev \ libxrandr-dev </syntaxhighlight>

Notes:

Qt on Linux typically depends on X11/XCB libraries, so missing XCB/DRM packages commonly block Qt GUI builds.

If you are doing a headless build (no GUI), you may be able to omit Qt and X11/XCB packages.

== Verify GUI dependency availability ==

To confirm the GUI-related packages are installed:

<syntaxhighlight lang="bash"> dpkg -l | egrep "libdrm-dev|libxcb|qtbase5-dev|cmake" </syntaxhighlight>

= Running the CMake GUI on Raspberry Pi (cmake-gui) =

The CMake GUI executable is '''cmake-gui''', provided by Debian’s '''cmake-qt-gui''' package.
Debian Packages
+1

== 1) Install the CMake GUI package ==

On Raspberry Pi OS / Debian Bookworm-like systems:

<syntaxhighlight lang="bash"> sudo apt update && sudo apt install -y cmake-qt-gui </syntaxhighlight>

This installs the '''cmake-gui''' executable.
Debian Packages
+1

== 2) Run cmake-gui on the Pi desktop ==

If your Pi is running a desktop environment and you are logged in locally:

<syntaxhighlight lang="bash"> cmake-gui </syntaxhighlight>

If launched from a terminal within the Pi desktop, it should open normally.

==Configure BCI2000 for Compilation==

===Run the CMake GUI===
Double-click "Configure.sh.cmd" in your BCI2000 build directory.

[[File:Cmake-init-RPI.png|700px]]

===Tell CMake which Qt installation to use===
Click "AddEntry" in the CMake window (Note that checking off "Advanced" in CMake is optional and does not impact compilation) and enter the path to a Qt directory.

Use CMAKE_PREFIX_PATH as the name for the new entry. Be aware that the entry's name is case sensitive.

[[File:Cmake-add-cache-RPI.png|700px]]

===Configuration===
In the CMake window, click "Configure" and choose a generator that is consistent with your compiler. This tutorial will be using Unix Makefiles.

Then click "Done" to perform the configuration step.

[[File:Cmake-generators-RPI.png|700px]]

You will see a list of targets scrolling by, and a number of new entries in the variable list at the top of the window, marked in red.

===Choose Build Options===
Make sure the "Grouped" checkbox is checked, and configure the build by customizing values in the "BUILD" group, "EXTENSIONS" group, and "USE" group.

[[File:Cmake-done-RPI.png|700px]]

===Generate Makefiles===
Then, click "Generate" to create build files. When CMake displays its "Generating done" message, your BCI2000 build directory will now contain a Makefile (or a project file for your compiler of choice), as well as a number of additional CMake-generated files.

[[File:Cmake-configured-RPI.png|700px]]

==Compile BCI2000==
===Open Terminal===
Open a new terminal window and navigate to your BCI2000 build directory.

[[File:terminal-bulid-directory-RPI.png|700px]]

===Build Executables===
Run:
make -j4
from your BCI2000 build directory. Once this is finished your BCI2000 prog directory will contain a number of executables, one for each module, plus a few helper executables. Not everything works the same or, in some cases, at all on non-windows platforms. See [[Non-Windows Functionality]] for more information.

[[File:Make-done-RPI.png|700px]]

The build process is now complete. Run
make -j4
again to recompile. Or
make <target>
to recompile only a specific target.

[[Category:Howto]]

File:Terminal-bulid-directory-RPI.png

2025-12-19T15:50:19Z

Nluczak:

RaspberryPi

2025-12-19T15:49:53Z

Nluczak:

= Raspberry Pi (Linux) Build Dependencies (BCI2000 GUI build) =

This section documents system packages needed to compile BCI2000 on a Raspberry Pi with GUI components enabled (e.g., ''OperatorQt'', ''StimulusPresentation'', ''BCI2000Viewer'').

== Dependencies observed during build troubleshooting ==

During compilation, missing headers/libraries were resolved by installing the following packages:

'''libdrm-dev''' — Direct Rendering Manager development files (graphics stack)

'''libxcb-dev''' / '''libxcb1-dev''' — XCB (X11) client library development files

'''libxcb-cursor-dev''' — XCB cursor support (required by Qt/X11)

== Recommended minimal install command (GUI build) ==

The following is a practical minimal set for a Raspberry Pi OS / Debian-like system when building BCI2000 with Qt GUI components:

<syntaxhighlight lang="bash"> sudo apt update sudo apt install -y \ build-essential \ cmake \ qtbase5-dev \ qt5-qmake \ qtbase5-dev-tools \ libdrm-dev \ libxcb1-dev \ libxcb-dev \ libxcb-cursor-dev \ libx11-dev \ libxext-dev \ libxrender-dev \ libxi-dev \ libxrandr-dev </syntaxhighlight>

Notes:

Qt on Linux typically depends on X11/XCB libraries, so missing XCB/DRM packages commonly block Qt GUI builds.

If you are doing a headless build (no GUI), you may be able to omit Qt and X11/XCB packages.

== Verify GUI dependency availability ==

To confirm the GUI-related packages are installed:

<syntaxhighlight lang="bash"> dpkg -l | egrep "libdrm-dev|libxcb|qtbase5-dev|cmake" </syntaxhighlight>

= Running the CMake GUI on Raspberry Pi (cmake-gui) =

The CMake GUI executable is '''cmake-gui''', provided by Debian’s '''cmake-qt-gui''' package.
Debian Packages
+1

== 1) Install the CMake GUI package ==

On Raspberry Pi OS / Debian Bookworm-like systems:

<syntaxhighlight lang="bash"> sudo apt update sudo apt install -y cmake-qt-gui </syntaxhighlight>

This installs the '''cmake-gui''' executable.
Debian Packages
+1

== 2) Run cmake-gui on the Pi desktop ==

If your Pi is running a desktop environment and you are logged in locally:

<syntaxhighlight lang="bash"> cmake-gui </syntaxhighlight>

If launched from a terminal within the Pi desktop, it should open normally.

==Configure BCI2000 for Compilation==

===Run the CMake GUI===
Double-click "Configure.sh.cmd" in your BCI2000 build directory.

[[File:Cmake-init-RPI.png|700px]]

===Tell CMake which Qt installation to use===
Click "AddEntry" in the CMake window (Note that checking off "Advanced" in CMake is optional and does not impact compilation) and enter the path to a Qt directory.

Use CMAKE_PREFIX_PATH as the name for the new entry. Be aware that the entry's name is case sensitive.

[[File:Cmake-add-cache-RPI.png|700px]]

===Configuration===
In the CMake window, click "Configure" and choose a generator that is consistent with your compiler. This tutorial will be using Unix Makefiles.

Then click "Done" to perform the configuration step.

[[File:Cmake-generators-RPI.png|700px]]

You will see a list of targets scrolling by, and a number of new entries in the variable list at the top of the window, marked in red.

===Choose Build Options===
Make sure the "Grouped" checkbox is checked, and configure the build by customizing values in the "BUILD" group, "EXTENSIONS" group, and "USE" group.
[[File:Cmake-done-RPI.png|700px]]

===Generate Makefiles===
Then, click "Generate" to create build files. When CMake displays its "Generating done" message, your BCI2000 build directory will now contain a Makefile (or a project file for your compiler of chioce), as well as a number of additional CMake-generated files.

[[File:Cmake-configured-RPI.png|700px]]

==Compile BCI2000==
===Open Terminal===
Open a new terminal window and navigate to your BCI2000 build directory.

[[File:terminal-bulid-directory-RPI.png|700px]]

===Build Executables===
Run:
make -j
from your BCI2000 build directory. Once this is finished your BCI2000 prog directory will contain a number of executables, one for each module, plus a few helper executables. Not everything works the same or, in some cases, at all on non-windows platforms. See [[Non-Windows Functionality]] for more information.

[[File:Make-done-RPI.png|700px]]

The build process is now complete. Run
make -j
again to recompile. Or
make <target>
to recompile only a specific target.

[[Category:Howto]]

File:Cmake-done-RPI.png

2025-12-19T15:48:50Z

Nluczak:

File:Cmake-configured-RPI.png

2025-12-19T15:48:13Z

Nluczak:

File:Cmake-generators-RPI.png

2025-12-19T15:47:46Z

Nluczak:

File:Cmake-add-cache-RPI.png

2025-12-19T15:47:20Z

Nluczak:

File:Cmake-init-RPI.png

2025-12-19T15:46:46Z

Nluczak:

RaspberryPi

2025-12-19T15:46:12Z

Nluczak:

= Raspberry Pi (Linux) Build Dependencies (BCI2000 GUI build) =

This section documents system packages needed to compile BCI2000 on a Raspberry Pi with GUI components enabled (e.g., ''OperatorQt'', ''StimulusPresentation'', ''BCI2000Viewer'').

== Dependencies observed during build troubleshooting ==

During compilation, missing headers/libraries were resolved by installing the following packages:

'''libdrm-dev''' — Direct Rendering Manager development files (graphics stack)

'''libxcb-dev''' / '''libxcb1-dev''' — XCB (X11) client library development files

'''libxcb-cursor-dev''' — XCB cursor support (required by Qt/X11)

== Recommended minimal install command (GUI build) ==

The following is a practical minimal set for a Raspberry Pi OS / Debian-like system when building BCI2000 with Qt GUI components:

<syntaxhighlight lang="bash"> sudo apt update sudo apt install -y \ build-essential \ cmake \ qtbase5-dev \ qt5-qmake \ qtbase5-dev-tools \ libdrm-dev \ libxcb1-dev \ libxcb-dev \ libxcb-cursor-dev \ libx11-dev \ libxext-dev \ libxrender-dev \ libxi-dev \ libxrandr-dev </syntaxhighlight>

Notes:

Qt on Linux typically depends on X11/XCB libraries, so missing XCB/DRM packages commonly block Qt GUI builds.

If you are doing a headless build (no GUI), you may be able to omit Qt and X11/XCB packages.

== Verify GUI dependency availability ==

To confirm the GUI-related packages are installed:

<syntaxhighlight lang="bash"> dpkg -l | egrep "libdrm-dev|libxcb|qtbase5-dev|cmake" </syntaxhighlight>

= Running the CMake GUI on Raspberry Pi (cmake-gui) =

The CMake GUI executable is '''cmake-gui''', provided by Debian’s '''cmake-qt-gui''' package.
Debian Packages
+1

== 1) Install the CMake GUI package ==

On Raspberry Pi OS / Debian Bookworm-like systems:

<syntaxhighlight lang="bash"> sudo apt update sudo apt install -y cmake-qt-gui </syntaxhighlight>

This installs the '''cmake-gui''' executable.
Debian Packages
+1

== 2) Run cmake-gui on the Pi desktop ==

If your Pi is running a desktop environment and you are logged in locally:

<syntaxhighlight lang="bash"> cmake-gui </syntaxhighlight>

If launched from a terminal within the Pi desktop, it should open normally.

==Configure BCI2000 for Compilation==

===Run the CMake GUI===
Double-click "Configure.sh.cmd" in your BCI2000 build directory.

[[File:Cmake-init-RPI.png|700px]]

===Tell CMake which Qt installation to use===
Click "AddEntry" in the CMake window (Note that checking off "Advanced" in CMake is optional and does not impact compilation) and enter the path to a Qt directory.

Use CMAKE_PREFIX_PATH as the name for the new entry. Be aware that the entry's name is case sensitive.

[[File:Cmake-add-cache-RPI.png|700px]]

===Configuration===
In the CMake window, click "Configure" and choose a generator that is consistent with your compiler. This tutorial will be using Unix Makefiles.

Then click "Done" to perform the configuration step.

[[File:Cmake-generators-RPI.png|700px]]

You will see a list of targets scrolling by, and a number of new entries in the variable list at the top of the window, marked in red.

===Choose Build Options===
Make sure the "Grouped" checkbox is checked, and configure the build by customizing values in the "BUILD" group, "EXTENSIONS" group, and "USE" group.
[[File:Cmake-configured-RPI.png|700px]]

===Generate Makefiles===
Then, click "Generate" to create build files. When CMake displays its "Generating done" message, your BCI2000 build directory will now contain a Makefile (or a project file for your compiler of chioce), as well as a number of additional CMake-generated files.

[[File:Cmake-done-RPI.png|700px]]

==Compile BCI2000==
===Open Terminal===
Open a new terminal window and navigate to your BCI2000 build directory.

[[File:terminal-bulid-directory-RPI.png|700px]]

===Build Executables===
Run:
make -j
from your BCI2000 build directory. Once this is finished your BCI2000 prog directory will contain a number of executables, one for each module, plus a few helper executables. Not everything works the same or, in some cases, at all on non-windows platforms. See [[Non-Windows Functionality]] for more information.

[[File:Make-done-RPI.png|700px]]

The build process is now complete. Run
make -j
again to recompile. Or
make <target>
to recompile only a specific target.

[[Category:Howto]]

RaspberryPi

2025-12-18T21:59:25Z

Nluczak:

= Raspberry Pi (Linux) Build Dependencies (BCI2000 GUI build) =

This section documents system packages needed to compile BCI2000 on a Raspberry Pi with GUI components enabled (e.g., ''OperatorQt'', ''StimulusPresentation'', ''BCI2000Viewer'').

== Dependencies observed during build troubleshooting ==

During compilation, missing headers/libraries were resolved by installing the following packages:

'''libdrm-dev''' — Direct Rendering Manager development files (graphics stack)

'''libxcb-dev''' / '''libxcb1-dev''' — XCB (X11) client library development files

'''libxcb-cursor-dev''' — XCB cursor support (required by Qt/X11)

== Recommended minimal install command (GUI build) ==

The following is a practical minimal set for a Raspberry Pi OS / Debian-like system when building BCI2000 with Qt GUI components:

<syntaxhighlight lang="bash"> sudo apt update sudo apt install -y \ build-essential \ cmake \ qtbase5-dev \ qt5-qmake \ qtbase5-dev-tools \ libdrm-dev \ libxcb1-dev \ libxcb-dev \ libxcb-cursor-dev \ libx11-dev \ libxext-dev \ libxrender-dev \ libxi-dev \ libxrandr-dev </syntaxhighlight>

Notes:

Qt on Linux typically depends on X11/XCB libraries, so missing XCB/DRM packages commonly block Qt GUI builds.

If you are doing a headless build (no GUI), you may be able to omit Qt and X11/XCB packages.

== Verify GUI dependency availability ==

To confirm the GUI-related packages are installed:

<syntaxhighlight lang="bash"> dpkg -l | egrep "libdrm-dev|libxcb|qtbase5-dev|cmake" </syntaxhighlight>

= Running the CMake GUI on Raspberry Pi (cmake-gui) =

The CMake GUI executable is '''cmake-gui''', provided by Debian’s '''cmake-qt-gui''' package.
Debian Packages
+1

== 1) Install the CMake GUI package ==

On Raspberry Pi OS / Debian Bookworm-like systems:

<syntaxhighlight lang="bash"> sudo apt update sudo apt install -y cmake-qt-gui </syntaxhighlight>

This installs the '''cmake-gui''' executable.
Debian Packages
+1

== 2) Run cmake-gui on the Pi desktop (local monitor) ==

If your Pi is running a desktop environment and you are logged in locally:

<syntaxhighlight lang="bash"> cmake-gui </syntaxhighlight>

If launched from a terminal within the Pi desktop, it should open normally.

==Configure BCI2000 for Compilation==

===Run the CMake GUI===
Double-click "Configure.sh.cmd" in your BCI2000 build directory.

[[File:Cmake-init-non-windows.png|700px]]

===Tell CMake which Qt installation to use===
Click "AddEntry" in the CMake window (Note that checking off "Advanced" in CMake is optional and does not impact compilation) and enter the path to a Qt directory.

Use CMAKE_PREFIX_PATH as the name for the new entry. Be aware that the entry's name is case sensitive.

[[File:Cmake-add-cache-non-windows.png|700px]]

===Configuration===
In the CMake window, click "Configure" and choose a generator that is consistent with your compiler. This tutorial will be using Unix Makefiles.

Then click "Done" to perform the configuration step.

[[File:Cmake-generators-non-windows.png|700px]]

You will see a list of targets scrolling by, and a number of new entries in the variable list at the top of the window, marked in red.

===Choose Build Options===
Make sure the "Grouped" checkbox is checked, and configure the build by customizing values in the "BUILD" group, "EXTENSIONS" group, and "USE" group.
[[File:Cmake-configured-non-windows.png|700px]]

===Generate Makefiles===
Then, click "Generate" to create build files. When CMake displays its "Generating done" message, your BCI2000 build directory will now contain a Makefile (or a project file for your compiler of chioce), as well as a number of additional CMake-generated files.

[[File:Cmake-done-non-windows.png|700px]]

==Compile BCI2000==
===Open Terminal===
Open a new terminal window and navigate to your BCI2000 build directory.

[[File:terminal-bulid-directory-non-windows.png|700px]]

===Build Executables===
Run:
make -j
from your BCI2000 build directory. Once this is finished your BCI2000 prog directory will contain a number of executables, one for each module, plus a few helper executables. Not everything works the same or, in some cases, at all on non-windows platforms. See [[Non-Windows Functionality]] for more information.

[[File:Make-done-non-windows.png|700px]]

The build process is now complete. Run
make -j
again to recompile. Or
make <target>
to recompile only a specific target.

[[Category:Howto]]

RaspberryPi

2025-12-18T21:58:08Z

Nluczak:

= Raspberry Pi (Linux) Build Dependencies (BCI2000 GUI build) =

This section documents system packages needed to compile BCI2000 on a Raspberry Pi with GUI components enabled (e.g., ''OperatorQt'', ''StimulusPresentation'', ''BCI2000Viewer'').

== Dependencies observed during build troubleshooting ==

During compilation, missing headers/libraries were resolved by installing the following packages:

'''libdrm-dev''' — Direct Rendering Manager development files (graphics stack)

'''libxcb-dev''' / '''libxcb1-dev''' — XCB (X11) client library development files

'''libxcb-cursor-dev''' — XCB cursor support (required by Qt/X11)

== Recommended minimal install command (GUI build) ==

The following is a practical minimal set for a Raspberry Pi OS / Debian-like system when building BCI2000 with Qt GUI components:

<syntaxhighlight lang="bash"> sudo apt update sudo apt install -y \ build-essential \ cmake \ qtbase5-dev \ qt5-qmake \ qtbase5-dev-tools \ libdrm-dev \ libxcb1-dev \ libxcb-dev \ libxcb-cursor-dev \ libx11-dev \ libxext-dev \ libxrender-dev \ libxi-dev \ libxrandr-dev </syntaxhighlight>

Notes:

Qt on Linux typically depends on X11/XCB libraries, so missing XCB/DRM packages commonly block Qt GUI builds.

If you are doing a headless build (no GUI), you may be able to omit Qt and X11/XCB packages.

== Verify GUI dependency availability ==

To confirm the GUI-related packages are installed:

<syntaxhighlight lang="bash"> dpkg -l | egrep "libdrm-dev|libxcb|qtbase5-dev|cmake" </syntaxhighlight>

= Running the CMake GUI on Raspberry Pi (cmake-gui) =

The CMake GUI executable is '''cmake-gui''', provided by Debian’s '''cmake-qt-gui''' package.
Debian Packages
+1

== 1) Install the CMake GUI package ==

On Raspberry Pi OS / Debian Bookworm-like systems:

<syntaxhighlight lang="bash"> sudo apt update sudo apt install -y cmake-qt-gui </syntaxhighlight>

This installs the '''cmake-gui''' executable.
Debian Packages
+1

== 2) Run cmake-gui on the Pi desktop (local monitor) ==

If your Pi is running a desktop environment and you are logged in locally:

<syntaxhighlight lang="bash"> cmake-gui </syntaxhighlight>

If launched from a terminal within the Pi desktop, it should open normally.

==Configure BCI2000 for Compilation==

===Run the CMake GUI===
Double-click "Configure.sh.cmd" in your BCI2000 build directory.

[[File:Cmake-init-non-windows.png|700px]]

===Tell CMake which Qt installation to use===
Click "AddEntry" in the CMake window (Note that checking off "Advanced" in CMake is optional and does not impact compilation) and enter the path to a Qt directory.

If you installed Qt using the Qt online installer, the path will look like /Users/foo/Qt/6.9.0/macos.
Use CMAKE_PREFIX_PATH as the name for the new entry. Be aware that the entry's name is case sensitive.

Also, currently, on non-windows platforms, Qt 6 is the only version that is supported.

[[File:Cmake-add-cache-non-windows.png|700px]]

===Configuration===
In the CMake window, click "Configure" and choose a generator that is consistent with your compiler. This tutorial will be using Unix Makefiles.

Then click "Done" to perform the configuration step.

[[File:Cmake-generators-non-windows.png|700px]]

You will see a list of targets scrolling by, and a number of new entries in the variable list at the top of the window, marked in red.

===Choose Build Options===
Make sure the "Grouped" checkbox is checked, and configure the build by customizing values in the "BUILD" group, "EXTENSIONS" group, and "USE" group.
[[File:Cmake-configured-non-windows.png|700px]]

===Generate Makefiles===
Then, click "Generate" to create build files. When CMake displays its "Generating done" message, your BCI2000 build directory will now contain a Makefile (or a project file for your compiler of chioce), as well as a number of additional CMake-generated files.

[[File:Cmake-done-non-windows.png|700px]]

==Compile BCI2000==
===Open Terminal===
Open a new terminal window and navigate to your BCI2000 build directory.

[[File:terminal-bulid-directory-non-windows.png|700px]]

===Build Executables===
Run:
make -j
from your BCI2000 build directory. Once this is finished your BCI2000 prog directory will contain a number of executables, one for each module, plus a few helper executables. Not everything works the same or, in some cases, at all on non-windows platforms. See [[Non-Windows Functionality]] for more information.

[[File:Make-done-non-windows.png|700px]]

The build process is now complete. Run
make -j
again to recompile. Or
make <target>
to recompile only a specific target.

[[Category:Howto]]

RaspberryPi

2025-12-18T20:52:57Z

Nluczak:

RaspberryPi

2025-12-18T20:51:10Z

Nluczak: Created page with "= Raspberry Pi (Linux) Build Dependencies (BCI2000 GUI build) = This section documents system packages needed to compile BCI2000 on a Raspberry Pi with GUI components enabled (e.g., ''OperatorQt'', ''StimulusPresentation'', ''BCI2000Viewer''). == Dependencies observed during build troubleshooting == During compilation, missing headers/libraries were resolved by installing the following packages: '''libdrm-dev''' — Direct Rendering Manager development files (graphic..."

File:RippleCSV.png

2025-12-09T15:44:24Z

Nluczak:

Contributions:RippleADC

2025-12-09T15:42:21Z

Nluczak:

[[File:RippleDeviceImage.webp|400px|thumb|right|Ripple Neural Interface Processor]]

RippleADC is a source module that allows for neural recording and stimulation using Ripple's Grapevine Neural Interface Processor. It supports high-channel-count recording and precise electrical stimulation capabilities. See the [https://rippleneuro.com/ Ripple site] for more information.

==[https://scribehow.com/page/Using_a_Ripple_device_with_BCI2000__fqrBfPskSSGBQPLttTlx2A Detailed installation instructions]==

==Versioning==

===Authors===
* Nicholas Luczak (luczak@neurotechcenter org)

===Version History===
* 04/29/2025 - Initial version
* 06/10/2025 - Added stimulation support
* 11/15/2025 - Added Luciano's Tool, added new important states, and improved Stimulation matrix configuration

===Source Code Revisions===
* Initial development: XXXX
* Tested under: XXXX
* Known to compile under: XXXX
* Broken since: --
==Dependencies==
Other than BCI2000, all you should need is the [https://rippleneuro.com/trellis-eeg-software/ Trellis software that comes with your Ripple device]
==Source Parameters==
These parameters can be found in the "Source" tab of the BCI2000 config window.
[[File:Ripple_Source_Parameters.png|600px|thumb|center|upright=2.5|Figure 1. The default source parameters for the RippleADC]]

===SourceCh===
The total number of digitized and stored channels. This can be set manually or left as "auto" to detect all available 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.

===SamplingRate===
The sample rate of the system. Supported rates are:
* 30,000 Hz (RAW)
* 15,000 Hz (HiFreq)
* 2,000 Hz (HiRes/EMG)
* 1,000 Hz (LFP)

===SourceChOffset===
Offset for each channel in raw A/D units.

===SourceChGain===
Gain for each channel in physical units per raw A/D unit (typically µV).

===ChannelNames===
Names of each channel in the format "FrontendName_ChannelNumber".

===SourceChList===
List of channels to actually transmit (subset of available channels).

==Stimulation Parameters==
These parameters can be found in the "Stimulation" tab and in both the BCI2000 config window and the Ripple Stimulation Tool. Parameters are checked and will throw a warning if they exceed device's safety limits or capabilities in both BCI2000 and the Ripple Stimulation Tool.
[[File:RippleStimulationParameters.png|600px|thumb|center|upright=2.5|Figure 2. Stimulation parameters for the RippleADC]]

===StimEnable===
Enable/disable stimulation functionality (0 or 1).

===Step Size===

This parameter defines the amplitude resolution of the stimulator in µA.
It indicates the granularity with which the stimulation amplitude may be adjusted. The allowed values depend on the hardware and are typically fixed by the front-end.

===Frequency===

This parameter defines the frequency of stimulation pulses in Hz.
It specifies how many biphasic pulses occur per second during stimulation. Controls the pulse rate within a stimulation train. Higher frequencies produce temporally denser stimulation.
Unit: Hz

===Amplitude===

This parameter defines the stimulation amplitude in mA.
It sets the magnitude of the delivered current for each pulse in the stimulation train. Primary determinant of stimulation intensity.
Unit: mA
===Duration===

This parameter defines the total duration of the stimulation train in seconds.
It specifies how long stimulation continues once triggered.
Unit: s

===Burst Length===

This parameter defines the length of each stimulation burst in seconds.
If burst-mode stimulation is used, pulses are grouped into bursts separated by silent periods.

Unit: s
Significance: Controls how long each burst remains active before an interburst pause occurs.

===Interburst Length===

This parameter defines the silent interval between bursts in milliseconds. Sets the recovery or idle period between active bursts; used to generate patterned or duty-cycled stimulation.

Unit: ms

===Pulse Width===

This parameter defines the width of each stimulation phase in microseconds (µs).
It corresponds to the duration of the main pulse phase. Affects charge delivery per pulse.
Unit: µs

===Interpulse Width===

This parameter defines the interval of time between pulses in microseconds. Controls how tightly pulses are packed in time; together with Pulse Width and Frequency, shapes the temporal profile of stimulation.
Unit: µs
===Gap Until Next===

This parameter defines the delay between this stimulation block and the next block in seconds.
Unit: s
Significance: Used in multi-step or sequential stimulation programs to introduce timing gaps before the next configured stimulation event.

===StimulationTriggers===
This parameter defines when stimulation is applied, what pulse is used, how many pulses are applied, and the source and destination locations of the stimulation. These parameters are defined in the rows of this matrix with labels
====Triggers====
This must be a [https://www.bci2000.org/mediawiki/index.php/User_Reference:Expression_Syntax BCI2000 expression]. When this expression evaluates true during the run, the stimulation is applied.

==Device Parameters==

===DeviceInfo===
This parameter cannot be edited and is automatically populated with information returned from the device, including:
* Processor type
* Firmware version
* Network address
* Available front ends

===ConnectionSettings===
Advanced TCP/IP connection settings for the Grapevine processor.

==States==
The states encode auxiliary information about the system status and stimulation events.

===Timestamp===
16-bit state containing the processor timestamp for each sample block.

===StimulusCode===
16-bit state that records the amplitude of active stimulation.

===StimulusType===
16-bit state that indicates stimulation status.

===ConnectionStatus===
8-bit state reporting the network connection quality.

==Technical Details==

===Supported Front Ends===
{| class="wikitable"
! Front End Type !! Channels !! Supported Sampling Rates
|-
| Stimulation || 32 || HiRes (2kHz), HiFreq (15kHz)
|-
| Raw || 32 || LFP (1kHz), HiRes (2kHz), Raw (30kHz)
|}

===Stimulation Waveforms===
Pulse parameters are converted to Ripple's stimulation command format as described in XippStimCmd.h.

[[File:RippleStimulationWaveform.png|800px|thumb|center|Figure 3. Example monophasic stimulation waveform]]

===Network Protocol===
The module uses Ripple's xipplib library to communicate with the Grapevine processor over TCP/IP. All data is transmitted in real-time with timestamps for synchronization.

==Stimulation How-to==
We have implemented and are distributing two different methods of stimulation through the Ripple device. One is a native implementation within BCI2000. The more capable method of driving stimulation is through a tool made using Matlab. This tool was created by Luciano Branco at the Mayo Clinic. This tool is distributed with BCI2000 and should be accessible through our SVN under src/contrib/SignalSource/RippleADC/cnel_stim. The tool allows you to create a wide range of stimulation configurations while visualising it and driving the stimulation in tandem with BCI2000 so that all of the relevant information is recorded.
===Native BCI2000===
In order to use stimulation through BCI2000, you simply need to go into the configuration window after launching a batch file with the RippleADC as your source. There, all you need to do is go to the Source tab, then scroll down until you see the stimulation section, then click the checkbox to enable stimulation and configure your stimulation parameters. These stimulation parameters will allow you to specify step size, frequency, amplitude, duration, burst length, interburst length, pulse width, interpulse width, and the gap until the next stimulation (if you're setting things up for multiple blocks of stimulation). The final relevant parameter is the StimulationTriggers parameter which allows you to define a trigger for your different configured stimulation patterns. For example, one could use a state such as stimulusCode to trigger stimulation based on when a stimulus is presented, or one could use some signal as a threshold for stimulation.
A step by step tutorial with screenshots can be found here:
[https://scribehow.com/viewer/Macro_Raw__DSjk-3QJRxe7EQVS8cSx4A Stimulation instructions]
===Matlab GUI tool===
This tool, developed by Luciano Branco at the Mayo Clinic is a much more advanced tool for driving stimulation which allows you to inspect your stimulation trains visually and also drive stimulation. The parameters for stimulation are identical to those within BCI2000

[[File:RippleStimulationParameters.png|800px|thumb|center|Image of settings possible to configure Ripple cnelStim tool]]

After configuring your various stimulation configurations you can inspect each train of stimulations.
[[File:RippleStimulationWaveform.png|800px|thumb|center|Image of example monophasic waveform]]

Once you are happy with your different waveforms and have confirmed that they are appropriate you can proceed to the Control Panel which allows you to define if you want to do bipolar stimulation, whether you want to drive stimulation from the cathode first, and other extra features. Once you are happy with the configuration and you have BCI2000 running you're ready to start stimulation. You can either drive the cnelStim tool by simply clicking the "Start Stimulation" button, or you can configure it to drive stimulation using a BCI2000 state which is pulled from BCI2000 using BCI2000Remote.
[[File:RippleControlPanel.png|800px|thumb|center|Image of example monophasic waveform]]

====Ripple GUI Configuration Files====
In order to easily configure and save complex stimulation parameters within the Matlab GUI tool, a CSV can be used to save and load desired stimulation parameters. You can find different example files [https://wustl.box.com/s/hl25jzr4ay5chhfmsw3g8ud219jn8m1l here.]
[[File:RippleCSV.png|800px|thumb|center|Image of an example CSV file for monophasic stimulation]]
==See also==
[[User Reference:Filters]], [[Contributions:ADCs]]
[[Category:Contributions]][[Category:Data Acquisition]]

File:RippleControlPanel.png

2025-12-05T20:22:00Z

Nluczak:

Contributions:RippleADC

2025-12-05T20:21:48Z

Nluczak: /* Native BCI2000 */

[[File:RippleDeviceImage.webp|400px|thumb|right|Ripple Neural Interface Processor]]

RippleADC is a source module that allows for neural recording and stimulation using Ripple's Grapevine Neural Interface Processor. It supports high-channel-count recording and precise electrical stimulation capabilities. See the [https://rippleneuro.com/ Ripple site] for more information.

==[https://scribehow.com/page/Using_a_Ripple_device_with_BCI2000__fqrBfPskSSGBQPLttTlx2A Detailed installation instructions]==

==Versioning==

===Authors===
* Nicholas Luczak (luczak@neurotechcenter org)

===Version History===
* 04/29/2025 - Initial version
* 06/10/2025 - Added stimulation support
* 11/15/2025 - Added Luciano's Tool, added new important states, and improved Stimulation matrix configuration

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

==Source Parameters==
These parameters can be found in the "Source" tab of the BCI2000 config window.
[[File:Ripple_Source_Parameters.png|600px|thumb|center|upright=2.5|Figure 1. The default source parameters for the RippleADC]]

===SourceCh===
The total number of digitized and stored channels. This can be set manually or left as "auto" to detect all available 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.

===SamplingRate===
The sample rate of the system. Supported rates are:
* 30,000 Hz (RAW)
* 15,000 Hz (HiFreq)
* 2,000 Hz (HiRes/EMG)
* 1,000 Hz (LFP)

===SourceChOffset===
Offset for each channel in raw A/D units.

===SourceChGain===
Gain for each channel in physical units per raw A/D unit (typically µV).

===ChannelNames===
Names of each channel in the format "FrontendName_ChannelNumber".

===SourceChList===
List of channels to actually transmit (subset of available channels).

==Stimulation Parameters==
These parameters can be found in the "Stimulation" tab and in both the BCI2000 config window and the Ripple Stimulation Tool. Parameters are checked and will throw a warning if they exceed device's safety limits or capabilities in both BCI2000 and the Ripple Stimulation Tool.
[[File:RippleStimulationParameters.png|600px|thumb|center|upright=2.5|Figure 2. Stimulation parameters for the RippleADC]]

===StimEnable===
Enable/disable stimulation functionality (0 or 1).

===Step Size===

This parameter defines the amplitude resolution of the stimulator in µA.
It indicates the granularity with which the stimulation amplitude may be adjusted. The allowed values depend on the hardware and are typically fixed by the front-end.

===Frequency===

This parameter defines the frequency of stimulation pulses in Hz.
It specifies how many biphasic pulses occur per second during stimulation. Controls the pulse rate within a stimulation train. Higher frequencies produce temporally denser stimulation.
Unit: Hz

===Amplitude===

This parameter defines the stimulation amplitude in mA.
It sets the magnitude of the delivered current for each pulse in the stimulation train. Primary determinant of stimulation intensity.
Unit: mA
===Duration===

This parameter defines the total duration of the stimulation train in seconds.
It specifies how long stimulation continues once triggered.
Unit: s

===Burst Length===

This parameter defines the length of each stimulation burst in seconds.
If burst-mode stimulation is used, pulses are grouped into bursts separated by silent periods.

Unit: s
Significance: Controls how long each burst remains active before an interburst pause occurs.

===Interburst Length===

This parameter defines the silent interval between bursts in milliseconds. Sets the recovery or idle period between active bursts; used to generate patterned or duty-cycled stimulation.

Unit: ms

===Pulse Width===

This parameter defines the width of each stimulation phase in microseconds (µs).
It corresponds to the duration of the main pulse phase. Affects charge delivery per pulse.
Unit: µs

===Interpulse Width===

This parameter defines the interval of time between pulses in microseconds. Controls how tightly pulses are packed in time; together with Pulse Width and Frequency, shapes the temporal profile of stimulation.
Unit: µs
===Gap Until Next===

This parameter defines the delay between this stimulation block and the next block in seconds.
Unit: s
Significance: Used in multi-step or sequential stimulation programs to introduce timing gaps before the next configured stimulation event.

===StimulationTriggers===
This parameter defines when stimulation is applied, what pulse is used, how many pulses are applied, and the source and destination locations of the stimulation. These parameters are defined in the rows of this matrix with labels

==Device Parameters==

===DeviceInfo===
This parameter cannot be edited and is automatically populated with information returned from the device, including:
* Processor type
* Firmware version
* Network address
* Available front ends

===ConnectionSettings===
Advanced TCP/IP connection settings for the Grapevine processor.

==States==
The states encode auxiliary information about the system status and stimulation events.

===Timestamp===
16-bit state containing the processor timestamp for each sample block.

===StimulusCode===
16-bit state that records the amplitude of active stimulation.

===StimulusType===
16-bit state that indicates stimulation status.

===ConnectionStatus===
8-bit state reporting the network connection quality.

==Technical Details==

===Supported Front Ends===
{| class="wikitable"
! Front End Type !! Channels !! Supported Sampling Rates
|-
| Stimulation || 32 || HiRes (2kHz), HiFreq (15kHz)
|-
| Raw || 32 || LFP (1kHz), HiRes (2kHz), Raw (30kHz)
|}

===Stimulation Waveforms===
Pulse parameters are converted to Ripple's stimulation command format as described in XippStimCmd.h.

[[File:RippleStimulationWaveform.png|800px|thumb|center|Figure 3. Example monophasic stimulation waveform]]

===Network Protocol===
The module uses Ripple's xipplib library to communicate with the Grapevine processor over TCP/IP. All data is transmitted in real-time with timestamps for synchronization.

==Stimulation How-to==
We have implemented and are distributing two different methods of stimulation through the Ripple device. One is a native implementation within BCI2000. The more capable method of driving stimulation is through a tool made using Matlab. This tool was created by Luciano Branco at the Mayo Clinic. This tool is distributed with BCI2000 and should be accessible through our SVN under src/contrib/SignalSource/RippleADC/cnel_stim. The tool allows you to create a wide range of stimulation configurations while visualising it and driving the stimulation in tandem with BCI2000 so that all of the relevant information is recorded.
===Native BCI2000===
In order to use stimulation through BCI2000, you simply need to go into the configuration window after launching a batch file with the RippleADC as your source. There, all you need to do is go to the Source tab, then scroll down until you see the stimulation section, then click the checkbox to enable stimulation and configure your stimulation parameters. These stimulation parameters will allow you to specify step size, frequency, amplitude, duration, burst length, interburst length, pulse width, interpulse width, and the gap until the next stimulation (if you're setting things up for multiple blocks of stimulation). The final relevant parameter is the StimulationTriggers parameter which allows you to define a trigger for your different configured stimulation patterns. For example, one could use a state such as stimulusCode to trigger stimulation based on when a stimulus is presented, or one could use some signal as a threshold for stimulation.
A step by step tutorial with screenshots can be found here:
[https://scribehow.com/viewer/Macro_Raw__DSjk-3QJRxe7EQVS8cSx4A Stimulation instructions]
===Matlab GUI tool===
This tool, developed by Luciano Branco at the Mayo Clinic is a much more advanced tool for driving stimulation which allows you to inspect your stimulation trains visually and also drive stimulation. The parameters for stimulation are identical to those within BCI2000

[[File:RippleStimulationParameters.png|800px|thumb|center|Image of settings possible to configure Ripple cnelStim tool]]

After configuring your various stimulation configurations you can inspect each train of stimulations.
[[File:RippleStimulationWaveform.png|800px|thumb|center|Image of example monophasic waveform]]

Once you are happy with your different waveforms and have confirmed that they are appropriate you can proceed to the Control Panel which allows you to define if you want to do bipolar stimulation, whether you want to drive stimulation from the cathode first, and other extra features. Once you are happy with the configuration and you have BCI2000 running you're ready to start stimulation. You can either drive the cnelStim tool by simply clicking the "Start Stimulation" button, or you can configure it to drive stimulation using a BCI2000 state which is pulled from BCI2000 using BCI2000Remote.
[[File:RippleControlPanel.png|800px|thumb|center|Image of example monophasic waveform]]

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

Contributions:RippleADC

2025-12-05T20:20:31Z

Nluczak:

[[File:RippleDeviceImage.webp|400px|thumb|right|Ripple Neural Interface Processor]]

RippleADC is a source module that allows for neural recording and stimulation using Ripple's Grapevine Neural Interface Processor. It supports high-channel-count recording and precise electrical stimulation capabilities. See the [https://rippleneuro.com/ Ripple site] for more information.

==[https://scribehow.com/page/Using_a_Ripple_device_with_BCI2000__fqrBfPskSSGBQPLttTlx2A Detailed installation instructions]==

==Versioning==

===Authors===
* Nicholas Luczak (luczak@neurotechcenter org)

===Version History===
* 04/29/2025 - Initial version
* 06/10/2025 - Added stimulation support
* 11/15/2025 - Added Luciano's Tool, added new important states, and improved Stimulation matrix configuration

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

==Source Parameters==
These parameters can be found in the "Source" tab of the BCI2000 config window.
[[File:Ripple_Source_Parameters.png|600px|thumb|center|upright=2.5|Figure 1. The default source parameters for the RippleADC]]

===SourceCh===
The total number of digitized and stored channels. This can be set manually or left as "auto" to detect all available 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.

===SamplingRate===
The sample rate of the system. Supported rates are:
* 30,000 Hz (RAW)
* 15,000 Hz (HiFreq)
* 2,000 Hz (HiRes/EMG)
* 1,000 Hz (LFP)

===SourceChOffset===
Offset for each channel in raw A/D units.

===SourceChGain===
Gain for each channel in physical units per raw A/D unit (typically µV).

===ChannelNames===
Names of each channel in the format "FrontendName_ChannelNumber".

===SourceChList===
List of channels to actually transmit (subset of available channels).

==Stimulation Parameters==
These parameters can be found in the "Stimulation" tab and in both the BCI2000 config window and the Ripple Stimulation Tool. Parameters are checked and will throw a warning if they exceed device's safety limits or capabilities in both BCI2000 and the Ripple Stimulation Tool.
[[File:RippleStimulationParameters.png|600px|thumb|center|upright=2.5|Figure 2. Stimulation parameters for the RippleADC]]

===StimEnable===
Enable/disable stimulation functionality (0 or 1).

===Step Size===

This parameter defines the amplitude resolution of the stimulator in µA.
It indicates the granularity with which the stimulation amplitude may be adjusted. The allowed values depend on the hardware and are typically fixed by the front-end.

===Frequency===

This parameter defines the frequency of stimulation pulses in Hz.
It specifies how many biphasic pulses occur per second during stimulation. Controls the pulse rate within a stimulation train. Higher frequencies produce temporally denser stimulation.
Unit: Hz

===Amplitude===

This parameter defines the stimulation amplitude in mA.
It sets the magnitude of the delivered current for each pulse in the stimulation train. Primary determinant of stimulation intensity.
Unit: mA
===Duration===

This parameter defines the total duration of the stimulation train in seconds.
It specifies how long stimulation continues once triggered.
Unit: s

===Burst Length===

This parameter defines the length of each stimulation burst in seconds.
If burst-mode stimulation is used, pulses are grouped into bursts separated by silent periods.

Unit: s
Significance: Controls how long each burst remains active before an interburst pause occurs.

===Interburst Length===

This parameter defines the silent interval between bursts in milliseconds. Sets the recovery or idle period between active bursts; used to generate patterned or duty-cycled stimulation.

Unit: ms

===Pulse Width===

This parameter defines the width of each stimulation phase in microseconds (µs).
It corresponds to the duration of the main pulse phase. Affects charge delivery per pulse.
Unit: µs

===Interpulse Width===

This parameter defines the interval of time between pulses in microseconds. Controls how tightly pulses are packed in time; together with Pulse Width and Frequency, shapes the temporal profile of stimulation.
Unit: µs
===Gap Until Next===

This parameter defines the delay between this stimulation block and the next block in seconds.
Unit: s
Significance: Used in multi-step or sequential stimulation programs to introduce timing gaps before the next configured stimulation event.

===StimulationTriggers===
This parameter defines when stimulation is applied, what pulse is used, how many pulses are applied, and the source and destination locations of the stimulation. These parameters are defined in the rows of this matrix with labels

==Device Parameters==

===DeviceInfo===
This parameter cannot be edited and is automatically populated with information returned from the device, including:
* Processor type
* Firmware version
* Network address
* Available front ends

===ConnectionSettings===
Advanced TCP/IP connection settings for the Grapevine processor.

==States==
The states encode auxiliary information about the system status and stimulation events.

===Timestamp===
16-bit state containing the processor timestamp for each sample block.

===StimulusCode===
16-bit state that records the amplitude of active stimulation.

===StimulusType===
16-bit state that indicates stimulation status.

===ConnectionStatus===
8-bit state reporting the network connection quality.

==Technical Details==

===Supported Front Ends===
{| class="wikitable"
! Front End Type !! Channels !! Supported Sampling Rates
|-
| Stimulation || 32 || HiRes (2kHz), HiFreq (15kHz)
|-
| Raw || 32 || LFP (1kHz), HiRes (2kHz), Raw (30kHz)
|}

===Stimulation Waveforms===
Pulse parameters are converted to Ripple's stimulation command format as described in XippStimCmd.h.

[[File:RippleStimulationWaveform.png|800px|thumb|center|Figure 3. Example monophasic stimulation waveform]]

===Network Protocol===
The module uses Ripple's xipplib library to communicate with the Grapevine processor over TCP/IP. All data is transmitted in real-time with timestamps for synchronization.

==Stimulation How-to==
We have implemented and are distributing two different methods of stimulation through the Ripple device. One is a native implementation within BCI2000. The more capable method of driving stimulation is through a tool made using Matlab. This tool was created by Luciano Branco at the Mayo Clinic. This tool is distributed with BCI2000 and should be accessible through our SVN under src/contrib/SignalSource/RippleADC/cnel_stim. The tool allows you to create a wide range of stimulation configurations while visualising it and driving the stimulation in tandem with BCI2000 so that all of the relevant information is recorded.
===Native BCI2000===
In order to use stimulation through BCI2000, you simply need to go into the configuration window after launching a batch file with the RippleADC as your source. There, all you need to do is go to the Source tab, then scroll down until you see the stimulation section, then click the checkbox to enable stimulation and configure your stimulation parameters. These stimulation parameters will allow you to specify step size, frequency, amplitude, duration, burst length, interburst length, pulse width, interpulse width, and the gap until the next stimulation (if you're setting things up for multiple blocks of stimulation). The final relevant parameter is the StimulationTriggers parameter which allows you to define a trigger for your different configured stimulation patterns. For example, one could use a state such as stimulusCode to trigger stimulation based on when a stimulus is presented, or one could use some signal as a threshold for stimulation.
A step by step tutorial with screenshots can be found here:
[https://scribehow.com/viewer/Macro_Raw__DSjk-3QJRxe7EQVS8cSx4A Stimulation instructions]
===Matlab GUI tool==-
This tool, developed by Luciano Branco at the Mayo Clinic is a much more advanced tool for driving stimulation which allows you to inspect your stimulation trains visually and also drive stimulation. The parameters for stimulation are identical to those within BCI2000

[[File:RippleGUISettings.png|800px|thumb|center|Image of settings possible to configure Ripple cnelStim tool]]

After configuring your various stimulation configurations you can inspect each train of stimulations.
[[File:RippleStimulationWaveform.png|800px|thumb|center|Image of example monophasic waveform]]

Once you are happy with your different waveforms and have confirmed that they are appropriate you can proceed to the Control Panel which allows you to define if you want to do bipolar stimulation, whether you want to drive stimulation from the cathode first, and other extra features. Once you are happy with the configuration and you have BCI2000 running you're ready to start stimulation. You can either drive the cnelStim tool by simply clicking the "Start Stimulation" button, or you can configure it to drive stimulation using a BCI2000 state which is pulled from BCI2000 using BCI2000Remote.
[[File:RippleControlPanel.png|800px|thumb|center|Image of example monophasic waveform]]
==See also==
[[User Reference:Filters]], [[Contributions:ADCs]]
[[Category:Contributions]][[Category:Data Acquisition]]

Contributions:RippleADC

2025-11-18T03:35:08Z

Nluczak: /* Version History */

Contributions:RippleADC

2025-11-15T06:34:39Z

Nluczak: /* Stimulation Parameters */

Contributions:RippleADC

2025-11-15T06:33:37Z

Nluczak: /* StimEnable */

Contributions:RippleADC

2025-11-15T06:33:31Z

Nluczak: /* Stimulation Parameters */

Contributions:RippleADC

2025-11-15T06:17:35Z

Nluczak: /* Supported Front Ends */