Functions for controlling the arbitrary waveform buffer of a generator. More...

Collaboration diagram for Arbitrary waveform buffer:

Functions
TIEPIE_HW_API tiepie_hw_bool	tiepie_hw_generator_has_data (tiepie_hw_handle handle)
	Check whether the current signal type of a specified generator supports controlling the Arbitrary waveform buffer.

TIEPIE_HW_API uint64_t	tiepie_hw_generator_get_data_length_min (tiepie_hw_handle handle)
	Get the minimum length of the waveform buffer of a specified generator.

TIEPIE_HW_API uint64_t	tiepie_hw_generator_get_data_length_max (tiepie_hw_handle handle)
	Get the maximum length of the waveform buffer of a specified generator.

TIEPIE_HW_API uint64_t	tiepie_hw_generator_get_data_length (tiepie_hw_handle handle)
	Get the length of the currently loaded waveform pattern of a specified generator.

TIEPIE_HW_API void	tiepie_hw_generator_set_data (tiepie_hw_handle handle, const float *buffer, uint64_t sample_count)
	Load a waveform pattern into the waveform buffer of a specified generator.

Detailed 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 TIEPIE_HW_ST_ARBITRARY. Waveform patterns must have a length in samples between a minimum and maximum value. Use tiepie_hw_generator_get_data_length_min() and tiepie_hw_generator_get_data_length_max() 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 rate", the samples of the loaded pattern are generated at the set sample rate.

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 / WiFiScope WS5: for pattern lengths larger than 128 Ki_samples (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 Ki_samples, 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 (stretched) to the closest larger power of 2 samples.

When uploading patterns that get resampled, tiepie_hw_generator_set_data() will set status TIEPIE_HW_STATUS_VALUE_MODIFIED. Use tiepie_hw_generator_get_data_length() to determine the actually used length.

Function Documentation

◆ tiepie_hw_generator_has_data()

TIEPIE_HW_API tiepie_hw_bool tiepie_hw_generator_has_data ( tiepie_hw_handle handle )

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

Parameters

[in] handle A device handle identifying the generator.

Returns: TIEPIE_HW_BOOL_TRUE if supported, TIEPIE_HW_BOOL_FALSE if not.

Status values

TIEPIE_HW_STATUS_INVALID_HANDLE	The handle is not a valid generator handle.
TIEPIE_HW_STATUS_OBJECT_GONE
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS

See also: tiepie_hw_generator_set_data

Since: 1.0

◆ tiepie_hw_generator_get_data_length_min()

TIEPIE_HW_API uint64_t tiepie_hw_generator_get_data_length_min ( tiepie_hw_handle handle )

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

Parameters

[in] handle A device handle identifying the generator.

Returns: The minimum waveform buffer length in samples.

Status values

TIEPIE_HW_STATUS_NOT_SUPPORTED	The generator does not support getting the data length for the current signal type.
TIEPIE_HW_STATUS_INVALID_HANDLE	The handle is not a valid generator handle.
TIEPIE_HW_STATUS_OBJECT_GONE
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS

See also: tiepie_hw_generator_get_data_length_max; tiepie_hw_generator_get_data_length

Since: 1.0

◆ tiepie_hw_generator_get_data_length_max()

TIEPIE_HW_API uint64_t tiepie_hw_generator_get_data_length_max ( tiepie_hw_handle handle )

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

Parameters

[in] handle A device handle identifying the generator.

Returns: The maximum waveform buffer length in samples.

Status values

TIEPIE_HW_STATUS_NOT_SUPPORTED	The generator does not support getting the data length for the current signal type.
TIEPIE_HW_STATUS_INVALID_HANDLE	The handle is not a valid generator handle.
TIEPIE_HW_STATUS_OBJECT_GONE
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS

See also: tiepie_hw_generator_get_data_length_min; tiepie_hw_generator_get_data_length

Since: 1.0

◆ tiepie_hw_generator_get_data_length()

TIEPIE_HW_API uint64_t tiepie_hw_generator_get_data_length ( tiepie_hw_handle handle )

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

Parameters

[in] handle A device handle identifying the generator.

Returns: The currently set waveform pattern length in samples.

Status values

TIEPIE_HW_STATUS_NOT_SUPPORTED	The generator does not support getting the data length for the current signal type.
TIEPIE_HW_STATUS_INVALID_HANDLE	The handle is not a valid generator handle.
TIEPIE_HW_STATUS_OBJECT_GONE
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS

See also: tiepie_hw_generator_get_data_length_min; tiepie_hw_generator_get_data_length_max

Since: 1.0

◆ tiepie_hw_generator_set_data()

TIEPIE_HW_API void tiepie_hw_generator_set_data	(	tiepie_hw_handle	handle,
		const float *	buffer,
		uint64_t	sample_count
	)

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

Parameters

[in]	handle	A device handle identifying the generator.
[in]	buffer	A pointer to a buffer with the waveform data.
[in]	sample_count	The number of samples in the pattern.

Status values

TIEPIE_HW_STATUS_VALUE_MODIFIED	The requested data length is not available. The data is resampled to the closest valid length.
TIEPIE_HW_STATUS_INVALID_VALUE	The buffer pointer is `NULL` or the requested waveform pattern length is `0`.
TIEPIE_HW_STATUS_NOT_SUPPORTED	The generator does not support uploading pattern data for the current signal type.
TIEPIE_HW_STATUS_UNSUCCESSFUL
TIEPIE_HW_STATUS_NOT_CONTROLLABLE
TIEPIE_HW_STATUS_INVALID_HANDLE	The handle is not a valid generator handle.
TIEPIE_HW_STATUS_OBJECT_GONE
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS

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 tiepie_hw_generator_set_data with Buffer = NULL and sample_count = 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 TIEPIE_HW_GM_BURST_SEGMENT_COUNT or TIEPIE_HW_GM_BURST_SEGMENT_COUNT_OUTPUT.

See also: tiepie_hw_generator_get_data_length_min; tiepie_hw_generator_get_data_length_max; tiepie_hw_generator_get_data_length

Since: 1.0