Contributions:RippleADC
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 Ripple site for more information.
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 Trellis software that comes with your Ripple device
Source Parameters
These parameters can be found in the "Source" tab of the BCI2000 config window.
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.
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 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
| 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.
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: 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
After configuring your various stimulation configurations you can inspect each train of stimulations.
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.
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 here.
