cbSetTrigger()

Selects the trigger source and sets up its parameters. This trigger is used to initiate a scan using the following Universal Library functions:

cbAInScan(), if the EXTTRIGGER option is selected.
cbDInScan(), if the EXTTRIGGER option is selected.
cbCInScan(), if the EXTTRIGGER option is selected.
cbAPretrig()
cbFilePretrig()

Function prototype

C/C++

int cbSetTrigger(int BoardNum, int TrigType, unsigned short LowThreshold, unsigned short HighThreshold);

Visual Basic

Function cbSetTrigger(ByVal BoardNum&, ByVal TrigType&, ByVal LowThreshold%, ByVal HighThreshold%) As Long

Arguments

BoardNum

The number associated with the board when it was installed with InstaCal or created with cbCreateDaqDevice(). BoardNum may be 0 to 99. The board must have a software-selectable triggering source and/or options.

TrigType

Specifies the type of triggering based on the external trigger source. Set it to one of the constants in the TrigType argument values section below.

LowThreshold

Selects the low threshold used when the trigger input is analog. The range depends upon the resolution of the trigger circuitry. Must be 0 to 255 for 8-bit trigger circuits, 0 to 4,095 for 12-bit trigger circuits, and 0 to 65,535 for 16-bit trigger circuits. Refer to the Analog Trigger Notes section below.

When the trigger input is a digital pattern, LowThreshold selects the pattern value.

HighThreshold

Selects the high threshold used when the trigger input is analog. The range depends upon the resolution of the trigger circuitry. Must be 0 to 255 for 8-bit trigger circuits, 0 to 4,095 for 12-bit trigger circuits, and 0 to 65,535 for 16-bit trigger circuits. Refer to the Analog Trigger Notes section below.

When the trigger input is a digital pattern, HighThreshold selects the port mask.

Returns

Error code or 0 if no errors.

TrigType argument values

Trigger source	Type	Explanation
Analog	GATE_NEG_HYS	Scanning is enabled as long as the external analog trigger input is more positive than HighThreshold. Hysteresis is the level between LowThreshold and HighThreshold.
	GATE_POS_HYS	Scanning is enabled as long as the external analog trigger input is more negative than LowThreshold. Hysteresis is the level between LowThreshold and HighThreshold.
	GATE_ABOVE	Scanning is enabled as long as the external analog trigger input is more positive than HighThreshold.
	GATE_BELOW	Scanning is enabled as long as the external analog trigger input is more negative than LowThreshold.
	GATE_IN_WINDOW	Scanning is enabled as long as the external analog trigger is inside the region defined by LowThreshold and HighThreshold.
	GATE_OUT_WINDOW	Scanning is enabled as long as the external analog trigger is outside the region defined by LowThreshold and HighThreshold.
	TRIG_ABOVE	Scanning begins when the external analog trigger input transitions from below HighThreshold to above. Once conversions are enabled, the external trigger is ignored.
	TRIG_BELOW	Scanning begins when the external analog trigger input transitions from above LowThreshold to below. Once conversions are enabled, the external trigger is ignored.
	TRIG_RISING	Scanning begins when the external analog trigger input transitions from below LowThreshold to above HighThreshold. Once conversions are enabled, the external trigger is ignored.
	TRIG_FALLING	Scanning begins when the external analog trigger input transitions from above HighThreshold to below LowThreshold. Once conversions are enabled, the external trigger is ignored.
	Analog Trigger Notes The value of the threshold must be within the range of the analog trigger circuit associated with the board. Refer to the board-specific information in the Universal Library User's Guide. For example, on the PCI-DAS1602/16 the analog trigger circuit handles ±10 V. A value of 0 corresponds to –10 V, whereas a value of 65,535 corresponds to +10 V. If you are using signed integer types, the thresholds range from –32,768 to 32,767 for 16-bit boards, instead of from 0 to 65,535. In this case, the unsigned value of 65,535 corresponds to a value of –1, 65,534 corresponds to –2, …, 32,768 corresponds to –32,768. For most boards that support analog triggering, you can pass the required trigger voltage level and the appropriate range to cbFromEngUnits() function to calculate the highThreshold and lowThreshold values. For some boards, you must manually calculate the threshold: first calculate the least significant bit (LSB) for a particular range for the trigger resolution of your hardware, then use the LSB to find the threshold in counts based on an analog voltage trigger threshold. Refer below to the Manually calculating the threshold example for details. For board-specific information, refer to the Universal Library User's Guide section of the Help.
Digital	GATE_HIGH	Scanning is enabled as long as the external digital trigger input is 5V (logic HIGH or '1').
	GATE_LOW	Scanning is enabled as long as the external digital trigger input is 0V (logic LOW or '0').
	TRIG_HIGH	Scanning begins when the external digital trigger is 5V (logic HIGH or '1'). Once conversions are enabled, the external trigger is ignored.
	TRIG_LOW	Scanning begins when the external digital trigger is 0V (logic LOW or '0'). Once conversions are enabled, the external trigger is ignored.
	TRIG_PATTERN_EQ	Scanning begins when the digital port value AND bitwise mask are equal to the pattern value AND bitwise mask. Once conversions are enabled, the external trigger is ignored.
	TRIG_PATTERN_NE	Scanning begins when the digital port value AND bitwise mask are not equal to the pattern value AND bitwise mask. Once conversions are enabled, the external trigger is ignored.
	TRIG_PATTERN_ABOVE	Scanning begins when the digital port value AND bitwise mask are greater than the pattern value AND bitwise mask. Once conversions are enabled, the external trigger is ignored.
	TRIG_PATTERN_BELOW	Scanning begins when the digital port value AND bitwise mask are less than the pattern value AND bitwise mask. Once conversions are enabled, the external trigger is ignored.
	TRIG_POS_EDGE	Scanning begins when the external digital trigger transitions from 0V to 5V (logic LOW to HIGH). Once conversions are enabled, the external trigger is ignored.
	TRIG_NEG_EDGE	Scanning begins when the external digital trigger transitions from 5V to 0V (logic HIGH to LOW). Once conversions are enabled, the external trigger is ignored.
	Digtal Trigger Notes For pattern trigger types, the LowThreshold argument represents the pattern value, and the HighThreshold argument represents the port mask. Use the cbSetConfig() ConfigItem BIPATTERNTRIGPORT to set the pattern trigger port.

Manually calculating the threshold

To calculate the threshold, do the following:

Calculate the LSB by dividing the full scale range (FSR) by 2^resolution. FSR is the entire span from –FS to +FS of your hardware for a particular range. For example, the full scale range of ±10 V is 20 V.
Calculate how many times you need to add the LSB calculated in step 1 to the negative full scale (–FS) to reach the trigger threshold value.
The maximum threshold value is 2 ^resolution – 1. The formula is shown here:

Abs (–FS – threshold in volts) ÷ (LSB) = threshold in counts

Here are two examples that use this formula — one for 8-bit trigger resolution, and one for 12-bit trigger resolution:

8-bit example using the ±10 V range with a –5 V threshold:

Calculate the LSB: LSB = 20 ÷ 2⁸ = 20 ÷ 256 = 0.078125

Calculate the threshold: Abs(–10 – (–5)) ÷ 0.078125 = 5 ÷ 0.078125 = 64 (round this result if it is not an integer). A count of 64 translates to a voltage threshold of –5.0 V.

12-bit example using the ±10 V range with a +1 V threshold:

Calculate the LSB: LSB = 20 ÷ 2¹² = 20 ÷ 4096 = 0.00488

Calculate the threshold: Abs(–10 – 1) ÷ 0.00488 = 11 ÷ 0.00488 = 2254 (rounded from 2254.1). A count of 2254 translates to a voltage threshold of 0.99952 V.