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.