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]	hDevice	A device handle identifying the oscilloscope.
[out]	pBuffers	A pointer to a buffer with pointers to buffers for channel data, the pointer buffer may contain `NULL` pointers.
[in]	wChannelCount	The number of pointers in the pointer buffer.
[in]	qwStartIndex	The position in the record to start reading.
[in]	qwSampleCount	The 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_INITIALIZED	The 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]	hDevice	A device handle identifying the oscilloscope.
[out]	pBufferCh1	A pointer to the buffer for channel 1 data or `NULL`.
[in]	qwStartIndex	The psition in the record to start reading.
[in]	qwSampleCount	The 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_INITIALIZED	The 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]	hDevice	A device handle identifying the oscilloscope.
[out]	pBufferCh1	A pointer to the buffer for channel 1 data or `NULL`.
[out]	pBufferCh2	A pointer to the buffer for channel 2 data or `NULL`.
[in]	qwStartIndex	The position in the record to start reading.
[in]	qwSampleCount	The 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_INITIALIZED	The 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]	hDevice	A device handle identifying the oscilloscope.
[out]	pBufferCh1	A pointer to the buffer for channel 1 data or `NULL`.
[out]	pBufferCh2	A pointer to the buffer for channel 2 data or `NULL`.
[out]	pBufferCh3	A pointer to the buffer for channel 3 data or `NULL`.
[in]	qwStartIndex	The position in the record to start reading.
[in]	qwSampleCount	The 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_INITIALIZED	The 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]	hDevice	A device handle identifying the oscilloscope.
[out]	pBufferCh1	A pointer to the buffer for channel 1 data or `NULL`.
[out]	pBufferCh2	A pointer to the buffer for channel 2 data or `NULL`.
[out]	pBufferCh3	A pointer to the buffer for channel 3 data or `NULL`.
[out]	pBufferCh4	A pointer to the buffer for channel 4 data or `NULL`.
[in]	qwStartIndex	The position in the record to start reading.
[in]	qwSampleCount	The 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_INITIALIZED	The 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] hDevice A 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_INITIALIZED	The 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]	hDevice	A device handle identifying the oscilloscope.
[in]	wCh	The channel number identifying the channel, `0` to `ScpGetChannelCount() - 1`.
[out]	pMin	A pointer to a buffer for the minimum value of the range or `NULL`.
[out]	pMax	A 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_INITIALIZED	The 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]	hDevice	A device handle identifying the oscilloscope.
[in]	wCh	The 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_INITIALIZED	The 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]	hDevice	A device handle identifying the oscilloscope.
[in]	wCh	The 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_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

See also: ScpChGetDataValueMin; ScpChGetDataValueRange; Probe

Since: 0.4.0