Python Measurement Scripts
When FlexDCA runs your user measurement script, the following FlexDCA/Python interaction occurs:
- FlexDCA launches a Python wrapper script and sends to the wrapper a number of variables, including the source waveform.
- The wrapper loads this file as a module and runs the "algorithm" function, passing in the dictionary formed from the input variables.
- The algorithm runs and returns a dictionary containing several variables, including the measurement status and result.
- The wrapper script formats the output variables and sends them back to FlexDCA.
Before running your script, you must install Python on either an N1000A or the PC where N1010A FlexDCA is running. Python is not provided by Keysight.
The following figure illustrates the required setup files using an example Pre-Emphasis measurement in Oscilloscope mode. The same setup files are used for Eye and TDR mode user measurements.
You must create a simple XML configuration file that identifies your measurement script. The XML file also populates a measurement tab in the User Measurement Setup dialog. In the dialog, click Browse and install your XML file.
Your Python script must include and begin with the algorithm function. FlexDCA passes data to the algorithm function which calculates your new measurement and returns the measurement results to be displayed on FlexDCA's Results panel. Your script can include other functions, but this is optional.
Python 3 and Python 2.7 are supported for user measurements. Python 2 support will be removed in a future FlexDCA release. At that time any Python 2 code will need to be ported to Python 3.
All of the example scripts are written in Python 3.
Python 3's native support for Unicode provides an advantage over using Python 2. Your script must identify measurement results using the exact names that are shown in FlexDCA's Results panel and these names often use Unicode symbols such as the Δ symbol.
Don't forget to modify the PC's PATH environment variable to include the path to the Python executable. This enables FlexDCA to locate the Python executable.
When a user measurement is run, FlexDCA performs the following tasks on each data acquisition cycle just like FlexDCA's standard measurements:
- Passes the source waveform, standard variables and any custom variables to the Python script.
- If not already running, FlexDCA runs any required dependent FlexDCA scalar measurements that are specified in the XML file.
- Executes the script.
- Sends the output of any print() function to the FlexDCA's User Measurement Setup dialog's Show Output window. This window shows ASCII characters but will not show any Unicode characters.
- The script returns a dictionary to FlexDCA that includes your measurements result and the result is displayed in the measurement Results panel. A number of standard output variables are also retrieved from the script. The measurement's name on the Results panel is taken from the user measurement's XML configuration file's <Abbreviation> element. When controlling FlexDCA remotely, you can return your user measurement result using the following SCPI queries:
:MEASure:EYE:USER?:MEASure:OSCilloscope:USER?:MEASure:TDR:USER?- The value of the returned dictionary's "ErrorMsg" key populates the Details dialog as shown in the following figure. Click the Results panel's Details button to view this dialog. The Details dialog is a vital tool when troubleshooting your script. The figure shows Questionable measurement that includes a message string that was passed from your script. If Python throws an exception (Error measurement result), the Details dialog shows Python's Traceback listing.
NumPy, a library for creating multidimensional arrays, must be installed. In Oscilloscope and TDR modes, the source waveform is a one-dimensional NumPy array. In Eye mode, the source database is a two-dimensional NumPy array. To import NumPy into your Python script enter the following line:
import numpy as np
NumPy is used by FlexDCA to pass input variables to your scripts in Scope, Eye, and TDR modes. In Eye mode, you must import NumPy into your script. In Scope and TDR modes, you don't need to import NumPy into your scripts but you must still have NumPy installed with Python.
Any dependent measurements not already running will be started but will not be displayed in FlexDCA's Results panel. This does not affect the running of the script or its ability to perform it's measurement.
If the Show Output button is not displayed, close and then reopen the Show Output window.
The Show Output window is simple ASCII messages without any Unicode characters. Python Examples 2, 3, and 4 include a simple function that you can add to your scripts to increase its capability.
