ZNA Custom DLL SDK  Version1.0.0
Network Analyser Extensions
ZNA Custom DLL SDK Documentation

1 General

This file defines the interface for custom DLLs which can be used with the ZNX firmware. The mechanism for adding and removing DLLs is described in the manual of the firmware. The DLL is installed in the firmware as *.zip file. This file must include the *.dll file with the functions defined in this header. Additionally this *.zip file is allowed to contain further files. These are stored with the DLL in an internal folder. The firmware will not access these files directly. The files are kept until the package is removed again. Files with the extension *.json are used by the firmware to create customized buttons if possible (see chapter 6).

2 Functions in the Interface

The interface consists of a set of functions which must be implemented. They can be divided into four groups:

2.1. DLL Handling: The functions in this group are

  • RsVnaOnLoadDll
  • RsVnaOnUnloadDll These functions are rarely called from the firmware. Typical calls are when starting or stopping the firmware.

2.2. General Properties: The functions in this group are

  • RsVnaGetVersion
  • RsVnaGetNumberOfTaskTypes
  • RsVnaGetTaskTypes
  • RsVnaGetUnit These functions provide information about the capabilities of the DLL to the firmware. Calls can occur often e.g. to retrieve values for the visualization.

2.3. Trace Calculation: The functions in this group are

  • RsVnaGetNumberOfHumanNames (Init)
  • RsVnaGetTraceRequirements (Init)
  • RsVnaCalculateTrace (Meas) These functions are used to actually provide data for a trace which shall be used by the firmware. Calls are explained in the next part.

2.4. Device Control: The functions in this group are

  • RsVnaGetInterruptRequests (Init)
  • RsVnaInterruptCallback (Meas)

2.5. Summary

These functions are used to control external devices and provide the results to the firmware. Calls are explained in the next part. All these functions have in common that the firmware expects that the same input results to the same output. The only exception is RsVnaInterruptCallback (for details see function description).

3 General Firmware Structure

To understand the impact of the "Trace Calculation" (2.3) functions and the "Device Control" (2.4) functions a more detailed understanding of the processes in the firmware is required. Three general parts exist:

3.1. GUI/Parser/Internal Logic:

This part of the firmware directly interacts with the user. The task is to setup the measurements. This part of the firmware also contains the functionality which computes the trace from the complex data including math operations, statistics, etc.. In this part of the firmware, the functions from the "DLL Handling" (2.1) and "General Properties" (2.2) are called as needed by the firmware.

3.2. Initialization:

In this part of the firmware the required wave measurements are computed from the settings made in "GUI/Parser/Internal Logic" (3.1) and passed to the hardware for execution. This process is triggered when settings change. In this process the following steps occur in this order:

  • Initialize Trace Calculation (e.g. Format or Trace Math)
  • Initialize Averaging
  • Calls to functions from "Trace Calculation" (2.3) marked with "Init"
  • Preparation of the required wave measurements (e.g. decomposition of a ratio into two waves)
  • Initialization of the hardware during this step call to functions from "Device Control" (2.4) marked with "Init" occur.

3.3. Measurement:

In this part of the firmware the data from the actual measurement is processed and further measurements are controlled. In continuous sweep mode this part of the firmware is permanently working to process the incoming measurements. The speed of this code can have a big impact on the device performance. The following steps occur in this order:

  • Delivery of the measured waves. In this part also the functions from "Device Control" (2.4) marked with "Meas" are called to collect the measurements by additional devices.
  • Calculation of composite measurements (e.g. the division of two waves to get a ratio)
  • Calls to functions from "Trace Calculation" (2.3) marked with "Meas"
  • Calculation of averages
  • Application of trace calculations (e.g. Format or Trace Math)

4 Concept for Different Drive Ports

Another concept to have in mind when implementing this interface is different drive ports. The interface uses the "Number of Sweep Points" as it is used by the user interface of the firmware. However, the actual steps required during the measurement might be higher due to the fact that one measurement is using a different drive port (e.g. forward and backwards measurement). To associate a task with a drive port this drive port is part of the task type usually denoted "PX" or "DX". This is the same for tasks requested from the DLL. Especially for the control of external devices this can have a big impact.

5 Memory Handling

For all functions in this interface the ZNX firmware allocates and deletes the required memory. The pointers provided already have the required memory. This memory can be accessed and the values can be read or written according to the description of the function.

  • Do not delete the memory provided by the interface functions. This is done by the firmware.
  • Expect that all the memory is deleted immediately after the function of this interface returns. Do not store any pointers.

6 Customized Buttons in the Firmware

As part of the package installed with the DLL it is possible to add customized buttons to the firmware. This is done by *.json files. Simply add such a file to the *.zip container with the following content:

{
"SoftKeyId": "E_Meas_Spectrum", // Decides to which SoftTool the Button is added. You find theses Ids in “MMI_IDs” folder. ID greater than 10000.
"PathOfExecuteable": "executable.exe", // Path for the executable to run when the button is pressed.
"Icon": "C:\\path\\to\\image.svg", // Icon for the button. It is shown on the right side. Use a *.svg file.
"ButtonText": "DoSomething", // Text on the button (for two lines use \n). ButtonText and Icon should not be too wide to fit in the SoftTool.
"Separator": false, // A white line is shown above the button if true is set.
"SeperatorText": "label", // The given text is shown between the Separator and the Button. The text should not be too wide for the SoftTool.
"CmdLineOptions": ["String1",”String2”], // Command Line parameters for the executable.
"UserInteraction": false // Set the macro modal if “true”.
}

Optionally also a Menu.json can be added with the following content

{
"SoftMenuId": "E_SoftKeyMenu_Display", // Decides to which SoftToolMenu the Button is added. You find theses Ids in “MMI_IDs” folder (E_SoftKeyMenu_XXX).
"TabText": "Test" // Text on the Tab for the SoftTool.
}

7 Exception settings

As the VNA Firmware translates structured exceptions into C++ Exception any structured exception usage inside your dll may be translated to an unspecified c++ exception. This is subject to change and as a user you shouldn't rely on it.