Table Of Contents

Read Measurement (G Dataflow)

Version:
    Last Modified: March 3, 2017

    Initiates an acquisition, waits for it to complete, and performs the specified waveform measurement for a single channel and record.

    connector_pane_image
    datatype_icon

    timeout

    The time, in seconds, to wait for the data to be acquired.

    Alternate Uses

    Use 0 for this parameter to fetch whatever is currently available. Use -1 for this parameter to imply an infinite timeout.

    Default: 5

    datatype_icon

    session in

    Identifies a particular instrument session.

    datatype_icon

    error in

    Error conditions that occur before this node runs.

    The node responds to this input according to standard error behavior.

    Standard Error Behavior

    Many nodes provide an error in input and an error out output so that the node can respond to and communicate errors that occur while code is running. The value of error in specifies whether an error occurred before the node runs. Most nodes respond to values of error in in a standard, predictable way.

    error in does not contain an error error in contains an error
    If no error occurred before the node runs, the node begins execution normally.

    If no error occurs while the node runs, it returns no error. If an error does occur while the node runs, it returns that error information as error out.

    If an error occurred before the node runs, the node does not execute. Instead, it returns the error in value as error out.

    Default: No error

    datatype_icon

    channels

    The channel from which to acquire data.

    Channel String Syntax

    You can input channels with the following options:
    • A single channel, such as 0
    • A list of channels, such as 0,1 or 3,2,1,0.
    • A range of channels, such as 0-7 or 0:7.
    spd-note-note
    Note  

    The order of channels in a list is important. The data for each channel is returned in the order the channels occur in the list.

    datatype_icon

    scalar measurement

    The measurement to perform on the waveform read from the digitizer.

    Name Value Description
    None 4000 No scalar measurement is performed.
    Frequency 2 Corresponds to the NISCOPE_VAL_FREQUENCY C or C++ command. 1.0 divided by the period, in hertz.
    Average Frequency 1016 Corresponds to the NISCOPE_VAL_AVERAGE_FREQUENCY C or C++ command. 1.0 divided by the average period, in hertz.
    FFT Frequency 1008 Corresponds to the NISCOPE_VAL_FFT_FREQUENCY C or C++ command. The FFT amplitude spectrum is calculated using a split-radix real FFT, and the frequency corresponding to the maximum amplitude is returned. If the input waveform size is not a power of two, the waveform is zero padded to the next higher power of two. The frequency resolution is sampling rate / number of points.The DC bin of the FFT is ignored when searching for the maximum amplitude, so the FFT frequency should ignore any DC offsets. However, the zero padding used in the FFT measurement can introduce other low frequency components if the waveform has a large DC offset. To avoid problems, make sure the Horizontal Actual Record Length property is a power of 2, so no zero padding occurs. This property can be fetched using niScope Actual Record Length. Alternatively, configuring the digitizer for AC coupling solves the problem.
    Period 3 Corresponds to the NISCOPE_VAL_PERIOD C or C++ command. Finds the time, in seconds, between the first and third mid reference level crosspoints. A hysteresis window is applied when finding crosspoints. The mid reference level is 50% by default and is set with the Channel Based Mid Ref Level property.
    Average Period 1015 Corresponds to the NISCOPE_VAL_AVERAGE_PERIOD C or C++ command. Up to 256 mid reference level crossings are found on the waveform using a digital hysteresis. The time difference between the last crossing and the first crossing is divided by the number of periods found in the waveform. The last crossing is defined as the last crossing in the waveform with the same slope as the first crossing, so an integer number of periods exist in the waveform.
    Rise Time 0 Corresponds to the NISCOPE_VAL_RISE_TIME C or C++ command. The time span, in seconds, from when the waveform crosses the low reference level until it crosses the high reference level. The measurement starts at the left edge of the waveform and finds all low reference level crossings until a high reference level crossing. The final low reference level crossing is used in the calculation. The reference levels are specified by Channel Based Low Ref and Channel Based High Ref, and their default values are 10% and 90%.
    Fall Time 1 Corresponds to the NISCOPE_VAL_FALL_TIME C or C++ command. The time span, in seconds, from when the waveform crosses the high reference level until it crosses the low reference level. The measurement starts at the left edge of the waveform and finds all high reference level crossings until a low reference level crossing. The final high reference level crossing is used in the calculation. The reference levels are specified by Channel Based Low Ref and Channel Based High Ref, and their default values are 10% and 90%.
    Rising Slew Rate 1010 Corresponds to the NISCOPE_VAL_RISE_SLEW_RATE C or C++ command. The high reference voltage minus the low reference voltage is divided by the rise-time calculation.
    Falling Slew Rate 1011 Corresponds to the NISCOPE_VAL_FALL_SLEW_RATE C or C++ command. The low reference voltage minus the high reference voltage is divided by the fall-time calculation. The result is always negative.
    Overshoot 18 Corresponds to the NISCOPE_VAL_OVERSHOOT C or C++ command. The measurement is taken on the first edge of the waveform. If two edges exist, the algorithm finds the time interval from the first edge until one half the time to the second edge. The local maxima and minima are found in this interval. If only one edge is present in the waveform, the local maximum and minimum is found between the first edge and the end of the waveform. If the first edge is positive sloped, overshoot = 100 × (local maximum - voltage high) / voltage amplitude. If the first edge is negative sloped, overshoot = 100 × (voltage low - local minimum) / voltage amplitude.
    Preshoot 19 Corresponds to the NISCOPE_VAL_PRESHOOT C or C++ command. The measurement is taken on the second edge of the waveform if two edges exist. The algorithm finds the time interval from the middle time between the two edges until the second edge. The local maxima and minima are found in this interval. If only one edge is present in the waveform, the local maximum and minimum are found from the start of the waveform to the first edge. If the edge is negative sloped, preshoot = 100 × (local maximum - voltage high) / voltage amplitude. If the edge is positive sloped, preshoot = 100 × (voltage low - local minimum) / voltage amplitude.
    Voltage RMS 4 Corresponds to the NISCOPE_VAL_VOLTAGE_RMS C or C++ command. Voltage RMS is determined by the following equation:Voltage RMS = √[( Σ waveform[i]2) / numPoints]
    Voltage Cycle RMS 16 Corresponds to the NISCOPE_VAL_VOLTAGE_CYCLE_RMS C or C++ command. Voltage Cycle RMS = √[(Σ waveform[i]2) / pointsPerPeriod] The number points in a period is calculated using the equation:pointsPerPeriod = period / dtwhere period is the measured period of the signal and dt is the time between two points. The result will then be converted to an integer from a floating point value.
    AC Estimate 1012 Corresponds with the NISCOPE_VAL_AC_ESTIMATE C or C++ command. The DC estimate is subtracted from the waveform, and a Hanning window is applied to give a processed waveform. The RMS voltage is calculated with the following equation:√([Σ processed waveform[i]2] / [numPoints × enbw × cg2]), where the equivalent noise bandwidth (enbw) for the Hanning window is 1.5, and the coherent gain (cg) is 0.5. This algorithm minimizes the effect of an uneven number of waveform cycles in the measurement, which could arbitrarily increase or decrease the RMS value.
    FFT Amplitude 1009 Corresponds to the NISCOPE_VAL_FFT_AMPLITUDE C or C++ command. The FFT amplitude spectrum is calculated using a split-radix real FFT, and the maximum amplitude is returned. If the input waveform size is not a power of two, the waveform is zero-padded to the next highest power of two. For best results, verify that your actual record length is a power of 2.
    Voltage Average 10 Corresponds to the NISCOPE_VAL_VOLTAGE C or C++ command. The voltage average is determined by the following equation:Voltage Average = Σ waveform[i] / numPoints
    Voltage Cycle Average 17 Corresponds to the NISCOPE_VAL_VOLTAGE_CYCLE_AVERAGE C or C++ command. Voltage Cycle Average = ( Σ waveform[i]) / pointsPerPeriod The number of points in a period in volts is calculated using the following equation:pointsPerPeriod = period / dt where period is the measured period of the signal and dt is the time between two points. The result will then be converted to an integer from a floating point value.
    DC Estimate 1013 Corresponds to the NISCOPE_VAL_DC_ESTIMATE C or C++ command. A Hanning window is applied to give a processed waveform and the voltage average is calculated with the following equation: voltage average = (Σ processed waveform[i]) / (cg × numPoints), where the coherent gain (cg) of the Hanning window is 0.5 - the DC gain of the window. The algorithm minimizes the effect of an uneven number of waveform cycles. For example, performing a smiple voltage average on 5.5 cycles of a sine waveform gives a slightly incorrect DC estimate if the extra half cycle is not evenly divided between the positive and negative portions of the sine wave.
    Voltage Max 6 Corresponds to the NISCOPE_VAL_VOLTAGE_MAX C or C++ command. Searches the waveform for its maximum point.
    Voltage Min 7 Corresponds to the NISCOPE_VAL_VOLTAGE_MIN C or C++ command. Searches the waveform for the minimum point in volts.
    Voltage Peak-to-Peak 5 Corresponds to the NISCOPE_VAL_VOLTAGE_PEAK_TO_PEAK C or C++ command. The maximum voltage minus the minimum voltage in volts.
    Voltage High 8 Corresponds to the NISCOPE_VAL_VOLTAGE_HIGH C or C++ command. Uses the last-acquisition histogram method, where the voltage high result is the voltage of the histogram bin with the maximum number of hits above 60% of the waveform's voltage peak-to-peak value. This calculation is useful for ignoring the overshoot and preshoot on square waves.
    Voltage Low 9 Corresponds to the NISCOPE_VAL_VOLTAGE_LOW C or C++ command. The last acquisition histogram method is used where the voltage low result is the voltage of the histogram bin with the maximum number of hits below 40% of the waveform's voltage peak-to-peak value. This calculation is useful for ignoring the overshoot and preshoot on square waves.
    Voltage Amplitude 15 Corresponds to the NISCOPE_VAL_VOLTAGE_AMPLITUDE C or C++ command. The voltage amplitude is calculated by the voltage high minus the voltage low.
    Voltage Top 1007 Corresponds to the NISCOPE_VAL_VOLTAGE_TOP C or C++ command. If the histogram bin corresponding to voltage high has over fiver percent of the total hits, the voltage high result is returned. Otherwise, the voltage maximum calculation is returned. Otherwise, the voltage maximum calculation is returned. This allows using the voltage top to get a reasonable answer for either a square wave (ignoring the overshoot and preshoot) or a triangle wave (where a histogram fails).
    Voltage Base 1006 Corresponds to the NISCOPE_VAL_VOLTAGE_BASE C or C++ command. If the histogram bin corresponding to voltage low has over five percent of the total hits, the voltage low result is returned. Otherwise, the voltage minimum calculation is returned. Otherwise, the voltage minimum calculation is returned. This allows using the voltage base to get a reasonable answer for either a square wave (ignoring the overshoot and preshoot) or a triangle wave (where a histogram fails).
    Voltage Base-to-Top 1017 Corresponds to the NISCOPE_VAL_VOLTAGE_BASE_TO_TOP C or C++ command. Voltage Base-to-Top is calculated by subtracting voltage base from voltage top.
    Negative Width 11 Corresponds to the NISCOPE_VAL_WIDTH_NEG C or C++ command. The time difference between the first two mid reference level crossings, where the slopes are negative and positive, respectively. A digital hysteresis is used when finding the crosspoints.
    Positive Width 12 Corresponds to the NISCOPE_VAL_WIDTH_POS C or C++ command. The time difference, in seconds, between the first two mid reference level crossings, where the slopes are positive and negative respectively. A digital hysteresis is used when finding the crosspoints.
    Negative Duty Cycle 13 Corresponds to the NISCOPE_VAL_DITY_CYCLE_NEG C or C++ command. The negative duty cycle is the negative width divided by the period times 100.
    Positive Duty Cycle 14 Corresponds to the NISCOPE_VAL_DUTY_CYCLE_POS C or C++ command. Positive duty cycle is the positive width divided by the period times 100.
    Integral 1005 Corresponds to the NISCOPE_VAL_INTEGRAL C or C++ command. Performs numerical integration using Simpson's rule, in units of volts × seconds.
    Area 1003 Corresponds to the NISCOPE_VAL_AREA C or C++ command. Calculates the area between two points using the following equation: area = voltage average × numPoints × delta time
    Cycle Area 1004 Corresponds to the NISCOPE_VAL_CYCLE C or C++ command. Uses the following equation:Cycle area = voltage cycle average × pointsPerPeriod × dtwhere pointsPerPeriod = period / dt.
    Time Delay 1014 Corresponds to the NISCOPE_VAL_TIME_DELAY C or C++ command. The algorithm finds the first time, in seconds, that the waveform from the channel specified by the channel parameter crosses its mid-reference level. Next, the algorithm finds the first two times that the waveform from the Other Channel property crosses its mid-reference level.
    spd-note-note
    Note  

    If you want to measure from falling edge to falling edge, you can invert the data from both channels by adding a processing step and using the array measurement gain with a value of -1. With this method, you can also measure from rising edge to falling edge or from falling edge to rising edge by inverting a signal on one of the two channels.

    The mid-reference level is stored on a per channel basis, and mid-reference levels do not need to be the same. All reference levels use a digital hysteresis.
    Phase Delay 1018 Corresponds to the NISCOPE_VAL_PHASE_DELAY C or C++ command. Phase Delay is the time delay divided by the period (of the waveform on the channel specified by the measurement node) times 360 degrees.
    Low Ref Volts 1000 Corresponds to the NISCOPE_VAL_LOW_REF_VOLTS C or C++ command. The voltage corresponding to the low reference level. If the Reference Level Units property is set to Voltage, the value of the Channel Based Low Ref Level property is returned.If the Reference Level Units property is set to Percentage, the voltage is calculated with the method specified by the Percentage Units Method property.
    Mid Ref Volts 1001 Corresponds to the NISCOPE_VAL_MID_REF_VOLTS C or C++ command. The voltage corresponding to the mid reference level. If the Reference Level Units property is set to Voltage, the value of the Channel Based Mid Ref property is returned.If the Reference Level Units is set to Percentage, the voltage is calculated with the mehod specified by the Percentage Units Method property.
    High Ref Volts 1002 Corresponds to the NISCOPE_VAL_HIGH_REF_VOLTS C or C++ command. The voltage corresponding to the high reference level. If the Reference Level Units property is set to Voltage, the value of the Channel Based High Ref property is returned.If the Reference Level Units property is set to Percentage, the voltage is calculated with the method specified by the Percentage Units Method property.
    Volt. Hist. Mean 2000 Corresponds to the NISCOPE_VAL_VOLTAGE_HISTOGRAM_MEAN C or C++ command. Histogram Mean = [∑(bin hits × bin value) ] / volt hist hitsThe bin value is the center voltage value of the histogram bin.
    Volt. Hist. Stdev 2001 Corresponds to the NISCOPE_VAL_VOLTAGE_HISTOGRAM_STDEV command. Histogram Stdev = √∑[bin hits × (bin value - histogram mean)2]/(total hits - 1)
    Volt. Hist. Median 2003 Corresponds to the NISCOPE_VAL_VOLTAGE_HISTOGRAM_MEDIAN C or C++ command. The bin value where half the histogram hits are above it and half the histogram hits are below.
    Volt Hist. Mode 2010 Corresponds to the NISCOPE_VAL_VOLTAGE_HISTOGRAM_MODE C or C++ command. The bin value with the most hits. If there is a tie, the lower voltage or time value is returned.
    Volt. Hist. Max 2005 Corresponds to the NISCOPE_VAL_VOLTAGE_HISTOGRAM_MAX C or C++ command. The highest bin value with at least one hit.
    Volt. Hist. Min 2006 Corresponds to the NISCOPE_VAL_VOLTAGE_HISTOGRAM_MIN C or C++ command. The lowest bin value with at least one hit.
    Volt. Hist. Peak to Peak 2002 Corresponds to the NISCOPE_VAL_VOLTAGE_HISTOGRAM_PEAK_TO_PEAK C or C++ command. Histogram maximum minus the histogram minimum.
    Volt. Hist. Mean + Stdev 2007 Corresponds to the NISCOPE_VAL_VOLTAGE_HISTOGRAM_MEAN_PLUS_STDEV C or C++ command. The percentage of hits in the histogram between mean minus the standard deviation and mean plus the standard deviation. The percentage is returned in the range 0-100.
    Volt. Hist. Mean + 2 Stdev 2008 Corresponds to the NISCOPE_VAL_VOLTAGE_HISTOGRAM_MEAN_PLUS_2_STDEV C or C++ command. The percentage of hits in the histogram between the mean minus two times the standard deviation and the mean plus to times the standard deviation.The percentage is returned in the range 0-100.
    Volt. Hist. Mean + 3 Stdev 2009 Corresponds to the NISCOPE_VAL_VOLTAGE_HISTOGRAM_MEAN_PLUS_3_STDEV C or C++ command. The percentage of hits in the histogram between the mean minus three times the standard deviation and the mean plus three times the standard deviation. The percentage is returned in the range 0-100.
    Volt. Hist. Hits 2004 Corresponds to the NISCOPE_VAL_VOLTAGE_HISTOGRAM_HITS C or C++ command. Number of points in the histogram.
    Volt. Hist. New Hits 2011 Corresponds to the NISCOPE_VAL_VOLTAGE_HISTOGRAM_NEW_HITS C or C++ command. Number of points added to the histogram by the most recent acquisition.
    Time Hist. Mean 3000 Corresponds to the NISCOPE_VAL_TIME_HISTOGRAM_MEAN C or C++ command. Histogram Mean = [ Σ (bin hits × bin value) ] / time hist hits.The bin value is the center time value of the histogram bin.
    Time Hist. Stdev 3001 Corresponds to the NISCOPE_VAL_TIME_HISTOGRAM_STDEV C or C++ command. Histogram Stdev = √Σ[bin hits × (bin value - histogram mean)2]/(total hits - 1)
    Time Hist. Median 3003 Corresponds to the NISCOPE_VAL_TIME_HISTOGRAM_MEDIA C or C++ command. The bin value where half the histogram hits are above it and half the histogram hits are below.
    Time Hist. Mode 3010 Corresponds to the NISCOPE_VAL_TIME_HISTOGRAM_MODE C or C++ command. The bin value with the most hits. If there is a tie, the lower voltage or time value is returned.
    Time Hist. Max 3005 Corresponds to the NISCOPE_VAL_TIME_HISTOGRAM_MAX C or C++ command. The highest bin value with at least one hit.
    Time Hist. Min 3006 Corresponds to the NISCOPE_VAL_TIME_HISTOGRAM_MIN C or C++ command. The lowest bin value with at least one hit.
    Time Hist. Peak-to-Peak 3002 Corresponds to the NISCOPE_VAL_TIME_HISTOGRAM_PEAK_TO_PEAK C or C++ command. Histogram maximum minus the histogram minimum.
    Time Hist. Mean + Stdev 3007 Corresponds to the NISCOPE_VAL_TIME_HISTOGRAM_MEAN_PLUS_STDEV C or C++ command. The percentage of hits in the histogram between mean minus the standard deviation and mean plus the standard deviation. The percentage is returned in the range 0-100.
    Time Hist. Mean + 2 Stdev 3008 Corresponds to the NISCOPE_VAL_TIME_HISTOGRAM_MEAN_PLUS_2_STDEV C or C++ command. The percentage of hits in the histogram between the mean minus two times the standard deviation and the mean plus two times the standard deviation. The percentage is returned in the range 0-100.
    Time Hist. Mean + 3 Stdev 3009 Corresponds to the NISCOPE_VAL_TIME_HISTOGRAM_MEAN_PLUS_3_STDEV C or C++ command. The percentage of hits in the histogram between the mean minus three times the standard deviation and the mean plus three times the standard deviation. The percentage is returned in the range 0-100.
    Time Hist. Hits 3004 Corresponds to the NISCOPE_VAL_TIME_HISTOGRAM_HITS C or C++ command. Number of points in the histogram.
    Time Hist. New Hits 3011 Corresponds to the NISCOPE_VAL_TIME_HISTOGRAM_NEW_HITS C or C++ command. Number of points added to the histogram by the most recent acquisition.

    Default: None

    datatype_icon

    session out

    Passes the instrument handle to the next node in the program. This parameter has the same value as session in.

    datatype_icon

    error out

    Error information.

    The node produces this output according to standard error behavior.

    Standard Error Behavior

    Many nodes provide an error in input and an error out output so that the node can respond to and communicate errors that occur while code is running. The value of error in specifies whether an error occurred before the node runs. Most nodes respond to values of error in in a standard, predictable way.

    error in does not contain an error error in contains an error
    If no error occurred before the node runs, the node begins execution normally.

    If no error occurs while the node runs, it returns no error. If an error does occur while the node runs, it returns that error information as error out.

    If an error occurred before the node runs, the node does not execute. Instead, it returns the error in value as error out.
    datatype_icon

    result

    The acquired measurement.

    Where This Node Can Run:

    Desktop OS: Windows

    FPGA: Not supported


    Recently Viewed Topics