Returning Measurements

Instrument:

N1010A

DCA-X

DCA-M

Meas. mode:

Scope

Eye

Jitter

TDR

Flex Apps:

FlexDCA

FlexRT

FlexPLL

How can you return reliable scalar measurements? The simple answer is to always check the status of a measurement before reading the measurement. All measurements have a :STATus? child query that you can use for this task, as demonstrated in the script Example of :STATus? query included in this topic. For example, to check the readiness of an Eye Height measurement (:MEASure:EYE:EHEight?), first send the :MEASure:EYE:EHEight:STATus? query. The :STATus? query returns CORR (correct) if the measurement is ready to return, INV (invalid) if the measurement not ready to be returned, and QUES (questionable) if the measurement may not be valid.

Depending on the type of source waveform, FlexDCA's settings, and what you want to achieve, it may be helpful to add an acquisition limit test to capture more data before returning a measurement result. For example, measurements made on very long patterns may, under certain conditions, require several minutes to complete. An acquisition limit test followed by reading the measurement is demonstrated in Example of acquisition limit test in this topic.

Measurement Identification

Avoid subtle programming errors! To ensure that the correct measurement is installed or queried, always explicitly identify a measurement when installing a measurement or querying a measured value, status, or detail. To identify a measurement, specify the measurement's source waveform (:SOURce child command). With some measurements, you may also need to specify other identifying values. Generally, when selecting a measurement using FlexDCA's GUI, if a dialog appears prompting you to select values, you should explicitly specify these values when remotely identifying the measurement. More information.

For example, to return the status of the measurement, :

flex.write(':SOURce CHAN1A')
if flex.query(':STATus?') == 'CORR';
    measurement = flex.query('?')
else:
	details = flex.query(':STATus:DETails?')
	reason = flex.query(':STATus:REASon?')

Eye Mode Considerations

Pattern Lock is off:

Data acquisition is quick. Add an acquisition limit test if you want to acquire more data. This is true even with:

with long patterns.
when Samples/Waveform or Samples/UI are set to Manual.

Data acquisition is even faster if Rapid Eye is turned on.
Acquisition limit tests are based on either waveforms or samples.

Pattern Lock is on:

Acquire Entire Pattern is on. Data acquisition is quick, because sampling starts with the data that is within the currently displayed UI. Because eye measurements do not wait for the pattern acquisition to complete, there is no need to precede a measurement query with a pattern acquisition limit test. Acquisition limit tests are based on patterns. Expand the horizontal scaling to see the order in which the pattern data is acquired.

If Wrap Waveform setting is off, the data appears as a single-valued waveform, but in reality it is a multi-valued waveform displayed from a database.

Acquire Entire Pattern is off. Data acquisition is quick. Add an acquisition limit test if you want to acquire more data. Acquisition limit tests are based on waveforms or samples.

The data appears as a single-valued waveform, but in reality it is a multi-valued waveform displayed from a database. Depending on the time scale, some eye measurements are questionable and cannot be made.

Waveform Smoothing can be applied.

Oscilloscope Mode Considerations

With a data waveform, FlexDCA must be in pattern lock in order to properly display the single-valued waveform.
Acquire Entire Pattern is off.

Data acquisition is quick.
Add an acquisition limit test if you want to acquire more data.
Acquisition limit tests can be based on either waveforms or samples.
Smoothing can be applied to the waveform.

Acquire Entire Pattern is on:

Samples/UI is set to Automatic (default setting).

Data acquisition is quick.
Add an acquisition limit test if you want to acquire more data.

Samples/UI is set to Manual.

Data acquisition time is greatly increased. It is recommended to keep the Samples/UI setting to 128 or less on long patterns as setting greater than 128 result in a very large waveform record length and measurement times can take several minutes. For example, if View Entire Pattern is on for a PRBS-15 waveform and 4096 Samples/UI, one pattern can take nearly an hour to acquire. Avoid making a scalar measurement when the entire pattern is viewed.
Add an acquisition limit test (configured to capture one pattern) followed by checking the measurement with the :STATus? query.

Measurements are not made until at least one entire pattern acquisition has occurred.
Acquisition limit tests are based on patterns.

Jitter Mode Considerations

Data acquisition is quick.
Pattern lock is always on. The waveform record length is always automatically determined and cannot be manually set. Waveform smoothing cannot be applied.
Acquisition limit tests are available and are based on patterns.

Example of :STATus? query

The following Python script is an example of using the :STATus? query to return a measurement as soon as the waveform has enough samples to be valid. A valid eye diagram is assumed to be displayed on FlexDCA. The return_scalar() function returns an Eye Height measurement. If the measurement takes longer than this timeout value, the script throws an exception which is defined at the top of the function. If your script is timing out, increase the IO timeout.

Copy

Scalar Measurement

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
import time
import visa  # import VISA library

def return_scalar(FlexDCA, query):
    class ScalarMeasQuestionableException(Exception):
        """ A scalar measurement result is questionable. """
        pass

    class ScalarMeasTimeOutException(Exception):
        """ A scalar measurement has timed out. """
        pass

    timeout = FlexDCA.timeout / 1000  # convert ms to s
    query = query.strip('?')
    start_time = time.time()  # time in seconds
    while(True):
        time.sleep(0.2)
        status = FlexDCA.query(query + ':STATus?')
        if 'CORR' in status:  # valid measurement result
            return FlexDCA.query(query + '?')
        elif 'QUES' in status:
            s = query + '\nReason: ' + FlexDCA.query(query + ':STATus:REASon?')
            raise ScalarMeasQuestionableException(s)
        elif (int(time.time() - start_time)) > timeout:
            s = query + '\nReason: ' + FlexDCA.query(query + ':STATus:REASon?')
            raise ScalarMeasTimeOutException(s)

rm = visa.ResourceManager()
FlexDCA = rm.open_resource('TCPIP0::localhost::hislip0,4880::INSTR')
FlexDCA.timeout = 20000  # in milliseconds
FlexDCA.read_termination = '\n'
FlexDCA.write_termination = '\n'
FlexDCA.write(':MEAS:EYE:EHEight')  # show measurment on FlexDCA
print('Eye height: ', return_scalar(FlexDCA, ':MEAS:EYE:EHEight?'))
FlexDCA.write(':SYSTem:GTLocal')
FlexDCA.close()

Example of acquisition limit test

Use an acquisition limit test to ensure that a waveform has been built up from a specific number of waveforms, samples, or patterns before returning the measurement. This Python script is identical to the above script except for the addition of an waveform_acquisition() function. The function's count parameter is an integer that allows you to set the exact number of acquisitions. The :TRIGger:PLOCk? query determines if pattern lock is enabled, which requires that the test be based on patterns. A valid eye diagram is assumed to be displayed on FlexDCA with a short-pattern waveform without pattern locking. After the acquisition limit test, the data acquisition is stopped and is not re-started. As a result, the measurement is not being updated and if the measurement is not correct the return_scalar() function will timeout. You can, of course, place FlexDCA in run mode after the acquisition test completes. If your script is timing out, increase the IO timeout, or turn pattern lock off.

Copy

Scalar Measurement

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
import time
import visa  # import VISA library

def waveform_acquisition(FlexDCA, count):
    FlexDCA.write(':ACQuire:STOP')  # single acquisition mode
    FlexDCA.write(':ACQuire:CDISplay')  # Clear display
    if '1' in FlexDCA.query(':TRIGger:PLOCk?'):  # pattern lock is on
        FlexDCA.write(':LTESt:ACQuire:CTYPe:PATTerns ' + str(count))
    else:
        FlexDCA.write(':LTESt:ACQuire:CTYPe:WAVeforms ' + str(count))
    FlexDCA.write(':LTESt:ACQuire:STATe ON')
    FlexDCA.query(':ACQuire:RUN;*OPC?')  # OPC required when limit testing
    FlexDCA.write(':LTESt:ACQuire:STATe OFF')

def return_scalar(FlexDCA, query):
    class ScalarMeasQuestionableException(Exception):
        """ A scalar measurement result is questionable. """
        pass

    class ScalarMeasTimeOutException(Exception):
        """ A scalar measurement has timed out. """
        pass

    timeout = FlexDCA.timeout / 1000  # convert ms to s
    query = query.strip('?')
    start_time = time.time()  # time in seconds
    while(True):
        time.sleep(0.2)
        status = FlexDCA.query(query + ':STATus?')
        if 'CORR' in status:  # valid measurement result
            return FlexDCA.query(query + '?')
        elif 'QUES' in status:
            s = query + '\nReason: ' + FlexDCA.query(query + ':STATus:REASon?')
            raise ScalarMeasQuestionableException(s)
        elif (int(time.time() - start_time)) > timeout:
            s = query + '\nReason: ' + FlexDCA.query(query + ':STATus:REASon?')
            raise ScalarMeasTimeOutException(s)

rm = visa.ResourceManager()
FlexDCA = rm.open_resource('TCPIP0::localhost::hislip0,4880::INSTR')
FlexDCA.timeout = 20000  # in milliseconds
FlexDCA.read_termination = '\n'
FlexDCA.write_termination = '\n'
waveform_acquisition(FlexDCA, 10)
FlexDCA.write(':MEAS:EYE:EHEight')  # show measurment on FlexDCA
print('Eye height: ', return_scalar(FlexDCA, ':MEAS:EYE:EHEight?'))
FlexDCA.write(':SYSTem:GTLocal')
FlexDCA.close()