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.