LibTiePie  0.9.12
Library for interfacing TiePie engineering instruments
Arbitrary waveform buffer

Description

Functions for controlling the arbitrary waveform buffer of a generator.

A generator has a buffer in which arbitrary waveform patterns can be loaded, after which the loaded pattern can be generated, when the signal type is set to ST_ARBITRARY. Waveform patterns must have a length in samples between a minimum and maximum value. Use GenGetDataLengthMin() and GenGetDataLengthMax() to get the buffer length limits in samples.

When the frequency mode is set to "signal frequency", the loaded pattern is treated as one period of the signal to generate. When the frequency mode is set to "sample frequency", the samples of the loaded pattern are generated at the set sample frequency.

The samples in the waveform pattern buffer represent the voltage values of the signal to generate. These sample values are unitless floating point values. Positive values represent the positive part of the signal. Negative values represent the negative part of the signal. When loading the buffer, the values in the buffer are normalized:

Example pattern:

Sample numberBuffer valueGenerated voltage
Amplitude = 7 V
Offset = 0 V
Generated voltage
Amplitude = 4V
Offset = -1 V
00.0 0.0 V -1.0 V
10.5 3.5 V 1.0 V
21.0 7.0 V 3.0 V
30.5 3.5 V 1.0 V
40.0 0.0 V -1.0 V
5-0.5 -3.5 V -3.0 V
6-1.0 -7.0 V -5.0 V
7-0.5 -3.5 V -3.0 V

There are a few limitations with the arbitrary waveform pattern length:

Handyscope HS5: for pattern lengths larger than 128 KiSamples (131072 samples), the pattern length must be a multiple of 4 samples. When the length is not a multiple of 4, the data will be resampled to the closest smaller multiple of 4 samples. For pattern lengths smaller than 128 KiSamples, there are no length limitations.

Handyscope HS3: patterns must have a length that is a "power of 2" samples long, e.g. 1024, 2048, 4096, etc.. When the length is not a power of 2, the data will be resampled to the closest larger power of 2 samples.

When uploading patterns that get resampled, GenSetData() will set status LIBTIEPIESTATUS_VALUE_MODIFIED. Use GenGetDataLength() to determine the actually used length.

Functions

bool8_t GenHasData (LibTiePieHandle_t hDevice)
 Check whether the current signal type of a specified generator supports controlling the Arbitrary waveform buffer. More...
 
uint64_t GenGetDataLengthMin (LibTiePieHandle_t hDevice)
 Get the minimum length of the waveform buffer of a specified generator. More...
 
uint64_t GenGetDataLengthMax (LibTiePieHandle_t hDevice)
 Get the maximum length of the waveform buffer of a specified generator. More...
 
uint64_t GenGetDataLength (LibTiePieHandle_t hDevice)
 Get the length of the currently loaded waveform pattern of a specified generator. More...
 
void GenSetData (LibTiePieHandle_t hDevice, const float *pBuffer, uint64_t qwSampleCount)
 Load a waveform pattern into the waveform buffer of a specified generator. More...
 

Function Documentation

bool8_t GenHasData ( LibTiePieHandle_t  hDevice)

Check whether the current signal type of a specified generator supports controlling the Arbitrary waveform buffer.

Parameters
[in]hDeviceA device handle identifying the generator.
Returns
BOOL8_TRUE if supported, BOOL8_FALSE if not.
Status values
INVALID_HANDLE The handle is not a valid generator 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
GenSetData
Since
0.6
uint64_t GenGetDataLengthMin ( LibTiePieHandle_t  hDevice)

Get the minimum length of the waveform buffer of a specified generator.

Parameters
[in]hDeviceA device handle identifying the generator.
Returns
The minimum waveform buffer length in samples.
Status values
NOT_SUPPORTED The generator does not support getting the data length for the current signal type.
INVALID_HANDLE The handle is not a valid generator 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
GenGetDataLengthMax
GenGetDataLength
Since
0.4.2
uint64_t GenGetDataLengthMax ( LibTiePieHandle_t  hDevice)

Get the maximum length of the waveform buffer of a specified generator.

Parameters
[in]hDeviceA device handle identifying the generator.
Returns
The maximum waveform buffer length in samples.
Status values
NOT_SUPPORTED The generator does not support getting the data length for the current signal type.
INVALID_HANDLE The handle is not a valid generator 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
GenGetDataLengthMin
GenGetDataLength
Since
0.4.0
uint64_t GenGetDataLength ( LibTiePieHandle_t  hDevice)

Get the length of the currently loaded waveform pattern of a specified generator.

Parameters
[in]hDeviceA device handle identifying the generator.
Returns
The currently set waveform pattern length in samples.
Status values
NOT_SUPPORTED The generator does not support getting the data length for the current signal type.
INVALID_HANDLE The handle is not a valid generator 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
GenGetDataLengthMin
GenGetDataLengthMax
Since
0.4.0
void GenSetData ( LibTiePieHandle_t  hDevice,
const float *  pBuffer,
uint64_t  qwSampleCount 
)

Load a waveform pattern into the waveform buffer of a specified generator.

Parameters
[in]hDeviceA device handle identifying the generator.
[in]pBufferA pointer to a buffer with the waveform data.
[in]qwSampleCountThe number of samples in the pattern.
Status values
VALUE_MODIFIED The requested data length is not available. The data is resampled to the closest valid length.
INVALID_VALUE The buffer pointer is NULL or the requested waveform pattern length is 0.
NOT_SUPPORTED The generator does not support uploading pattern data for the current signal type.
UNSUCCESSFUL An error occurred during execution of the last called function.
NOT_CONTROLLABLE The generator is currently not controllable, see GenIsControllable.
INVALID_HANDLE The handle is not a valid generator 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.
Remarks
Signal type must be set to arbitrary mode to load a waveform pattern into the waveform buffer.
To clear and reset the waveform buffer, call GenSetData with pBuffer = NULL and qwSampleCount = 0.
When the generator is active, uploading new a waveform pattern will shortly interrupt the output signal.
Changing the data may change the burst segment count if generator mode is GM_BURST_SEGMENT_COUNT or GM_BURST_SEGMENT_COUNT_OUTPUT.
See also
GenGetDataLengthMin
GenGetDataLengthMax
GenGetDataLength
Since
0.4.0