2. Answers to Your Questions

Programming Essentials

What SCPI subsystems do I use?

The following links open the introductory topic for each subsystem where you'll find additional information.

  • :CONFigure subsystem to build the Hardware Diagram.
  • Root-level commands :STARt, :STOP, and :RUNNing to launch and stop Stations processes and to confirm if Stations are running.
  • :TPRogram subsystem to build Test Programs.
  • :JOBS subsystem to run Test Programs.
  • :EUSage subsystem to scale the Job Timing Diagram.
  • :SWITch subsystem to select to scan for a supported switch or to run your instrument drivers for a switch that is not natively supported.
  • :INSTrument subsystem to run an instrument driver to add a measurement instrument.
  • :CALibrate subsystem to perform various calibrations.

How do I run a Test Program?

Use the :TPRogram:RUN? query. Most importantly, the :TPRogram:RUN? query returns a comma separated string of Job IDs. You need Job IDs to identify measurements for a specific DUT's lane. Most :JOBS subsystem commands require a Job ID argument to identify the correct measurements.

job_ids = station.query(':TPRogram:RUN?')

When are the measurements ready to return?

When you run a Test Program, you'll need to know when the measurements are ready for you to query. Simply send the :JOBS:ACQuire:COMPlete? query followed by an *OPC query as shown below.

job_ids = station.query(':TPRogram:RUN?')
station.query(':JOBS:ACQuire:COMPlete?')
station.query('*OPC?')

How do I return all Job Results panel measurements for a lane?

To return all data in a single query for a row in the Job Results panel (Job ID), use the :JOBS:RESults? query. Notice that a Job ID (9 in this example) is sent as an argument with this command.

lane_measurements = station.query(':JOBS:RESults? 9')

The data is returned in one string as shown in this listing. In the listing, newlines have been added to make the string easier to read in this topic. The newline characters are not included in the returned string.

"Fixture=DUT Fixture 1,Lane=Lane 1;
Name=TDECQ,Value=0,Status=Correct;
Name=Ceq,Value=0,Status=Correct;
Name=Outer OMA,Value=5.000E-4,Status=Correct;
Name=Outer ER,Value=3.770E+1,Status=Correct;
Name=Eye Linearity (CEI),Value=9.97E-1,Status=Correct;
Name=Level 0,Value=2E-7,Status=Correct;
Name=Level 1,Value=1.666E-4,Status=Correct;
Name=Level 2,Value=3.334E-4,Status=Correct;
Name=Level 3,Value=4.998E-4,Status=Correct;
Name=Trans. Time (Slowest  5 6),Value=6E-12,Status=Correct;
Name=Overshoot(1.0E-2),Value=1.75,Status=Correct;
Name=Undershoot(1.0E-2),Value=1.66,Status=Correct;
Name=Power Excursion(1.0E-2),Value=2.588E-4,Status=Correct;
Name=Average Power,Value=2.5000E-4,Status=Correct;
Name=Pk-Pk Power(1.0E-2),Value=5.170E-4,Status=Correct;

How do I return a single measurement from the Job Results panel?

Use one of the following queries from the :JOBS:RESults:MEASure SCPI node. You must append a Job ID (23' in this example) as an argument to each of these commands. Notice that the query for a USER measurement (for example, a power meter) includes a formatted version. The format of the returned string should include the unit of measurement as defined in your instrument driver.

avg_pwr = station.query(':JOBS:RESults:MEASure:APOWer? 23')

How do I learn information about a measurement?

The measurement queries return raw real number without additional information such as units of measure. You can return information about a measurement, such as units of measure, transition edges, applied presets, and elapsed time, using the :JOBS:CONFig and :JOBS:RESults:INFO SCPI nodes. You must append a Job ID as an argument to each of these commands. For example,

lane_measurements = station.query(':JOBS:RESults:MEASure:APOWer? 23')
results = parse_measurement_string(lane_measurements)
units_of_measure = station.query(':JOBS:CONFig:PUNits? 23')
print('Average Power: ' + results['APWR'] + units_of_measure)

Measurement Configuration Queries (PAM4 Waveform)
Measurement Power Units Outer ER Units Linearity Definition Target Transition Target Hit Ratio
:JOBS:CONFig:PUNits? :JOBS:CONFig:ERUNits? :JOBS:CONFig:LDEFinition? :JOBS:CONFig:TRANsition? :JOBS:CONFig:THRatio?
Average Power ■
Ceq Noise Gain
Levels ■
Linearity ■
Outer ER ■
Outer OMA ■
Overshoot ■
Peak-Peak Power ■
TDECQ
Transition Time ■
Tx Power Excursion ■ ■
Undershoot ■

How are user instrument measurements returned?

You can write an instrument driver to add a measurement instrument (for example, a power meter) to FlexOTO's Hardware Diagram. The instrument driver tells FlexOTO what measurements it makes at the time that it is run. FlexOTO tells the instrument driver when to make its measurements (whatever they are) and the driver returns the measurement names and values. Instrument driver measurements are always given their own Job ID and dedicated row in the Job Results panel. As a result, your program code will process user instrument measurement exactly as it would FlexOTO's standard measurements.

For example, if your driver defines User Meas1 and User Meas2 you would the measurements.

lane_measurements = station.query(':JOBS:RESults? 2')

Which would return the following string. The newline characters are not included in the returned string.

"Fixture=DUT Fixture 1,Lane=Lane 2;
Name=User Meas1,Value=1.24700000000000,Status=Correct;
Name=User Meas2,Value=1.15300000000000E-4,Status=Correct"

Or, you could separately return each measurement resulting in values such as "1.247000000" and "1.15300000000".

user_meas_1 = station.query(':JOBS:RESults:MEASure:USER? 2, "User Meas1"')
user_meas_2 = station.query(':JOBS:RESults:MEASure:USER? 2, "User Meas2"')

For user measurements, you can also use this variation to return formatted results such as "1.25 dB" and "1.15 dB".

user_meas_1 = station.query(':JOBS:RESults:MEASure:USER:FORMatted? 2, "User Meas1"')
user_meas_2 = station.query(':JOBS:RESults:MEASure:USER:FORMatted? 2, "User Meas2"')