xPCI-3001 API

Functions

_INT_ i_PCI3001_SetAnalogInputMode (HANDLE h_DeviceHandle, BYTE b_InputMode)
 
_INT_ i_PCI3001_GetAnalogInputMode (HANDLE h_DeviceHandle, PBYTE pb_InputMode)
 
_INT_ i_PCI3001_Read1AnalogInput (HANDLE h_DeviceHandle, BYTE b_Channel, BYTE b_Gain, BYTE b_Polarity, WORD w_ConvertingTime, BYTE b_InterruptFlag, PWORD pw_ChannelValue)
 
_INT_ i_PCI3001_ReadMoreAnalogInputs (HANDLE h_DeviceHandle, BYTE b_ChannelCount, PBYTE pb_Channel, PBYTE pb_Gain, PBYTE pb_Polarity, WORD w_ConvertingTime, BYTE b_InterruptFlag, PWORD pw_ChannelValue)
 
_INT_ i_PCI3001_InitAndStartAnalogInputSequence (HANDLE h_DeviceHandle, DWORD dw_SequenceCount, DWORD dw_SequenceBeforeInterrupt, BYTE b_ChannelCount, PBYTE pb_Channel, PBYTE pb_Gain, PBYTE pb_Polarity, WORD w_ConvertingTime, BYTE b_DelayMode, DWORD dw_DelayTime, BYTE b_ExtTriggerMode)
 
_INT_ i_PCI3001_StopAnalogAcquisition (HANDLE h_DeviceHandle)
 
_LONG_ l_PCI3001_ReadSequenceData (HANDLE deviceHandle, DWORD size, PVOID data)
 

Detailed Description

Function Documentation

_INT_ i_PCI3001_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 (PCI3001_INPUT_MODE_SINGLE_ENDED or PCI3001_INPUT_MODE_DIFFERENTIAL)
Returns
0 : No Error
-1 : The device handle parameter is wrong
-2 : Invalid input mode
_INT_ i_PCI3001_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 (PCI3001_INPUT_MODE_UNDEFINED, PCI3001_INPUT_MODE_SINGLE_ENDED or PCI3001_INPUT_MODE_DIFFERENTIAL)
Returns
0 : No Error
-1 : The device handle parameter is wrong
_INT_ i_PCI3001_Read1AnalogInput ( HANDLE  h_DeviceHandle,
BYTE  b_Channel,
BYTE  b_Gain,
BYTE  b_Polarity,
WORD  w_ConvertingTime,
BYTE  b_InterruptFlag,
PWORD  pw_ChannelValue 
)

Reads the current value of the analog input channel b_Channel with a gain b_Gain, in the input voltage range b_Polarity and a conversion time w_ConvertingTime

Parameters
[in]h_DeviceHandleHandle of the board
[in]b_ChannelChannel to read (Single-ended : 0 to 15, differential : 0-7)
[in]b_GainInput gain. Adjusts the input voltage to be in the converter's range (-10V to 10V) and get the best resolution.
Gain acts like a multiplying coefficient, so a value of 2 will double the input voltage before it goes through the converter.
For example, if the input voltage is between 0V and 2V, a gain value of 5 should be used.
Possible values are PCI3001_GAIN_1, PCI3001_GAIN_2, PCI3001_GAIN_5 and PCI3001_GAIN_10
[in]b_PolaritySelection of the input voltage range.
  • Unipolar : Input voltage between 0V and 10V (value APCI3001_UNIPOLAR)
  • Bipolar : Input voltage range between -10V and +10V. Twice the range, so half the resolution (value APCI3001_BIPOLAR)
    N.B. : Those values are given for APCI3001_1_GAIN. For other values, see above
[in]w_ConvertingTimeSelection of the conversion time, from 10 to 32767us.
[in]b_InterruptFlagWether an interrupt is generated at EOS (End Of Sequence) or not
[out]pw_ChannelValueThe raw analog value (0x0000 to 0x0FFF) (12 bits)
Returns
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 : Error while calling IOCTL function (wrong handle ?)
_INT_ i_PCI3001_ReadMoreAnalogInputs ( HANDLE  h_DeviceHandle,
BYTE  b_ChannelCount,
PBYTE  pb_Channel,
PBYTE  pb_Gain,
PBYTE  pb_Polarity,
WORD  w_ConvertingTime,
BYTE  b_InterruptFlag,
PWORD  pw_ChannelValue 
)

Reads several analog input channels
The priority of the analog input channels is set with the scan list
The scan list allows to determine the input voltage range and the gain for each analog input channel
The gain is defined with parameter pb_Gain for each analog input channel
The input voltage range is defined with parameter pb_Polarity for each analog input channel

Parameters
[in]h_DeviceHandleHandle of the board
[in]b_ChannelCountNumber of acquisitions in the sequence (1 to 16)
[in]pb_ChannelArray of the channels to read
[in]pb_GainArray of gain for each channel (see i_PCI3001_Read1AnalogInput)
[in]pb_PolarityArray of input voltage range for each channel (see i_PCI3001_Read1AnalogInput)
[in]w_ConvertingTimeSelection of the conversion time, from 10us to 32767us.
[in]b_InterruptFlagWether an interrupt is generated at EOS (End Of Sequence) or not.
Read values are available in the interrupt callback function
[out]pw_ChannelValueRaw output values (0x0 to 0x0FFF) (12 bits)
Returns
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 : Error while calling IOCTL function (wrong handle ?)
_INT_ i_PCI3001_InitAndStartAnalogInputSequence ( HANDLE  h_DeviceHandle,
DWORD  dw_SequenceCount,
DWORD  dw_SequenceBeforeInterrupt,
BYTE  b_ChannelCount,
PBYTE  pb_Channel,
PBYTE  pb_Gain,
PBYTE  pb_Polarity,
WORD  w_ConvertingTime,
BYTE  b_DelayMode,
DWORD  dw_DelayTime,
BYTE  b_ExtTriggerMode 
)

This function initializes a sequence acquisition
Thanks to a sequence acquisition, you can get analog values from the board very fastely (or slowly if you want)
After having initialized the sequence, to get the data you will have to wait an interrupt, and then read the data from the board.
You may have a look on the sample available with this DLL, that will explain you how to do.

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_ChannelArray of the channels to read (see i_PCI3001_Read1AnalogInput)
[in]pb_GainArray of gain for each channels (see i_PCI3001_Read1AnalogInput)
[in]pb_PolarityArray of polarity for each channels (see i_PCI3001_Read1AnalogInput)
[in]w_ConvertingTimeTime interval in us between 2 conversions of successive input channels (from 10 us to 32767 us).
[in]b_DelayModeSpecifiy the type of delay to use between two acquisitions of a sequence
  • APCI3001_SIMPLE_MODUS : A conversion occurs every w_ConvertingTime (no delay)
  • APCI3001_DELAY_MODUS : Conversions occur every w_ConvertingTime until all analog input channels have been acquired
    Afterwards there is a waiting time of dw_DelayTime before the next cycle
    Please note: If the total time ( dw_DelayTime + b_ChannelCount * w_ConvertingTime ) is not a multiple of 50us,
    then the resulting delay time is rounded because it depends on the timer resolution
    One delay timer step corresponds to 50us
  • APCI3001_DELAY_1_MODUS : Conversions occur every w_ConvertingTime until all analog input channels have been acquired
    dw_DelayTime defines the time between the beginning of 2 cycles
    That means dw_DelayTime can't be less than b_ChannelCount * w_ConvertingTime
    This value must be a multiple of 50
[in]dw_DelayTimeWaiting time in us between two conversion cycles (from 100 us to 3276850 us)
This parameter is only relevant if APCI3001_DELAY_MODUS or APCI3001_DELAY_1_MODUS are used
This parameter must be a multiple of 50
[in]b_ExtTriggerModeTwo modes are possible :
  • APCI3001_DISABLE No hardware trigger
  • APCI3001_ENABLE Hardware trigger is set
    A logic "1" on the digital input 1 starts the conversion. The conversion is stopped by calling "i_PCI3001_StopAnalogInputAcquisition"
Returns
0 : No error -1 : The device handle parameter is wrong
-2 : b_ChannelCount is invalid (must be between 1 and 16)
-3 : The current input mode is wrong. Please call i_PCI3001_SetAnalogInputMode before calling this function
-4 : The index of a channel in the pb_Channel array is too high
-5 : The gain of a channel in the pb_Gain array is invalid
-6 : The polarity of a channel in the pb_Polarity array is invalid
-7 : w_ConvertingTime is invalid (must be between 10 and 32767)
-8 : b_DelayMode is invalid
-9 : dw_DelayTime is invalid (must be between 100 and 3276850)
-10 : dw_DelayTime is invalid (must be a multiple of 50)
-11 : dw_DelayTime is not a multiple of 50
-12 : dw_DelayTime is smaller than (b_ChannelCount * w_ConvertingTime)
-13 : no interrupt handler is installed. Please call i_PCI3001_SetBoardIntRoutine before calling this function
-14 : dw_SequenceBeforeInterrupt is wrong. Must be higher than 1
-15 : (dw_SequenceBeforeInterrupt * b_ChannelCount ) is not a multiple of 2
-16 : b_ExtTriggerMode is invalid
-17 : Error while calling IOCTL function (wrong handle ?)
Error -17: this error occurs when a driver error is detected. If you receive this error, the two mains grounds are:
  • A wrong handle (h_DeviceHandle) is used. Did you open your board with i_PCI3001_OpenBoardViaIndex ?
  • The parameter dw_SequenceBeforeInterrupt is too high. Check in the device manager, you will have a option DMA buffer size in the configuration of the board. Set the correct number and retry. Note: a channel is encoded on 2 bytes.
_INT_ i_PCI3001_StopAnalogAcquisition ( HANDLE  h_DeviceHandle)

Stops any analog acquisition

Parameters
[in]h_DeviceHandleHandle of the board
Returns
0 : No Error
-1 : Error while calling IOCTL function (wrong handle ?)
_LONG_ l_PCI3001_ReadSequenceData ( HANDLE  deviceHandle,
DWORD  size,
PVOID  data 
)

Enables to read data acquired by a sequence acquisition.
This function can be called in the interrupt routine that you registered. (see samples)

Parameters
deviceHandlehandle to the board
sizesize of data to read. To be powerfull, should be ( sequence size * sequence before interrupt ) * sizeof ( USHORT )
dataPointer that will be fill with the data of the board
Returns
>= 0: size of data read
-1 : error while reading