View source for Contributions:g.EstimSwitchingUnit

==Versioning==
[[File:g.switching-unit-device.jpg|400px|thumb|right|g.tec g.Estim Switching Unit]]
===Author===
Alexander Belsten (belsten@neurotechcenter.org)

===Version History===
* 2020/05/22: Initial release for the switching unit prototype
* 2020/01/25: Usability improvements and hardware API updated to latest version.

===Source Code Revisions===
*Initial development: 6125
*Known to compile under: 6191
*Broken since: --

==Functional Description== 
The purpose of this device and filter is to automate the process of switching channels from recording to stimulation during cortical stimulation experiments. Previously, channels had to be switched manually (unplugging electrodes from the amplifier and plugging them into a stimulator). With the switching unit and this filter, this process is automated. 

==Integration into BCI2000==
Compile the filter by enabling <code>BUILD_PRIVATE</code> in your CMake configuration. Access to the private directory in the SVN is necessary. Then compile the filter, and make <code>gEstimProSwitchingUnit</code> the filter in your batch file. 

==Parameters==
The g.EstimSwitchingUnit is configured in the filtering tab. The configurable parameters are:

===ActivateSwitchingUnit===
This parameter enables the switching unit. 

===DeviceID===
Index of the device on the system. If one switching unit is plugged into the computer this value should be 0. 

===Trigger===
There are two options for the trigger, a software trigger, and a digital trigger. 

====Software Trigger====
Channel switching is triggered when a ''SwitchExpression'' defined in the first row of the ''StimConfig'' parameter evaluates true. See the [[Contributions:g.EstimSwitchingUnit#Latency|latency]] section for details on how switching latency varies based on the number of electrode pairs that are defined. 

====Digital Trigger====
Channel switching is triggered by digital input on the back of the device, allowing for the use of foot pedals or push buttons. Only one electrode pair (one column) can be defined in the ''StimConfig'' parameter to use the digital trigger. When the digital trigger occurs, the switching configuration for that one configuration will be applied.

If trigger is set to digital, the '''SwitchExpression will not be used'''. Instead, the channels will be set to active or not based on the digital input.

===StimConfig===
<gallery mode="packed" widths=300px heights=300px>
File:switching_unit_one_electrode_pair.png|Figure 1: One electrode pair defined.
File:switching_unit_multiple_electrode_pairs.png|Figure 2: Multiple electrode pairs defined.
</gallery>

This matrix configures channel routing. The StimConfig parameter is where expressions for the software triggers and electrode pairs are defined.  Each column contains information for a specific switching configuration and the number of configurations must be configured in accordance with the trigger type. If the trigger type is set to ''Digital'', there must only be one configuration (one column) as shown in Fig. 1. If the trigger type is ''Software'', one configuration can be defined, or multiple can be defined as seen in Fig. 2. 

The cells in rows corresponding to ''Stim+ ch'' (anode) and ''Stim- ch'' (cathode) define the electrode pairs. These cells are embedded lists that can be edited by right-clicking on the list cell and selecting “Edit submatrix.” For a given configuration, the cathode and anode electrode lists must be disjoint. 
==States==
===EstimSU===
This binary state records when the switching unit is switched into the active state (<code>1</code>) and inactive state (<code>0</code>).

==Latency==
[[File:switching_unit_latency.png|600px|thumb|center|upright=2.5|Figure 3: Latency changes greatly depending on if there is one electrode pair or multiple]]

The time between a SwitchExpression evaluating true and the channels switching varies based on the number of electrode pairs. The latency is much lower if there is only one electrode pair (one column) defined in StimConfig. When more than one electrode pairs are specified, the latency increases. A comparison of these latencies can be seen in Fig. 3. The large jump in latency from one electrode pair to multiple electrode pairs is due to the fact that the expression that evaluated true must now have its corresponding anode and cathode channels uploaded to the device. In the case of one software configuration, the configuration does not need to be uploaded online because it is uploaded before the run. Checking which SwitchExpression evaluates true does not take very long, so the latency does not vary substantially when there are 2 electrode pairs defined, or 20. 

Knowing what to expect in terms of switching latency allows the experimentalist to design their stimulation montage such that the switching of channels occurs before the stimulation is applied and even add some additional time to allow the switching artifact introduced to other channels to subside.