Contributions:CortecADC: Difference between revisions
| Line 86: | Line 86: | ||
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. (see state information on this page for a complete enumeration of states) with floats, but BCI2000 states can only be integers. These multipliers are used to increase the amount of precision in the state values. To approximately recover the float values, divide each state by its corresponding multiplier. | 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. (see state information on this page for a complete enumeration of states) with floats, but BCI2000 states can only be integers. These multipliers are used to increase the amount of precision in the state values. To approximately recover the float values, divide each state by its corresponding multiplier. | ||
=States= | ==States== | ||
==ImplantLostSample== | ===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. | 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== | ===ImplantVoltage=== | ||
16 bit state that changes when new supply voltage value is received from the implant. Units in volts. | 16 bit state that changes when new supply voltage value is received from the implant. Units in volts. | ||
==ImplantHumidity== | ===ImplantHumidity=== | ||
16 bit state that changes when new humidity value is received from the implant. Units in %rh. | 16 bit state that changes when new humidity value is received from the implant. Units in %rh. | ||
==ImplantControlValue== | ===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. | 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. | 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== | ===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. | 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== | ===ImplantTemperature=== | ||
16 bit state that changes when new temperature value is received from the implant. Units are degrees Celsius. | 16 bit state that changes when new temperature value is received from the implant. Units are degrees Celsius. | ||
==ImplantStimulation== | ===ImplantStimulation=== | ||
Binary state that changes when the device reports that it is stimulating. | Binary state that changes when the device reports that it is stimulating. | ||
Revision as of 18:06, 19 April 2021
Introduction
CorTec BIC is an application interface (API) in BCI2000 that facilitates with the CorTec hardware device, which is implanted in animals (primarily, pigs) for research and medical purposes. The API enables programmatic access to BIC implants.
CorTec BIC Architecture
Walkthrough: Experimental Steps
The following steps are the primary steps to perform the necessary experiment for medical and research purposes.
Initial Access and Device Discovery
There are several functions in the header file bciapi.h that provide central access to the application interface which helps in creating an implant factory and obtaining some information and details regarding the connected external units and implant devices (device discovery).
Implant Object Creation
This steps involves creation of implant object. During this step, it is assumed that only one external unit is connected and one implant is connected to this external unit. Then this implant object is used to query the temperature and the humidity within the implant's hermetic capsule.
Obtaining Measurement Data
In this step, an Implant listener object is created and registered to an Implant object. Then the measurement is started and one channel is written to standard output.
- Attention
Please note that the current implementation writes a value to stdout approximately every millisecond (i.e., with the sampling frequency) will cause performance issues on slow machines. For productive use, the measurement data can be passed to another thread for further processing or written to a binary file, instead of being written to stdout.
Doing Stimulation
In this step, electrical stimulation is performed via an implant by first creating a stimulation command that stimulates with a frequency of ~18.5Hz.
Parameters
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.
Stimulation Parameters
Enable Stimulation
This parameter enables/disables stimulation.
Stimulation Pulses
This parameter defines the shape of the stimulation pulse applied, as described in Fig 1. It is possible to define an arbitrary number of pulses, each are associated with a PulseID, which is an integer defined by the user. Each pulse must adhere to the charge-balanced pulse shape and is defined in one column of this parameter matrix. The rows are labeled and there are some limitations to the magnitudes and durations which are elaborated on in the subsequent section.
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.
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 us. 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. The first row contains a BCI2000 expression. When this expression evaluates true during the run, the stimulation is applied. The second row should contain a valid PulseID that is to be used. The third row is an embedded list that defines the source electrodes. The fourth row is also an embedded list that defines the destination electrodes. Lastly, the fifth row defines how many times that pulse is repeated. The max is 255.
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. (see state information on this page for a complete enumeration of states) with floats, but BCI2000 states can only be integers. These multipliers are used to increase the amount of precision in the state values. To approximately recover the float values, divide each state by its corresponding multiplier.
States
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. Units 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.
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.