![]() |
VSG60 API
|
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) |
API functions for the VSG60A vector signal generator.
This is the main file for user accessible functions for controlling the VSG60A vector signal generator.
#define VSG_MAX_DEVICES (8) |
Maximum number of devices that can be managed by the API.
#define VSG60_MIN_FREQ (30.0e6) |
Minimum configurable center frequency in Hz.
#define VSG60_MAX_FREQ (6.0e9) |
Maximum configurable center frequency in Hz.
#define VSG_MIN_SAMPLE_RATE (12.5e3) |
Minimum configurable sample (DAC) rate in Hz.
#define VSG_MAX_SAMPLE_RATE (54.0e6) |
Maximum configurable sample (DAC) rate in Hz.
#define VSG_MIN_LEVEL (-120.0) |
Minimum configurable output level in dBm.
#define VSG_MAX_LEVEL (10.0) |
Maximum configurable output level in dBm.
#define VSG_MIN_IQ_OFFSET (-1024) |
Minimum configurable I/Q offset
#define VSG_MAX_IQ_OFFSET (1024) |
Maximum configurable I/Q offset
#define VSG_MIN_TRIGGER_LENGTH (0.1e-6) |
Minimum configurable trigger length in seconds.
#define VSG_MAX_TRIGGER_LENGTH (0.1) |
Maximum configurable trigger length in seconds.
enum VsgTimebaseState |
enum VsgBool |
enum VsgStatus |
Status code returned from all API functions.
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”
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.
[out] | serials | Pointer to array. |
[in,out] | count | Pointer 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. |
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.
[out] | handle | Returns device handle. |
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.
[out] | handle | If this function returns successfully, handle will point to an integer that can be used to access this device through the API. |
[in] | serialNumber | The serial number of the device you wish to open. |
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.
[in] | handle | Device handle. |
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.
[in] | handle | Device handle. |
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.
[in] | handle | Device handle. |
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.
[in] | handle | Device handle. |
VSG_API VsgStatus vsgGetSerialNumber | ( | int | handle, |
int * | serial | ||
) |
Retreive the device serial number.
[in] | handle | Device handle. |
[out] | serial | Serial number. |
VSG_API VsgStatus vsgGetFirmwareVersion | ( | int | handle, |
int * | version | ||
) |
Retrieve the firmware version number. The version is a single integer value.
[in] | handle | Device handle. |
[out] | version | Firmware version. |
VSG_API VsgStatus vsgGetCalDate | ( | int | handle, |
uint32_t * | lastCalDate | ||
) |
Retrieve the last calibration date as the seconds since epoch.
[in] | handle | Device handle. |
[out] | lastCalDate | Calibration date as seconds since epoch. |
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.
[in] | handle | Device handle. |
[out] | temp | Device temperature in C. |
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.
[in] | handle | Device handle. |
[in] | enabled | Set to vsgFalse to disable the RF output. |
Retrive the RF output state.
[in] | handle | Device handle. |
[out] | enabled | Returns vsgTrue if the RF output is enabled. |
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.
handle | Device handle. |
state | New timebase state. |
VSG_API VsgStatus vsgGetTimebase | ( | int | handle, |
VsgTimebaseState * | state | ||
) |
Retrieve the current timebase state.
handle | Device handle. |
state | Returns current timebase state. |
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.
handle | Device handle. |
ppm | New timebase offset. The value will be clamped between [-2,+2] ppm. |
VSG_API VsgStatus vsgGetTimebaseOffset | ( | int | handle, |
double * | ppm | ||
) |
Retrieve the current user configured timebase offset in parts per million (PPM).
handle | Device handle. |
ppm | Returns current user PPM offset. |
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).
handle | Device handle. |
frequency | New center frequency in Hz. |
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.
handle | Device handle. |
frequency | Returns the center frequency in Hz. |
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.
handle | Device handle. |
sampleRate | New sample rate in Hz. |
VSG_API VsgStatus vsgGetSampleRate | ( | int | handle, |
double * | sampleRate | ||
) |
Retrieve the current I/Q (DAC) sample rate.
handle | Device handle. |
sampleRate | Returns the sample rate in Hz. |
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).
handle | Device handle. |
level | New output level in dBm. |
VSG_API VsgStatus vsgGetLevel | ( | int | handle, |
double * | level | ||
) |
Retrieve the current output level.
handle | Device handle. |
level | Output level in dBm. |
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.
handle | Device handle. |
atten | Attenuator value between [-50, 20] in 2dB steps. Must be an even number. |
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.
handle | Device handle. |
iqScale | Returns floating point value between [0.0, 1.0]. |
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.
handle | Device handle. |
iOffset | I channel offset between [-1024,1024]. |
qOffset | Q channel offset between [-1024,1024]. |
VSG_API VsgStatus vsgGetIQOffset | ( | int | handle, |
int16_t * | iOffset, | ||
int16_t * | qOffset | ||
) |
Retrieve the user configured I/Q offsets.
handle | Device handle. |
iOffset | Returns I channel offset. |
qOffset | Returns Q channel offset. |
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.
handle | Device handle. |
enabled | Set to vsgTrue to enable digital tuning. |
Retrieve whether digital tuning is enabled.
handle | Device handle. |
enabled | Returns vsgTrue if digital tuning is enabled. |
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.
handle | Device handle. |
seconds | Trigger length in seconds. |
VSG_API VsgStatus vsgGetTriggerLength | ( | int | handle, |
double * | seconds | ||
) |
Retrieve the output trigger length.
handle | Device handle. |
seconds | Returns the trigger length in seconds. |
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.
handle | Device handle. |
iq | Pointer to array of interleaved I/Q values. The array must be len*2 floating point values. |
len | Number of I/Q samples in the iq array |
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.
handle | Device handle. |
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.
handle | Device handle. |
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.
handle | Device handle. |
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.
handle | Device handle. |
iq | Pointer to arry of interleaved I/Q values. The array must be len*2 floating point values. |
len | The number of I/Q samples in the iq array. |
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.
handle | Device handle. |
iq | Pointer to arry of interleaved I/Q values. The array must be len*2 floating point values. |
len | The number of I/Q samples in the iq array. |
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}.
handle | Device handle. |
Detect whether a waveform is currently being generated via the vsgRepeatWaveform function.
handle | Device handle. |
active | Returns vsgTrue if a waveform is currently being transmitted. |
VSG_API VsgStatus vsgGetUSBStatus | ( | int | handle | ) |
Return the USB status warning.
handle | Device handle. |
VSG_API void vsgEnablePowerSavingCpuMode | ( | VsgBool | enabled | ) |
Enable power saving CPU mode See Power Saving CPU Mode for more information.
enabled | Set to vsgTrue to enable power saving CPU mode. |
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.
status | Status returned from an API function. |