FFI: Add functions for clamp, headstage and TP control

Added the following functions:

FFI_GetClampState
returns a wave with the current clamp control values

FFI_SetClampMode

FFI_SetHoldingPotential
- allowed only in VC mode

FFI_SetBiasCurrent
- allowed only in IC mode

FFI_SetAutoBias
- allowed only in IC mode

FFI_SetHeadstageActive
- allowed only when no DAQ is running

FFI_SetTestPulseEnable
- allowed only when no DAQ is running

FFI_TriggerAutoClampControl
- wraps Pipette, Capacitance and Bridge Balance auto setting in a single call

Author: MichaelHuth

Packages/MIES/MIES_ForeignFunctionInterface.ipf

@@ -9,6 +9,14 @@
 /// @file MIES_ForeignFunctionInterface.ipf
 /// @brief __FFI__ ACQ4/ZeroMQ accessible functions
 
+/// @name Auto Clamp Ctrls enum for FFI_TriggerAutoClampControl
+/// @anchor FFI_AutoClampCtrls
+///@{
+static Constant AUTO_PIPETTE       = 1
+static Constant AUTO_CAPACITANCE   = 2
+static Constant AUTO_BRIDGEBALANCE = 3
+///@}
+
 /// @brief Function to return Peak Resistance, Steady State Resistance to ACQ4 (Neurophysiology Acquisition and Analysis System.
 /// See http://acq4.org/ for more details)
 ///
@@ -323,3 +331,242 @@ Function FFI_TestPulseMDSingleResult(string device, variable action)
 
 	return ret
 End
+
+/// @brief Returns the clamp state of a headstage of a locked device
+///
+/// The clamp state wave is DP numeric wave and has 11 elements with the following information
+/// - non-applicable values for the current clamp mode are NaN
+/// - if the requested head stage is not active then clamp mode returned NaN
+///
+/// \rst
+/// +-------+------------------------+----------------------------+----------+----------+------------+
+/// | Index | Label                  | Value description          | Units VC | Units IC | Units I=0  |
+/// +=======+========================+============================+==========+==========+============+
+/// | 0     | Mode                   | Clamp Mode                 |          |          |            |
+/// |       |                        | 0 : VC                     |          |          |            |
+/// |       |                        | 1 : IC                     |          |          |            |
+/// |       |                        | 2 : I=0                    |          |          |            |
+/// |       |                        | NaN : headstage not active |          |          |            |
+/// +-------+------------------------+----------------------------+----------+----------+------------+
+/// | 1     | HoldingPotential       |                            | mV       | pA       | pA         |
+/// +-------+------------------------+----------------------------+----------+----------+------------+
+/// | 2     | HoldingPotentialEnable | 1 : On 0: Off              | On/Off   | On/Off   | On/Off     |
+/// +-------+------------------------+----------------------------+----------+----------+------------+
+/// | 3     | BiasCurrent            |                            | mV       | pA       | pA         |
+/// +-------+------------------------+----------------------------+----------+----------+------------+
+/// | 4     | BiasCurrentEnable      | 1 : On 0: Off              | On/Off   | On/Off   | On/Off     |
+/// +-------+------------------------+----------------------------+----------+----------+------------+
+/// | 5     | AutoBiasVcom           |                            | mV       | mV       | mV         |
+/// +-------+------------------------+----------------------------+----------+----------+------------+
+/// | 6     | AutoBiasVcomVariance   |                            | mV       | mV       | mV         |
+/// +-------+------------------------+----------------------------+----------+----------+------------+
+/// | 7     | AutoBiasIbiasmax       |                            | pA       | pA       | pA         |
+/// +-------+------------------------+----------------------------+----------+----------+------------+
+/// | 8     | AutoBiasEnable         | 1 : On 0: Off              | On/Off   | On/Off   | On/Off     |
+/// +-------+------------------------+----------------------------+----------+----------+------------+
+/// | 9     | PipetteOffsetVC        |                            | mV       | mV       | mV         |
+/// +-------+------------------------+----------------------------+----------+----------+------------+
+/// | 10    | PipetteOffsetIC        |                            | mV       | mV       | mV         |
+/// +-------+------------------------+----------------------------+----------+----------+------------+
+/// \endrst
+///
+/// @param[in] device    Device title, e.g. "Dev1"
+/// @param[in] headstage headstage number
+/// @returns             wave with clamp state
+Function/WAVE FFI_GetClampState(string device, variable headstage)
+
+	variable clampMode
+	string stateList = "Mode;HoldingPotential;HoldingPotentialEnable;BiasCurrent;BiasCurrentEnable;AutoBiasVcom;AutoBiasVcomVariance;AutoBiasIbiasmax;AutoBiasEnable;PipetteOffsetVC;PipetteOffsetIC;"
+
+	FFI_CheckValidDeviceAndHeadstage(device, headstage)
+
+	Make/FREE/D/N=(ItemsInList(stateList)) clampState
+
+	SetDimensionLabels(clampState, stateList, ROWS)
+	FastOp clampState = (NaN)
+
+	if(!DAG_GetHeadstageState(device, headstage))
+		return clampState
+	endif
+
+	clampMode         = DAG_GetHeadstageMode(device, headstage)
+	clampState[%Mode] = clampMode
+
+	WAVE/T stateNames = ListToTextWave(stateList, ";")
+	clampState[1,] = DAG_GetNumericalValue(device, AI_MapFunctionConstantToControl(AI_MapNameToFunctionConstant(stateNames[p]), clampMode))
+
+	Duplicate/FREE/T stateNames, units
+	units[1,] = AI_GetUnitForFunctionConstant(AI_MapNameToFunctionConstant(stateNames[p]), clampMode)
+
+	return clampState
+End
+
+/// @brief Triggers an auto clamp control
+///
+/// @param[in] device    Device title, e.g. "Dev1"
+/// @param[in] headstage headstage number
+/// @param[in] autoCtrl  auto control number @ref FFI_AutoClampCtrls
+Function FFI_TriggerAutoClampControl(string device, variable headstage, variable autoCtrl)
+
+	variable clampMode
+
+	FFI_CheckValidDeviceAndHeadstage(device, headstage)
+
+	clampMode = DAG_GetHeadstageMode(device, headstage)
+
+	if(autoCtrl == AUTO_PIPETTE)
+		AI_WriteToAmplifier(device, headstage, clampMode, MCC_AUTOPIPETTEOFFSET_FUNC, 1, GUIWrite = 0)
+	elseif(autoCtrl == AUTO_CAPACITANCE)
+		AI_WriteToAmplifier(device, headstage, V_CLAMP_MODE, MCC_AUTOWHOLECELLCOMP_FUNC, 1, GUIWrite = 0)
+	elseif(autoCtrl == AUTO_BRIDGEBALANCE)
+		AI_WriteToAmplifier(device, headstage, I_CLAMP_MODE, MCC_AUTOBRIDGEBALANCE_FUNC, 1, GUIWrite = 0)
+	else
+		FATAL_ERROR("Unknown auto clamp control")
+	endif
+End
+
+/// @brief Sets clamp mode
+///
+/// @param[in] device    Device title, e.g. "Dev1"
+/// @param[in] headstage headstage number
+/// @param[in] clampMode clamp mode @ref AmplifierClampModes
+Function FFI_SetClampMode(string device, variable headstage, variable clampMode)
+
+	FFI_CheckValidDeviceAndHeadstage(device, headstage)
+	ASSERT(AI_IsValidClampMode(clampMode), "Invalid clamp mode: " + num2istr(clampMode))
+
+	DAP_SetClampMode(device, headstage, clampMode)
+End
+
+/// @brief Sets Holding Potential
+///
+/// @param[in] device    Device title, e.g. "Dev1"
+/// @param[in] headstage headstage number
+/// @param[in] potential holding potential in mV when current clamp mode of headstage is VC, bias current in pA when current clamp mode of headstage is IC
+Function FFI_SetHoldingPotential(string device, variable headstage, variable potential)
+
+	variable clampMode
+
+	FFI_CheckValidDeviceAndHeadstage(device, headstage)
+
+	clampMode = DAG_GetHeadstageMode(device, headstage)
+	ASSERT(clampMode == V_CLAMP_MODE, "Attempt to set holding potential but current clamp mode is not VC !")
+	ASSERT(!IsNaN(potential), "potential argument is NaN")
+
+	FFI_SetHolding(device, headstage, clampMode, potential)
+End
+
+/// @brief Sets Bias Current
+///
+/// @param[in] device      Device title, e.g. "Dev1"
+/// @param[in] headstage   headstage number
+/// @param[in] biasCurrent bias current in pA
+Function FFI_SetBiasCurrent(string device, variable headstage, variable biasCurrent)
+
+	variable clampMode
+
+	FFI_CheckValidDeviceAndHeadstage(device, headstage)
+
+	clampMode = DAG_GetHeadstageMode(device, headstage)
+	ASSERT(clampMode == I_CLAMP_MODE, "Attempt to set holding potential but current clamp mode is not IC !")
+	ASSERT(!IsNaN(biasCurrent), "bias current argument is NaN")
+
+	FFI_SetHolding(device, headstage, clampMode, biasCurrent)
+End
+
+static Function FFI_SetHolding(string device, variable headstage, variable clampMode, variable value)
+
+	AI_WriteToAmplifier(device, headstage, clampMode, MCC_HOLDING_FUNC, value, GUIWrite = 0)
+End
+
+static Function FFI_CheckValidDeviceAndHeadstage(string device, variable headstage)
+
+	ASSERT(!DAP_DeviceIsUnlocked(device), "Target device is not locked:" + device)
+	ASSERT(IsValidHeadstage(headstage), "Invalid headStage index: " + num2str(headstage))
+End
+
+/// @brief Sets Auto Bias
+///
+/// @param[in] device    Device title, e.g. "Dev1"
+/// @param[in] headstage headstage number
+/// @param[in] potential Vm in mV in the range -99 mV to 99 mV
+/// @param[in] enable    when set to 1 then auto bias gets enabled, 0 disabled
+Function FFI_SetAutoBias(string device, variable headstage, variable potential, variable enable)
+
+	variable clampMode
+
+	enable = !!enable
+
+	FFI_CheckValidDeviceAndHeadstage(device, headstage)
+
+	clampMode = DAG_GetHeadstageMode(device, headstage)
+	ASSERT(clampMode == I_CLAMP_MODE, "Attempt to set auto bias but current clamp mode is not IC !")
+	ASSERT(!IsNaN(potential) && potential > -100 && potential < 100, "Potential out of range")
+
+	AI_WriteToAmplifier(device, headstage, clampMode, MCC_NO_AUTOBIAS_V_FUNC, potential, GUIWrite = 0)
+	AI_WriteToAmplifier(device, headstage, clampMode, MCC_NO_AUTOBIAS_ENABLE_FUNC, enable, GUIWrite = 0)
+End
+
+/// @brief Enables/Disables a headstage
+///
+/// The headstage state can not be changed while a data acquisition is running
+///
+/// @param[in] device    Device title, e.g. "Dev1"
+/// @param[in] headstage headstage number
+/// @param[in] enable    when set to 1 the headstage gets enabled, 0 disabled
+/// @returns 0 when successful
+Function FFI_SetHeadstageActive(string device, variable headstage, variable enable)
+
+	string ctrlName
+
+	enable = !!enable
+
+	FFI_CheckValidDeviceAndHeadstage(device, headstage)
+
+	ctrlName = "Check_DataAcqHS_" + num2str(headstage, "%02d")
+	PGC_SetAndActivateControl(device, ctrlName, val = enable)
+
+	return 0
+End
+
+/// @brief Enables/Disables a TestPulse
+///
+/// TestPulse can only be enabled when there is no data acquisition running
+///
+/// @param[in] device    Device title, e.g. "Dev1"
+/// @param[in] headstage headstage number
+/// @param[in] enable    when set to 1 the headstage gets enabled, 0 disabled
+/// @returns 0 when successful
+Function FFI_SetTestPulseEnable(string device, variable headstage, variable enable)
+
+	string   ctrlName
+	variable tpIsRunning
+
+	enable = !!enable
+
+	FFI_CheckValidDeviceAndHeadstage(device, headstage)
+
+	NVAR dataAcqRunMode = $GetDataAcqRunMode(device)
+	if(dataAcqRunMode != DAQ_NOT_RUNNING)
+		return 1
+	endif
+
+	tpIsRunning = TP_CheckIfTestpulseIsRunning(device)
+	if(!enable)
+		if(tpIsRunning)
+			TP_StopTestPulse(device)
+		endif
+
+		return 0
+	endif
+
+	if(!tpIsRunning)
+		if(DAG_GetNumericalValue(device, "check_Settings_MD"))
+			TPM_StartTestPulseMultiDevice(device)
+		else
+			TPS_StartTestPulseSingleDevice(device)
+		endif
+	endif
+
+	return 0
+End