AKELA OpenVNA
RAW_VNA Class Reference

Minimal wrapper for the VNA Dll. More...

Inheritance diagram for RAW_VNA:

## Public Member Functions

def __init__
Initialized a handle to the VNA by creating a new Task object. More...

def __del__

def initialize

def start
Attempts to program the VNA using the settings stored in the Task object. More...

def stop

Sets the IPv4 address on which to communicate with the unit. More...

def setIPPort
Sets the port on which to communicate with the unit. More...

def setTimeout
Sets the default time to wait, in milliseconds, for a unit to reply to a command before giving up and returning an ERR_NO_RESPONSE condition. More...

def setHopRate
Set the frequency hopping rate. More...

def setAttenuation
Set the attenuation amount. More...

def setFrequencies
Set the frequencies to measure during each sweep. More...

def getState
Get the current state of the Task object. More...

def getTimeout
Get the current network timeout setting for communications to the VNA. More...

def getIPPort
Get the port associated with this Task object. More...

def getHopRate
Get the frequency hopping rate associated with this Task object. More...

def getAttenuation
Get the attenuation associated with this Task object. More...

def getNumberOfFrequencies
Get the number of frequencies in the sweep. More...

def getFrequencies
Get the list of actual frequencies the hardware generates during the sweep. More...

def getHardwareDetails
Get the hardware details for the unit associated with this Task. More...

def utilNearestLegalFreq
Adjusts a requested frequency, in MHz, to the nearest able to be generated by the VNA hardware. More...

def utilFixLinearSweepLimits
Adjusts the start and end of a requested linear sweep with N points such that all frequencies in the sweep will land on exactly generateable values, and the inter-point spacing is constant across the entire scan. More...

def utilPingUnit
Sends an "are you there" message to the unit. More...

def utilGenerateLinearSweep
Generates a linear sweep with the requested parameters. More...

def measureUncalibrated
Measures the paths through the VNA, without applying calibration. More...

def measure2PortCalibrated
Measures the S-parameter of the connected device, applying the current calibration. More...

def measureCalibrationStep
Measures the paths necessary to get data for the requested calibration step. More...

def interruptMeasurement
Interrupts one of the measurement functions while it is waiting for data. More...

def clearCalibration
Deletes the calibration data (if any) that the Task is storing. More...

def isCalibrationComplete
Determine if the task has any calibration parameters. More...

def hasFactoryCalibration
Determine if the connected VNA has a preloaded factory calibration in it's embedded memory. More...

def importFactoryCalibration
Load the calibration from the VNA's embedded PROM into the current task. More...

def getCalibrationNumberOfFrequencies
Get the number of frequencies in the calibration data. More...

def getCalibrationFrequencies
Get the list of frequencies used in the calibration data. More...

def exportCalibration
Retreives the calibration arrays from the current task. More...

def importCalibration
Imports calibration coefficients from caller provided arrays. More...

## Detailed Description

Minimal wrapper for the VNA Dll.

Does type-conversion, return-code -> exception translation, and not much else.

## Constructor & Destructor Documentation

 def __init__ ( self )

Initialized a handle to the VNA by creating a new Task object.

The internal state of the VNA task will be TASK_UNINITIALIZED upon instantiation of the RAW_VNA() object.

Returns
Nothing

## Member Function Documentation

 def clearCalibration ( self )

Deletes the calibration data (if any) that the Task is storing.

Parameters
 None
Returns
Nothing

Will never throw an exception

If the caller does not do this, the task-handle memory will leak.

Note that this will be called automatically by the destructor.

Parameters
 None
Returns
Nothing
 def exportCalibration ( self )

Retreives the calibration arrays from the current task.

Note that to fully contain a calibration the caller must also get the frequency list and number of frequencies.

It is recommended to use the getCalibrationFrequencies() function to get the corresponding frequency point table, because the number and position of the of calibration frequency points do not have to match the sweep parameters.

Return value is a 12-tuple of arrays of length getCalibrationNumberOfFrequencies().

This function is the complement of importCalibration().

Parameters
 None
Returns
e00 Complex number which is an array of the EDF/e00 calibration term.
e11 Complex number which is an array of the ESF/e11 calibration term.
e10e01 Complex number which is an array of the ERF/e10e01 calibration term.
e30 Complex number which is an array of the EXF/e30 calibration term.
e22 Complex number which is an array of the ELF/e22 calibration term.
e10e32 Complex number which is an array of the ETF/e10e32 calibration term.
ep33 Complex number which is an array of the EDR/ep33 calibration term.
ep22 Complex number which is an array of the ESR/ep22 calibration term.
ep23ep32 Complex number which is an array of the ERR/ep23ep32 calibration term.
ep03 Complex number which is an array of the EXR/ep03 calibration term.
ep11 Complex number which is an array of the ELR/ep11 calibration term.
ep23ep01 Complex number which is an array of the ETR/ep23ep01 calibration term.

Exceptions
 def getAttenuation ( self )

Get the attenuation associated with this Task object.

Parameters
 None
Returns
Returns one of the values defined in AttenuationSettings-Py. If no rate has yet been set, this function returns ATTEN_UNDEFINED.
 def getCalibrationFrequencies ( self )

Get the list of frequencies used in the calibration data.

Parameters
 None
Returns
Numpy array of frequency points for which there is calibration data. If there is no calibration data, returns an empty numpy array.
 def getCalibrationNumberOfFrequencies ( self )

Get the number of frequencies in the calibration data.

Parameters
 None
Returns
Number of frequency points the current calibration contains. If there is no calibration present, the return value is 0
 def getFrequencies ( self )

Get the list of actual frequencies the hardware generates during the sweep.

TODO VALIDATE THIS!

Parameters
 None
Returns
If no frequencies have been set, this function returns 0.
 def getHardwareDetails ( self )

Get the hardware details for the unit associated with this Task.

TODO VALIDATE THIS!

Parameters
 None
Returns
An dictionary of the HardwareDetails members -> value mappings.

If the Task has not yet been initialized, the returned dict has all values set to 0.

 def getHopRate ( self )

Get the frequency hopping rate associated with this Task object.

Parameters
 None
Returns
Returns one of the values defined in HopRateSettings-Py. If no rate has yet been set, this function returns HOP_UNDEFINED.

Parameters
 None
Returns
VNA IP Address or None if no IP has been set.
 def getIPPort ( self )

Get the port associated with this Task object.

Parameters
 None
Returns
Configured communication port. Defaults to 0 if not set.
 def getNumberOfFrequencies ( self )

Get the number of frequencies in the sweep.

TODO VALIDATE THIS!

Parameters
 None
Returns
the number of frequency points in the currently configured sweep. If no frequencies have been set, this function defaults to returning 0.
 def getState ( self )

Get the current state of the Task object.

Parameters
 None
Returns
Returns one of the values defined in TaskState-Py.
 def getTimeout ( self )

Get the current network timeout setting for communications to the VNA.

When a Task is first created, the timeout defaults to 1000 milliseconds.

Parameters
 None
Returns
Integer timeout in milliseconds
 def hasFactoryCalibration ( self )

Determine if the connected VNA has a preloaded factory calibration in it's embedded memory.

Parameters
 None
Returns
True if the connected VNA has a factory calibration in it's PROM. False if it does not.
 def importCalibration ( self, freqs, e00, e11, e10e01, e30, e22, e10e32, ep33, ep22, ep12ep32, ep03, ep11, ep23ep01 )

Imports calibration coefficients from caller provided arrays.

Note that these frequencies do not have to be exactly generateable by the hardware. At import an interpolated calibration is generated that matches the current sweep settings.

Altering sweep settings automatically generates a new interpolated calibration from the original imported data provided here.

Copies of the passed arrays are stored in the task's memory for the duration of it's lifetime, or until overridden.

All 13 passed arrays must be the same length.

This function is the complement of exportCalibration().

Parameters
 freqs Array of frequency points for the calibration data arrays. Units are in Mhz. e00 Array of complex numbers containing the set of EDF/e00 calibration terms. e11 Array of complex numbers containing the set of ESF/e11 calibration terms. e10e01 Array of complex numbers containing the set of ERF/e10e01 calibration terms. e30 Array of complex numbers containing the set of EXF/e30 calibration terms. e22 Array of complex numbers containing the set of ELF/e22 calibration terms. e10e32 Array of complex numbers containing the set of ETF/e10e32 calibration terms. ep33 Array of complex numbers containing the set of EDR/ep33 calibration terms. ep22 Array of complex numbers containing the set of ESR/ep22 calibration terms. ep12ep32 Array of complex numbers containing the set of ERR/ep12ep32 calibration terms. ep03 Array of complex numbers containing the set of EXR/ep03 calibration terms. ep11 Array of complex numbers containing the set of ELR/ep11 calibration terms. ep23ep01 Array of complex numbers containing the set of ETR/ep23ep01 calibration terms.
Exceptions
 def importFactoryCalibration ( self )

Load the calibration from the VNA's embedded PROM into the current task.

Parameters
 None
Returns
Nothing
Throws
Exceptions
 ERR_BAD_CAL if the embedded calibration data is not present, or invalid. ERR_WRONG_STATE if the task is not in the TASK_STOPPED or TASK_STARTED state
 def initialize ( self )

Parameters
 Nothing
Returns
Nothing
Exceptions
 ERR_MISSING_IP if an IP has not been specified ERR_MISSING_PORT if a port has not been specified ERR_SOCKET if there was a problem setting up the UDP socket or sending a message ERR_NO_RESPONSE if the unit did not respond to commands ERR_BAD_PROM if the unit returned hardware details that this DLL doesn't understand ERR_WRONG_STATE if the Task is not in the TASK_UNINITIALIZED state
 def interruptMeasurement ( self )

Interrupts one of the measurement functions while it is waiting for data.

Since the measurement functions are blocking, this function must be called from a different thread. This function returns immediately, however the measurement function may continue to block for a short additional amount of time.

Parameters
 None
Exceptions
 def isCalibrationComplete ( self )

Determine if the task has any calibration parameters.

Parameters
 None
Returns
True if the task has calibration parameters. False if it does not.
 def measure2PortCalibrated ( self )

Measures the S-parameter of the connected device, applying the current calibration.

This command measures all 5 paths, as every path is required to properly apply the calibration.

Note that this function blocks while the measurement is being performed. Use the interruptMeasurement() function to prematurely halt a slow measurement.

Parameters
 None
Returns
(S11, S21, S12, S22) - numpy complex arrays as a 4-tuple. Each array is a 1-dimentional numpy array of complex numbers, with a length of getNumberOfFrequencies(). Each value in the array corresponds to a single frequency measurement. The measurement points can be retreived by calling getFrequencies(), where the [n]th getFrequencies() value corresponds to the frequency for the [n]th measure2PortCalibrated() entry.

Exceptions
 ERR_SOCKET if there was a problem sending a message ERR_NO_RESPONSE if the unit did not respond to commands ERR_WRONG_STATE if the Task is not in the TASK_STARTED state ERR_BAD_PATH if there is something wrong with the paths parameter ERR_BAD_CAL if the calibration is missing (i.e. isCalibrationComplete() == false) ERR_BYTES if the wrong number of bytes were received ERR_INTERRUPTED if the measurement was interrupted (generally by interruptMeasurement())
 def measureCalibrationStep ( self, step )

Measures the paths necessary to get data for the requested calibration step.

Note that this function blocks while the measurement is being performed. Use the interruptMeasurement() function to prematurely halt a slow measurement.

Calibration results are written into the local memory of the current task. The calibration results can later be retreived by calling exportCalibration().

Parameters
 step Instance of CalibrationStepSelector-Py corresponding the calibration step which should be measured.

Exceptions
 ERR_SOCKET if there was a problem sending a message ERR_NO_RESPONSE if the unit did not respond to commands ERR_WRONG_STATE if the Task is not in the TASK_STARTED state ERR_BAD_CAL if the current calibration settings do not match the current sweep settings (clear the calibration first before recalibrating) ERR_BYTES if the wrong number of bytes were received ERR_INTERRUPTED if the measurement was interrupted
 def measureUncalibrated ( self )

Measures the paths through the VNA, without applying calibration.

All 5 paths are always measured.

Note that this function blocks while the measurement is being performed. Use the interruptMeasurement() function to prematurely halt a slow measurement. The automatic timeout value is the length of the measurement plus getTimeout().

Parameters
 None
Returns
(T1R1, T1R2, T2R1, T2R2, Ref) - numpy complex arrays as a 5-tuple. Each array is a 1-dimentional numpy array of complex numbers, with a length of getNumberOfFrequencies(). Each value in the array corresponds to a single frequency measurement. The measurement points can be retreived by calling getFrequencies(), where the [n]th getFrequencies() value corresponds to the frequency for the [n]th measureUncalibrated() entry.

Exceptions
 ERR_SOCKET if there was a problem sending a message ERR_NO_RESPONSE if the unit did not respond to commands ERR_WRONG_STATE if the Task is not in the TASK_STARTED state ERR_BAD_PATH if there is something wrong with the paths parameter ERR_BYTES if the wrong number of bytes were received ERR_INTERRUPTED if the measurement was interrupted
 def setAttenuation ( self, atten )

Set the attenuation amount.

See the values defined above.

Parameters
 t Task-Handle rate An instance of AttenuationSettings-Py.
Returns
Nothing
Exceptions
 def setFrequencies ( self, freqs, N )

Set the frequencies to measure during each sweep.

Units are MHz. The freqs parameter is an array of length N. Note that the VNA frequency generation hardware has fixed precision and so the generated frequency may not be exactly equal to the requested frequency. This function silently converts all requested frequencies to frequencies that can be exactly generated by the hardware. This has important implications for doppler noise when doing a linear sweep. AKELA recommends using the function utilFixLinearSweepLimits() to ensure every frequency is exactly generateable and that the frequencies are equally spaced. Use the getFrequencies() function to get the actual frequencies being generated.

Parameters
 freqs A ctypes array of frequencies (as doubles, in MHz) to measure in a single sweep. The frequency points to not have to be linear, equally spaced, or follow any sort of ordering. However, due to band-change requirements (changing bands takes somewhat longer then changing frequencies within a band), grouping frequency points by band can improve sweep times.

Due to type resolution issues, this array MUST be constructed using the DoubleArrayFactory() call.

Parameters
 N The number of items in the array freqs
Returns
Nothing
Exceptions
 ERR_WRONG_STATE if the Task is not in the TASK_STOPPED state ERR_FREQ_OUT_OF_BOUNDS if a frequency is beyond the allowed min/max. (You can get the min and max from the HardwareDetails struct returned by getHardwareDetails()) ERR_TOO_MANY_POINTS if N is larger than the maximum allowed (see HardwareDetails)
 def setHopRate ( self, rate )

Set the frequency hopping rate.

See the values defined above.

Parameters
 rate An instance of HopRateSettings-Py.
Returns
Nothing
Exceptions
 ERR_BAD_HOP if there was something wrong with the hop rate parameter ERR_WRONG_STATE if the Task is not in the TASK_UNINITIALIZED or TASK_STOPPED state
 def setIPAddress ( self, ipv4 )

Sets the IPv4 address on which to communicate with the unit.

The ipv4 parameter is copied into the Task's memory. On success the Task's state will be TASK_UNINITIALIZED. Example setIPAddress(t, "192.168.1.197");

Parameters
 ipv4 VNA IP Address as a ASCII string.
Returns
Nothing
Exceptions
 ERR_MISSING_IP if the pointer is null ERR_WRONG_STATE if the Task is not in the TASK_UNINITIALIZED or TASK_STOPPED state
 def setIPPort ( self, port )

Sets the port on which to communicate with the unit.

Values should be >= 1024. On success the Task's state will be TASK_UNINITIALIZED.

Parameters
 port VNA desired port as an integer.
Returns
Nothing
Exceptions
 def setTimeout ( self, timeout )

Sets the default time to wait, in milliseconds, for a unit to reply to a command before giving up and returning an ERR_NO_RESPONSE condition.

For the measurement functions, this is the amount of time to wait beyond the expected sweep time. When a Task is created, the timeout value defaults to 1000.

A timeout value of 0 results in non-blocking call, where the call will return immediately if there is no data in the OS RX Buffer.

Parameters
 timeout Requested timeout in milliseconds.
Returns
Nothing
 def start ( self )

Attempts to program the VNA using the settings stored in the Task object.

Parameters
 Nothing
Returns
Nothing
    \exception ERR_SOCKET if there was a problem sending a message
\exception ERR_NO_RESPONSE if the unit did not respond to commands
\exception ERR_MISSING_HOP if the hop rate has not yet been specified
\exception ERR_MISSING_ATTEN if the attenuation has not yet been specified
\exception ERR_MISSING_FREQS if the frequencies have not yet been specified
\exception ERR_PROG_OVERFLOW if the size of the program is too large for the hardware's memory
(this can happen if there are too many frequencies)
 def stop ( self )

Parameters
 Nothing
Returns
Nothing
Exceptions
 def utilFixLinearSweepLimits ( self, target_start_freq, target_end_freq, N )

Adjusts the start and end of a requested linear sweep with N points such that all frequencies in the sweep will land on exactly generateable values, and the inter-point spacing is constant across the entire scan.

Unequal spacing can cause doppler noise in your data.

This may move the start and end frequencies of your scan slightly (<1 MHz).

If the input frequencies are equal, or N is 0 or 1, the frequencies are each simply adjusted to exactly generateable values.

TODO VALIDATE THIS!

Parameters
 target_start_freq Target Start-frequecny for linear sweep, in Mhz. target_end_freq Target End-frequency for linear-sweep, in Mhz. N Number of points to sample, spaced linearly between startFreq and endFreq
Returns
Adjusted start and stop frequencies as a 2-tuple
    \exception ERR_WRONG_STATE if the Task is in the TASK_UNINITIALIZED state
\exception ERR_FREQ_OUT_OF_BOUNDS if one of the bounds is beyond the allowed min/max. (You can get
the min and max from the HardwareDetails struct returned by getHardwareDetails())
\exception ERR_TOO_MANY_POINTS if N is larger than the maximum allowed (see \ref HardwareDetails)
 def utilGenerateLinearSweep ( self, startFreq, endFreq, N )

Generates a linear sweep with the requested parameters.

Note that the start and end frequency will be adjusted as documented in utilFixLinearSweepLimits() so that all frequency points fall on exactly generateable values. This function internally calls setFrequencies() with the resulting array. The caller can retrieve the frequency list with the getFrequencies() function. Since it changes the frequencies this function is only available in the TASK_STOPPED state.

Parameters
 startFreq Target Start-frequecny for linear sweep, in Mhz. endFreq Target End-frequency for linear-sweep, in Mhz. N Number of points to sample, spaced linearly between startFreq and endFreq
Returns
Nothing
Exceptions
 ERR_WRONG_STATE if the Task is not in the TASK_STOPPED state ERR_FREQ_OUT_OF_BOUNDS if one of the bounds is beyond the allowed min/max. (You can get the min and max from the HardwareDetails struct returned by getHardwareDetails()) ERR_TOO_MANY_POINTS if N is larger than the maximum allowed (see HardwareDetails)
 def utilNearestLegalFreq ( self, target_freq )

Adjusts a requested frequency, in MHz, to the nearest able to be generated by the VNA hardware.

This is not available in the TASK_UNINITIALIZED state.

TODO VALIDATE THIS!

Parameters
 target_freq Target frequency to be adjusted
Returns
Adjusted target_freq Frequency value as a float
    \exception ERR_WRONG_STATE if the Task is in the TASK_UNINITIALIZED state
\exception ERR_FREQ_OUT_OF_BOUNDS if the frequency is beyond the allowed min/max. (You can get
the min and max from the HardwareDetails struct returned by getHardwareDetails())
\exception VNADLL_API ErrCode utilNearestLegalFreq(TaskHandle t, double& freq);
 def utilPingUnit ( self )

Sends an "are you there" message to the unit.

Note that this function should not be called while a frequency sweep is ongoing, because it causes that sweep to prematurely halt and respond to this message instead. This is only an issue in multithreaded code, since the data acquisition functions are blocking. This function waits for a reply for the length of time specified by getTimeout() before giving up.

Note that this can be called from any state, provided an IP and port are present.

Raises an exception if the unit did not respond, returns nothing otherwise.

Parameters
 None
Returns
Nothing
    \exception ERR_SOCKET if there was a problem sending a message
\exception ERR_NO_RESPONSE if the unit did not respond to commands
\exception ERR_MISSING_IP if no IP address has been set
\exception ERR_MISSING_PORT if no port has been set

The documentation for this class was generated from the following file:
• /media/sf_Code/avmu-components-vna/VNA_Applications/PyVna/VNA/vnalibrary.py