VSG60 API
Macros | Enumerations | Functions
vsg_api.h File Reference

API functions for the VSG60A vector signal generator. More...

Go to the source code of this file.

Macros

#define VSG_MAX_DEVICES   (8)
 
#define VSG60_MIN_FREQ   (30.0e6)
 
#define VSG60_MAX_FREQ   (6.0e9)
 
#define VSG_MIN_SAMPLE_RATE   (12.5e3)
 
#define VSG_MAX_SAMPLE_RATE   (54.0e6)
 
#define VSG_MIN_LEVEL   (-120.0)
 
#define VSG_MAX_LEVEL   (10.0)
 
#define VSG_MIN_IQ_OFFSET   (-1024)
 
#define VSG_MAX_IQ_OFFSET   (1024)
 
#define VSG_MIN_TRIGGER_LENGTH   (0.1e-6)
 
#define VSG_MAX_TRIGGER_LENGTH   (0.1)
 

Enumerations

enum  VsgTimebaseState { vsgTimebaseStateInternal = 0 , vsgTimebaseStateExternal = 1 }
 
enum  VsgBool { vsgFalse = 0 , vsgTrue = 1 }
 
enum  VsgStatus {
}
 

Functions

VSG_API const char * vsgGetAPIVersion ()
 
VSG_API VsgStatus vsgGetDeviceList (int *serials, int *count)
 
VSG_API VsgStatus vsgOpenDevice (int *handle)
 
VSG_API VsgStatus vsgOpenDeviceBySerial (int *handle, int serialNumber)
 
VSG_API VsgStatus vsgCloseDevice (int handle)
 
VSG_API VsgStatus vsgPreset (int handle)
 
VSG_API VsgStatus vsgRecal (int handle)
 
VSG_API VsgStatus vsgAbort (int handle)
 
VSG_API VsgStatus vsgGetSerialNumber (int handle, int *serial)
 
VSG_API VsgStatus vsgGetFirmwareVersion (int handle, int *version)
 
VSG_API VsgStatus vsgGetCalDate (int handle, uint32_t *lastCalDate)
 
VSG_API VsgStatus vsgReadTemperature (int handle, float *temp)
 
VSG_API VsgStatus vsgSetRFOutputState (int handle, VsgBool enabled)
 
VSG_API VsgStatus vsgGetRFOutputState (int handle, VsgBool *enabled)
 
VSG_API VsgStatus vsgSetTimebase (int handle, VsgTimebaseState state)
 
VSG_API VsgStatus vsgGetTimebase (int handle, VsgTimebaseState *state)
 
VSG_API VsgStatus vsgSetTimebaseOffset (int handle, double ppm)
 
VSG_API VsgStatus vsgGetTimebaseOffset (int handle, double *ppm)
 
VSG_API VsgStatus vsgSetFrequency (int handle, double frequency)
 
VSG_API VsgStatus vsgGetFrequency (int handle, double *frequency)
 
VSG_API VsgStatus vsgSetSampleRate (int handle, double sampleRate)
 
VSG_API VsgStatus vsgGetSampleRate (int handle, double *sampleRate)
 
VSG_API VsgStatus vsgSetLevel (int handle, double level)
 
VSG_API VsgStatus vsgGetLevel (int handle, double *level)
 
VSG_API VsgStatus vsgSetAtten (int handle, int atten)
 
VSG_API VsgStatus vsgGetIQScale (int handle, double *iqScale)
 
VSG_API VsgStatus vsgSetIQOffset (int handle, int16_t iOffset, int16_t qOffset)
 
VSG_API VsgStatus vsgGetIQOffset (int handle, int16_t *iOffset, int16_t *qOffset)
 
VSG_API VsgStatus vsgSetDigitalTuning (int handle, VsgBool enabled)
 
VSG_API VsgStatus vsgGetDigitalTuning (int handle, VsgBool *enabled)
 
VSG_API VsgStatus vsgSetTriggerLength (int handle, double seconds)
 
VSG_API VsgStatus vsgGetTriggerLength (int handle, double *seconds)
 
VSG_API VsgStatus vsgSubmitIQ (int handle, float *iq, int len)
 
VSG_API VsgStatus vsgSubmitTrigger (int handle)
 
VSG_API VsgStatus vsgFlush (int handle)
 
VSG_API VsgStatus vsgFlushAndWait (int handle)
 
VSG_API VsgStatus vsgOutputWaveform (int handle, float *iq, int len)
 
VSG_API VsgStatus vsgRepeatWaveform (int handle, float *iq, int len)
 
VSG_API VsgStatus vsgOutputCW (int handle)
 
VSG_API VsgStatus vsgIsWaveformActive (int handle, VsgBool *active)
 
VSG_API VsgStatus vsgGetUSBStatus (int handle)
 
VSG_API void vsgEnablePowerSavingCpuMode (VsgBool enabled)
 
VSG_API const char * vsgGetErrorString (VsgStatus status)
 

Detailed Description

API functions for the VSG60A vector signal generator.

This is the main file for user accessible functions for controlling the VSG60A vector signal generator.

Macro Definition Documentation

◆ VSG_MAX_DEVICES

#define VSG_MAX_DEVICES   (8)

Maximum number of devices that can be managed by the API.

◆ VSG60_MIN_FREQ

#define VSG60_MIN_FREQ   (30.0e6)

Minimum configurable center frequency in Hz.

◆ VSG60_MAX_FREQ

#define VSG60_MAX_FREQ   (6.0e9)

Maximum configurable center frequency in Hz.

◆ VSG_MIN_SAMPLE_RATE

#define VSG_MIN_SAMPLE_RATE   (12.5e3)

Minimum configurable sample (DAC) rate in Hz.

◆ VSG_MAX_SAMPLE_RATE

#define VSG_MAX_SAMPLE_RATE   (54.0e6)

Maximum configurable sample (DAC) rate in Hz.

◆ VSG_MIN_LEVEL

#define VSG_MIN_LEVEL   (-120.0)

Minimum configurable output level in dBm.

◆ VSG_MAX_LEVEL

#define VSG_MAX_LEVEL   (10.0)

Maximum configurable output level in dBm.

◆ VSG_MIN_IQ_OFFSET

#define VSG_MIN_IQ_OFFSET   (-1024)

Minimum configurable I/Q offset

◆ VSG_MAX_IQ_OFFSET

#define VSG_MAX_IQ_OFFSET   (1024)

Maximum configurable I/Q offset

◆ VSG_MIN_TRIGGER_LENGTH

#define VSG_MIN_TRIGGER_LENGTH   (0.1e-6)

Minimum configurable trigger length in seconds.

◆ VSG_MAX_TRIGGER_LENGTH

#define VSG_MAX_TRIGGER_LENGTH   (0.1)

Maximum configurable trigger length in seconds.

Enumeration Type Documentation

◆ VsgTimebaseState

Used to indicate the source of the timebase reference for the device.

Enumerator
vsgTimebaseStateInternal 

Use the internal 10MHz timebase.

vsgTimebaseStateExternal 

Use an external 10MHz timebase on the 10 MHz In port.

◆ VsgBool

enum VsgBool

Boolean type. Used in public facing functions instead of bool to improve API use from different programming languages.

Enumerator
vsgFalse 

False

vsgTrue 

True

◆ VsgStatus

enum VsgStatus

Status code returned from all API functions.

Enumerator
vsgWaveformAlreadyActiveErr 

The auto pattern output is already active.

vsgWaveformNotActiveErr 

The waveform is already inactive.

vsgUsbXferErr 

There was a problem during USB data transfer.

vsgInvalidParameterErr 

Required parameter found to have invalid value.

vsgNullPtrErr 

One or more required pointer parameters were null.

vsgInvalidDeviceErr 

User specified invalid device index.

vsgDeviceNotFoundErr 

Unable to open device.

vsgNoError 

Function returned successfully. No error.

vsgAlreadyFlushed 

There are no pending operations.

vsgSettingClamped 

One or more of the provided settings were adjusted.

Function Documentation

◆ vsgGetAPIVersion()

VSG_API const char * vsgGetAPIVersion ( )

Returns a string indicating the version of the API. The returned string is of the form major.minor.revision. Ascii periods (‘.’) separate positive integers. Major/minor/revision are not guaranteed to be a single decimal digit. The string is null terminated. The string should not be modified or freed by the user. An example string is below… [‘3’ | ‘.’ | ‘0’ | ‘.’ | ‘1’ | ‘1’ | ‘\0’] = “3.0.11”

Returns

◆ vsgGetDeviceList()

VSG_API VsgStatus vsgGetDeviceList ( int *  serials,
int *  count 
)

This function is used to retrieve the serial number of all unopened VSG60 devices connected to the PC. If any device is open in a different process, it will be returned by this function. The serial numbers returned can then be used to open specific devices with the vsgOpenDeviceBySerial function.

Parameters
[out]serialsPointer to array.
[in,out]countPointer to integer that should equal the size of the serials array. If the function returns successfully, this value will be set to the number devices returned in the serials array. It will not exceed the size of the serials array.
Returns

◆ vsgOpenDevice()

VSG_API VsgStatus vsgOpenDevice ( int *  handle)

Claim the first unopened VSG60 detected on the system. If the device is opened successfully, a handle to the device will be returned. This handle can then be used to interface this device for all future API calls. This function has the same effect as calling vsgGetDeviceList and using the first device found to call vsgOpenDeviceBySerial.

Parameters
[out]handleReturns device handle.
Returns

◆ vsgOpenDeviceBySerial()

VSG_API VsgStatus vsgOpenDeviceBySerial ( int *  handle,
int  serialNumber 
)

This function operates similarly to vsgOpenDevice except it allows you to specify the device you wish to open. This function is often used in conjunction with vsgGetDeviceList when managing several VSG60 devices on one PC.

Parameters
[out]handleIf this function returns successfully, handle will point to an integer that can be used to access this device through the API.
[in]serialNumberThe serial number of the device you wish to open.
Returns

◆ vsgCloseDevice()

VSG_API VsgStatus vsgCloseDevice ( int  handle)

This function should be called when you are finished with the VSG60. It will release all resources for the device and the device will become available again for use in the current process. The device handle specified will no longer point to a valid device and the device must be re-opened again to be used. This function should be called before the process exits.

Parameters
[in]handleDevice handle.
Returns

◆ vsgPreset()

VSG_API VsgStatus vsgPreset ( int  handle)

Performs a full device preset. When this function returns, the hardware will have performed a full reset, the device handle will no longer be valid, vsgCloseDevice will have been called for the device handle, and the device will need to be re-opened. This function can be used to recover from an undesirable device state. This function takes roughly 3 seconds to complete.

Parameters
[in]handleDevice handle.
Returns

◆ vsgRecal()

VSG_API VsgStatus vsgRecal ( int  handle)

When operating the VSG60 for long periods of time with a fixed configuration, environmental changes leading to changes in the internal operating temperature of the VSG can cause signal drift leading to loss of amplitude accuracy and image rejection performance. This function aborts any current operation, and updates internal temperature corrections for the current configuration.

Parameters
[in]handleDevice handle.
Returns

◆ vsgAbort()

VSG_API VsgStatus vsgAbort ( int  handle)

This function returns the device to an idle state. If any waveform is being generated, it will be stopped. If the device is streaming in the complex generation mode, all I/Q data pending is discarded and all frequency/level changes are finished before returning. When this function returns, the device will be in an idle state.

Parameters
[in]handleDevice handle.
Returns

◆ vsgGetSerialNumber()

VSG_API VsgStatus vsgGetSerialNumber ( int  handle,
int *  serial 
)

Retreive the device serial number.

Parameters
[in]handleDevice handle.
[out]serialSerial number.
Returns

◆ vsgGetFirmwareVersion()

VSG_API VsgStatus vsgGetFirmwareVersion ( int  handle,
int *  version 
)

Retrieve the firmware version number. The version is a single integer value.

Parameters
[in]handleDevice handle.
[out]versionFirmware version.
Returns

◆ vsgGetCalDate()

VSG_API VsgStatus vsgGetCalDate ( int  handle,
uint32_t *  lastCalDate 
)

Retrieve the last calibration date as the seconds since epoch.

Parameters
[in]handleDevice handle.
[out]lastCalDateCalibration date as seconds since epoch.
Returns

◆ vsgReadTemperature()

VSG_API VsgStatus vsgReadTemperature ( int  handle,
float *  temp 
)

Retrive the device temperature in Celcius. If the device is not idle, the last read temperature is returned, otherwise the device temperature is queried before returning.

Parameters
[in]handleDevice handle.
[out]tempDevice temperature in C.
Returns

◆ vsgSetRFOutputState()

VSG_API VsgStatus vsgSetRFOutputState ( int  handle,
VsgBool  enabled 
)

Use this function to disable the RF output of the VSG60. Even when the VSG is not transmitting, it might still be emitting spurious energy related to clock frequencies and the DC offset. Disabling the RF output will eliminate most spurious signals. The RF output is enabled by default. When the RF output is disabled the only way to enable it again is to call this function. Until then, all actions will continue to be performed but with the RF output disabled. Additionally, the vsgAbort function is called when this function is called. This means any signal actively being generated will be stopped when this function is called.

Parameters
[in]handleDevice handle.
[in]enabledSet to vsgFalse to disable the RF output.
Returns

◆ vsgGetRFOutputState()

VSG_API VsgStatus vsgGetRFOutputState ( int  handle,
VsgBool enabled 
)

Retrive the RF output state.

Parameters
[in]handleDevice handle.
[out]enabledReturns vsgTrue if the RF output is enabled.
Returns

◆ vsgSetTimebase()

VSG_API VsgStatus vsgSetTimebase ( int  handle,
VsgTimebaseState  state 
)

Specify whether the VSG60 should use its internal 10MHz reference or one provided on the 10MHz reference input port. If external reference is selected and no reference is provided, the frequency error may be off by several PPM. If the state provided matches the current state, the function returns immediately. Any active waveforms are paused, and the stream is flushed before this operation takes place.

Parameters
handleDevice handle.
stateNew timebase state.
Returns

◆ vsgGetTimebase()

VSG_API VsgStatus vsgGetTimebase ( int  handle,
VsgTimebaseState state 
)

Retrieve the current timebase state.

Parameters
handleDevice handle.
stateReturns current timebase state.
Returns

◆ vsgSetTimebaseOffset()

VSG_API VsgStatus vsgSetTimebaseOffset ( int  handle,
double  ppm 
)

Adjust the VSG60 timebase. The adjustment is provided in parts per million (PPM) This adjustment will only last until the device is closed via vsgCloseDevice or the program is terminated. If the value provided matches the currently set value, this function returns immediately. Any active waveforms are paused, and the stream is flushed before this operation takes place.

Parameters
handleDevice handle.
ppmNew timebase offset. The value will be clamped between [-2,+2] ppm.
Returns

◆ vsgGetTimebaseOffset()

VSG_API VsgStatus vsgGetTimebaseOffset ( int  handle,
double *  ppm 
)

Retrieve the current user configured timebase offset in parts per million (PPM).

Parameters
handleDevice handle.
ppmReturns current user PPM offset.
Returns

◆ vsgSetFrequency()

VSG_API VsgStatus vsgSetFrequency ( int  handle,
double  frequency 
)

Set the center frequency of the signal generator. This function is used for both basic and streaming operation. In streaming operation, this operation takes 200us to complete. This operation will occur even if the provided frequency matches the current frequency. This operation may configure a recalibration (at no time penalty).

Parameters
handleDevice handle.
frequencyNew center frequency in Hz.
Returns

◆ vsgGetFrequency()

VSG_API VsgStatus vsgGetFrequency ( int  handle,
double *  frequency 
)

Retrieve the current center frequency. This function will return the last user configured center frequency even if the hardware has yet to update to the new value.

Parameters
handleDevice handle.
frequencyReturns the center frequency in Hz.
Returns

◆ vsgSetSampleRate()

VSG_API VsgStatus vsgSetSampleRate ( int  handle,
double  sampleRate 
)

Sets the I/Q (DAC) sample rate of the signal generator. The streaming queue is flushed via vsgFlushAndWait before the sample rate is updated. If the supplied sample rate is the same as the current rate, this function returns immediately and no operation occurs. A full sample rate change takes approximately 200-250ms.

Parameters
handleDevice handle.
sampleRateNew sample rate in Hz.
Returns

◆ vsgGetSampleRate()

VSG_API VsgStatus vsgGetSampleRate ( int  handle,
double *  sampleRate 
)

Retrieve the current I/Q (DAC) sample rate.

Parameters
handleDevice handle.
sampleRateReturns the sample rate in Hz.
Returns

◆ vsgSetLevel()

VSG_API VsgStatus vsgSetLevel ( int  handle,
double  level 
)

Set the output level of the signal generator. The output level represents the output power at the RF output port when I/Q samples of magnitude 1.0 are transmitted. Hardware attenuation, amplification, and digital scaling are used to achieve the requested output level. What values are used depend on the temperature calibration coefficients for individual device and the frequency of the output. In streaming operation, this operation takes 10us to complete. This operation will occur even if the provided level matches the current level. This operation may configure a recalibration (at no time penalty).

Parameters
handleDevice handle.
levelNew output level in dBm.
Returns

◆ vsgGetLevel()

VSG_API VsgStatus vsgGetLevel ( int  handle,
double *  level 
)

Retrieve the current output level.

Parameters
handleDevice handle.
levelOutput level in dBm.
Returns

◆ vsgSetAtten()

VSG_API VsgStatus vsgSetAtten ( int  handle,
int  atten 
)

This function allows the customer to guarantee the configuration of the internal attenuator and amplifier directly by specifying a fixed system attenuation. Values that are positive utilize the amplifier to achieve the desired setting. Calling this function overrides the output level configured via vsgSetLevel. A digital I/Q scale of 0.5 is used when attenuation is manually set. See vsgGetIQScale.

Parameters
handleDevice handle.
attenAttenuator value between [-50, 20] in 2dB steps. Must be an even number.
Returns

◆ vsgGetIQScale()

VSG_API VsgStatus vsgGetIQScale ( int  handle,
double *  iqScale 
)

Returns the currently used digital scale applied to the I/Q data before transmitting. The digital scaling is used in conjunction with the hardware amplifier and attenuator to achieve the desired output level. This function does not interrupt any active waveforms or streaming generation.

Parameters
handleDevice handle.
iqScaleReturns floating point value between [0.0, 1.0].
Returns

◆ vsgSetIQOffset()

VSG_API VsgStatus vsgSetIQOffset ( int  handle,
int16_t  iOffset,
int16_t  qOffset 
)

Specify an additional I/Q offset applied to the I/Q data before transmit. Used to fine improve carrier feedthrough. The offset lasts until the device is closed or the program is terminated. vsgFlushAndWait is called at the beginning of this function. If the supplied value matches the current value, this function returns immediately.

Parameters
handleDevice handle.
iOffsetI channel offset between [-1024,1024].
qOffsetQ channel offset between [-1024,1024].
Returns

◆ vsgGetIQOffset()

VSG_API VsgStatus vsgGetIQOffset ( int  handle,
int16_t *  iOffset,
int16_t *  qOffset 
)

Retrieve the user configured I/Q offsets.

Parameters
handleDevice handle.
iOffsetReturns I channel offset.
qOffsetReturns Q channel offset.
Returns

◆ vsgSetDigitalTuning()

VSG_API VsgStatus vsgSetDigitalTuning ( int  handle,
VsgBool  enabled 
)

If the value is provided is, this function returns immediately with no effect. vsgFlushAndWait is called before the operation occurs. See the VSG60 Product Manual for a description of digital tuning.

Parameters
handleDevice handle.
enabledSet to vsgTrue to enable digital tuning.
Returns

◆ vsgGetDigitalTuning()

VSG_API VsgStatus vsgGetDigitalTuning ( int  handle,
VsgBool enabled 
)

Retrieve whether digital tuning is enabled.

Parameters
handleDevice handle.
enabledReturns vsgTrue if digital tuning is enabled.
Returns

◆ vsgSetTriggerLength()

VSG_API VsgStatus vsgSetTriggerLength ( int  handle,
double  seconds 
)

Set the length of time the output trigger port remains high when a trigger is output. Default is 10us. (10.0e-6) The range of acceptable values is [100ns, 1s] This function does not interrupt any active waveforms or streaming operation.

Parameters
handleDevice handle.
secondsTrigger length in seconds.
Returns

◆ vsgGetTriggerLength()

VSG_API VsgStatus vsgGetTriggerLength ( int  handle,
double *  seconds 
)

Retrieve the output trigger length.

Parameters
handleDevice handle.
secondsReturns the trigger length in seconds.
Returns

◆ vsgSubmitIQ()

VSG_API VsgStatus vsgSubmitIQ ( int  handle,
float *  iq,
int  len 
)

Submit an array of I/Q samples to be generated with the current configuration. If an ARB waveform is currently being transmitted via the vsgRepeatWaveform function, it is aborted, and the device starts operating in the streaming configuration. This function should only be used for streaming operation. For generating simple waveforms, use the vsgOutputWaveform and vsgRepeatWaveform functions. This function will block until there is room in the processing and command queue. See Complex Signal Generation (Streaming) for more information.

Parameters
handleDevice handle.
iqPointer to array of interleaved I/Q values. The array must be len*2 floating point values.
lenNumber of I/Q samples in the iq array
Returns

◆ vsgSubmitTrigger()

VSG_API VsgStatus vsgSubmitTrigger ( int  handle)

Submit a streaming trigger event. If an ARB waveform is currently being transmitted, it is aborted, and the device starts operating in the streaming configuration. If a trigger is already active when the new trigger is output, it is first toggled low before re-toggling high, resetting the trigger high period in the process. See the Basic Signal Generation section for more information.

Parameters
handleDevice handle.
Returns

◆ vsgFlush()

VSG_API VsgStatus vsgFlush ( int  handle)

Pushes all pending operations in a stream out to the device. This function should be called after a sequence of streaming events to ensure there are no gaps in the output. Also see vsgFlushAndWait.

Parameters
handleDevice handle.
Returns

◆ vsgFlushAndWait()

VSG_API VsgStatus vsgFlushAndWait ( int  handle)

Pushes all pending operations in a stream out to the device and waits for all operations to complete. This function should be called after a sequence of streaming events to ensure there are no gaps in the output. When this function returns, the device will be idle.

Parameters
handleDevice handle.
Returns

◆ vsgOutputWaveform()

VSG_API VsgStatus vsgOutputWaveform ( int  handle,
float *  iq,
int  len 
)

Output the I/Q waveform once and returns. This function has the same effect as calling vsgSubmitIQ followed by vsgFlushAndWait. This function returns once the waveform has been transmitted. The device will be in an idle state when returned. If an ARB waveform is active, it is aborted prior to transmission.

Parameters
handleDevice handle.
iqPointer to arry of interleaved I/Q values. The array must be len*2 floating point values.
lenThe number of I/Q samples in the iq array.
Returns

◆ vsgRepeatWaveform()

VSG_API VsgStatus vsgRepeatWaveform ( int  handle,
float *  iq,
int  len 
)

This function instructs the API to continually generate the provided waveform. A full copy of the waveform is made before generation occurs. This function blocks until signal generation has begun. The repeated waveform is only stopped after calling the vsgAbort function or by calling a function that interrupts operation. Setting any other configuration value, such as frequency, level, etc. will pause the waveform until the configuration completes and then generation starts again from the beginning. See vsgIsWaveformActive.

Parameters
handleDevice handle.
iqPointer to arry of interleaved I/Q values. The array must be len*2 floating point values.
lenThe number of I/Q samples in the iq array.
Returns

◆ vsgOutputCW()

VSG_API VsgStatus vsgOutputCW ( int  handle)

Convenience function which outputs a CW signal with the current frequency, level, and sample rate. This function has the same effect as calling vsgRepeatWaveform with a single I/Q value of {1,0}.

Parameters
handleDevice handle.
Returns

◆ vsgIsWaveformActive()

VSG_API VsgStatus vsgIsWaveformActive ( int  handle,
VsgBool active 
)

Detect whether a waveform is currently being generated via the vsgRepeatWaveform function.

Parameters
handleDevice handle.
activeReturns vsgTrue if a waveform is currently being transmitted.
Returns

◆ vsgGetUSBStatus()

VSG_API VsgStatus vsgGetUSBStatus ( int  handle)

Return the USB status warning.

Parameters
handleDevice handle.
Returns

◆ vsgEnablePowerSavingCpuMode()

VSG_API void vsgEnablePowerSavingCpuMode ( VsgBool  enabled)

Enable power saving CPU mode See Power Saving CPU Mode for more information.

Parameters
enabledSet to vsgTrue to enable power saving CPU mode.

◆ vsgGetErrorString()

VSG_API const char * vsgGetErrorString ( VsgStatus  status)

Retrieve an ascii description string for a given VsgStatus. The string is useful for printing an debugging purposes.

Parameters
statusStatus returned from an API function.
Returns
A pointer to a null terminated string. The memory should not be freed/deallocated/modified.