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:

a value 0 (zero) will equal the set offset value.
the highest absolute value will equal the set amplitude value.

Example pattern:

Sample number	Buffer value	Generated voltage Amplitude = 7 V Offset = 0 V	Generated voltage Amplitude = 4V Offset = -1 V
0	0.0	0.0 V	-1.0 V
1	0.5	3.5 V	1.0 V
2	1.0	7.0 V	3.0 V
3	0.5	3.5 V	1.0 V
4	0.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] hDevice A 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_INITIALIZED	The 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] hDevice A 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_INITIALIZED	The 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] hDevice A 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_INITIALIZED	The 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] hDevice A 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_INITIALIZED	The 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]	hDevice	A device handle identifying the generator.
[in]	pBuffer	A pointer to a buffer with the waveform data.
[in]	qwSampleCount	The 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_INITIALIZED	The 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