libtiepie-hw  1.2.0
Arbitrary waveform buffer

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

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:

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 / 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]handleA 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]handleA 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]handleA 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]handleA 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]handleA device handle identifying the generator.
[in]bufferA pointer to a buffer with the waveform data.
[in]sample_countThe 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