# NI Virtual Bench

## General Information

The armstrap/pyvirtualbench Python wrapper for the VirtualBench C-API is required. This Instrument driver only interfaces the pyvirtualbench Python wrapper.

## Examples

To be documented. Check the examples in the pyvirtualbench repository to get an idea.

Simple Example to switch digital lines of the DIO module.

    from pymeasure.instruments.ni import VirtualBench

    vb = VirtualBench(device_name='VB8012-3057E1C')
    line = 'dig/2'  # may be list of lines
    # initialize DIO module -> available via vb.dio
    vb.acquire_digital_input_output(line, reset=False)

    vb.dio.write(self.line, {True})
    sleep(1000)
    vb.dio.write(self.line, {False})

    vb.shutdown()

## Instrument Class

class pymeasure.instruments.ni.virtualbench.VirtualBench(device_name='', name='VirtualBench')

  Bases: `object`

  Represents National Instruments Virtual Bench main frame.

  Subclasses implement the functionalities of the different modules:

  > - Mixed-Signal-Oscilloscope (MSO)

  > - Digital Input Output (DIO)

  > - Function Generator (FGEN)

  > - Power Supply (PS)

  > - Serial Peripheral Interface (SPI) -> not implemented for pymeasure yet

  > - Inter Integrated Circuit (I2C) -> not implemented for pymeasure yet

  For every module exist methods to save/load the configuration to file. These methods are not wrapped so far, checkout the pyvirtualbench file.

  All calibration methods and classes are not wrapped so far, since these are not required on a very regular basis. Also the connections via network are not yet implemented. Check the pyvirtualbench file, if you need the functionality.

  Parameters:

    - device_name (str) – Full unique device name

    - name (str) – Name for display in pymeasure

  class DigitalInputOutput(virtualbench, lines, reset, vb_name='')

    Bases: `VirtualBenchInstrument`

    Represents Digital Input Output (DIO) Module of Virtual Bench device. Allows to read/write digital channels and/or set channels to export the start signal of FGEN module or trigger of MSO module.

    export_signal(line, digitalSignalSource)

      Exports a signal to the specified line.

      Parameters:

        - line (str) – Line string

        - digitalSignalSource (int) – `0` for FGEN start or `1` for MSO trigger

    query_export_signal(line)

      Indicates the signal being exported on the specified line.

      Parameters:

        line (str) – Line string

      Returns:

        Exported signal (FGEN start or MSO trigger)

      Return type:

        enum

    query_line_configuration()

      Indicates the current line configurations. Tristate Lines, Static Lines, and Export Lines contain comma-separated range_data and/or colon-delimited lists of all acquired lines

    read(lines)

      Reads the current state of the specified lines.

      Parameters:

        lines (str) – Line string, requires full name specification e.g. `'VB8012-xxxxxxx/dig/0:7'` since instrument_handle is not required (only library_handle)

      Returns:

        List of line states (HIGH/LOW)

      Return type:

        list

    reset_instrument()

      Resets the session configuration to default values, and resets the device and driver software to a known state.

    shutdown()

      Removes the session and deallocates any resources acquired during the session. If output is enabled on any channels, they remain in their current state.

    tristate_lines(lines)

      Sets all specified lines to a high-impedance state. (Default)

    validate_lines(lines, return_single_lines=False, validate_init=False)

      Validate lines string Allowed patterns (case sensitive):

      > - `'VBxxxx-xxxxxxx/dig/0:7'`

      > - `'VBxxxx-xxxxxxx/dig/0'`

      > - `'dig/0'`

      > - `'VBxxxx-xxxxxxx/trig'`

      > - `'trig'`

      > Allowed Line Numbers: 0-7 or trig

      Parameters:

        - lines (str) – Line string to test

        - return_single_lines (bool, optional) – Return list of line numbers as well, defaults to False

        - validate_init (bool, optional) – Check if lines are initialized (in `self._line_numbers`), defaults to False

      Returns:

        Line string, optional list of single line numbers

      Return type:

        str, optional (str, list)

    write(lines, data)

      Writes data to the specified lines.

      Parameters:

        - lines (str) – Line string

        - data (list or tuple) – List of data, (`True` = High, `False` = Low)

  class DigitalMultimeter(virtualbench, reset, vb_name='')

    Bases: `VirtualBenchInstrument`

    Represents Digital Multimeter (DMM) Module of Virtual Bench device. Allows to measure either DC/AC voltage or current, Resistance or Diodes.

    configure_ac_current(auto_range_terminal)

      Configure auto rage terminal for AC current measurement

      Parameters:

        auto_range_terminal – Terminal to perform auto ranging (`'LOW'` or `'HIGH'`)

    configure_dc_current(auto_range_terminal)

      Configure auto rage terminal for DC current measurement

      Parameters:

        auto_range_terminal – Terminal to perform auto ranging (`'LOW'` or `'HIGH'`)

    configure_dc_voltage(dmm_input_resistance)

      Configure DC voltage input resistance

      Parameters:

        dmm_input_resistance (int or str) – Input resistance (`'TEN_MEGA_OHM'` or `'TEN_GIGA_OHM'`)

    configure_measurement(dmm_function, auto_range=True, manual_range=1.0)

      Configure Instrument to take a DMM measurement

      Parameters:

        - name (dmm_function:DMM function index or) –

          - `'DC_VOLTS'`, `'AC_VOLTS'`

          - `'DC_CURRENT'`, `'AC_CURRENT'`

          - `'RESISTANCE'`

          - `'DIODE'`

        - auto_range (bool) – Enable/Disable auto ranging

        - manual_range (float) – Manually set measurement range

    query_ac_current()

      Indicates auto range terminal for AC current measurement

    query_dc_current()

      Indicates auto range terminal for DC current measurement

    query_dc_voltage()

      Indicates input resistance setting for DC voltage measurement

    query_measurement()

      Query DMM measurement settings from the instrument

      Returns:

        Auto range, range data

      Return type:

        (bool, float)

    read()

      Read measurement value from the instrument

      Returns:

        Measurement value

      Return type:

        float

    reset_instrument()

      Reset the DMM module to defaults

    shutdown()

      Removes the session and deallocates any resources acquired during the session. If output is enabled on any channels, they remain in their current state.

    validate_auto_range_terminal(auto_range_terminal)

      Check value for choosing the auto range terminal for DC current measurement

      Parameters:

        auto_range_terminal (int or str) – Terminal to perform auto ranging (`'LOW'` or `'HIGH'`)

      Returns:

        Auto range terminal to pass to the instrument

      Return type:

        int

    validate_dmm_function(dmm_function)

      Check if DMM function dmm_function exists

      Parameters:

        dmm_function (int or str) –

        DMM function index or name:

        - `'DC_VOLTS'`, `'AC_VOLTS'`

        - `'DC_CURRENT'`, `'AC_CURRENT'`

        - `'RESISTANCE'`

        - `'DIODE'`

      Returns:

        DMM function index to pass to the instrument

      Return type:

        int

    static validate_range(dmm_function, range)

      Checks if `range` is valid for the chosen `dmm_function`

      Parameters:

        - dmm_function (int) – DMM Function

        - range (int or float) – Range value, e.g. maximum value to measure

      Returns:

        Range value to pass to instrument

      Return type:

        int

  class FunctionGenerator(virtualbench, reset, vb_name='')

    Bases: `VirtualBenchInstrument`

    Represents Function Generator (FGEN) Module of Virtual Bench device.

    configure_arbitrary_waveform(waveform, sample_period)

      Configures the instrument to output a waveform. The waveform is output either after the end of the current waveform if output is enabled, or immediately after output is enabled.

      Parameters:

        - waveform (list) – Waveform as list of values

        - sample_period (float) – Time between two waveform points (maximum of 125MS/s, which equals 80ns)

    configure_arbitrary_waveform_gain_and_offset(gain, dc_offset)

      Configures the instrument to output an arbitrary waveform with a specified gain and offset value. The waveform is output either after the end of the current waveform if output is enabled, or immediately after output is enabled.

      Parameters:

        - gain (float) – Gain, multiplier of waveform values

        - dc_offset (float) – DC offset in volts

    configure_standard_waveform(waveform_function, amplitude, dc_offset, frequency, duty_cycle)

      Configures the instrument to output a standard waveform. Check instrument manual for maximum ratings which depend on load.

      Parameters:

        - waveform_function (int or str) – Waveform function (`"SINE", "SQUARE", "TRIANGLE/RAMP", "DC"`)

        - amplitude (float) – Amplitude in volts

        - dc_offset (float) – DC offset in volts

        - frequency (float) – Frequency in Hz

        - duty_cycle (int) – Duty cycle in %

    property filter

      Enables or disables the filter on the instrument.

      Parameters:

        enable_filter (bool) – Enable/Disable filter

    query_arbitrary_waveform()

      Returns the samples per second for arbitrary waveform generation.

      Returns:

        Samples per second

      Return type:

        int

    query_arbitrary_waveform_gain_and_offset()

      Returns the settings for arbitrary waveform generation that includes gain and offset settings.

      Returns:

        Gain, DC offset

      Return type:

        (float, float)

    query_generation_status()

      Returns the status of waveform generation on the instrument.

      Returns:

        Status

      Return type:

        enum

    query_standard_waveform()

      Returns the settings for a standard waveform generation.

      Returns:

        Waveform function, amplitude, dc_offset, frequency, duty_cycle

      Return type:

        (enum, float, float, float, int)

    query_waveform_mode()

      Indicates whether the waveform output by the instrument is a standard or arbitrary waveform.

      Returns:

        Waveform mode

      Return type:

        enum

    reset_instrument()

      Resets the session configuration to default values, and resets the device and driver software to a known state.

    run()

      Transitions the session from the Stopped state to the Running state.

    self_calibrate()

      Performs offset nulling calibration on the device. You must run FGEN Initialize prior to running this method.

    shutdown()

      Removes the session and deallocates any resources acquired during the session. If output is enabled on any channels, they remain in their current state.

    stop()

      Transitions the acquisition from either the Triggered or Running state to the Stopped state.

  class MixedSignalOscilloscope(virtualbench, reset, vb_name='')

    Bases: `VirtualBenchInstrument`

    Represents Mixed Signal Oscilloscope (MSO) Module of Virtual Bench device. Allows to measure oscilloscope data from analog and digital channels.

    Methods from pyvirtualbench not implemented in pymeasure yet:

    > - `enable_digital_channels`

    > - `configure_digital_threshold`

    > - `configure_advanced_digital_timing`

    > - `configure_state_mode`

    > - `configure_digital_edge_trigger`

    > - `configure_digital_pattern_trigger`

    > - `configure_digital_glitch_trigger`

    > - `configure_digital_pulse_width_trigger`

    > - `query_digital_channel`

    > - `query_enabled_digital_channels`

    > - `query_digital_threshold`

    > - `query_advanced_digital_timing`

    > - `query_state_mode`

    > - `query_digital_edge_trigger`

    > - `query_digital_pattern_trigger`

    > - `query_digital_glitch_trigger`

    > - `query_digital_pulse_width_trigger`

    > - `read_digital_u64`

    auto_setup()

      Automatically configure the instrument

    configure_analog_channel(channel, enable_channel, vertical_range, vertical_offset, probe_attenuation, vertical_coupling)

      Configure analog measurement channel

      Parameters:

        - channel (str) – Channel string

        - enable_channel (bool) – Enable/Disable channel

        - vertical_range (float) – Vertical measurement range (0V - 20V), the instrument discretizes to these ranges: `[20, 10, 5, 2, 1, 0.5, 0.2, 0.1, 0.05]` which are 5x the values shown in the native UI.

        - vertical_offset (float) – Vertical offset to correct for (inverted compared to VB native UI, -20V - +20V, resolution 0.1mV)

        - probe_attenuation (int or str) – Probe attenuation (`'ATTENUATION_10X'` or `'ATTENUATION_1X'`)

        - vertical_coupling (int or str) – Vertical coupling (`'AC'` or `'DC'`)

    configure_analog_channel_characteristics(channel, input_impedance, bandwidth_limit)

      Configure electrical characteristics of the specified channel

      Parameters:

        - channel (str) – Channel string

        - input_impedance (int or str) – Input Impedance (`'ONE_MEGA_OHM'` or `'FIFTY_OHMS'`)

        - bandwidth_limit (int) – Bandwidth limit (100MHz or 20MHz)

    configure_analog_edge_trigger(trigger_source, trigger_slope, trigger_level, trigger_hysteresis, trigger_instance)

      Configures a trigger to activate on the specified source when the analog edge reaches the specified levels.

      Parameters:

        - trigger_source (str) – Channel string

        - trigger_slope (int or str) – Trigger slope (`'RISING'`, `'FALLING'` or `'EITHER'`)

        - trigger_level (float) – Trigger level

        - trigger_hysteresis (float) – Trigger hysteresis

        - trigger_instance (int or str) – Trigger instance

    configure_analog_pulse_width_trigger(trigger_source, trigger_polarity, trigger_level, comparison_mode, lower_limit, upper_limit, trigger_instance)

      Configures a trigger to activate on the specified source when the analog edge reaches the specified levels within a specified window of time.

      Parameters:

        - trigger_source (str) – Channel string

        - trigger_polarity (int or str) – Trigger slope (`'POSITIVE'` or `'NEGATIVE'`)

        - trigger_level (float) – Trigger level

        - comparison_mode (int or str) – Mode of compariosn ( `'GREATER_THAN_UPPER_LIMIT'`, `'LESS_THAN_LOWER_LIMIT'`, `'INSIDE_LIMITS'` or `'OUTSIDE_LIMITS'`)

        - lower_limit (float) – Lower limit

        - upper_limit (float) – Upper limit

        - trigger_instance (int or str) – Trigger instance

    configure_immediate_trigger()

      Configures a trigger to immediately activate on the specified channels after the pretrigger time has expired.

    configure_timing(sample_rate, acquisition_time, pretrigger_time, sampling_mode)

      Configure timing settings of the MSO

      Parameters:

        - sample_rate (int) – Sample rate (15.26kS - 1GS)

        - acquisition_time (float) – Acquisition time (1ns - 68.711s)

        - pretrigger_time (float) – Pretrigger time (0s - 10s)

        - sampling_mode – Sampling mode (`'SAMPLE'` or `'PEAK_DETECT'`)

    configure_trigger_delay(trigger_delay)

      Configures the amount of time to wait after a trigger condition is met before triggering.

      > param float trigger_delay:

      >   Trigger delay (0s - 17.1799s)

    force_trigger()

      Causes a software-timed trigger to occur after the pretrigger time has expired.

    query_acquisition_status()

      Returns the status of a completed or ongoing acquisition.

    query_analog_channel(channel)

      Indicates the vertical configuration of the specified channel.

      Returns:

        Channel enabled, vertical range, vertical offset, probe attenuation, vertical coupling

      Return type:

        (bool, float, float, enum, enum)

    query_analog_channel_characteristics(channel)

      Indicates the properties that control the electrical characteristics of the specified channel. This method returns an error if too much power is applied to the channel.

      > return:

      >   Input impedance, bandwidth limit

      > rtype:

      >   (enum, float)

    query_analog_edge_trigger(trigger_instance)

      Indicates the analog edge trigger configuration of the specified instance.

      Returns:

        Trigger source, trigger slope, trigger level, trigger hysteresis

      Return type:

        (str, enum, float, float)

    query_analog_pulse_width_trigger(trigger_instance)

      Indicates the analog pulse width trigger configuration of the specified instance.

      Returns:

        Trigger source, trigger polarity, trigger level, comparison mode, lower limit, upper limit

      Return type:

        (str, enum, float, enum, float, float)

    query_enabled_analog_channels()

      Returns String of enabled analog channels.

      Returns:

        Enabled analog channels

      Return type:

        str

    query_timing()

      Indicates the timing configuration of the MSO. Call directly before measurement to read the actual timing configuration and write it to the corresponding class variables. Necessary to interpret the measurement data, since it contains no time information.

      Returns:

        Sample rate, acquisition time, pretrigger time, sampling mode

      Return type:

        (float, float, float, enum)

    query_trigger_delay()

      Indicates the trigger delay setting of the MSO.

      Returns:

        Trigger delay

      Return type:

        float

    query_trigger_type(trigger_instance)

      Indicates the trigger type of the specified instance.

      Parameters:

        trigger_instance – Trigger instance (`'A'` or `'B'`)

      Returns:

        Trigger type

      Return type:

        str

    read_analog_digital_dataframe()

      Transfers data from the instrument and returns a pandas dataframe of the analog measurement data, including time coordinates

      Returns:

        Dataframe with time and measurement data

      Return type:

        pd.DataFrame

    read_analog_digital_u64()

      Transfers data from the instrument as long as the acquisition state is Acquisition Complete. If the state is either Running or Triggered, this method will wait until the state transitions to Acquisition Complete. If the state is Stopped, this method returns an error.

      Returns:

        Analog data out, analog data stride, analog t0, digital data out, digital timestamps out, digital t0, trigger timestamp, trigger reason

      Return type:

        (list, int, pyvb.Timestamp, list, list, pyvb.Timestamp, pyvb.Timestamp, enum)

    reset_instrument()

      Resets the session configuration to default values, and resets the device and driver software to a known state.

    run(autoTrigger=True)

      Transitions the acquisition from the Stopped state to the Running state. If the current state is Triggered, the acquisition is first transitioned to the Stopped state before transitioning to the Running state. This method returns an error if too much power is applied to any enabled channel.

      Parameters:

        autoTrigger (bool) – Enable/Disable auto triggering

    shutdown()

      Removes the session and deallocates any resources acquired during the session. If output is enabled on any channels, they remain in their current state.

    stop()

      Transitions the acquisition from either the Triggered or Running state to the Stopped state.

    validate_channel(channel)

      Check if `channel` is a correct specification

      Parameters:

        channel (str) – Channel string

      Returns:

        Channel string

      Return type:

        str

    static validate_trigger_instance(trigger_instance)

      Check if `trigger_instance` is a valid choice

      Parameters:

        trigger_instance (int or str) – Trigger instance (`'A'` or `'B'`)

      Returns:

        Trigger instance

      Return type:

        int

  class PowerSupply(virtualbench, reset, vb_name='')

    Bases: `VirtualBenchInstrument`

    Represents Power Supply (PS) Module of Virtual Bench device

    configure_current_output(channel, current_level, voltage_limit)

      Configures a current output on the specified channel. This method should be called once for every channel you want to configure to output current.

    configure_voltage_output(channel, voltage_level, current_limit)

      Configures a voltage output on the specified channel. This method should be called once for every channel you want to configure to output voltage.

    property outputs_enabled

      Enables or disables all outputs on all channels of the instrument.

      Parameters:

        enable_outputs (bool) – Enable/Disable outputs

    query_current_output(channel)

      Indicates the current output settings on the specified channel.

    query_voltage_output(channel)

      Indicates the voltage output settings on the specified channel.

    read_output(channel)

      Reads the voltage and current levels and outout mode of the specified channel.

    reset_instrument()

      Resets the session configuration to default values, and resets the device and driver software to a known state.

    shutdown()

      Removes the session and deallocates any resources acquired during the session. If output is enabled on any channels, they remain in their current state.

    property tracking

      Enables or disables tracking between the positive and negative 25V channels. If enabled, any configuration change on the positive 25V channel is mirrored to the negative 25V channel, and any writes to the negative 25V channel are ignored.

      Parameters:

        enable_tracking (bool) – Enable/Disable tracking

    validate_channel(channel, current=False, voltage=False)

      Check if channel string is valid and if output current/voltage are within the output ranges of the channel

      Parameters:

        - channel (str) – Channel string (`"ps/+6V","ps/+25V","ps/-25V"`)

        - current (bool, optional) – Current output, defaults to False

        - voltage (bool, optional) – Voltage output, defaults to False

      Returns:

        channel or channel, current & voltage

      Return type:

        str or (str, float, float)

  acquire_digital_input_output(lines, reset=False)

    Establishes communication with the DIO module. This method should be called once per session.

    Parameters:

      - lines (str) – Lines to acquire, reading is possible on all lines

      - reset (bool, optional) – Reset DIO module, defaults to False

  acquire_digital_multimeter(reset=False)

    Establishes communication with the DMM module. This method should be called once per session.

    Parameters:

      reset (bool, optional) – Reset the DMM module, defaults to False

  acquire_function_generator(reset=False)

    Establishes communication with the FGEN module. This method should be called once per session.

    Parameters:

      reset (bool, optional) – Reset the FGEN module, defaults to False

  acquire_mixed_signal_oscilloscope(reset=False)

    Establishes communication with the MSO module. This method should be called once per session.

    Parameters:

      reset (bool, optional) – Reset the MSO module, defaults to False

  acquire_power_supply(reset=False)

    Establishes communication with the PS module. This method should be called once per session.

    Parameters:

      reset (bool, optional) – Reset the PS module, defaults to False

  collapse_channel_string(names_in)

    Collapses a channel string into a comma and colon-delimited equivalent. Last element is the number of channels.

    Parameters:

      names_in (str) – Channel string

    Returns:

      Channel string with colon notation where possible, number of channels

    Return type:

      (str, int)

  convert_timestamp_to_values(timestamp)

    Converts a timestamp to seconds and fractional seconds

    Parameters:

      timestamp (pyvb.Timestamp) – VirtualBench timestamp

    Returns:

      (seconds_since_1970, fractional seconds)

    Return type:

      (int, float)

  convert_values_to_datetime(timestamp)

    Converts timestamp to datetime object

    Parameters:

      timestamp (pyvb.Timestamp) – VirtualBench timestamp

    Returns:

      Timestamp as DateTime object

    Return type:

      DateTime

  convert_values_to_timestamp(seconds_since_1970, fractional_seconds)

    Converts seconds and fractional seconds to a timestamp

    Parameters:

      - seconds_since_1970 (int) – Date/Time in seconds since 1970

      - fractional_seconds (float) – Fractional seconds

    Returns:

      VirtualBench timestamp

    Return type:

      pyvb.Timestamp

  expand_channel_string(names_in)

    Expands a channel string into a comma-delimited (no colon) equivalent. Last element is the number of channels. `'dig/0:2'` -> `('dig/0, dig/1, dig/2',3)`

    Parameters:

      names_in (str) – Channel string

    Returns:

      Channel string with all channels separated by comma, number of channels

    Return type:

      (str, int)

  get_calibration_information()

    Returns calibration information for the specified device, including the last calibration date and calibration interval.

    Returns:

      Calibration date, recommended calibration interval in months, calibration interval in months

    Return type:

      (pyvb.Timestamp, int, int)

  get_library_version()

    Return the version of the VirtualBench runtime library

  shutdown()

    Finalize the VirtualBench library.

class pymeasure.instruments.ni.virtualbench.VirtualBench_Direct(*args: Any, **kwargs: Any)

  Bases: `PyVirtualBench`

  Represents National Instruments Virtual Bench main frame. This class provides direct access to the armstrap/pyvirtualbench Python wrapper.