Admin Production ni-theme
Current Publication

Read Waveform Measurement

IVI Compliance Package

IviScope Read Waveform Measurement

IviScopeWaveformMeas Capability Group [WM]

This VI initiates an acquisition on all channels that you enable with the IviScope Configure Channel VI. If the channel you specify in the Channel Name parameter is not enabled for the acquisition, this VI returns the IVISCOPE_ERROR_CHANNEL_NOT_ENABLED error. It then waits for the acquisition to complete and returns the waveform measurement for the channel you specify. If the oscilloscope did not complete the acquisition within the time period you specify with the Maximum Time parameter, the VI returns the IVISCOPE_ERROR_MAX_TIME_EXCEEDED error.

You call the IviScope Fetch Waveform Measurement [WM] VI to obtain any other waveform measurement on a specific channel without initiating another acquisition.

Notes
  1. You must configure the appropriate reference levels before you call this VI. You configure the low, mid, and high references either by calling the IviScope Configure Reference Levels [WM] VI or by setting the following properties:
    IviScope Measurement High Reference [WM]
    IviScope Measurement Low Reference [WM]
    IviScope Measurement Mid Reference [WM]
  2. This VI performs interchangeability checking when the IviScope Interchange Check property is set to TRUE. Use NI I/O Trace to view interchangeability warnings. Alternately, you may use the IviScope Get Next Interchange Warning VI to retrieve interchangeability warnings. For more information about interchangeability checking, refer to the IviScope Interchange Checkproperty.
  3. The class driver returns simulated minimum and maximum waveforms when this VI is called and the IviScope Simulate property is set to TRUE and the IviScope Use Specific Simulation property is set to FALSE. For information on how to configure a simulated waveform, refer to IviScope Simulator Setup Dialog Box.
instrument handle The instrument handle that you obtain from the IviScope Initialize or the IviScope Initialize With Options VI.
channel name Pass the virtual channel name that you assign to the instrument in MAX from which you want to read a waveform measurement.

Virtual channel names are aliases for instrument specific channel strings. The instrument specific channel strings can differ from one instrument to another. Virtual channel names allow you to use and swap instruments without having to change the channel names in your source code. You assign a virtual channel name to an instrument specific channel in MAX. This control accepts virtual channel names you have assigned to the specific instrument you are using. It also accepts the instrument specific channel names.

Default Value: ""

measurement function Pass the waveform measurement you want the oscilloscope to perform.

Defined values:

IVISCOPE_VAL_RISE_TIME—Rise Time
The length of time for the first rising edge of the signal to rise from the low reference level to the high reference level.

IVISCOPE_VAL_FALL_TIME—Fall Time
The length of time for the first falling edge of the signal to fall from the high reference level to the low reference level.

IVISCOPE_VAL_FREQUENCY—Frequency
The frequency of one complete cycle in the waveform.

IVISCOPE_VAL_PERIOD—Period
The length of time of one complete cycle in the waveform.

IVISCOPE_VAL_VOLTAGE_RMS—Voltage RMS
The true Root Mean Square voltage of the entire waveform.

IVISCOPE_VAL_VOLTAGE_CYCLE_RMS—Voltage RMS (Cycle)
The true Root Mean Square voltage over the first cycle in the waveform.

IVISCOPE_VAL_VOLTAGE_MAX—Voltage Max
The maximum amplitude found in the entire waveform.

IVISCOPE_VAL_VOLTAGE_MIN—Voltage Min
The minimum amplitude found in the entire waveform.

IVISCOPE_VAL_VOLTAGE_PEAK_TO_PEAK—Voltage Vpp
The absolute difference between the Voltage Max and the Voltage Min.

IVISCOPE_VAL_VOLTAGE_HIGH—Voltage High
The voltage that corresponds to 100% when you use the reference levels. The oscilloscope calculates this value using either the min/max or histogram methods. The min/max method uses the maximum value found. The histogram method uses the most common value found above the middle of the waveform.

IVISCOPE_VAL_VOLTAGE_LOW—Voltage Low
The voltage that corresponds to 0% when you use the reference levels. The oscilloscope calculates this value using either the min/max or histogram methods. The min/max method uses the minimum value found. The histogram method uses the most common value found below the middle of the waveform.

IVISCOPE_VAL_VOLTAGE_AVERAGE—Voltage Avg.
The arithmetic average amplitude of the entire waveform.

IVISCOPE_VAL_VOLTAGE_CYCLE_AVERAGE—Voltage Avg. (Cycle)
The arithmetic average amplitude of the first cycle in the waveform.

IVISCOPE_VAL_WIDTH_NEG—Width Negative
The length of time between the mid reference level points of the first negative pulse in the waveform.

IVISCOPE_VAL_WIDTH_POS—Width Positive
The length of time between the mid reference level points of the first positive pulse in the waveform.

IVISCOPE_VAL_DUTY_CYCLE_NEG—Duty Cycle Negative
The ratio of the Width Negative to the Period of the first cycle in the waveform expressed as a percentage.

Duty Cycle Negative = 100.0 x (Width Negative)/Period

IVISCOPE_VAL_DUTY_CYCLE_POS—Duty Cycle Positive
The ratio of the Width Positive to the Period of the first cycle in the waveform expressed as a percentage.

Duty Cycle Positive = 100.0 X (Width Positive)/Period

IVISCOPE_VAL_AMPLITUDE—Amplitude
The Voltage High less the Voltage Low in Volts over the entire waveform.

IVISCOPE_VAL_OVERSHOOT—Overshoot
The relative waveform distortion which follows an edge transition. It is calculated using one of the following formulas:

For the rising edge:

OVERSHOOT = ((local maximum - Voltage High)/Amplitude)*100%

where the local maximum is the maximum voltage of the signal in the first half of the time period that commences when the rising edge crosses the high reference level and concludes when the subsequent falling edge crosses the high reference level.

For the falling edge:

OVERSHOOT = ((Voltage Low - local minimum)/Amplitude)*100%

where the local minimum is the minimum value of the signal measured in the first half of the time period that commences when the falling edge crosses the low reference level and concludes when the subsequent rising edge crosses the low reference level. The instrument makes the measurement on the edge closest to the beginning of the waveform record.

IVISCOPE_VAL_PRESHOOT—Preshoot
The relative waveform distortion which precedes an edge transition. It is calculated using one of the following formulas:

For the rising edge:

PRESHOOT = ((Voltage Low - local minimum)/Amplitude)*100%

where the local minimum is the minimum value of the signal measured in the second half of the time period that commences when the preceding falling edge crosses the low reference level and concludes when the rising edge crosses the low reference level.

For the falling edge:
PRESHOOT = ((local maximum - Voltage High)/Amplitude)*100%

where the local maximum is the maximum voltage of the signal in the second half of the time period that commences when the preceding rising edge crosses the high reference level and concludes when the falling edge crosses the high reference level. The instrument makes the measurement on the edge closest to the beginning of the waveform record.

Default Value: IVISCOPE_VAL_RISE_TIME

Note  You must configure the appropriate reference levels before you call this VI. You configure the low, mid, and high references either by calling the IviScope Configure Reference Levels [WM] VI or by setting the following properties:
IviScope Measurement High Reference [WM]
IviScope Measurement Low Reference [WM]
IviScope Measurement Mid Reference [WM]
maximum time (ms) Pass the maximum length of time in which to allow the read waveform measurement operation to complete.

If the operation does not complete within this time interval, the VI returns the IVISCOPE_ERROR_MAX_TIME_EXCEEDED error code. When this occurs, you can call IviScope Abort to cancel the read waveform operation and return the oscilloscope to the Idle state.

Units: milliseconds.

Defined Values:

IVISCOPE_VAL_MAX_TIME_INFINITE IVISCOPE_VAL_MAX_TIME_IMMEDIATE

Default Value: 5000 (ms)

Note  The Maximum Time parameter applies only to this VI. It has no effect on other timeout parameters or properties.
error in (no error) The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

instrument handle out The instrument handle that you obtain from the IviScope Initialize or the IviScope Initialize With Options VI.
measurement Returns the measured value.

Units The units depend on the Measurement Function you select, as shown below:

Rise Time—seconds

Fall Time—seconds

Frequency—hertz

Period—seconds

Voltage RMS—volts

Voltage RMS (Cycle)—volts

Voltage Max—volts

Voltage Min—volts

Voltage Vpp—volts

Voltage High—volts

Voltage Low—volts

Voltage Avg.—volts

Voltage Avg. (Cycle)—volts

Width Negative—seconds

Width Positive—seconds

Duty Cycle Negative—percentage

Duty Cycle Positive—percentage

Amplitude—volts

Overshoot—percentage

Preshoot—percentage

error out The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.