Modules
	ErrorCodes
	Potential error-codes API calls can return.

	HopRateSettings
	Settings for the hop-rate (e.g. time spent sampling each frequency point) in a sweep.

	AttenuationSettings
	Attenuation options for the attenuation parameter.

	TaskState
	Available task states.

	CalibrationStep
	Available calibration steps.

Data Structures
struct	HardwareDetails

struct	ComplexData

Typedefs
typedef struct task_t *	TaskHandle
	Opaque type for containing the parameters and associated resources for interfacing with a single VNA. More...

typedef bool(*	progress_callback )(int progressPercent, void *user)
	This is the method signature for the callback function passed to the `initialize()` function. More...

Functions
const char *	versionString ()
	Returns a string describing the version of the DLL and its components. More...

TaskHandle	createTask ()
	Creates a new Task object and returns a handle to it. This handle is required by all of the other API functions. The returned object is in the TASK_UNINITIALIZED state. More...

void	deleteTask (TaskHandle t)
	Deletes the Task object. If the caller does not do this, the handle memory will leak. More...

ErrCode	initialize (TaskHandle t, progress_callback callback=0, void *user=0)
	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. More...

ErrCode	start (TaskHandle t)
	Attempts to program the VNA using the settings stored in the Task object. If it succeeds the Task enters the TASK_STARTED state. More...

ErrCode	stop (TaskHandle t)
	Puts the Task object into the TASK_STOPPED state. More...

ErrCode	setIPAddress (TaskHandle t, const char *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");. More...

ErrCode	setIPPort (TaskHandle t, const int port)
	Sets the port on which to communicate with the unit. In general, ports >= 1024 should be used. On success the Task's state will be TASK_UNINITIALIZED. More...

ErrCode	setTimeout (TaskHandle t, const unsigned int 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 150. More...

ErrCode	setHopRate (TaskHandle t, const HopRate rate)
	Set the frequency hopping rate. See the values defined in the "HopRate" type above. More...

ErrCode	setAttenuation (TaskHandle t, const Attenuation atten)
	Set the attenuation amount. See the values defined above. More...

ErrCode	setFrequencies (TaskHandle t, const double *freqs, const unsigned int 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. More...

TaskState	getState (TaskHandle t)
	Get the current state of the Task object. Returns one of the values defined above. More...

unsigned int	getTimeout (TaskHandle t)
	Get the current time to wait for the unit to reply to commands. When a Task is first created, this will default to 150. More...

const char *	getIPAddress (TaskHandle t)
	Get the current AVMU IP address for the Task object. When no IP has yet been set, this will return a NULL char*. More...

int	getIPPort (TaskHandle t)
	Get the current port for IP communications. When uninitialized, this will default to 0. More...

HopRate	getHopRate (TaskHandle t)
	Get the frequency hopping rate associated with this Task object. If no rate has yet been set, this function returns HOP_UNDEFINED. More...

Attenuation	getAttenuation (TaskHandle t)
	Get the attenuation associated with this Task object. If no rate has yet been set, this function returns ATTEN_UNDEFINED. More...

unsigned int	getNumberOfFrequencies (TaskHandle t)
	Get the number of frequency points for the sweep configured for Task `t`. If no frequencies have been set, this function returns 0. More...

const double *	getFrequencies (TaskHandle t)
	Get a list containing the actual frequencies the hardware will sample for the configured sweep in task `t`. More...

HardwareDetails	getHardwareDetails (TaskHandle t)
	Get the hardware details for the unit associated with Task `t`. If the Task has not yet been initialized, the returned struct has all values set to 0. More...

ErrCode	utilNearestLegalFreq (TaskHandle t, double &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. More...

ErrCode	utilFixLinearSweepLimits (TaskHandle t, double &startFreq, double &endFreq, const unsigned int 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. This is important so that the frequency spacing between all points is identical. Unequal spacing can cause doppler noise in your data. More...

ErrCode	utilPingUnit (TaskHandle t)
	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. More...

ErrCode	utilGenerateLinearSweep (TaskHandle t, const double startFreq, const double endFreq, const unsigned int 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. More...

ErrCode	measureUncalibrated (TaskHandle t, ComplexData T1R1, ComplexData T1R2, ComplexData T2R1, ComplexData T2R2, ComplexData Ref)
	Measures the path(s) of your choice through the VNA, without applying calibration. The reference path is always measured. The ComplexData parameters are objects that contain pointers to data arrays that the caller has allocated. This function copies the returned data into those arrays, so they must have a minimum length of getNumberOfFrequencies(). 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(). Note that it is safe to supply null pointers. More...

ErrCode	measure2PortCalibrated (TaskHandle t, ComplexData S11, ComplexData S21, ComplexData S12, ComplexData S22)
	Measures the S-parameter(s) of your choice, applying the current calibration. Only paths specified by the 'paths' parameter get data copied into the output ComplexData structures. To select more than one path, bitwise-OR the constants together, e.g. `PARAM_S11 \| PARAM_S22` Like the other measurement functions, the ComplexData structures contain pointers to memory that you the caller have allocated. Note that this function blocks while the measurement is being performed. Use the interruptMeasurement() function to prematurely halt a slow measurement. You must pass buffers for all parameters, even if you don't want to measure them. Possible return values: More...

ErrCode	measureCalibrationStep (TaskHandle t, CalibrationStep 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. Possible return values: More...

bool	haveCalP1Open (TaskHandle t)

bool	haveCalP1Short (TaskHandle t)

bool	haveCalP1Load (TaskHandle t)

bool	haveCalP2Open (TaskHandle t)

bool	haveCalP2Short (TaskHandle t)

bool	haveCalP2Load (TaskHandle t)

bool	haveCalThru (TaskHandle t)

ErrCode	interruptMeasurement (TaskHandle t)
	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. More...

ErrCode	clearCalibration (TaskHandle t)
	Delete any calibration data stored in the Task `t`. More...

bool	isCalibrationComplete (TaskHandle t)
	Query if calibration parameters are present in the task. More...

unsigned int	getCalibrationNumberOfFrequencies (TaskHandle t)
	Get the number of frequencies in the calibration data. More...

const double *	getCalibrationFrequencies (TaskHandle t)
	Get a pointer to the list of frequencies used in the calibration data. This pointer becomes invalid after clearCalibration() is called. When no calibration data is loaded, this returns 0. Calibration data must be loaded via a measureCalibrationStep() call. More...

ErrCode	exportCalibration (TaskHandle t, ComplexData e00, ComplexData e11, ComplexData e10e01, ComplexData e30, ComplexData e22, ComplexData e10e32, ComplexData ep33, ComplexData ep22, ComplexData ep23ep32, ComplexData ep03, ComplexData ep11, ComplexData ep23ep01)
	Copies out the calibration coefficients to caller-allocated arrays. Note that to fully contain a calibration the caller must also get the frequency list and number of frequencies. It is the caller's responsibility to ensure the arrays have enough memory allocated to hold all of the data. It is recommended to use the getCalibrationNumberOfFrequencies() function to get the length because the number of calibration frequencies does not have to match the number of sweep frequencies. More...

ErrCode	importCalibration (TaskHandle t, const double *freqs, const unsigned int N, const ComplexData e00, const ComplexData e11, const ComplexData e10e01, const ComplexData e30, const ComplexData e22, const ComplexData e10e32, const ComplexData ep33, const ComplexData ep22, const ComplexData ep23ep32, const ComplexData ep03, const ComplexData ep11, const ComplexData ep23ep01)
	Imports calibration coefficients from caller-allocated 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. Data is copied out of these arrays into the Tasks's memory. More...

bool	hasFactoryCalibration (TaskHandle t)
	Determine of the VNA has a factory calibration stored in it's onboard EEPROM. More...

ErrCode	importFactoryCalibration (TaskHandle t)
	Load the factory calibration from the VNA into the current task. More...

Detailed Description

Authors: Steven Hunt (shunt.nosp@m.@ake.nosp@m.lainc.nosp@m..com), Connor Wolf (cwolf.nosp@m.@ake.nosp@m.lainc.nosp@m..com)

Run-state overview

A Task exists in one of four states:

Uninitialized (TASK_UNINITIALIZED)
Stopped (TASK_STOPPED)
Started (TASK_STARTED)

When the object is first created, it is in the uninitialized state. Here is the state table. The cell content is the new state. Blank cells mean the action is ignored.

               |--------------------Action-------------------------|

—Current state—	initialize()	start()	stop()	setIPAddress()
uninitialized	stopped			uninitialized
stopped		started		uninitialized
started			stopped

The initialize() action ensures that the AVMU unit is online and is responding to commands. It also downloads the hardware details from the unit needed to properly program the unit.

The start() action programs the AVMU unit. At this stage the unit is able to respond to measurement commands.

The stop() action idles the unit.

The setIPAddress() action puts the state back to uninitialized, because the assumption is that a different VNA unit is going to be targeted. Hardware details can vary from unit to unit and so those details must be re-downloaded prior to programming the new unit. NOTE: any calibration data is marked invalid when the state transitions to uninitialized. If you would like to use the calibration on a different unit (or save it for later), see the exportCalibration() function.

Typedef Documentation

typedef bool(* progress_callback)(int progressPercent, void *user)

This is the method signature for the callback function passed to the initialize() function.

The initialize() function takes a callback because it can take >30 seconds to execute while it downloads the embedded calibration from the VNA.

As such, the callback is called periodically while retreiving the cal data so the process can be presented to the user.

Parameters

progressPercent	Percentage of the download, from 0 - 100 %. Value is an integer. The callback may be called multiple times with the same progress percentage.
user	"user data". This is a void pointer that is passed in to the `initialize()` function, and then simply passed through to the callback every time it's called. It's intention is to allow a reference to any relevant user-code to be made available to the callback, so it could potentially update some external state. Set as NULL if unused.

Returns: Continue value. If the callback returns false, the cal download will halt immediately and initialize() will return ERR_INTERRUPTED. If the callback returns true, the download will continue.

typedef struct task_t* TaskHandle

Opaque type for containing the parameters and associated resources for interfacing with a single VNA.

One piece of software can have multiple tasks open at any one time, though having multiple tasks for the same VNA simultaneouslt can cause undetermined behaviour. At any time, there should only ever be one non-TASK_UNINITIALIZED task for a single VNA.

Function Documentation

ErrCode clearCalibration ( TaskHandle t )

Delete any calibration data stored in the Task t.

Parameters

t	Handle for the current task

Returns: Always returns ERR_OK

TaskHandle createTask ( )

Creates a new Task object and returns a handle to it. This handle is required by all of the other API functions. The returned object is in the TASK_UNINITIALIZED state.

Returns: new task handle

void deleteTask ( TaskHandle t )

Deletes the Task object. If the caller does not do this, the handle memory will leak.

Parameters

t	Task to delete

ErrCode exportCalibration	(	TaskHandle	t,
		ComplexData	e00,
		ComplexData	e11,
		ComplexData	e10e01,
		ComplexData	e30,
		ComplexData	e22,
		ComplexData	e10e32,
		ComplexData	ep33,
		ComplexData	ep22,
		ComplexData	ep23ep32,
		ComplexData	ep03,
		ComplexData	ep11,
		ComplexData	ep23ep01
	)

Copies out the calibration coefficients to caller-allocated arrays. Note that to fully contain a calibration the caller must also get the frequency list and number of frequencies. It is the caller's responsibility to ensure the arrays have enough memory allocated to hold all of the data. It is recommended to use the getCalibrationNumberOfFrequencies() function to get the length because the number of calibration frequencies does not have to match the number of sweep frequencies.

The calibration terms are for a full, 12-term model.

Parameters

t	Handle for the current task
e00	EDF Calibration term.
e11	ESF Calibration term.
e10e01	ERF Calibration term.
e30	EXF Calibration term.
e22	ELF Calibration term.
e10e32	ETF Calibration term.
ep33	EDR Calibration term.
ep22	ESR Calibration term.
ep23ep32	ERR Calibration term.
ep03	EXR Calibration term.
ep11	ELR Calibration term.
ep23ep01	ETR Calibration term.

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
ERR_BAD_CAL if isCalibrationComplete() returns false

Attenuation getAttenuation ( TaskHandle t )

Get the attenuation associated with this Task object. If no rate has yet been set, this function returns ATTEN_UNDEFINED.

[long description]

Parameters

t	Handle for the current task

Returns: Attenuation for Task t.

const double* getCalibrationFrequencies ( TaskHandle t )

Get a pointer to the list of frequencies used in the calibration data. This pointer becomes invalid after clearCalibration() is called. When no calibration data is loaded, this returns 0. Calibration data must be loaded via a measureCalibrationStep() call.

Parameters

t	Handle for the current task

Returns: Pointer to array of double containing calibration frequencies. array size can be determined by calling getCalibrationNumberOfFrequencies()

unsigned int getCalibrationNumberOfFrequencies ( TaskHandle t )

Get the number of frequencies in the calibration data.

Parameters

t	Handle for the current task

Returns: number of frequencies in calibration data.

const double* getFrequencies ( TaskHandle t )

Get a list containing the actual frequencies the hardware will sample for the configured sweep in task t.

The actual frequency points can differ from the requested frequency points because the hardware has fixed precision, and cannot achieve every arbitrary frequency value within it's tunable bands. The values in this list are the requested frequency points after snapping them to the closest achievable frequency.

TODO: What units are these in?

Parameters

t	Handle for the current task

Returns: array of double frequency values. The array length can be retreived by calling getNumberOfFrequencies()

HardwareDetails getHardwareDetails ( TaskHandle t )

Get the hardware details for the unit associated with Task t. If the Task has not yet been initialized, the returned struct has all values set to 0.

Parameters

t	Handle for the current task

Returns: HardwareDetails containing the details of the connected hardware (if initialized), else zeroes.

HopRate getHopRate ( TaskHandle t )

Get the frequency hopping rate associated with this Task object. If no rate has yet been set, this function returns HOP_UNDEFINED.

Parameters

t	Handle for the current task

Returns: HopRate for the Task t in question.

const char* getIPAddress ( TaskHandle t )

Get the current AVMU IP address for the Task object. When no IP has yet been set, this will return a NULL char*.

Parameters

t	Handle for the current task

Returns: char* to string containing the AVMU IP address. NULL if not set.

int getIPPort ( TaskHandle t )

Get the current port for IP communications. When uninitialized, this will default to 0.

Parameters

t	Handle for the current task

Returns: current port number

unsigned int getNumberOfFrequencies ( TaskHandle t )

Get the number of frequency points for the sweep configured for Task t. If no frequencies have been set, this function returns 0.

Parameters

t	Handle for the current task

Returns: Number of frequency points in Task t.

TaskState getState ( TaskHandle t )

Get the current state of the Task object. Returns one of the values defined above.

Parameters

t	Handle for the current task

Returns: A value from the TaskState state list

unsigned int getTimeout ( TaskHandle t )

Get the current time to wait for the unit to reply to commands. When a Task is first created, this will default to 150.

Parameters

t	Handle for the current task

Returns: current timeout in milliseconds

bool hasFactoryCalibration ( TaskHandle t )

Determine of the VNA has a factory calibration stored in it's onboard EEPROM.

Parameters

t	Handle for the current task

Returns: True if the EEPROM has a factory calibration, False if not.

bool haveCalP1Load ( TaskHandle t )

Return whether internal cal array for the Port-1 load measurement is present

bool haveCalP1Open ( TaskHandle t )

Return whether internal cal array for the Port-1 open measurement is present

bool haveCalP1Short ( TaskHandle t )

Return whether internal cal array for the Port-1 shorted measurement is present

bool haveCalP2Load ( TaskHandle t )

Return whether internal cal array for the Port-2 load measurement is present

bool haveCalP2Open ( TaskHandle t )

Return whether internal cal array for the Port-2 open measurement is present

bool haveCalP2Short ( TaskHandle t )

Return whether internal cal array for the Port-2 shorted measurement is present

bool haveCalThru ( TaskHandle t )

Return whether internal cal array for the through-cal measurement is present

ErrCode importCalibration	(	TaskHandle	t,
		const double *	freqs,
		const unsigned int	N,
		const ComplexData	e00,
		const ComplexData	e11,
		const ComplexData	e10e01,
		const ComplexData	e30,
		const ComplexData	e22,
		const ComplexData	e10e32,
		const ComplexData	ep33,
		const ComplexData	ep22,
		const ComplexData	ep23ep32,
		const ComplexData	ep03,
		const ComplexData	ep11,
		const ComplexData	ep23ep01
	)

Imports calibration coefficients from caller-allocated 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. Data is copied out of these arrays into the Tasks's memory.

The calibration terms are for a full, 12-term model.

Parameters

t	Handle for the current task
freqs	Double[] of frequencies for the calibration data.
N	Size of `freqs` value
e00	EDF calibration term.
e11	ESF calibration term.
e10e01	ERF calibration term.
e30	EXF calibration term.
e22	ELF calibration term.
e10e32	ETF calibration term.
ep33	EDR calibration term.
ep22	ESR calibration term.
ep23ep32	ERR calibration term.
ep03	EXR calibration term.
ep11	ELR calibration term.
ep23ep01	ETR calibration term.

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
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

ErrCode importFactoryCalibration ( TaskHandle t )

Load the factory calibration from the VNA into the current task.

Parameters

t	Handle for the current task

Returns

Call status - Possible return values:

ERR_BAD_CAL if the unit doesn't have a factory calibration
ERR_WRONG_STATE if the task is not in the TASK_STOPPED or TASK_STARTED state

ErrCode initialize	(	TaskHandle	t,
		progress_callback	callback = `0`,
		void *	user = `0`
	)

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.

This call can take a fair bit of time, up to 30 seconds <-> 1 minte. For that purpose, a callback interface is provided

Parameters

t	Handle for the current task
callback	User-provided callback function. Method signature must match progress_callback. See progress_callback for further details of the callback system. Set to NULL if no callback is required.
user	user-data provided to the callback function. See progress_callback for further description. Not used if the progress_callback param is NULL;

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
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
ERR_INTERRUPTED if the initialization was cancelled from the callback.

ErrCode interruptMeasurement ( TaskHandle t )

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

t	Handle for the current task

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
ERR_WRONG_STATE if the Task is not in the TASK_STARTED state

bool isCalibrationComplete ( TaskHandle t )

Query if calibration parameters are present in the task.

Parameters

t	Handle for the current task

Returns: true if the task has cal parameters, false otherwise.

ErrCode measure2PortCalibrated	(	TaskHandle	t,
		ComplexData	S11,
		ComplexData	S21,
		ComplexData	S12,
		ComplexData	S22
	)

Measures the S-parameter(s) of your choice, applying the current calibration. Only paths specified by the 'paths' parameter get data copied into the output ComplexData structures. To select more than one path, bitwise-OR the constants together, e.g. PARAM_S11 | PARAM_S22 Like the other measurement functions, the ComplexData structures contain pointers to memory that you the caller have allocated. Note that this function blocks while the measurement is being performed. Use the interruptMeasurement() function to prematurely halt a slow measurement. You must pass buffers for all parameters, even if you don't want to measure them. Possible return values:

Parameters

t	Handle for the current task
S11	User-Allocated ComplexData() instance.
S21	User-Allocated ComplexData() instance.
S12	User-Allocated ComplexData() instance.
S22	User-Allocated ComplexData() instance.

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
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

ErrCode measureCalibrationStep	(	TaskHandle	t,
		CalibrationStep	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. Possible return values:

Parameters

t	Handle for the current task
step	Which step of the calibration process you want to run. One of CalibrationStep options.

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
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

ErrCode measureUncalibrated	(	TaskHandle	t,
		ComplexData	T1R1,
		ComplexData	T1R2,
		ComplexData	T2R1,
		ComplexData	T2R2,
		ComplexData	Ref
	)

Measures the path(s) of your choice through the VNA, without applying calibration. The reference path is always measured. The ComplexData parameters are objects that contain pointers to data arrays that the caller has allocated. This function copies the returned data into those arrays, so they must have a minimum length of getNumberOfFrequencies(). 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(). Note that it is safe to supply null pointers.

Parameters

t	Handle for the current task
T1R1	Transmit port 1, receive port 1 reading.
T1R2	Transmit port 1, receive port 2 reading.
T2R1	Transmit port 2, receive port 1 reading.
T2R2	Transmit port 2, receive port 2 reading.
Ref	Reference reading

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
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

ErrCode setAttenuation	(	TaskHandle	t,
		const Attenuation	atten
	)

Set the attenuation amount. See the values defined above.

Parameters

t	Handle for the current task
atten	One of the `Attenuation` types defined in the DLL

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
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

ErrCode setFrequencies	(	TaskHandle	t,
		const double *	freqs,
		const unsigned int	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

t	Handle for the current task
freqs	array of frequencies to sample (each frequency is a single double)
N	Length of `freqs` array.

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
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)

ErrCode setHopRate	(	TaskHandle	t,
		const HopRate	rate
	)

Set the frequency hopping rate. See the values defined in the "HopRate" type above.

Parameters

t	Handle for the current task
rate	HopRate as member of HopRate type.

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
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

ErrCode setIPAddress	(	TaskHandle	t,
		const char *	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

t	Handle for the current task
ipv4	ASCII String IP representation, e.g. "192.168.1.207", etc...

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
ERR_MISSING_IP if the pointer is null
ERR_WRONG_STATE if the Task is not in the TASK_UNINITIALIZED or TASK_STOPPED state

ErrCode setIPPort	(	TaskHandle	t,
		const int	port
	)

Sets the port on which to communicate with the unit. In general, ports >= 1024 should be used. On success the Task's state will be TASK_UNINITIALIZED.

Parameters

t	Handle for the current task
port	integer port number

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
ERR_WRONG_STATE if the Task is not in the TASK_UNINITIALIZED or TASK_STOPPED state

ErrCode setTimeout	(	TaskHandle	t,
		const unsigned int	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 150.

TODO: VALIDATE THIS - What happens if passed 0?

Parameters

t	Handle for the current task
timeout	timeout in milliseconds

Returns: Always returns ERR_OK.

ErrCode start ( TaskHandle t )

Attempts to program the VNA using the settings stored in the Task object. If it succeeds the Task enters the TASK_STARTED state.

Parameters

t	Handle for the current task

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
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_STOPPED state
ERR_MISSING_HOP if the hop rate has not yet been specified
ERR_MISSING_ATTEN if the attenuation has not yet been specified
ERR_MISSING_FREQS if the frequencies have not yet been specified
ERR_PROG_OVERFLOW if the size of the program is too large for the hardware's memory (this can happen if the VNA is asked to sample too many frequency points)

ErrCode stop ( TaskHandle t )

Puts the Task object into the TASK_STOPPED state.

Parameters

t	Handle for the current task

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
ERR_WRONG_STATE if the Task is not in the TASK_STARTED state

ErrCode utilFixLinearSweepLimits	(	TaskHandle	t,
		double &	startFreq,
		double &	endFreq,
		const unsigned int	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. This is important so that the frequency spacing between all points is identical. Unequal spacing can cause doppler noise in your data.

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

TODO: More units to validate!

Parameters

t	Handle for the current task
startFreq	Start frequency (in Mhz)
endFreq	Stop freqency (in Mhz)
N	Number of frequencies

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
ERR_WRONG_STATE if the Task is in the TASK_UNINITIALIZED 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)

ErrCode utilGenerateLinearSweep	(	TaskHandle	t,
		const double	startFreq,
		const double	endFreq,
		const unsigned int	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.

If startFreq == endFreq, the hardware will effectively be placed in zero-span mode, as it will repeatedly sample the same frequency for the duration of the sweep. This is a valid operating mode.

Parameters

t	Handle for the current task
startFreq	Start frequency of sweep in Mhz
endFreq	End frequency of sweep in Mhz
N	Number of points to sample.

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
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)

ErrCode utilNearestLegalFreq	(	TaskHandle	t,
		double &	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.

Parameters

t	Handle for the current task
freq	Target frequency value pointer, which will be modified to the nearest frequency the hardware can achieve.

Returns

Call status - Possible return values:

ERR_OK if all went according to plan
ERR_WRONG_STATE if the Task is in the TASK_UNINITIALIZED state
ERR_FREQ_OUT_OF_BOUNDS if the frequency is beyond the allowed min/max. (You can get

ErrCode utilPingUnit ( TaskHandle t )

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.

Parameters

t	Handle for the current task

Returns

Call status - Possible return values:

- ERR_OK if all went according to plan
- ERR_SOCKET if there was a problem sending a message
- ERR_NO_RESPONSE if the unit did not respond to commands
- ERR_MISSING_IP if no IP address has been set
- ERR_MISSING_PORT if no port has been set

const char* versionString ( )

Returns a string describing the version of the DLL and its components.

Returns: Human-readable ASCII string pointer.; String describing the VNA DLL components and version numbers.

Modules

Data Structures

Typedefs

Functions

Detailed Description

Run-state overview

Typedef Documentation

Function Documentation