LibTiePie  0.6.1
Library for interfacing TiePie engineering instruments

Description

Functions to collect the measured data.

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 zero. 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.

The data is returned directly in Volt, Ampere or Ohm, depending on the input coupling.

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.

These routines also incorporate the probe gain and offset that were set during the measurement.

Functions

uint64_t ScpGetData (LibTiePieHandle_t hDevice, float **pBuffers, uint16_t wChannelCount, uint64_t qwStartIndex, uint64_t qwSampleCount)
 Get the measurement data for specified channels. More...
 
uint64_t ScpGetData1Ch (LibTiePieHandle_t hDevice, float *pBufferCh1, uint64_t qwStartIndex, uint64_t qwSampleCount)
 Get the measurement data for the first channel. More...
 
uint64_t ScpGetData2Ch (LibTiePieHandle_t hDevice, float *pBufferCh1, float *pBufferCh2, uint64_t qwStartIndex, uint64_t qwSampleCount)
 Get the measurement data for the first two channels. More...
 
uint64_t ScpGetData3Ch (LibTiePieHandle_t hDevice, float *pBufferCh1, float *pBufferCh2, float *pBufferCh3, uint64_t qwStartIndex, uint64_t qwSampleCount)
 Get the measurement data for the first three channels. More...
 
uint64_t ScpGetData4Ch (LibTiePieHandle_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. More...
 
uint64_t ScpGetValidPreSampleCount (LibTiePieHandle_t hDevice)
 Get the number of valid pre samples in the measurement. More...
 
void ScpChGetDataValueRange (LibTiePieHandle_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. More...
 
double ScpChGetDataValueMin (LibTiePieHandle_t hDevice, uint16_t wCh)
 Get the minimum value of the input range the current data was measured with. More...
 
double ScpChGetDataValueMax (LibTiePieHandle_t hDevice, uint16_t wCh)
 Get the maximum value of the input range the current data was measured with. More...
 

Function Documentation

uint64_t ScpGetData ( LibTiePieHandle_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 retrieve measured data from specific channels. It uses an array of pointers to data buffers to indicate from which channels the data must be retrieved. NULL pointers can be used to indicate that no data needs to be retrieved for a specific channel.

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

To retrieve 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.

The buffers contain data directly in Volt, Ampere or Ohm, depending on the input coupling.

Parameters
[in]hDeviceA device handle identifying the oscilloscope.
[out]pBuffersA pointer to a buffer with pointers to buffers for channel data, the pointer buffer may contain NULL pointers.
[in]wChannelCountThe number of pointers in the pointer buffer.
[in]qwStartIndexThe position in the record to start reading.
[in]qwSampleCountThe number of samples to read.
Returns
The number of samples actually read.
Status values
UNSUCCESSFUL An error occurred during execution of the last called function.
VALUE_CLIPPED Retrieved less samples than indicated by qwSampleCount.
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
Pointer array for programming languages that don't support pointers to pointers, e.g. Matlab or Python.
ScpGetData1Ch, ScpGetData2Ch, ScpGetData3Ch, ScpGetData4Ch
Example
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 );
Since
0.4.0
uint64_t ScpGetData1Ch ( LibTiePieHandle_t  hDevice,
float *  pBufferCh1,
uint64_t  qwStartIndex,
uint64_t  qwSampleCount 
)

Get the measurement data for the first channel.

The buffers contain data directly in Volt, Ampere or Ohm, depending on the input coupling.

Parameters
[in]hDeviceA device handle identifying the oscilloscope.
[out]pBufferCh1A pointer to the buffer for channel 1 data or NULL.
[in]qwStartIndexThe psition in the record to start reading.
[in]qwSampleCountThe number of samples to read.
Returns
The number of samples actually read.
Status values
UNSUCCESSFUL An error occurred during execution of the last called function.
VALUE_CLIPPED Retrieved less samples than indicated by qwSampleCount.
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
ScpGetData
ScpGetData2Ch, ScpGetData3Ch, ScpGetData4Ch
Since
0.4.0
uint64_t ScpGetData2Ch ( LibTiePieHandle_t  hDevice,
float *  pBufferCh1,
float *  pBufferCh2,
uint64_t  qwStartIndex,
uint64_t  qwSampleCount 
)

Get the measurement data for the first two channels.

The buffers contain data directly in Volt, Ampere or Ohm, depending on the input coupling.

Parameters
[in]hDeviceA device handle identifying the oscilloscope.
[out]pBufferCh1A pointer to the buffer for channel 1 data or NULL.
[out]pBufferCh2A pointer to the buffer for channel 2 data or NULL.
[in]qwStartIndexThe position in the record to start reading.
[in]qwSampleCountThe number of samples to read.
Returns
The number of samples actually read.
Status values
UNSUCCESSFUL An error occurred during execution of the last called function.
VALUE_CLIPPED Retrieved less samples than indicated by qwSampleCount.
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
ScpGetData
ScpGetData1Ch, ScpGetData3Ch, ScpGetData4Ch
Since
0.4.0
uint64_t ScpGetData3Ch ( LibTiePieHandle_t  hDevice,
float *  pBufferCh1,
float *  pBufferCh2,
float *  pBufferCh3,
uint64_t  qwStartIndex,
uint64_t  qwSampleCount 
)

Get the measurement data for the first three channels.

The buffers contain data directly in Volt, Ampere or Ohm, depending on the input coupling.

Parameters
[in]hDeviceA device handle identifying the oscilloscope.
[out]pBufferCh1A pointer to the buffer for channel 1 data or NULL.
[out]pBufferCh2A pointer to the buffer for channel 2 data or NULL.
[out]pBufferCh3A pointer to the buffer for channel 3 data or NULL.
[in]qwStartIndexThe position in the record to start reading.
[in]qwSampleCountThe number of samples to read.
Returns
The number of samples actually read.
Status values
UNSUCCESSFUL An error occurred during execution of the last called function.
VALUE_CLIPPED Retrieved less samples than indicated by qwSampleCount.
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
ScpGetData
ScpGetData1Ch, ScpGetData2Ch, ScpGetData4Ch
Since
0.4.0
uint64_t ScpGetData4Ch ( LibTiePieHandle_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.

The buffers contain data directly in Volt, Ampere or Ohm, depending on the input coupling.

Parameters
[in]hDeviceA device handle identifying the oscilloscope.
[out]pBufferCh1A pointer to the buffer for channel 1 data or NULL.
[out]pBufferCh2A pointer to the buffer for channel 2 data or NULL.
[out]pBufferCh3A pointer to the buffer for channel 3 data or NULL.
[out]pBufferCh4A pointer to the buffer for channel 4 data or NULL.
[in]qwStartIndexThe position in the record to start reading.
[in]qwSampleCountThe number of samples to read.
Returns
The number of samples actually read.
Status values
UNSUCCESSFUL An error occurred during execution of the last called function.
VALUE_CLIPPED Retrieved less samples than indicated by qwSampleCount.
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
ScpGetData
ScpGetData1Ch, ScpGetData2Ch, ScpGetData3Ch
Since
0.4.0
uint64_t ScpGetValidPreSampleCount ( LibTiePieHandle_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
[in]hDeviceA device handle identifying the oscilloscope.
Returns
The number of valid pre samples.
Status values
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
Since
0.4.0
void ScpChGetDataValueRange ( LibTiePieHandle_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.

The buffers contain the minimum and maximum values of the input range directly in Volt, Ampere or Ohm, depending on the input coupling.

Parameters
[in]hDeviceA device handle identifying the oscilloscope.
[in]wChThe channel number identifying the channel, 0 to ScpGetChannelCount() - 1.
[out]pMinA pointer to a buffer for the minimum value of the range or NULL.
[out]pMaxA pointer to a buffer for the maximum value of the range or NULL.
Status values
INVALID_CHANNEL The requested channel number is invalid.
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
ScpChGetDataValueMin
ScpChGetDataValueMax
Probe
Since
0.4.0
double ScpChGetDataValueMin ( LibTiePieHandle_t  hDevice,
uint16_t  wCh 
)

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

Parameters
[in]hDeviceA device handle identifying the oscilloscope.
[in]wChThe channel number identifying the channel, 0 to ScpGetChannelCount() - 1.
Returns
The minimum value of the input range the current data was measured with, in Volt, Ampere or Ohm, depending on the input coupling.
Status values
INVALID_CHANNEL The requested channel number is invalid.
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
ScpChGetDataValueMax
ScpChGetDataValueRange
Probe
Since
0.4.0
double ScpChGetDataValueMax ( LibTiePieHandle_t  hDevice,
uint16_t  wCh 
)

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

Parameters
[in]hDeviceA device handle identifying the oscilloscope.
[in]wChThe channel number identifying the channel, 0 to ScpGetChannelCount() - 1.
Returns
The maximum value of the input range the current data was measured with, in Volt, Ampere or Ohm, depending on the input coupling.
Status values
INVALID_CHANNEL The requested channel number is invalid.
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
ScpChGetDataValueMin
ScpChGetDataValueRange
Probe
Since
0.4.0