br_stimpy.stimpy.Stimulator

class Stimulator

Bases: object

Simple python interface to Blackrock Cerestim 96

Raises:

RuntimeError – Only 12 stimulator objects can be created at a time

Methods

auto_stimulus	Stimulate in stim script
begin_group	Begin group stim
begin_sequence	Begin stim script
configure_stimulus_pattern	Set stim pattern configs
connect	Connect to Cerestim.
disable_module	Disable current module
disable_stimulus_configuration	Disables a stimulation waveform so that it is able to be reset
disconnect	Disconnect from Cerestim
enable_module	Enable current module
end_group	End group stim
end_sequence	End stim script
group_stimulus	Send group stimulus command
manual_stimulus	Manually stimulate on one electrode
pause	Pause stim script execution
play	Play stim script
read_all_stimulus_patterns	Read back all stim config patterns from stimulator
read_hardware_values	Reads the hardware values that are set based on the part number
read_max_output_voltage	Read compliance voltage
read_stimulus_max_values	Read maximum stimulus values set using set_stimulus_max_values()
read_stimulus_pattern	Read stim config pattern
reset_stimulator	Stimulator Reset
scan_for_devices	Scan for connected Cerestim devices
set_max_output_voltage	Set compliance voltage
set_stimulus_max_values	Set max limits
simple_stimulus	Simplest method to manually command a stimulus pulse
simple_stimulus_group	Simplest method to manually command a group stimulus pulse with identical parameters on all electrodes
stop	Stop stim script execution
stop_trigger_stimulus	Stop trigger mode
trigger_stimulus	Start trigger mode
update_electrode_channel_map	Set electrode map
wait	Wait between stim pulses

Attributes

api_version	Cerestim API library version
device_info	Read device hardware and firmware info
device_vector	list of stimulators across all class instances
is_connected	Check if stimulator is connected
is_device_locked	Check if stimulator is locked
is_safety_disabled	Check if safety limits are disabled
is_stim_sequence_playing	Check if a stim sequence is actively playing
max_hard_charge	Get hardware max charge per phase
max_hard_frequency	Get hardware maximum frequency in Hz
max_hard_interphase	Get hardware maximum interphase width in us
max_hard_width	Get hardware maximum pulse width in us
min_hard_frequency	Get hardware minimum frequency in Hz
min_max_amplitude	Get hardware min and max amplitudes
module_firmware_version	Get firmware versions of current modules
module_status	Get status of each current module
motherboard_firmware_version	Get main firmware version
number_modules	Get number of current modules installed
protocol_version	Get motherboard protocol version
sequence_status	Get stim sequence status
serial_number	Get device serial number
stimulus_patterns_cached	Cached list of configured stimulus patterns
usb_address	Gets the USB address of the connected stimulator

class ElectrodeChannelMap(self: br_stimpy._bstimulator.ElectrodeChannelMap)

Bases: pybind11_object

The stimulator is capable of sending stimulation up to 96 different electrodes. The layout of where those electrodes are mapped to sometimes are not a straight channel 1 to electrode 1, such as in a Blackrock .CMP file. This struct allows the user to specify a mapping for there electrodes so that they do not need to worry about what channel they need to stimulate if they want electrode 20 to be stimulated.

Map Channels to Electrodes.

property bankA

UINT8 Array, the pin on bank A is the index, and the value is the acutal electrode number.

property bankB

UINT8 Array, the pin on bank B is the index, and the value is the acutal electrode number.

property bankC

UINT8 Array, the pin on bank C is the index, and the value is the acutal electrode number.

class ModuleStatus(self: br_stimpy._bstimulator.ModuleStatus, value: int)

Bases: pybind11_object

The stimulator is capable of housing up to 16 current modules. Each current module can have several states based on how the user has configured the stimulator. The current modules are also capable of returning problem statuses based on the hardware.

Members:

module_unavailable : No current module in the specified position.

module_enabled : Current module in the specified position is enabled.

module_disabled : Current Module in the specified position is disabled.

module_ok : Voltage levels on the current module are normal.

module_voltagelimitation : Voltage levels on the current module are below normal, Module is bad.

module_count : Number of Statuses, Always the Last one.

property name

class OCVolt(self: br_stimpy._bstimulator.OCVolt, value: int)

Bases: pybind11_object

The Stimulator is capable of setting different output compliance voltage levels based on the users needs and safety considerations.

Members:

ocvolt4_7 : Output Voltage Level 4.7V.

ocvolt5_3 : Output Voltage Level 5.3V.

ocvolt5_9 : Output Voltage Level 5.9V.

ocvolt6_5 : Output Voltage Level 6.5V.

ocvolt7_1 : Output Voltage Level 7.1V.

ocvolt7_7 : Output Voltage Level 7.7V.

ocvolt8_3 : Output Voltage Level 8.3V.

ocvolt8_9 : Output Voltage Level 8.9V.

ocvolt9_5 : Output Voltage Level 9.5V.

ocvolt_invalid : Invalid Compliance Voltage, Always the Last One.

property name

class PartNumbers(self: br_stimpy._bstimulator.PartNumbers, value: int)

Bases: pybind11_object

There are many versions of the stimulator. There are research versions of micro and macro stimulators, each with varying number of installed current modules; and there is a clinical version of the macro stimulator with a single current module. The part number of the device sets internal safety levels of what stimulation parameters are allowed.

Members:

PN6425 : CereStim R96 Micro Stimulator Beta Unit, May be either a 3 or 16 current module unit.

PN7008 : CereStim R96 Micro Stimulator 3 current module unit.

PN7039 : CereStim R96 Micro Stimulator 16 current module unit.

PN7169 : CereStim R96 Micro Stimulator 1 current module unit.

PN8543 : CereStim R96 Micro Stimulator Customer Specified Configuration.

PN7655 : CereStim R96 Macro Stimulator 3 current module unit.

PN7656 : CereStim M96 Macro Stimulator Clinical 1 current module unit.

PN7875 : CereStim R96 Macro Stimulator 16 current module unit.

PN8544 : CereStim R96 Macro Stimulator Customer Specified Configuration.

PN_invalid : Invalid part number.

property name

class SeqType(self: br_stimpy._bstimulator.SeqType, value: int)

Bases: pybind11_object

The Stimulator has internal states, and based on those states the stimulator is allowed to perform different functions. The SeqType enumerator lists all the valid states.

Members:

stop : The stimulator is stopped.

pause : The stimulator is paused.

playing : The stimulator is actively delivering a stimulus.

writing : A stimulus sequence is being written to the stimulator.

trigger : The stimulator is waiting for a trigger on its trigger line.

invalid : Invalid Sequence, Always the last value.

property name

class TriggerType(self: br_stimpy._bstimulator.TriggerType, value: int)

Bases: pybind11_object

The stimulator is able to begin stimulating based on an external TTL logic. The Trigger type defines the possible trigger methods. It can be set to trigger on a low to high transistion, a high to low transistion, or any transistion.

Members:

trigger_disabled : Trigger mode is currently turned off.

trigger_rising : Trigger on a low to high transistion.

trigger_falling : Trigger on a high to low transistion

trigger_change : Trigger on any transistion.

trigger_invalid : Invalid Trigger, Always the last value

property name

class WFType(self: br_stimpy._bstimulator.WFType, value: int)

Bases: pybind11_object

The Stimulator is capable of outputting a biphasic current pulse. the BWFType enumerator allows the user to determine what the polarity is of the first phase of the biphasic pulse.

Members:

wf_anodic_first : The first phase is anodic.

wf_cathodic_first : The first phase is cathodic.

wf_invalid : Invalid Selection, always the last one.

property name

property api_version: Version

Cerestim API library version

auto_stimulus(electrode, configID)

Stimulate in stim script

This command tells the stimulator when to send a stimulus to an electrode in a stimulation script. It can be used as many times as needed so long as the total number of commands does not exceed 128. It should also be used within begin_group() and end_group() commands to allow for simultaneous stimulations.

Parameters:

• electrode (int) – The electrode that will be stimulated. Valid values are from 1 - 96

• configID (int) – One of the fifteen stimulation waveforms that should be used. Valid values are from 1-15

Return type:

None

begin_group()

Begin group stim

This command signifies that the following commands up to the end_group() command should all occur simultaneously. The only commands that are valid are the auto_stimulus() commands. You can only have as many stimulations as the number of current modules installed. Can’t be called on the last of the 128 instructions since it needs to have a closing end_group command.

Return type:

None

begin_sequence()

Begin stim script

This is the first command that must be called when creating a stimulation script. After calling this you are able to call wait(), auto_stimulus(), begin_group(), and end_group() commands. The stimulation script can have up to 128 commands, excluding begin_sequence() and end_sequence()

Return type:

None

configure_stimulus_pattern(configID, afcf, pulses, amp1, amp2, width1, width2, frequency, interphase)

Set stim pattern configs

Takes all of the parameters needed in order to create a custom biphasic stimulation waveform. The device is capable of handling 16 differnt waveforms, but waveform 0 is reserved and used for testing in getting measurements from electrodes and current modules. Micro and Macro stimulators have different ranges of valid values. Especially for the amplitude where micro stimulators are in the uA range with uA precision, Macro stimulators go from 100 uA to 10 mA with 100 uA precision. While the widths and interphases have quite a range, the user needs to somewhat understand how they interact with the frequency chosen. You dont want a stimulus waveform that is longer than the time between repeats.

Parameters:

• configID (int) – The stimulation waveform that is being configured 1 - 15

• afcf (WFType) – What polarity should the first phase be, Anodic or Cathodic first

• pulses (int) – The number of stimulation pulses in waveform from 1 - 255

• amp1 (int) – The amplitude of the first phase, for Micro it is 1 - 215 uA, and for Macro it is 100 uA - 10 mA

• amp2 (int) – The amplitude of the first phase, for Micro it is 1 - 215 uA, and for Macro it is 100 uA - 10 mA

• width1 (int) – The width of the first phase in the stimulation 1 - 65,535 uS

• width2 (int) – The width of the second phase in the stimulation 1 - 65,535 uS

• frequency (int) – The stimulating frequency at which the biphasic pulses should repeat 4 - 5000 Hz

• interphase (int) – The period of time between the first and second phases 53 - 65,535 uS

Return type:

None

connect(device_index=0)

Connect to Cerestim.

If multiple devices are attached to PC, first call scan_for_devices() to view the list of serial numbers, then input the device_index you would like to connect to.

Parameters:

device_index (int) – (Optional) Index of device from scan_for_devices(). Defaults to 0.

Raises:

• IndexError – Invalid device_index

• RuntimeError – No Cerestim devices found

Return type:

None

property device_info: dict

Read device hardware and firmware info

This returns all the information about the CereStim 96 that is connected to. It will tell its part number, serial number, firmware versions for both the motherboard and for the current modules. It will also tell you the protocol that the motherboard is using with the current modules and the number of installed current modules.

device_vector: Optional[List[int]] = None

list of stimulators across all class instances

disable_module(module)

Disable current module

Allows the user to disable different current modules that are installed in the CereStim. This is useful for testing and making sure that multiple current modules are all giving the same output values. The current module has to exist to be disabled.

Parameters:

module (int) – The current module to be disabled from 0 to 15

Return type:

None

disable_stimulus_configuration(configID)

Disables a stimulation waveform so that it is able to be reset

Parameters:

configID (int) – The configuration to disable

Return type:

None

disconnect()

Disconnect from Cerestim

Return type:

None

enable_module(module)

Enable current module

Allows the user to enable different current modules that have been disabled. This is useful for testing and making sure that multiple current modules are all giving the same output values.

Parameters:

module (int) – The current module to be enabled from 0 to 15

Return type:

None

end_group()

End group stim

This command closes off a group of simultaneous stimulations. If begin_group() is called during a sequence of commands, then there must be an end_group() otherwise the user will get a sequence error as a return value.

Return type:

None

end_sequence()

End stim script

This is the last command that must be called when creating a stimulation script. It does not count towards the maximum of 128 commands.

Return type:

None

group_stimulus(begin_seq, play, times, group_stim_struct)

Send group stimulus command

There is a lot of overhead in sending commands over the USB to the CereStim 96. each function call averages 2mS. This function allows the user to create the stimulation parameters beforehand and in a single function call perform simultaneous stimulations based on different electrodes and configured waveforms.

Parameters:

• begin_seq (bool) – Boolean expression to tell the function that it is the beginning of a sequence

• play (bool) – Boolean expression to tell if the stimulator should begin stimulating immedieatly after this call

• times (int) – The number of times to play the stimulation, is ignored if play = false

• group_stim_struct (GroupStimulusStruct) – structure which has a pair of arrays with electrodes and waveforms

Return type:

None

property is_connected: bool

Check if stimulator is connected

Lets the user know that the Stimulator object is connected to a physical CereStim 96 device.

property is_device_locked: bool

Check if stimulator is locked

If the detected number of current modules doesn’t match the hardware configuration or if the hardware configuration is not setup, the device will be locked down preventing any stimulation from occuring.

property is_safety_disabled: bool

Check if safety limits are disabled

For Internal validation and testing it is required to disable the safety limits in the firmware and API so that hardware limits can be observed and tested.

property is_stim_sequence_playing: bool

Check if a stim sequence is actively playing

manual_stimulus(electrode, configID)

Manually stimulate on one electrode

Allows the user to send a single stimulus pulse of one of the stimulation waveforms to a specified electrode.

Parameters:

• electrode (int) – The electrode that should be stimulated. Valid values are from 1 - 96.

• configID (int) – The stimulation waveform to use. Valid values are from 1 - 15.

Return type:

None

property max_hard_charge: int

Get hardware max charge per phase

This value is based on the hardware of the particular model of the CereStim 96. Again the micro and macro versions of the stimulator have different values

property max_hard_frequency: int

Get hardware maximum frequency in Hz

This value is based on the hardware of the particular model of the CereStim 96. Again the micro and macro versions of the stimulator have different values

property max_hard_interphase: int

Get hardware maximum interphase width in us

This value is based on the hardware of the particuliar model of the CereStim 96

property max_hard_width: int

Get hardware maximum pulse width in us

This value is based on the hardware of the particuliar model of the CereStim 96.

property min_hard_frequency: int

Get hardware minimum frequency in Hz

This value is based on the hardware of the particular model of the CereStim 96. Again the micro and macro versions of the stimulator have different values

property min_max_amplitude: dict

Get hardware min and max amplitudes

Since there are different models and version of the stimulator, such as the micro and macro versions, this will allow the user to get the min and max amplitudes that are allowed for stimulation.

property module_firmware_version: List[dict]

Get firmware versions of current modules

Each current module has its own microcontroller and has a firmware version. All current modules in a single stimulator should have the same firmware version. The MSB is the Major revision number and the LSB is the minor revision number. I.e. 0x0105 would be version 1.5

property module_status: List[ModuleStatus]

Get status of each current module

This tells the status of each current module, whether it is enabled, disabled, or not available.

property motherboard_firmware_version: dict

Get main firmware version

Retrieves the firmware revision of the microcontroller on the motherboard.

property number_modules: int

Get number of current modules installed

This value is based on the hardware of the particular model of the CereStim 96. Again the micro and macro versions of the stimulator have different values

pause()

Pause stim script execution

This will pause a currently running stimulation script and keep track of the next command that needs to be executed so if it receives a play command it can pick up where it left off.

Return type:

None

play(times)

Play stim script

Tells the stimulator the number of times that it should run the stimulation script. A zero passed in will tell it to run indefinitely until it is either stopped or paused by the user. Other values include between 1 and 65,535 repetitions. Cannot be called during a begin_sequence() and end_sequence() command call.

Parameters:

times (int) – Number of times to execute the stimulation script. 0 means indefinitely.

Raises:

ValueError – times must be between 0 and 65535.

Return type:

None

property protocol_version: dict

Get motherboard protocol version

The protocol version that the motherboard uses to send and receive data from the current modules.

read_all_stimulus_patterns()

Read back all stim config patterns from stimulator

Return type:

dict

Returns:

15 StimulusConfiguration structures. Values are None if configuration is inactive.

read_hardware_values()

Reads the hardware values that are set based on the part number

Return type:

ReadHardwareValuesOutput

Returns:

Structure containing the hardware values

read_max_output_voltage()

Read compliance voltage

This will read the values of +VDD and -VSS on the stimulator which allows it to effectively limit the maximum output voltage that can be delivered during a stimulation. If the output current times the impedance of the electrode is greater than the max compliance voltage then it means the full current is not being delivered to the electrode because it can not drive any more current.

Return type:

int

Returns:

the max output voltage in millivolts

read_stimulus_max_values()

Read maximum stimulus values set using set_stimulus_max_values()

Return type:

MaximumValues

Returns:

structure that will contain the current max values that are set

read_stimulus_pattern(configID)

Read stim config pattern

Reads back all of the parameters associated with a specific stimulation waveform and stores it in the structure supplied by the user.

Parameters:

configID (int) – The stimulation waveform that is being read back

Return type:

StimulusConfiguration

Returns:

structure which contains all the parameters that consist in a stimulation waveform

reset_stimulator()

Stimulator Reset

Administrative command that will call the reset interrupt vector on the uController. User will need to call connect() after calling this.

Return type:

None

classmethod scan_for_devices()

Scan for connected Cerestim devices

If only one Cerestim device is attached to PC, you can skip this step and just call connect().

Return type:

List[int]

Returns:

list of serial numbers of the connected Cerestims

property sequence_status: SeqType

Get stim sequence status

Can be read anytime as it does not interrupt other functions from executing, but simply reads what state the stimulator is in.

property serial_number: dict

Get device serial number

Retrieves the serial number that is programmed into the CereStim 96 device that is attached.

set_max_output_voltage(oc_voltage)

Set compliance voltage

This will set the values of +VDD and -VSS on the stimulator which allows it to effectively limit the maximum output voltage that can be delivered during a stimulation. If the output current times the impedance of the electrode is greater than the max compliance voltage then it means the full current is not being delivered to the electrode because it can not drive any more current.

Parameters:

oc_voltage (OCVolt) – The voltage level that is being set. Must be an oc_volt enum value.

Return type:

int

Returns:

the max output voltage in millivolts.

set_stimulus_max_values(voltage, amplitude, phaseCharge, frequency)

Set max limits

Intended to be an administrative interface that can be password protected and only allow the lead researcher to make changes. It allows the user to set other determined upper limits for the stimulation parameters for whatever safety protocol they are requiring. Again micro and macro stimulators will have some different bounds for setting max values due to the different ranges each are able to achieve.

Parameters:

• voltage (OCVolt) – The Max Compliance Voltage that can be set

• amplitude (int) – The Max amplitude that can be used in a stimulation

• phaseCharge (int) – The Max charge per phase that will be allowed (Charge = Amplitude * Width)

• frequency (int) – The Max frequency at which the stimulations can take place

Return type:

MaximumValues

Returns:

structure that will contain the current max values that are set

simple_stimulus(electrode, afcf, pulses, amp1, amp2, width1, width2, frequency, interphase)

Simplest method to manually command a stimulus pulse

Combines configure_stimulus_pattern() and manual_stimulus() into a single call. Note that the overhead of configure_stimulus_pattern() limits how quickly this can run. This method is simple, but inefficient.

Parameters:

• electrode (int) – The electrode that should be stimulated. Valid values are from 1 - 96.

• afcf (WFType) – What polarity should the first phase be, Anodic or Cathodic first

• pulses (int) – The number of stimulation pulses in waveform from 1 - 255

• amp1 (int) – The amplitude of the first phase, for Micro it is 1 - 215 uA, and for Macro it is 100 uA - 10 mA

• amp2 (int) – The amplitude of the first phase, for Micro it is 1 - 215 uA, and for Macro it is 100 uA - 10 mA

• width1 (int) – The width of the first phase in the stimulation 1 - 65,535 uS

• width2 (int) – The width of the second phase in the stimulation 1 - 65,535 uS

• frequency (int) – The stimulating frequency at which the biphasic pulses should repeat 4 - 5000 Hz

• interphase (int) – The period of time between the first and second phases 53 - 65,535 uS

Return type:

None

simple_stimulus_group(electrodes, afcf, pulses, amp1, amp2, width1, width2, frequency, interphase)

Simplest method to manually command a group stimulus pulse with identical parameters on all electrodes

Combines configure_stimulus_pattern() and group_stimulus() into a single call. Note that the overhead of configure_stimulus_pattern() limits how quickly this can run. This method is simple, but inefficient.

Parameters:

• electrodes (List[int]) – The electrodes that should be stimulated. Valid values are from 1 - 96.

• afcf (WFType) – What polarity should the first phase be, Anodic or Cathodic first

• pulses (int) – The number of stimulation pulses in waveform from 1 - 255

• amp1 (int) – The amplitude of the first phase, for Micro it is 1 - 215 uA, and for Macro it is 100 uA - 10 mA

• amp2 (int) – The amplitude of the first phase, for Micro it is 1 - 215 uA, and for Macro it is 100 uA - 10 mA

• width1 (int) – The width of the first phase in the stimulation 1 - 65,535 uS

• width2 (int) – The width of the second phase in the stimulation 1 - 65,535 uS

• frequency (int) – The stimulating frequency at which the biphasic pulses should repeat 4 - 5000 Hz

• interphase (int) – The period of time between the first and second phases 53 - 65,535 uS

Return type:

None

property stimulus_patterns_cached: dict

Cached list of configured stimulus patterns

stop()

Stop stim script execution

This will stop a currently running stimulation script and reset it so when played again it will begin from the first command. Can only be called while the stimulator has a status of stimulating or paused.

Return type:

None

stop_trigger_stimulus()

Stop trigger mode

Changes the state of the stimulator so that it is no longer waiting for a trigger. Frees up the stimulator for other commands to be called.

Return type:

None

trigger_stimulus(edge)

Start trigger mode

Allows the stimulator to wait for a trigger event before executing a stimulation script. The stimulator has an external TTL Trigger input port that uses TTL logic levels to determine whether the input is high or low. The stimulator can be set to fire on a rising edge, falling edge, or any edge transition. Once in trigger mode the stimulator is locked down from other function calls except for stop_trigger_stimulus()

Parameters:

edge (TriggerType) – The type of digital event to trigger the stimulation on

Return type:

None

update_electrode_channel_map(map)

Set electrode map

Since not all electrodes are found on channel 1 this function allows the user to create a map key pair where the channel is an index into an array which holds the value of the electrode at that channel.

Parameters:

map (ElectrodeChannelMap) – channel map structure

Return type:

None

property usb_address: int

Gets the USB address of the connected stimulator

wait(milliseconds)

Wait between stim pulses

This command can only be used within a stimulation script and is capable of adding a wait of up to 65,535 milliseconds.

Parameters:

milliseconds (int) – The number of milliseconds to wait before executing the next command

Raises:

ValueError – milliseconds must be between 0 and 65535.

Return type:

None