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 or1
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 chosendmm_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.