AKELA OpenVNA
|
|
AKELA OpenVNA
|
Minimal wrapper for the VNA Dll. More...
Public Member Functions | |
| def | __init__ |
| Initialized a handle to the VNA by creating a new Task object. More... | |
| def | __del__ |
| def | deleteTask |
| Deletes the Task object. More... | |
| def | initialize |
| Attempts to talk to the unit specified by the Task's IP address, and download its details. More... | |
| def | start |
| Attempts to program the VNA using the settings stored in the Task object. More... | |
| def | stop |
| Puts the Task object into the TASK_STOPPED state. More... | |
| def | setIPAddress |
| 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 | getIPAddress |
| Get the IP address associated with this Task object. 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... | |
Private Attributes | |
| __task | |
Minimal wrapper for the VNA Dll.
Does type-conversion, return-code -> exception translation, and not much else.
| 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.
| def clearCalibration | ( | self | ) |
Deletes the calibration data (if any) that the Task is storing.
| None |
Will never throw an exception
| def deleteTask | ( | self | ) |
Deletes the Task object.
If the caller does not do this, the task-handle memory will leak.
Note that this will be called automatically by the destructor.
| None |
| 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().
| None |
| ERR_BAD_CAL | if isCalibrationComplete() returns false |
| def getAttenuation | ( | self | ) |
Get the attenuation associated with this Task object.
| None |
| def getCalibrationFrequencies | ( | self | ) |
Get the list of frequencies used in the calibration data.
| None |
| def getCalibrationNumberOfFrequencies | ( | self | ) |
Get the number of frequencies in the calibration data.
| None |
| def getFrequencies | ( | self | ) |
Get the list of actual frequencies the hardware generates during the sweep.
TODO VALIDATE THIS!
| None |
| def getHardwareDetails | ( | self | ) |
Get the hardware details for the unit associated with this Task.
TODO VALIDATE THIS!
| None |
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.
| None |
| def getIPAddress | ( | self | ) |
Get the IP address associated with this Task object.
| None |
None if no IP has been set. | def getIPPort | ( | self | ) |
Get the port associated with this Task object.
| None |
| def getNumberOfFrequencies | ( | self | ) |
Get the number of frequencies in the sweep.
TODO VALIDATE THIS!
| None |
| def getState | ( | self | ) |
Get the current state of the Task object.
| None |
| 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.
| None |
| def hasFactoryCalibration | ( | self | ) |
Determine if the connected VNA has a preloaded factory calibration in it's embedded memory.
| None |
| 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().
| 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. |
| ERR_BAD_CAL | if any of the array pointers are null |
| ERR_WRONG_STATE | if the Task is not in the TASK_STOPPED or TASK_STARTED state |
| def importFactoryCalibration | ( | self | ) |
Load the calibration from the VNA's embedded PROM into the current task.
| None |
| 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 | ) |
Attempts to talk to the unit specified by the Task's IP address, and download its details.
If it succeeds the Task enters the TASK_STOPPED state.
| Nothing |
| 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.
| None |
| ERR_WRONG_STATE | if the Task is not in the TASK_STARTED state |
| def isCalibrationComplete | ( | self | ) |
Determine if the task has any calibration parameters.
| None |
| 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.
| None |
| 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().
| step | Instance of CalibrationStepSelector-Py corresponding the calibration step which should be measured. |
| 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().
| None |
| 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.
| t | Task-Handle |
| rate | An instance of AttenuationSettings-Py. |
| ERR_BAD_ATTEN | if there was something wrong with the attenuation parameter |
| ERR_WRONG_STATE | if the Task is not in the TASK_UNINITIALIZED or TASK_STOPPED state |
| 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.
| 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.
| N | The number of items in the array freqs |
| 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.
| rate | An instance of HopRateSettings-Py. |
| 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");
| ipv4 | VNA IP Address as a ASCII string. |
| 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.
| port | VNA desired port as an integer. |
| ERR_WRONG_STATE | if the Task is not in the TASK_UNINITIALIZED or TASK_STOPPED state |
| 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.
| timeout | Requested timeout in milliseconds. |
| def start | ( | self | ) |
Attempts to program the VNA using the settings stored in the Task object.
If it succeeds the Task enters the TASK_STARTED state.
| 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_WRONG_STATE if the Task is not in the TASK_STOPPED state
\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 | ) |
Puts the Task object into the TASK_STOPPED state.
| Nothing |
| ERR_WRONG_STATE | if the Task is not in the TASK_STARTED state |
| 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!
| 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 |
\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.
| 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 |
| 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!
| target_freq | Target frequency to be 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.
| None |
\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
1.8.6