ivi
— IVI driver¶
This module provides the base functionality of an IVI instrument driver.
Functions and Exceptions¶
DriverOperation
class¶
DriverIdentity
class¶
DriverUtility
class¶
Driver
class¶
-
class
ivi.
Driver
(resource=None, id_query=False, reset=False, *args, **kwargs)[source]¶ Bases:
ivi.ivi.DriverOperation
,ivi.ivi.DriverIdentity
,ivi.ivi.DriverUtility
Inherent IVI methods for all instruments
ivi.
close
¶When the user finishes using a Python IVI driver, the user should call either the Close method or __del__. Note that __del__ will call close automatically.
This function also does the following:
- Prevents the user from calling other functions in the driver that access the instrument until the user calls the Initialize function again.
- May deallocate internal resources used by the IVI session.
driver_operation.
cache
¶If True, the specific driver caches the value of attributes, and the IVI specific driver keeps track of the current instrument settings so that it can avoid sending redundant commands to the instrument. If False, the specific driver does not cache the value of attributes.
The default value is True. When the user opens an instrument session through an IVI class driver or uses a logical name to initialize a specific driver, the user can override this value by specifying a value in the IVI configuration store. The Initialize function allows the user to override both the default value and the value that the user specifies in the IVI configuration store.
driver_operation.
clear_interchange_warnings
¶This function clears the list of interchangeability warnings that the IVI specific driver maintains.
When this function is called on an IVI class driver session, the function clears the list of interchangeability warnings that the class driver and the specific driver maintain.
Refer to the Interchange Check attribute for more information on interchangeability checking.
driver_operation.
driver_setup
¶Returns the driver setup string that the user specified in the IVI configuration store when the instrument driver session was initialized or passes in the OptionString parameter of the Initialize function. Refer to Section 6.14, Initialize, for the restrictions on the format of the driver setup string.
The string that this attribute returns does not have a predefined maximum length.
driver_operation.
get_next_coercion_record
¶If the Record Value Coercions attribute is set to True, the IVI specific driver keeps a list of all value coercions it makes on integer and floating point attributes. This function obtains the coercion information associated with the IVI session. It retrieves and clears the oldest instance in which the specific driver coerced a value the user specified to another value.
The function returns an empty string in the CoercionRecord parameter if no coercion records remain for the session.
The coercion record string shall contain the following information:
- The name of the attribute that was coerced. This can be the generic name, the COM property name, or the C defined constant.
- If the attribute applies to a repeated capability, the name of the virtual or physical repeated capability identifier.
- The value that the user specified for the attribute.
- The value to which the attribute was coerced.
A recommended format for the coercion record string is as follows:
" Attribute " + <attribute name> + [" on <repeated capability> " + <repeated capability identifier>] + " was coerced from " + <desiredVal> + " to " + <coercedVal>.
And example coercion record string is as follows:
Attribute TKTDS500_ATTR_VERTICAL_RANGE on channel ch1 was coerced from 9.0 to 10.0.
driver_operation.
get_next_interchange_warning
¶If the Interchange Check attribute is set to True, the IVI specific driver keeps a list of all interchangeability warnings that it encounters. This function returns the interchangeability warnings associated with the IVI session. It retrieves and clears the oldest interchangeability warning from the list. Interchangeability warnings indicate that using the application with a different instrument might cause different behavior.
When this function is called on an IVI class driver session, it may return interchangeability warnings generated by the IVI class driver as well as interchangeability warnings generated by the IVI specific driver. The IVI class driver determines the relative order in which the IVI class driver warnings are returned in relation to the IVI specific driver warnings.
The function returns an empty string in the InterchangeWarning parameter if no interchangeability warnings remain for the session.
Refer to the Interchange Check attribute for more information on interchangeability checking.
driver_operation.
interchange_check
¶If True, the specific driver performs interchangeability checking. If the Interchange Check attribute is enabled, the specific driver maintains a record of each interchangeability warning that it encounters. The user calls the Get Next Interchange Warning function to extract and delete the oldest interchangeability warning from the list. Refer to Section 6.11, Get Next Interchange Warning, Section 6.2, Clear Interchange Warnings, and Section 6.18, Reset Interchange Check, for more information. If False, the specific driver does not perform interchangeability checking.
If the user opens an instrument session through an IVI class driver and the Interchange Check attribute is enabled, the IVI class driver may perform additional interchangeability checking. The IVI class driver maintains a list of the interchangeability warnings that it encounters. The user can retrieve both class driver interchangeability warnings and specific driver interchangeability warnings by calling the Get Next Interchange Warning function on the class driver session.
If the IVI specific driver does not implement interchangeability checking, the specific driver returns the Value Not Supported error when the user attempts to set the Interchange Check attribute to True. If the specific driver does implement interchangeability checking and the user opens an instrument session through an IVI class driver, the IVI class driver accepts True as a valid value for the Interchange Check attribute even if the class driver does not implement interchangeability checking capabilities of its own.
The default value is False. If the user opens an instrument session through an IVI class driver or initializes an IVI specific driver with a logical name, the user can override this value in the IVI configuration store. The Initialize function allows the user to override both the default value and the value that the userspecifies in the IVI configuration store.
driver_operation.
invalidate_all_attributes
¶This function invalidates the cached values of all attributes for the session.
driver_operation.
io_resource_descriptor
¶Returns the resource descriptor that the user specified for the physical device. The user specifies the resource descriptor by editing the IVI configuration store or by passing a resource descriptor to the Initialize function of the specific driver. Refer to Section 6.14, Initialize, for the restrictions on the contents of the resource descriptor string.
The string that this attribute returns contains a maximum of 256 characters including the NULL character.
driver_operation.
logical_name
¶Returns the IVI logical name that the user passed to the Initialize function. If the user initialized the IVI specific driver directly and did not pass a logical name, then this attribute returns an empty string. Refer to IVI-3.5: Configuration Server Specification for restrictions on the format of IVI logical names.
The string that this attribute returns contains a maximum of 256 characters including the NULL character.
driver_operation.
query_instrument_status
¶If True, the IVI specific driver queries the instrument status at the end of each user operation. If False, the IVI specific driver does not query the instrument status at the end of each user operation. Querying the instrument status is very useful for debugging. After validating the program, the user can set this attribute to False to disable status checking and maximize performance. The user specifies this value for the entire IVI driver session.
The default value is False. When the user opens an instrument session through an IVI class driver or uses a logical name to initialize an IVI specific driver, the user can override this value by specifying a value in the IVI configuration store. The Initialize function allows the user to override both the default value and the value that the user specifies in the IVI configuration store.
driver_operation.
range_check
¶If True, the IVI specific driver validates attribute values and function parameters. If False, the IVI specific driver does not validate attribute values and function parameters.
If range check is enabled, the specific driver validates the parameter values that users pass to driver functions. Validating attribute values and function parameters is useful for debugging. After validating the program, the user can set this attribute to False to disable range checking and maximize performance. The default value is True. When the user opens an instrument session through an IVI class driver or uses a logical name to initialize an IVI specific driver, the user can override this value by specifying a value in the IVI configuration store. The Initialize function allows the user to override both the default value and the value that the user specifies in the IVI configuration store.
driver_operation.
record_coercions
¶If True, the IVI specific driver keeps a list of the value coercions it makes for ViInt32 and ViReal64 attributes. If False, the IVI specific driver does not keep a list of the value coercions it makes for ViInt32 and ViReal64 attributes.
If the Record Value Coercions attribute is enabled, the specific driver maintains a record of each coercion. The user calls the Get Next Coercion Record function to extract and delete the oldest coercion record from the list. Refer to Section 6.10, Get Next Coercion Record, for more information.
If the IVI specific driver does not implement coercion recording, the specific driver returns the Value Not Supported error when the user attempts to set the Record Value Coercions attribute to True.
The default value is False. When the user opens an instrument session through an IVI class driver or uses a logical name to initialize a IVI specific driver, the user can override this value by specifying a value in the IVI configuration store. The Initialize function allows the user to override both the default value and the value that the user specifies in the IVI configuration store.
driver_operation.
reset_interchange_check
¶This function resets the interchangeability checking algorithms of the IVI specific driver so that specific driver functions that execute prior to calling this function have no effect on whether future calls to the specific driver generate interchangeability warnings.
When developing a complex test system that consists of multiple test modules, it is generally a good idea to design the test modules so that they can run in any order. To do so requires ensuring that each test module completely configures the state of each instrument it uses. If a particular test module does not completely configure the state of an instrument, the state of the instrument depends on the configuration from a previously executed test module. If the test modules execute in a different order, the behavior of the instrument and therefore the entire test module is likely to change. This change in behavior is generally instrument specific and represents an interchangeability problem.
Users can use this function to test for such cases. By calling this function at the beginning of a test module, users can determine whether the test module has dependencies on the operation of previously executed test modules. Any interchangeability warnings that occur after the user calls this function indicate that the section of the test program that executes after this function and prior to the generation of the warning does not completely configure the instrument and that the user is likely to experience different behavior if the user changes the execution order of the test modules or if the user changes instruments.
Note: This function does not clear interchangeability warnings from the list of interchangeability warnings. To guarantee that the Get Next Interchange Warning function returns interchangeability warnings that occur only after the program calls function, the user must clear the list of interchangeability warnings by calling the Clear Interchange Warnings function.
Refer to the Interchange Check attribute for more information on interchangeability checking.
driver_operation.
simulate
¶If True, the IVI specific driver simulates instrument driver I/O operations. If False, the IVI specific driver communicates directly with the instrument.
If simulation is enabled, the specific driver functions do not perform instrument I/O. For output parameters that represent instrument data, the specific driver functions return simulated values.
The default value is False. When the user opens an instrument session through an IVI class driver or uses a logical name to initialize an IVI specific driver, the user can override this value by specifying a value in the IVI configuration store. The Initialize function allows the user to override both the default value and the value that the user specifies in the IVI configuration store.
identity.
description
¶Returns a brief description of the IVI software component.
The string that this attribute returns has no maximum size.
identity.
get_group_capabilities
¶Returns a list of names of class capability groups that the IVI specific driver implements. The items in the list are capability group names that the IVI class specifications define. The list is returned as a list of strings.
If the IVI specific driver does not comply with an IVI class specification, the specific driver returns an array with zero elements.
identity.
get_supported_instrument_models
¶Returns a list of names of instrument models with which the IVI specific driver is compatible. The list is returned as a list of strings. For example, this attribute might return the strings “TKTDS3012”, “TKTDS3014”, and “TKTDS3016” .
It is not necessary for the string to include the abbreviation for the manufacturer if it is the same for all models. In the example above, it is valid for the attribute to return the strings “TDS3012”, “TDS3014”, and “TDS3016”.
identity.
group_capabilities
¶Returns a comma-separated list that identifies the class capability groups that the IVI specific driver implements. The items in the list are capability group names that the IVI class specifications define. The string has no white space except for white space that might be embedded in a capability group name.
If the IVI specific driver does not comply with an IVI class specification, the specific driver returns an empty string as the value of this attribute.
The string that this attribute returns does not have a predefined maximum length.
identity.
identifier
¶Returns the case-sensitive unique identifier of the IVI software component. The string that this attribute returns contains a maximum of 32 characters including the NULL character.
identity.
instrument_firmware_revision
¶Returns an instrument specific string that contains the firmware revision information of the physical instrument. The IVI specific driver returns the value it queries from the instrument as the value of this attribute or a string indicating that it cannot query the instrument identity.
In some cases, it is not possible for the specific driver to query the firmware revision of the instrument. This can occur when the Simulate attribute is set to True or if the instrument is not capable of returning the firmware revision. For these cases, the specific driver returns defined strings for this attribute. If the Simulate attribute is set to True, the specific driver returns “Not available while simulating” as the value of this attribute. If the instrument is not capable of returning the firmware version and the Simulate attribute is set to False, the specific driver returns “Cannot query from instrument” as the value of this attribute.
The string that this attribute returns does not have a predefined maximum length.
identity.
instrument_manufacturer
¶Returns the name of the manufacturer of the instrument. The IVI specific driver returns the value it queries from the instrument as the value of this attribute or a string indicating that it cannot query the instrument identity.
In some cases, it is not possible for the specific driver to query the manufacturer of the instrument. This can occur when the Simulate attribute is set to True or if the instrument is not capable of returning the manufacturer. For these cases, the specific driver returns defined strings for this attribute. If the Simulate attribute is set to True, the specific driver returns “Not available while simulating” as the value of this attribute. If the instrument is not capable of returning the manufacturer and the Simulate attribute is set to False, the specific driver returns “Cannot query from instrument” as the value of this attribute.
The string that this attribute returns does not have a predefined maximum length.
identity.
instrument_model
¶Returns the model number or name of the physical instrument. The IVI specific driver returns the value it queries from the instrument or a string indicating that it cannot query the instrument identity.
In some cases, it is not possible for the specific driver to query the model of the instrument. This can occur when the Simulate attribute is set to True or if the instrument is not capable of returning the model. For these cases, the specific driver returns defined strings for this attribute. If the Simulate attribute is set to True, the specific driver returns “Not available while simulating” as the value of this attribute. If the instrument is not capable of returning the model and the Simulate attribute is set to False, the specific driver returns “Cannot query from instrument” as the value of this attribute.
The string that this attribute returns does not have a predefined maximum length.
identity.
revision
¶Returns version information about the IVI software component. Refer to Section 3.1.2.2, Additional Compliance Rules for Revision String Attributes, for additional rules regarding this attribute.
The string that this attribute returns has no maximum size.
identity.
specification_major_version
¶Returns the major version number of the class specification in accordance with which the IVI software component was developed. The value is a positive integer value.
If the software component is not compliant with a class specification, the software component returns zero as the value of this attribute.
identity.
specification_minor_version
¶Returns the minor version number of the class specification in accordance with which the IVI software component was developed. The value is a positive integer value.
If the software component is not compliant with a class specification, the software component returns zero as the value of this attribute.
identity.
supported_instrument_models
¶Returns a comma-separated list of names of instrument models with which the IVI specific driver is compatible. The string has no white space except possibly embedded in the instrument model names. An example of a string that this attribute might return is “TKTDS3012,TKTDS3014,TKTDS3016”.
It is not necessary for the string to include the abbreviation for the manufacturer if it is the same for all models. In the example above, it is valid for the attribute to return the string “TDS3012,TDS3014,TDS3016”.
The string that this attribute returns does not have a predefined maximum length.
identity.
vendor
¶Returns the name of the vendor that supplies the IVI software component.
The string that this attribute returns has no maximum size.
ivi.
initialize
¶The user must call the Initialize function prior to calling other IVI driver functions that access the instrument. The Initialize function is called automatically by the constructor if a resource string is passed as the first argument to the constructor.
If simulation is disabled when the user calls the Initialize function, the function performs the following actions:
Opens and configures an I/O session to the instrument.
If the user passes True for the IdQuery parameter, the function queries the instrument for its ID and verifies that the IVI specific driver supports the particular instrument model. If the instrument cannot return its ID, the specific driver returns the ID Query Not Supported warning.
If the user passes True for the Reset parameter, the function places the instrument in a known state. In an IEEE 488.2 instrument, the function sends the command string “*RST” to the instrument. If the instrument cannot perform a reset, the IVI specific driver returns the Reset Not Supported warning.
Configures instrument options on which the IVI specific driver depends. For example, a specific driver might enable or disable headers or enable binary mode for waveform transfers.
- Performs the following operations in the given order:
- Disables the class extension capability groups that the IVI specific driver does not implement.
- If the class specification with which the IVI specific driver is compliant defines initial values for attributes, this function sets the attributes to the values that the class specification defines.
- If the ResourceName parameter is a logical name, the IVI specific driver configures the initial settings for the specific driver and instrument based on the configuration of the logical name in the IVI configuration store.
If simulation is enabled when the user calls the Initialize function, the function performs the following actions:
- If the user passes True for the IdQuery parameter and the instrument cannot return its ID, the IVI specific driver returns the ID Query Not Supported warning.
- If the user passes True for the Reset parameter and the instrument cannot perform a reset, the IVI specific driver returns the Reset Not Supported warning.
- If the ResourceName parameter is a logical name, the IVI specific driver configures the initial settings for the specific driver based on the configuration of the logical name in the IVI configuration store.
Some instrument driver operations require or take into account information from the IVI configuration store. Examples of such information are virtual repeated capability name mappings and the value of certain inherent attributes. An IVI driver shall retrieve all the information for a session from the IVI configuration store during the Initialization function. The IVI driver shall not read any information from the IVI configuration store for a session after the Initialization function completes. Refer to Section 3.2.3, Instantiating the Right Configuration Store From Software Modules, of IVI-3.5: Configuration Server Specification for details on how to correctly instantiate the configuration store.
The ResourceName parameter must contain either a logical name that is defined in the IVI configuration store or an instrument specific string that identifies the I/O address of the instrument, such as a VISA resource descriptor string. Refer to IVI-3.5: Configuration Server Specification for restrictions on the format of IVI logical names. Refer to the VXIplug&play specifications for the grammar of VISA resource descriptor strings.
Example resource strings:
'TCPIP::10.0.0.1::INSTR' 'TCPIP0::10.0.0.1::INSTR' 'TCPIP::10.0.0.1::gpib,5::INSTR' 'TCPIP0::10.0.0.1::gpib,5::INSTR' 'TCPIP0::10.0.0.1::usb0::INSTR' 'TCPIP0::10.0.0.1::usb0[1234::5678::MYSERIAL::0]::INSTR' 'USB::1234::5678::INSTR' 'USB::1234::5678::SERIAL::INSTR' 'USB0::0x1234::0x5678::INSTR' 'USB0::0x1234::0x5678::SERIAL::INSTR' 'GPIB::10::INSTR' 'GPIB0::10::INSTR' 'ASRL1::INSTR' 'ASRL::COM1,9600,8n1::INSTR' 'ASRL::/dev/ttyUSB0,9600::INSTR' 'ASRL::/dev/ttyUSB0,9600,8n1::INSTR'The user can use additional parameters to specify the initial values of certain IVI inherent attributes for the session. The following table lists the inherent attributes that the user can set through these named parameters. The user does not have to specify all or any of the attributes. If the user does not specify the initial value of an inherent attribute, the initial value of the attribute depends on the value of the ResourceName parameter:
- If the ResourceName parameter contains an IVI logical name, the IVI specific driver configures the initial settings based on the configuration of the logical name in the IVI configuration store.
- If the ResourceName parameter contains a resource descriptor string that identifies the I/O address of the instrument, the IVI specific driver sets inherent attributes to their default initial values. The following table shows the default initial value for each attribute.
The following table lists the IVI inherent attributes that the user can set, their default initial values, and the name that represents each attribute. These options are passed to the initialize function or the constructor as key-value pairs.
Attribute Default Inital Value Options String Name Range Check True range_check Query Instrument Status False query_instr_status Cache True cache Simulate False simulate Record Value Coercions False record_coercions Interchange Check False interchange_check Driver Setup ‘’ driver_setup Prefer PyVISA False prefer_pyvisa Each IVI specific driver defines it own meaning and valid values for the Driver Setup attribute. Many specific drivers ignore the value of the Driver Setup attribute. Other specific drivers use the Driver Setup string to configure instrument specific features at initialization. For example, if a specific driver supports a family of instrument models, the driver can use the Driver Setup attribute to allow the user to specify a particular instrument model to simulate.
If the user attempts to initialize the instrument a second time without first calling the Close function, the Initialize function returns the Already Initialized error.
ivi.
initialized
¶Returns a value that indicates whether the IVI specific driver is in the initialized state. After the specific driver is instantiated and before the Initialize function successfully executes, this attribute returns False. After the Initialize function successfully executes and prior to the execution of the Close function, this attribute returns True. After the Close function executes, this attribute returns False.
The Initialized attribute is one of the few IVI specific driver attributes that can be accessed while the specific driver is not in the initialized state. All the attributes of an IVI specific driver that can be accessed while the specific driver is not in the initialized state are listed below.
- Component Class Spec Major Version
- Component Class Spec Minor Version
- Component Description
- Component Prefix
- Component Identifier
- Component Revision
- Component Vendor
- Initialized
- Supported Instrument Models
utility.
disable
¶The Disable operation places the instrument in a quiescent state as quickly as possible. In a quiescent state, an instrument has no or minimal effect on the external system to which it is connected. The Disable operation might be similar to the Reset operation in that it places the instrument in a known state. However, the Disable operation does not perform the other operations that the Reset operation performs such as configuring the instrument options on which the IVI specific driver depends. For some instruments, the disable function may do nothing.
The IVI class specifications define the exact behavior of this function for each instrument class. Refer to the IVI class specifications for more information on the behavior of this function.
utility.
error_query
¶Queries the instrument and returns instrument specific error information.
Generally, the user calls this function after another function in the IVI driver returns the Instrument Status error. The IVI specific driver returns the Instrument Status error when the instrument indicates that it encountered an error and its error queue is not empty. Error Query extracts an error out of the instrument’s error queue.
For instruments that have status registers but no error queue, the IVI specific driver emulates an error queue in software.
The method returns a tuple containing the error code and error message.
utility.
lock_object
¶This function obtains a multithread lock for this instance of the driver. Before it does so, Lock Session waits until all other execution threads have released their locks or for the length of time specified by the maximum time parameter, whichever come first. The type of lock obtained depends upon the parameters passed to the specific driver constructor.
The user can use Lock Session with IVI specific drivers to protect a section of code that requires exclusive access to the instrument. This occurs when the user takes multiple actions that affect the instrument and the user wants to ensure that other execution threads do not disturb the instrument state until all the actions execute. For example, if the user sets various instrument attributes and then triggers a measurement, the user must ensure no other execution thread modifies the attribute values until the user finishes taking the measurement.
It is important to note that this lock is not related to I/O locks such as the VISA resource locking mechanism.
The user can safely make nested calls to Lock Session within the same thread. To completely unlock the session, the user must balance each call to Lock Session with a call to Unlock Session. Calls to Lock Session must always obtain the same lock that is used internally by the IVI driver to guard individual method calls.
utility.
reset
¶This function performs the following actions:
- Places the instrument in a known state. In an IEEE 488.2 instrument, the Reset function sends the command string
*RST
to the instrument.- Configures instrument options on which the IVI specific driver depends. A specific driver might enable or disable headers or enable binary mode for waveform transfers.
The user can either call the Reset function separately or specify that it be called from the Initialize function. The Initialize function performs additional operations after performing the reset operation to place the instrument in a state more suitable for interchangeable programming. To reset the device and perform these additional operations, call the Reset With Defaults function instead of the Reset function.
utility.
reset_with_defaults
¶The Reset With Defaults function performs the same operations that the Reset function performs and then performs the following additional operations in the specified order:
- Disables the class extension capability groups that the IVI specific driver implements.
- If the class specification with which the IVI specific driver is compliant defines initial values for attributes, this function sets those attributes to the initial values that the class specification defines.
- Configures the initial settings for the specific driver and instrument based on the information retrieved from the IVI configuration store when the instrument driver session was initialized.
Notice that the Initialize function also performs these functions. To place the instrument and the IVI specific driver in the exact same state that they attain when the user calls the Initialize function, the user must first call the Close function and then the Initialize function.
utility.
self_test
¶Causes the instrument to perform a self test. Self Test waits for the instrument to complete the test. It then queries the instrument for the results of the self test and returns the results to the user.
If the instrument passes the self test, this function returns the tuple:
(0, 'Self test passed')Otherwise, the function returns a tuple of the result code and message.
utility.
unlock_object
¶This function releases a lock that the Lock Session function acquires.
Refer to Lock Session for additional information on IVI session locks.
Helper Classes¶
PropertyCollection
class¶
IndexedPropertyCollection
class¶
-
class
ivi.
IndexedPropertyCollection
[source]¶ A building block to create hierarchical trees of methods and properties with an index that is converted to a parameter
-
_add_property
(name, fget=None, fset=None, fdel=None, doc=None, props=None, docs=None)[source]¶ Add a managed property
-
_add_sub_method
(sub, name, f=None, doc=None)[source]¶ Add a sub-method (equivalent to _add_method(‘sub.name’, ...))
-
_add_sub_property
(sub, name, fget=None, fset=None, fdel=None, doc=None)[source]¶ Add a sub-property (equivalent to _add_property(‘sub.name’, ...))
-