LibTiePie  0.4.3
Library for interfacing TiePie engineering instruments
 All Files Functions Typedefs Macros Groups Pages
Data

This section contains all data retrieving related functions. More...

Functions

uint64_t ScpGetData (TpDeviceHandle_t hDevice, float **pBuffers, uint16_t wChannelCount, uint64_t qwStartIndex, uint64_t qwSampleCount)
 Get the measurement data for specified channels.
 
uint64_t ScpGetData1Ch (TpDeviceHandle_t hDevice, float *pBufferCh1, uint64_t qwStartIndex, uint64_t qwSampleCount)
 Get the measurement data for the first channel.
 
uint64_t ScpGetData2Ch (TpDeviceHandle_t hDevice, float *pBufferCh1, float *pBufferCh2, uint64_t qwStartIndex, uint64_t qwSampleCount)
 Get the measurement data for the first two channels.
 
uint64_t ScpGetData3Ch (TpDeviceHandle_t hDevice, float *pBufferCh1, float *pBufferCh2, float *pBufferCh3, uint64_t qwStartIndex, uint64_t qwSampleCount)
 Get the measurement data for the first three channels.
 
uint64_t ScpGetData4Ch (TpDeviceHandle_t hDevice, float *pBufferCh1, float *pBufferCh2, float *pBufferCh3, float *pBufferCh4, uint64_t qwStartIndex, uint64_t qwSampleCount)
 Get the measurement data for the first four channels.
 
uint64_t ScpGetValidPreSampleCount (TpDeviceHandle_t hDevice)
 Get the number of valid pre samples in the measurement.
 
void ScpChGetDataValueRange (TpDeviceHandle_t hDevice, uint16_t wCh, double *pMin, double *pMax)
 Get the minimum and maximum values of the input range the current data was measured with.
 
double ScpChGetDataValueMax (TpDeviceHandle_t hDevice, uint16_t wCh)
 Get the maximum value of the input range the current data was measured with.
 
double ScpChGetDataValueMin (TpDeviceHandle_t hDevice, uint16_t wCh)
 Get the minimum value of the input range the current data was measured with.
 

Detailed Description

This section contains all data retrieving related functions.

When a measurement is performed, the data is stored inside the instrument. When no pre samples are selected (pre sample ratio = 0), the trigger point is located at the start of the record and all samples are measured post samples.

When pre samples are selected (pre sample ratio > 0), the trigger point is located at position (pre sample ratio * record length), dividing the record in pre samples and post samples.

When after starting the measurement a trigger occurs before all pre samples are measured, not all pre samples will be valid. Invalid pre samples are set to 0 V. Use ScpGetValidPreSampleCount to determine the amount of valid pre samples. See trigger hold off to force all pre samples to be measured.

When retrieving the measured data, the full record can be get, including the invalid presamples. The start index needs to be set to 0 then. It is also possible to get only the valid samples. In that case, the start index needs to be set to ( record length - ( number of post samples + number of valid pre samples ).

Example:

uint64_t qwPostSamples = llround( ( 1 - ScpGetPreSampleRatio( hScp ) ) * ScpGetRecordLength( hScp ) );
uint64_t qwValidSamples = qwPostSamples + ScpGetValidPreSampleCount( hScp );
uint64_t qwStart = ScpGetRecordLength( hScp ) - qwValidSamples;
uint64_t qwSamplesRead = ScpGetData1Ch( hScp , pDataCh1 , qwStart , qwValidSamples );

The data retrieval functions use buffers to store the measured data in. The caller must assure that enough memory is allocated for the buffer, to contain all data.

Several routines are available to get the measured data, one universal applicable routine and a number of dedicated routines, to collect data from specific channels.

Additionally, routines are available to retrieve range information of the measured data. Once a measurement is ready, the input range of a channel can be changed, e.g. by the auto ranging function or by the user. The input range will then no longer match with the range of the measured data. Use these routines to determine the actual range of the measured data.

Function Documentation

uint64_t ScpGetData ( TpDeviceHandle_t  hDevice,
float **  pBuffers,
uint16_t  wChannelCount,
uint64_t  qwStartIndex,
uint64_t  qwSampleCount 
)

Get the measurement data for specified channels.

This routine is used to get measured data from specific channels. It uses an array or pointers to data buffers to indicate from which channels the data must be get. NULL pointers can be used to indicate that no data needs to be get for a specific channel.

Examples:

To get data from channels 1 and 2 of the oscilloscope, create a pointer array with two pointers: { pDataCh1 , pDataCh2 } and set wChannelCount to 2.

To get data from channels 2 and 4 of the oscilloscope, create a pointer array with four pointers: { NULL , pDataCh2 , NULL , pDataCh4 } and set wChannelCount to 4.

uint64_t qwPostSamples = llround( ( 1 - ScpGetPreSampleRatio( hScp ) ) * ScpGetRecordLength( hScp ) );
uint64_t qwValidSamples = qwPostSamples + ScpGetValidPreSampleCount( hScp );
uint64_t qwStart = ScpGetRecordLength( hScp ) - qwValidSamples;
// Allocate memory for active channels:
float** ppChannelData = malloc( sizeof( float* ) * wChannelCount );
for( wCh = 0 ; wCh < wChannelCount ; wCh++ )
if( ScpChGetEnabled( hScp , wCh ) )
ppChannelData[ wCh ] = malloc( sizeof( float ) * qwValidSamples );
else
ppChannelData[ wCh ] = NULL;
// Get data:
uint64_t qwSamplesRead = ScpGetData( hScp , ppChannelData , wChannelCount , qwStart , qwValidSamples );
// do something with the data.
// Free memory:
for( wCh = 0 ; wCh < wChannelCount ; wCh++ )
free( ppChannelData[ wCh ] );
free( ppChannelData );
Parameters
hDeviceA device handle.
pBuffersPointer to a buffer with pointers to buffers for channel data, the pointer buffer may contain NULL pointers.
wChannelCountNumber of pointers in the pointer buffer.
qwStartIndexPosition in the record to start reading.
qwSampleCountNumber of samples to read.
Returns
Number of samples read.
See Also
Pointer array
uint64_t ScpGetData1Ch ( TpDeviceHandle_t  hDevice,
float *  pBufferCh1,
uint64_t  qwStartIndex,
uint64_t  qwSampleCount 
)

Get the measurement data for the first channel.

Parameters
hDeviceA device handle.
pBufferCh1Pointer to buffer for channel 1 data or NULL.
qwStartIndexPosition in the record to start reading.
qwSampleCountNumber of samples to read.
Returns
Number of samples read.
uint64_t ScpGetData2Ch ( TpDeviceHandle_t  hDevice,
float *  pBufferCh1,
float *  pBufferCh2,
uint64_t  qwStartIndex,
uint64_t  qwSampleCount 
)

Get the measurement data for the first two channels.

Parameters
hDeviceA device handle.
pBufferCh1Pointer to buffer for channel 1 data or NULL.
pBufferCh2Pointer to buffer for channel 2 data or NULL.
qwStartIndexPosition in the record to start reading.
qwSampleCountNumber of samples to read.
Returns
Number of samples read.
uint64_t ScpGetData3Ch ( TpDeviceHandle_t  hDevice,
float *  pBufferCh1,
float *  pBufferCh2,
float *  pBufferCh3,
uint64_t  qwStartIndex,
uint64_t  qwSampleCount 
)

Get the measurement data for the first three channels.

Parameters
hDeviceA device handle.
pBufferCh1Pointer to buffer for channel 1 data or NULL.
pBufferCh2Pointer to buffer for channel 2 data or NULL.
pBufferCh3Pointer to buffer for channel 3 data or NULL.
qwStartIndexPosition in the record to start reading.
qwSampleCountNumber of samples to read.
Returns
Number of samples read.
uint64_t ScpGetData4Ch ( TpDeviceHandle_t  hDevice,
float *  pBufferCh1,
float *  pBufferCh2,
float *  pBufferCh3,
float *  pBufferCh4,
uint64_t  qwStartIndex,
uint64_t  qwSampleCount 
)

Get the measurement data for the first four channels.

Parameters
hDeviceA device handle.
pBufferCh1Pointer to buffer for channel 1 data or NULL.
pBufferCh2Pointer to buffer for channel 2 data or NULL.
pBufferCh3Pointer to buffer for channel 3 data or NULL.
pBufferCh4Pointer to buffer for channel 4 data or NULL.
qwStartIndexPosition in the record to start reading.
qwSampleCountNumber of samples to read.
Returns
Number of samples read.
uint64_t ScpGetValidPreSampleCount ( TpDeviceHandle_t  hDevice)

Get the number of valid pre samples in the measurement.

When pre samples are selected (pre sample ratio > 0), the trigger point is located at position (pre sample ratio * record length), dividing the record in pre samples and post samples.

When after starting the measurement a trigger occurs before all presamples are measured, not all pre samples will be valid.

Parameters
hDeviceA device handle.
Returns
The number of valid pre samples.
void ScpChGetDataValueRange ( TpDeviceHandle_t  hDevice,
uint16_t  wCh,
double *  pMin,
double *  pMax 
)

Get the minimum and maximum values of the input range the current data was measured with.

Parameters
hDeviceA device handle.
wChChannel number, 0 to ScpGetChannelCount() - 1.
pMinPointer to buffer for the minimum value of the range or NULL.
pMaxPointer to buffer for the maximum value of the range or NULL.
See Also
ScpChGetDataValueMin
ScpChGetDataValueMax
double ScpChGetDataValueMax ( TpDeviceHandle_t  hDevice,
uint16_t  wCh 
)

Get the maximum value of the input range the current data was measured with.

Parameters
hDeviceA device handle.
wChChannel number, 0 to ScpGetChannelCount() - 1.
Returns
The maximum value of the input range the current data was measured with.
See Also
ScpChGetDataValueMin
ScpChGetDataValueRange
double ScpChGetDataValueMin ( TpDeviceHandle_t  hDevice,
uint16_t  wCh 
)

Get the minimum value of the input range the current data was measured with.

Parameters
hDeviceA device handle.
wChChannel number, 0 to ScpGetChannelCount() - 1.
Returns
The minimum value of the input range the current data was measured with.
See Also
ScpChGetDataValueMax
ScpChGetDataValueRange