br_stimpy._bstimulator.Stimulator

class Stimulator(self: br_stimpy._bstimulator.Stimulator)

Bases: pybind11_object

The stimulator class encapsulates all the functionallity of the stimulator and allows the user the ability to interface directly with Blackrock Microsystems CereStim 96 device. By encapsulating it in an object, multiple stimulators can be connected to a single Host PC and be used simultaneously.

Creates a stimulator object that is able to bind to an actual CereStim 96 that is connected to the host PC.

Methods

`auto_stimulus`	This command tells the stimulator when to send a stimulus to an electrode in a stimulation script.
`beginning_of_group`	This command signifies that the following commands up to the endOfGroup command should all occur simultaneously.
`beginning_of_sequence`	This is the first command that must be called when creating a stimulation script.
`configure_stimulus_pattern`	Takes all of the parameters needed in order to create a custom biphasic stimulation waveform.
`connect`	Tries to establish a connection with a CereStim 96 device that has been selected using setDevice().
`disable_module`	Allows the user to disable different current modules that are installed in the CereStim.
`disable_stimulus_configuration`	Disables a stimulation waveform so that it is able to be reset
`disconnect`	Disconnects from a connected CereStim 96 device.
`enable_module`	Allows the user to enable different current modules that have been disabled.
`end_of_group`	This command closes off a group of simultaneous stimulations.
`end_of_sequence`	This is the last command that must be called when creating a stimulation script.
`erase_eeprom`	Erases the complete EEProm on the the CereStim 96 motherboard, setting all values to 0xFF
`get_interface`	Checks to see what interface is being used for the connection between the stimulator object and the physical CereStim 96 Device.
`get_max_hard_charge`	This value is based on the hardware of the particuliar model of the CereStim 96.
`get_max_hard_frequency`	This value is based on the hardware of the particuliar model of the CereStim 96.
`get_max_hard_interphase`	This value is based on the hardware of the particuliar model of the CereStim 96
`get_max_hard_width`	This value is based on the hardware of the particuliar model of the CereStim 96.
`get_min_hard_frequency`	This value is based on the hardware of the particuliar model of the CereStim 96.
`get_min_max_amplitude`	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.
`get_module_firmware_version`	Each current module has its own microcontroller and has a firmware version.
`get_module_status`	This tells the status of each current module, whether it is enabled, disabled, or not available.
`get_motherboard_firmware_version`	Retrieves the firmware revision of the microcontroller on the motherboard.
`get_number_modules`	This value is based on the hardware of the particuliar model of the CereStim 96.
`get_protocol_version`	The protocol version that the motherboard uses to send and receive data from the current modules.
`get_serial_number`	Retrieves the serial number that is programmed into the CereStim 96 device that is attached.
`get_usb_address`
`group_stimulus`	There is a lot of overhead in sending commands over the USB to the CereStim 96.
`is_connected`	Lets the user know that the stimulator object is connected to a physical CereStim 96 device.
`is_device_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.
`is_safety_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.
`lib_version`	Takes a pointer to a BVersion structure and writes the libarary version to the structure.
`manual_stimulus`	Allows the user to send a single stimulus pulse of one of the stimulation waveforms to a specified electrode.
`max_output_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.
`measure_output_voltage`	Sends a known stimulation configuration, 45 uA for micro and 9 mA for Macro, from a selected current module to a specific module.
`pause`	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.
`play`	Tells the stimulator the number of times that it should run the stimulation script.
`read_device_info`	This returns all the information about the CereStim 96 that is connected to.
`read_eeprom`	Reads the CereStim 96 motherboards EEprom and returns all values
`read_hardware_values`	Reads the hardware values that are set based on the part number
`read_sequence_status`	Can be called anytime as it does not interrupt other functions from executing, but simply reads what state the stimulator is in.
`read_stimulus_pattern`	Reads back all of the parameters associated with a specific stimulation waveform and stores it in the structure supplied by the user
`reset_stimulator`	Administrative command that will call the reset interrupt vector on the uController User will need to call Connect after calling this.
`scan_for_devices`	Scans all USB devices and builds up a list of serial numbers of the devices connected to the computer.
`set_device`	Using the index of the device in the serial number list obtained from scanForDevices(), set the device you want to connect.
`stimulus_max_values`	Intended to be an administrative interface that can be password protected and only allow the lead researcher to make changes.
`stop`	This will stop a currently running stimulation script and reset it so when played again it will begin from the first command.
`stop_trigger_stimulus`	Changes the state of the stimulator so that it is no longer waiting for a trigger.
`test_electrodes`	This is a diagnostic tool that can be used to help determine which electrodes are good and which ones are bad.
`test_modules`	Used as a way to diagnose the current modules that reside in the stimulator to determine if there output voltage levels are okay and ensure that they continue to function at the right levels over time.
`trigger_stimulus`	Allows the stimulator to wait for a trigger event before executing a stimulation script.
`update_electrode_channel_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.
`wait`	This command can only be used within a stimulation script and is capable of adding a wait of up to 65,535 milliseconds.
`write_eeprom`

auto_stimulus(self: br_stimpy._bstimulator.Stimulator, electrode: int, configID: br_stimpy._bstimulator.Config) → br_stimpy._bstimulator.ResultType

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 beginningOfGroup and endOfGroup commands to allow for simultaneous stimulations.

electrode: The electrode that will be stimulated Valid values are from 1 - 96 configID: One of the fifteen stimulation waveforms that should be used

beginning_of_group(self: br_stimpy._bstimulator.Stimulator) → br_stimpy._bstimulator.ResultType: This command signifies that the following commands up to the endOfGroup command should all occur simultaneously. The only commands that are valid are the autoStimulus commands. You can only have as many stimulations as the number of current modules installed. Cant be called on the last of the 128 instructions since it needs to have a closing endOfGroup command.

beginning_of_sequence(self: br_stimpy._bstimulator.Stimulator) → br_stimpy._bstimulator.ResultType: This is the first command that must be called when creating a stimulation script. After calling this you are able to call wait, autoStimulus, beginningOfGroup, and endOfGroup commands. The stimulation script can have up to 128 commands, excluding beginningOfSequence and endOfSequence

configure_stimulus_pattern(self: br_stimpy._bstimulator.Stimulator, configID: br_stimpy._bstimulator.Config, afcf: br_stimpy._bstimulator.WFType, pulses: int, amp1: int, amp2: int, width1: int, width2: int, frequency: int, interphase: int) → br_stimpy._bstimulator.ResultType

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.

configID: The stimulation waveform that is being configured 1 - 15 afcf: What polarity should the first phase be, Anodic or Cathodic first pulses: The number of stimulation pulses in waveform from 1 - 255 amp1: The amplitude of the first phase, for Micro it is 1 - 215 uA, and for Macro it is 100 uA - 10 mA amp2: The amplitude of the first phase, for Micro it is 1 - 215 uA, and for Macro it is 100 uA - 10 mA width1: The width of the first phase in the stimulation 1 - 65,535 uS width2: The width of the second phase in the stimulation 1 - 65,535 uS frequency1: The stimulating frequency at which the biphasic pulses should repeat 4 - 5000 Hz interphase: The period of time between the first and second phases 53 - 65,535 uS

connect(self: br_stimpy._bstimulator.Stimulator, stim_interface: br_stimpy._bstimulator.InterfaceType, params: capsule) → br_stimpy._bstimulator.ResultType

Tries to establish a connection with a CereStim 96 device that has been selected using setDevice().

stim_interface: The type of interface that the object should try and connect over params: A void pointer to either an initialized BUsbParams structure or initialized BRs232Params structure

disable_module(self: br_stimpy._bstimulator.Stimulator, module: int) → br_stimpy._bstimulator.ResultType

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.

module: The current module to be disabled from 0 to 15

disable_stimulus_configuration(self: br_stimpy._bstimulator.Stimulator, config_id: int) → br_stimpy._bstimulator.ResultType

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

config_id: The configuration to disable

disconnect(self: br_stimpy._bstimulator.Stimulator) → br_stimpy._bstimulator.ResultType: Disconnects from a connected CereStim 96 device.

enable_module(self: br_stimpy._bstimulator.Stimulator, module: int) → br_stimpy._bstimulator.ResultType

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.

module: The current module to be enabled from 0 to 15

end_of_group(self: br_stimpy._bstimulator.Stimulator) → br_stimpy._bstimulator.ResultType: This command closes off a group of simultaneous stimulations. If beginningOfGroup is called during a sequence of commands, then there must be an endOfGroup otherwise the user will get a sequence error as a return value.

end_of_sequence(self: br_stimpy._bstimulator.Stimulator) → br_stimpy._bstimulator.ResultType: This is the last command that must be called when creating a stimulation script. It does not count towards the maximum of 128 commands.

erase_eeprom(self: br_stimpy._bstimulator.Stimulator) → br_stimpy._bstimulator.ResultType: Erases the complete EEProm on the the CereStim 96 motherboard, setting all values to 0xFF

get_interface(self: br_stimpy._bstimulator.Stimulator) → br_stimpy._bstimulator.InterfaceType

Checks to see what interface is being used for the connection between the stimulator object and the physical CereStim 96 Device.

Returns: The interface being used for the stimulator object

get_max_hard_charge(self: br_stimpy._bstimulator.Stimulator) → int: This value is based on the hardware of the particuliar model of the CereStim 96. Again the micro and macro versions of the stimulator have different values

get_max_hard_frequency(self: br_stimpy._bstimulator.Stimulator) → int

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

Returns: Maximum Stimulating Frequency in Hz

get_max_hard_interphase(self: br_stimpy._bstimulator.Stimulator) → int

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

Maximum interphase width in uS

get_max_hard_width(self: br_stimpy._bstimulator.Stimulator) → int

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

Returns: Maximum width of each phase in uS

get_min_hard_frequency(self: br_stimpy._bstimulator.Stimulator) → int

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

Returns: Minimum Stimulating Frequency in Hz

get_min_max_amplitude(self: br_stimpy._bstimulator.Stimulator) → int

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. The upper two MSB are the maximum amplitude while the lower two LSB are the minimum amplitude.

Returns: Min and Max Amplitude.

get_module_firmware_version(self: br_stimpy._bstimulator.Stimulator) → Annotated[list[int], FixedSize(16)]: 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

get_module_status(self: br_stimpy._bstimulator.Stimulator) → Annotated[list[int], FixedSize(16)]: This tells the status of each current module, whether it is enabled, disabled, or not available.

get_motherboard_firmware_version(self: br_stimpy._bstimulator.Stimulator) → int

Retrieves the firmware revision of the microcontroller on the motherboard. The MSB is the Major revision number and the LSB is the minor revision number. I.e. 0x0500 would be version 5.0

Returns: Firmware Version of the Motherboard

get_number_modules(self: br_stimpy._bstimulator.Stimulator) → int

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

Returns: Number of Modules installed

get_protocol_version(self: br_stimpy._bstimulator.Stimulator) → int

The protocol version that the motherboard uses to send and receive data from the current modules. The MSB is the Major revision number and the LSB is the minor revision number. I.e. 0x0105 would be version 1.5

Returns: Protocol Version of the Motherboard

get_serial_number(self: br_stimpy._bstimulator.Stimulator) → int

Retrieves the serial number that is programmed into the CereStim 96 device that is attached. The format of the 32 bit serial number is as follows 0xPPXXSSSS, where PP is the part number, XX is ignored, and SSSS is the serial number. The part number is a BPartNumbers enumeration.

Returns: Part Number and Serial number of the CereStim 96

get_usb_address(self: br_stimpy._bstimulator.Stimulator) → int

group_stimulus(self: br_stimpy._bstimulator.Stimulator, begin_seq: int, play: int, times: int, number: int, input: br_stimpy._bstimulator.GroupStimulus) → br_stimpy._bstimulator.ResultType

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.

begin_seq: Boolean expression to tell the function that it is the beginning of a sequence play: Boolean expression to tell if the stimulator should begin stimulating immedieatly after this call times: The number of times to play the stimulation, is ignored if play = false number: The number of stimulus that will occur simultaneously. input: Pointer to an instantiated BGroupStimulus structure which has a pair of arrays with electrodes and waveforms

is_connected(self: br_stimpy._bstimulator.Stimulator) → int

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

Returns: a boolean result, 1 = TRUE, 0 = FALSE

is_device_locked(self: br_stimpy._bstimulator.Stimulator) → int

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.

Returns: true if locked false otherwise

is_safety_disabled(self: br_stimpy._bstimulator.Stimulator) → int

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.

Returns: true if disabled false otherwise

lib_version(self: br_stimpy._bstimulator.Stimulator, output: br_stimpy._bstimulator.Version) → br_stimpy._bstimulator.ResultType: Takes a pointer to a BVersion structure and writes the libarary version to the structure.

manual_stimulus(self: br_stimpy._bstimulator.Stimulator, electrode: int, configID: br_stimpy._bstimulator.Config) → br_stimpy._bstimulator.ResultType

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

electrode: The electrode that should be stimulated Valid values are from 1 - 96 configID: The stimulation waveform to use Valid values are from 1 - 15

max_output_voltage(self: br_stimpy._bstimulator.Stimulator, output: br_stimpy._bstimulator.MaxOutputVoltage, rw: int, voltage: br_stimpy._bstimulator.OCVolt) → br_stimpy._bstimulator.ResultType

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 deliverd to the electrode because it can not drive any more current.

output: Pointer to a BMaxOutputVoltage structure that will contain the read value rw: Boolean expression for determining if you just want to read the output compliance voltage or update it with a new value Read = 0 and Write = 1 voltage: The voltage level that is being set if writing, otherwise it is ignored

measure_output_voltage(self: br_stimpy._bstimulator.Stimulator, output: br_stimpy._bstimulator.OutputMeasurement, module: int, electrode: int) → br_stimpy._bstimulator.ResultType

Sends a known stimulation configuration, 45 uA for micro and 9 mA for Macro, from a selected current module to a specific module. It is helpful for determining the impedance of the electrode.

output: A pointer to a BOutpuMeasurment structure to store the returned measurement values module: The specific current module (0 - 15) that should send the stimulus The module must be enabled. electrode: The electrode to send the stimulation to Valid values are from 1 - 96

pause(self: br_stimpy._bstimulator.Stimulator) → br_stimpy._bstimulator.ResultType: 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.

play(self: br_stimpy._bstimulator.Stimulator, times: int) → br_stimpy._bstimulator.ResultType

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

times: Number of times to execute the stimulation script 0 means indefinately

read_device_info(self: br_stimpy._bstimulator.Stimulator, output: br_stimpy._bstimulator.DeviceInfo) → br_stimpy._bstimulator.ResultType

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.

output: Pointer to a BDeviceInfo structure, the structure will be populated with the CereStim’s information

read_eeprom(self: br_stimpy._bstimulator.Stimulator, output: br_stimpy._bstimulator.ReadEEPROMOutput) → br_stimpy._bstimulator.ResultType

Reads the CereStim 96 motherboards EEprom and returns all values

output: Pointer to array of UINT8[256]

read_hardware_values(self: br_stimpy._bstimulator.Stimulator, output: br_stimpy._bstimulator.ReadHardwareValuesOutput) → br_stimpy._bstimulator.ResultType

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

output: Structure containing the hardware values

read_sequence_status(self: br_stimpy._bstimulator.Stimulator, output: br_stimpy._bstimulator.SequenceStatus) → br_stimpy._bstimulator.ResultType

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

output: Pointer to a BSequenceStatus that gets populate with the value from the CereStim 96

read_stimulus_pattern(self: br_stimpy._bstimulator.Stimulator, output: br_stimpy._bstimulator.StimulusConfiguration, configID: br_stimpy._bstimulator.Config) → br_stimpy._bstimulator.ResultType

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

output: Pointer to a BStimulusConfiguration structure which contains all the parameters that consist in a stimulation waveform configID: The stimulation waveform that is being read back

reset_stimulator(self: br_stimpy._bstimulator.Stimulator) → br_stimpy._bstimulator.ResultType: Administrative command that will call the reset interrupt vector on the uController User will need to call Connect after calling this.

static scan_for_devices() → br_stimpy._bstimulator.vector_UINT32: Scans all USB devices and builds up a list of serial numbers of the devices connected to the computer. In order to connect to a device, this function has to be invoked first, then a device needs to be selected through setDevice() and only then connect()

set_device(self: br_stimpy._bstimulator.Stimulator, device_index: int) → br_stimpy._bstimulator.ResultType: Using the index of the device in the serial number list obtained from scanForDevices(), set the device you want to connect.

stimulus_max_values(self: br_stimpy._bstimulator.Stimulator, output: br_stimpy._bstimulator.MaximumValues, rw: int, voltage: br_stimpy._bstimulator.OCVolt, amplitude: int, phase_charge: int, frequency: int) → br_stimpy._bstimulator.ResultType

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 requireing. Again micro and macro stimulators will have some different bounds for setting max values due to the different ranges each are able to achieve.

output: Pointer to a BMaximumValues structure that will contain the current max values that are set rw: Boolean to determine if updating new max values or just reading the old Read = 0 and Write = 1 voltage: The Max Compliance Voltage that can be set amplitude: The Max amplitude that can be used in a stimulation phase_charge: The Max charge per phase that will be allowed (Charge = Amplitude * Width) frequency: The Max frequency at which the stimulations can take place

stop(self: br_stimpy._bstimulator.Stimulator) → br_stimpy._bstimulator.ResultType: 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.

stop_trigger_stimulus(self: br_stimpy._bstimulator.Stimulator) → br_stimpy._bstimulator.ResultType: 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.

test_electrodes(self: br_stimpy._bstimulator.Stimulator, output: br_stimpy._bstimulator.TestElectrodes) → br_stimpy._bstimulator.ResultType

This is a diagnostic tool that can be used to help determine which electrodes are good and which ones are bad. The stimulator will send out a known stimulus configuration, (Config_0), and measure the voltage it returns. Off of these values the relative impedance calculated and returned.

output: Pointer to a BTestElectrodes Structure which will contain all the information from all the channels.

test_modules(self: br_stimpy._bstimulator.Stimulator, output: br_stimpy._bstimulator.TestModules) → br_stimpy._bstimulator.ResultType

Used as a way to diagnose the current modules that reside in the stimulator to determine if there output voltage levels are okay and ensure that they continue to function at the right levels over time. A known stimulus is applied to a known load and the voltage is compared to what it should be.

output: Pointer to a BTestModules structure which will contain the status of all the current modules

trigger_stimulus(self: br_stimpy._bstimulator.Stimulator, edge: br_stimpy._bstimulator.TriggerType) → br_stimpy._bstimulator.ResultType

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 wheather 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 stopTriggerStimulus

edge: The type of digital event to trigger the stimulation on

update_electrode_channel_map(self: br_stimpy._bstimulator.Stimulator, input: br_stimpy._bstimulator.ElectrodeChannelMap) → br_stimpy._bstimulator.ResultType: 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.

wait(self: br_stimpy._bstimulator.Stimulator, milliseconds: int) → br_stimpy._bstimulator.ResultType

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

milliseconds: The number of milliseconds to wait before executing the next command

write_eeprom(self: br_stimpy._bstimulator.Stimulator, addr: int, val: int) → br_stimpy._bstimulator.ResultType