xPCI-3016 API
xPCI-3016 Analog inputs/outputs functions

Functions

_INT_ i_PCI3016_SetAnalogInputMode (HANDLE h_DeviceHandle, BYTE b_InputMode)
 
_INT_ i_PCI3016_GetAnalogInputMode (HANDLE h_DeviceHandle, PBYTE pb_InputMode)
 
_INT_ i_PCI3016_InitAndStartAnalogInputSequence (HANDLE deviceHandle, DWORD sequenceCount, DWORD sequenceBeforeInterrupt, BYTE sequenceSize, PBYTE channels, PBYTE gain, PBYTE polarity, DWORD convertionTime, DWORD delayTime, BYTE softwareTriggerMode, BYTE hardwareTriggerMode, DWORD sequenceTriggerCount)
 
_INT_ i_PCI3016_ReadMoreAnalogInputs (HANDLE h_DeviceHandle, BYTE b_ChannelCount, PBYTE pb_Channel, PBYTE pb_Gain, PBYTE pb_Polarity, DWORD dw_ConvertingTime, BYTE b_InterruptFlag, BYTE b_SoftTriggerMode, BYTE b_ExtTriggerMode, PWORD pw_ChannelValue)
 
_INT_ i_PCI3016_Read1AnalogInput (HANDLE h_DeviceHandle, BYTE b_Channel, BYTE b_Gain, BYTE b_Polarity, DWORD dw_ConvertingTime, BYTE b_InterruptFlag, BYTE b_SoftTriggerMode, BYTE b_ExtTriggerMode, PWORD pw_ChannelValue)
 
_INT_ i_PCI3016_InitAndStartAutoRefreshAcquisition (HANDLE h_DeviceHandle, BYTE b_ChannelCount, PBYTE pb_Channel, PBYTE pb_Gain, PBYTE pb_Polarity, DWORD dw_ConvertingTime, PDWORD *ppdw_Channels)
 
_INT_ i_PCI3016_StopAnalogAcquisition (HANDLE h_DeviceHandle)
 
_INT_ i_PCI3016_TriggerAnalogAcquisition (HANDLE h_DeviceHandle)
 
_INT_ i_PCI3016_GetAnalogInputChannelsNbr (HANDLE h_DeviceHandle, PBYTE pb_NumberOfInputChannels)
 
_INT_ i_PCI3016_GetAnalogInputResolution (HANDLE h_DeviceHandle, PBYTE pb_Resolution)
 
_INT_ i_PCI3016_GetAnalogInputTriggerStatus (HANDLE h_DeviceHandle, PULONG softwareTriggerStatus, PULONG hardwareTriggerStatus)
 
_INT_ i_PCI3016_ReleaseHardwareTriggerWaitingRead (HANDLE deviceHandle)
 
_INT_ i_PCI3016_ReleaseSoftwareTriggerWaitingRead (HANDLE deviceHandle)
 
_INT_ i_PCI3016_GetConvertionTimeInMicroSeconds (DWORD *convertionTime, BYTE convertionTimeUnit)
 

Detailed Description

Function Documentation

_INT_ i_PCI3016_SetAnalogInputMode ( HANDLE  h_DeviceHandle,
BYTE  b_InputMode 
)

Set analog input mode to single-ended or differential input
The input mode has to be set at least once before any call to an analog input function.
Once set, the configuration will last until the program ends, or another mode is set.

In single-ended mode, 16 analog inputs are available.
In differential mode, there are only 8 analog inputs available.
Please refer to the manual for further information.

Parameters
[in]h_DeviceHandleHandle of the board
[in]b_InputModeInput mode (PCI3016_INPUT_MODE_SINGLE_ENDED or PCI3016_INPUT_MODE_DIFFERENTIAL)
Return values
0: No Error
-1: The device handle parameter is wrong
-2: Invalid input mode
_INT_ i_PCI3016_GetAnalogInputMode ( HANDLE  h_DeviceHandle,
PBYTE  pb_InputMode 
)

Get analog input mode (single-ended or differential input)

In single-ended mode, 16 analog inputs are available.
In differential mode, there are only 8 analog inputs available.
Please refer to the manual for further information.

Parameters
[in]h_DeviceHandleHandle of the board
[out]pb_InputModeInput mode (PCI3016_INPUT_MODE_UNDEFINED, PCI3016_INPUT_MODE_SINGLE_ENDED or PCI3016_INPUT_MODE_DIFFERENTIAL)
Return values
0: No Error
-1: The device handle parameter is wrong
_INT_ i_PCI3016_InitAndStartAnalogInputSequence ( HANDLE  deviceHandle,
DWORD  sequenceCount,
DWORD  sequenceBeforeInterrupt,
BYTE  sequenceSize,
PBYTE  channels,
PBYTE  gain,
PBYTE  polarity,
DWORD  convertionTime,
DWORD  delayTime,
BYTE  softwareTriggerMode,
BYTE  hardwareTriggerMode,
DWORD  sequenceTriggerCount 
)

Initialize and starts an analog acquisition
To use this function you must set an interrupt routine where you will handle the data, and you must also define the input mode.
Gain acts as a multiplier for the input voltage. Possible gain values are :

  • PCI3016_GAIN_1 : Input range is between -10V and 10V (bipolar)
  • PCI3016_GAIN_2 : Input range is between -5V and 5V (bipolar)
  • PCI3016_GAIN_5 : Input range is between -2V and 2V (bipolar)
  • PCI3016_GAIN_10 : Input range is between -1V and 1V (bipolar)

The converting time stands for the time spent to acquire one channel. The time to acquire a sequence is dw_ConvertingTime * b_ChannelCount
The software trigger is a combination of 2 parameters

  • The first one enables or disabled the trigger
    • PCI3016_SOFT_TRIGGER_ENABLED : The trigger is enabled
    • PCI3016_SOFT_TRIGGER_DISABLED : The trigger is disabled
  • The trigger type is selected with one of the following parameters
    • PCI3016_TRIGGER_ONE_SHOT : The acquisition starts when the trigger is set
    • PCI3016_TRIGGER_SEQUENCE_TRIGGER : A pre-defined number of sequence is acquired : dw_SequenceTriggerCount
    • PCI3016_TRIGGER_SINGLE_SEQUENCE : One whole sequence is read for each trigger

The external trigger is a combination of the following parameters :

  • The first one defines the trigger edge
    • PCI3016_EXT_TRIGGER_DISABLED : Trigger is disabled
    • PCI3016_EXT_TRIGGER_ENABLED_LOW : Triggers on low edge
    • PCI3016_EXT_TRIGGER_ENABLED_HIGH : Triggers on high edge
    • PCI3016_EXT_TRIGGER_ENABLED_BOTH : Triggers on both edges
  • The second one defines the trigger type
    • PCI3016_TRIGGER_ONE_SHOT : The acquisition starts when the trigger is set
    • PCI3016_TRIGGER_SEQUENCE_TRIGGER : A pre-defined number of sequence is acquired : dw_SequenceTriggerCount
    • PCI3016_TRIGGER_SINGLE_SEQUENCE : One whole sequence is read for each trigger
Parameters
[in]h_DeviceHandleHandle of the board
[in]dw_SequenceCountThe total number of sequence to acquire. Set it to 0 if you want to use continuous acquisition (i.e. infinite acquisition)
[in]dw_SequenceBeforeInterruptSpecify the number of sequence to wait before generating an interruption. For high frequency, set a high number (512 if using maximum frequency for example).
[in]b_ChannelCountThe number of channels in one sequence. Rule: (b_ChannelCount * dw_SequenceBeforeInterrupt) must be a multiple of 2
[in]pb_ChannelDefine the channels in the sequence (single ended : 0 to 15, differential : 0 to 7). Depending on your board, this number may be different.
[in]pb_GainDefine the gain for each channel
[in]pb_PolarityDefine the polarity for each channel (PCI3016_OUTPUT_MODE_UNIPOLAR or PCI3016_OUTPUT_MODE_BIPOLAR)
[in]dw_ConvertingTimeDefine the time between two channels acquisition (5us to 65 535 000us). If you choose 16 channels with a conversion time of 5us, an entire sequence will be acquired in 16 * 5 = 80us
[in]dw_DelayTimeDefine the time between two sequences acquisition (5us to 65 535 000us).
[in]b_SoftTriggerModeDefines the software trigger
[in]b_ExtTriggerModeDefines the external trigger
[in]dw_SequenceTriggerCountIf you choose a trigger with mode PCI3016_TRIGGER_SEQUENCE_TRIGGER, it defines the number of sequence to acquire when a trigger occurs (1 to 0xFFFFFFFF). If not use, give 0.
Return values
0: success
-1: The device handle parameter is wrong
-2: The sequence size is wrong
-3: The input mode has not been set
-4: A channel index is invalid (single-ended mode)
-5: A gain value is wrong
-6: A polarity value is wrong
-7: The converting time is invalid
-8: The delay time is invalid
-9: The interrupt routine is not installed
-10: dw_SequenceBeforeInterrupt is not valid
-11: (b_ChannelCount * dw_SequenceBeforeInterrupt) is not a multiple of 2
-12: both software and hardware trigger are enabled. In that case, they must have the same type (one shot, sequence trigger or single sequence)
-13: Error while calling IOCTL function (wrong handle ?)
_INT_ i_PCI3016_ReadMoreAnalogInputs ( HANDLE  h_DeviceHandle,
BYTE  b_ChannelCount,
PBYTE  pb_Channel,
PBYTE  pb_Gain,
PBYTE  pb_Polarity,
DWORD  dw_ConvertingTime,
BYTE  b_InterruptFlag,
BYTE  b_SoftTriggerMode,
BYTE  b_ExtTriggerMode,
PWORD  pw_ChannelValue 
)

Read analog inputs from the board
You must call the set analog input mode function before calling this function.
Gain acts as a multiplier for the input voltage. Possible gain values are :

  • PCI3016_GAIN_1 : Input range is between -10V and 10V (bipolar)
  • PCI3016_GAIN_2 : Input range is between -5V and 5V (bipolar)
  • PCI3016_GAIN_5 : Input range is between -2V and 2V (bipolar)
  • PCI3016_GAIN_10 : Input range is between -1V and 1V (bipolar)

The converting time stands for the time spent to acquire one channel. The time to acquire a sequence is ul_ConvertingTime * uc_ChannelCount
The software trigger is a combination of 2 parameters

  • The first one enables or disabled the trigger
    • PCI3016_SOFT_TRIGGER_ENABLED : The trigger is enabled
    • PCI3016_SOFT_TRIGGER_DISABLED : The trigger is disabled
  • The trigger type is selected with one of the following parameters
    • PCI3016_TRIGGER_ONE_SHOT : The acquisition starts when the trigger is set

The external trigger is a combination of the following parameters :

  • The first one defines the trigger edge
    • PCI3016_EXT_TRIGGER_DISABLED : Trigger is disabled
    • PCI3016_EXT_TRIGGER_ENABLED_LOW : Triggers on low edge
    • PCI3016_EXT_TRIGGER_ENABLED_HIGH : Triggers on high edge
    • PCI3016_EXT_TRIGGER_ENABLED_BOTH : Triggers on both edges
  • The second one defines the trigger type
    • PCI3016_TRIGGER_ONE_SHOT : The acquisition starts when the trigger is set

If the interrupts are enabled, the function returns, and the value can be read in the interrupt routine once available.
If the interrupts are disabled, the function waits for the results and return the values in the pus_ChannelValue parameter.

Parameters
[in]h_DeviceHandleHandle of the board
[in]b_ChannelCountSet the number of channels in a sequence (1 to 16)
[in]pb_ChannelDefine the channels in the sequence (single ended : 0 to 15, differential : 0 to 7)
[in]pb_GainDefine the gain for each channel
[in]pb_PolarityDefine the polarity for each channel (PCI3016_OUTPUT_MODE_UNIPOLAR or PCI3016_OUTPUT_MODE_BIPOLAR)
[in]dw_ConvertingTimeDefine the tine between two channels acquisition (5us to 65 535 000us)
[in]b_InterruptFlagEnable the interrupts
[in]b_SoftTriggerModeDefines the software trigger
[in]b_ExtTriggerModeDefines the external trigger
[out]pw_ChannelValueValue of the sequence, if interrupts are disabled
Return values
0: No Error
-1: The device handle parameter is wrong
-2: The sequence size is wrong
-3: The input mode has not been set
-4: A channel index is invalid (single-ended mode)
-5: A channel index is invalid (differential mode)
-6: A gain value is wrong
-7: A polarity value is wrong
-8: The converting time is invalid
-9: The interrupt routine is not installed
-10: The software trigger is invalid
-11: The external trigger is invalid
-12: Error while calling IOCTL function (wrong handle ?)
_INT_ i_PCI3016_Read1AnalogInput ( HANDLE  h_DeviceHandle,
BYTE  b_Channel,
BYTE  b_Gain,
BYTE  b_Polarity,
DWORD  dw_ConvertingTime,
BYTE  b_InterruptFlag,
BYTE  b_SoftTriggerMode,
BYTE  b_ExtTriggerMode,
PWORD  pw_ChannelValue 
)

Read one analog input from the board
You must call the set analog input mode function before calling this function.
Gain acts as a multiplier for the input voltage. Possible gain values are :

  • PCI3016_GAIN_1 : Input range is between -10V and 10V (bipolar)
  • PCI3016_GAIN_2 : Input range is between -5V and 5V (bipolar)
  • PCI3016_GAIN_5 : Input range is between -2V and 2V (bipolar)
  • PCI3016_GAIN_10 : Input range is between -1V and 1V (bipolar)

The converting time stands for the time spent to acquire one channel. The time to acquire a sequence is ul_ConvertingTime * uc_ChannelCount
The software trigger is a combination of 2 parameters

  • The first one enables or disabled the trigger
    • PCI3016_SOFT_TRIGGER_ENABLED : The trigger is enabled
    • PCI3016_SOFT_TRIGGER_DISABLED : The trigger is disabled
  • The trigger type is selected with one of the following parameters
    • PCI3016_TRIGGER_ONE_SHOT : The acquisition starts when the trigger is set

The external trigger is a combination of the following parameters :

  • The first one defines the trigger edge
    • PCI3016_EXT_TRIGGER_DISABLED : Trigger is disabled
    • PCI3016_EXT_TRIGGER_ENABLED_LOW : Triggers on low edge
    • PCI3016_EXT_TRIGGER_ENABLED_HIGH : Triggers on high edge
    • PCI3016_EXT_TRIGGER_ENABLED_BOTH : Triggers on both edges
  • The second one defines the trigger type
    • PCI3016_TRIGGER_ONE_SHOT : The acquisition starts when the trigger is set

If the interrupts are enabled, the function returns, and the value can be read in the interrupt routine once available.
If the interrupts are disabled, the function waits for the results and return the values in the pus_ChannelValue parameter.

Parameters
[in]h_DeviceHandleHandle of the board
[in]b_ChannelDefine the channel to acquire (single ended : 0 to 15, differential : 0 to 7)
[in]b_GainDefine the gain for the channel
[in]b_PolarityDefine the polarity for the channel (PCI3016_OUTPUT_MODE_UNIPOLAR or PCI3016_OUTPUT_MODE_BIPOLAR)
[in]dw_ConvertingTimeDefine the time needed to acquire the channel (5us to 65 535 000us)
[in]b_InterruptFlagEnable the interrupts
[in]b_SoftTriggerModeDefines the software trigger
[in]b_ExtTriggerModeDefines the external trigger
[out]pw_ChannelValueValue of the channel, if interrupts are disabled
Return values
0: No Error
-1: The device handle parameter is wrong
-3: The input mode has not been set
-4: A channel index is invalid (single-ended mode)
-5: A channel index is invalid (differential mode)
-6: A gain value is wrong
-7: A polarity value is wrong
-8: The converting time is invalid
-9: The interrupt routine is not installed
-10: The software trigger is invalid
-11: The external trigger is invalid
-12: Error while calling IOCTL function (wrong handle ?)
_INT_ i_PCI3016_InitAndStartAutoRefreshAcquisition ( HANDLE  h_DeviceHandle,
BYTE  b_ChannelCount,
PBYTE  pb_Channel,
PBYTE  pb_Gain,
PBYTE  pb_Polarity,
DWORD  dw_ConvertingTime,
PDWORD *  ppdw_Channels 
)

Starts an auto-refresh acquisition
You must call the set analog input mode function before calling this function.
Auto-refresh mode is started once, and returns an array of values, each one corresponding to a channel.
These values are automatically refreshed after each conversion cycle, so the values in this array are always the latest ones.
Gain acts as a multiplier for the input voltage. Possible gain values are :

  • PCI3016_GAIN_1 : Input range is between -10V and 10V (bipolar)
  • PCI3016_GAIN_2 : Input range is between -5V and 5V (bipolar)
  • PCI3016_GAIN_5 : Input range is between -2V and 2V (bipolar)
  • PCI3016_GAIN_10 : Input range is between -1V and 1V (bipolar)

The converting time stands for the time spent to acquire one channel. The time to acquire a sequence is dw_ConvertingTime * b_ChannelCount

Parameters
[in]h_DeviceHandleHandle of the board
[in]b_ChannelCountSet the number of channels in a sequence (1 to 16)
[in]pb_ChannelDefine the channels in the sequence (single ended : 0 to 15, differential : 0 to 7)
[in]pb_GainDefine the gain for each channel
[in]pb_PolarityDefine the polarity for each channel (PCI3016_OUTPUT_MODE_UNIPOLAR or PCI3016_OUTPUT_MODE_BIPOLAR)
[in]dw_ConvertingTimeDefine the tine between two channels acquisition (5us to 65 535 000us)
[out]ppdw_ChannelsPointer to an array that contains the value of each channels
Return values
0: No Error
-1: The device handle parameter is wrong
-2: The sequence size is wrong
-3: The input mode has not been set
-4: A channel index is invalid (single-ended mode)
-5: A channel index is invalid (differential mode)
-6: A gain value is wrong
-7: A polarity value is wrong
-8: The converting time is invalid
-9: Error while calling IOCTL function (wrong handle ?)
-20: Error while calling IOCTL function (wrong handle ?)
_INT_ i_PCI3016_StopAnalogAcquisition ( HANDLE  h_DeviceHandle)

Stops any analog acquisition

Parameters
[in]h_DeviceHandleHandle of the board
Return values
0: No Error
-1: Error while calling IOCTL function (wrong handle ?)
_INT_ i_PCI3016_TriggerAnalogAcquisition ( HANDLE  h_DeviceHandle)

Triggers any analog acquisition

Parameters
[in]h_DeviceHandleHandle of the board
Return values
0: No Error
-1: Error while calling IOCTL function (wrong handle ?)
_INT_ i_PCI3016_GetAnalogInputChannelsNbr ( HANDLE  h_DeviceHandle,
PBYTE  pb_NumberOfInputChannels 
)

Get the number of analog inputs available on this board

Parameters
[in]h_DeviceHandleHandle of the board
[out]pb_NumberOfInputChannelsNumber of analog inputs available on this board
Return values
0: No Error
-1: The device handle parameter is wrong
_INT_ i_PCI3016_GetAnalogInputResolution ( HANDLE  h_DeviceHandle,
PBYTE  pb_Resolution 
)

Get the resolution of the analog inputs of this board, in bits

Parameters
[in]h_DeviceHandleHandle of the board
[out]pb_ResolutionResolution of the analog inputs of this board, in bits
Return values
0: No Error
-1: The device handle parameter is wrong
_INT_ i_PCI3016_GetAnalogInputTriggerStatus ( HANDLE  h_DeviceHandle,
PULONG  softwareTriggerStatus,
PULONG  hardwareTriggerStatus 
)

Retrieves the analog input software and hardware trigger status

Parameters
[in]h_DeviceHandleHandle of the board
[out]softwareTriggerStatusPointer to an unsingned long containing:
  • in bit 0 if the trigger is enabled or disabled (ADDIDATA_ENABLE or ADDIDATA_DISABLE)
  • in bit 1 the status of the trigger (0 software trigger did not occur, 1 software trigger occurred)
[out]hardwareTriggerStatusPointer to an unsigned long containing:
  • in bit 0 if the trigger is enabled or disabled (ADDIDATA_ENABLE or ADDIDATA_DISABLE)
  • in bit 1 the trigger status
  • in bit 2 the trigger state
[out]hardwareTriggerCountPointer to un unsigned long containing the hardware trigger count.
_INT_ i_PCI3016_ReleaseHardwareTriggerWaitingRead ( HANDLE  deviceHandle)

Computes convertion time given convertiontimeunit and returns a result in micro seconds.

Parameters
inout] convertionTime the time to convert [in] convertionTimeUnit the time unit to use (0 for ns, 1 for micro s, 2 for ms, 3 for s) Sets a bit to 1 in a global variable to release a blocked polling reading in case of hardware trigger disabling.
[in]h_DeviceHandleHandle of the board
_INT_ i_PCI3016_ReleaseSoftwareTriggerWaitingRead ( HANDLE  deviceHandle)

Sets a bit to 1 in a global variable to release a blocked polling reading in case of software trigger disabling.

Parameters
[in]h_DeviceHandleHandle of the board
_INT_ i_PCI3016_GetConvertionTimeInMicroSeconds ( DWORD *  convertionTime,
BYTE  convertionTimeUnit 
)