DOCSEARCHbyAlgolia
Submit Docs

PyVISA Documentation

repository·main·Indexed 21 days ago

https://github.com/pyvisa/pyvisa

Python VISA bindings for controlling measurement instruments and test equipment via the VISA (Virtual Instrument Software Architecture) standard. It supports interfaces including GPIB, RS232, TCPIP, and USB. The library features a three-layer architecture consisting of high-level Resource managers, middle-level bound methods, and low-level static methods for direct VISA library interaction. It supports multiple backends, including ivi, and provides a framework for developing custom backends via the VisaLibraryBase class.

Tokens
20.5K
Snippets
59
Records
79
Agent score
67%

What's inside PyVISA

  1. PyVISA Overview and Purpose

    main

    PyVISA is a Python package designed to support the "Virtual Instrument Software Architecture" (VISA) specification. It enables the control of measurement devices and test equipment across various interfaces, including:

    • GPIB
    • RS232
    • Ethernet
    • USB

    PyVISA acts as a Python wrapper for existing VISA shared libraries (.dll, .so, .dylib), allowing you to leverage standard vendor implementations (like NI-VISA or Keysight-VISA). It can also serve as a front-end for pure-Python implementations like PyVISA-Py.

  2. What is a Resource in PyVISA

    main

    A Resource represents an instrument (e.g., a measurement device). PyVISA uses different classes to represent different resource types (like GPIB or Serial).

    Resources are not instantiated directly; they are returned by the open_resource method of a ResourceManager. Most resources fall into two categories:

    1. MessageBasedResource (e.g., Serial, GPIB)
    2. RegisterBasedResource

    PyVISA automatically selects the correct Python class based on the resource name, but you can force a specific class using the resource_pyclass argument.

    from pyvisa.resources import MessageBasedResource
# Force a specific resource class during opening
inst = rm.open('ASRL1::INSTR', resource_pyclass=MessageBasedResource)

  3. Understand VISA resource names

    main

    When using the open_resource method in PyVISA, you must provide a VISA resource name to identify the instrument.

    General Syntax

    Resource names typically follow the pattern: [Bus Type]::[Address/Number].

    • GPIB: Uses GPIB::[address] or GPIB[board]::[address]. For example, GPIB::10 is instrument 10 on the default board, while GPIB1::10 is instrument 10 on board 1.
    • Serial (ASRL): Uses ASRL[board]. For example, ASRL2 connects to COM2. Note that serial interfaces do not use the double colon :: separator because only one instrument can be connected per interface.
    • Case Sensitivity: Resource names are case-insensitive (e.g., ASRL2 is the same as asrl2).
    • Aliases: Many VISA systems support aliases like "COM2" or "LPT1" instead of the standard syntax.

  4. Select a VISA backend

    main

    PyVISA supports two main backends:

    1. The IVI backend: Uses installed IVI libraries like NI-VISA, Keysight VISA, R&S VISA, or tekVISA. This is the default if an IVI library is detected.
    2. The pyvisa-py backend: A pure Python implementation. This is used if no IVI library is found.

    You can explicitly select a backend in three ways:

    • Pass the backend identifier to the ResourceManager constructor.
    • Set the PYVISA_LIBRARY environment variable.
    • Use a .pyvisarc configuration file.
    # Using pyvisa-py backend explicitly
import pyvisa
rm = pyvisa.ResourceManager('@py')

  5. Use ResourceManager and VisaLibrary for explicit control

    main

    PyVISA 1.6+ moved away from singleton objects to support thread safety and multiple library instances. You should now instantiate a ResourceManager to manage your connections and access the underlying VisaLibrary via the visalib attribute if low-level access is required.

    Loading a specific VISA library

    Instead of using a global load method, pass the path directly to the ResourceManager constructor:

    import pyvisa
rm = pyvisa.ResourceManager("/path/to/my/libvisa.so.7")
lib = rm.visalib

    Accessing low-level functions

    All low-level functions from the underlying library are available as bound methods on the VisaLibrary object (accessed via rm.visalib).

    import pyvisa
import ctypes

rm = pyvisa.ResourceManager("/path/to/my/libvisa.so.7")
lib = rm.visalib
# Example of calling a low-level function
status = ctypes.c_ushort()
ret = lib.viReadSTB(session, ctypes.byref(status))
    import pyvisa
rm = pyvisa.ResourceManager("/path/to/my/libvisa.so.7")
lib = rm.visalib
print(lib.read_stb(session))

  6. Event handling mechanisms and types

    main

    PyVISA supports two primary mechanisms for handling VISA events:

    • constants.EventMechanism.queue: Events are stored in a queue for the user to retrieve via wait_on_event().
    • constants.EventMechanism.handler: A registered callback function is called directly when the event occurs.
    • constants.EventMechanism.all: Enables both mechanisms simultaneously.

    Common event types are provided via constants.EventType (e.g., constants.EventType.service_request).

  7. How PyVISA backends and layers work

    main

    PyVISA acts as a frontend for various VISA implementations (backends).

    Backends

    • Vendor Backends (Default): Wraps compiled libraries like NI-VISA, Keysight VISA, R&S VISA, or tekVISA.
    • PyVISA-py: A pure Python backend using PySerial and PyUSB for environments where proprietary drivers cannot be used.
    • PyVISA-sim: A simulation backend for testing code without hardware.

    Abstraction Layers

    1. Layer 1 (Low level): Direct bindings to compiled libraries. Not intended for direct use.
    2. Layer 2 (Mid level): A Pythonic, function-oriented API that handles type conversions and interacts with the low-level layer.
    3. Layer 3 (High level): The primary user interface, consisting of the ResourceManager and Resource classes (and subclasses like USBInstrument).

  8. How PyVISA's three-layer architecture works

    main

    PyVISA is organized into three distinct layers to provide both high-level Pythonic convenience and low-level control:

    1. High-level (ResourceManager and Resource): The primary interface for most users. It provides an object-oriented way to inspect connected resources and interact with them using Pythonic methods and attributes. You typically start by instantiating a ResourceManager and using open_resource to get a Resource object.

    2. Middle-level (VisaLibrary bound methods): A layer of Python functions that wrap the low-level calls. These functions handle type conversions (especially for values returned by reference) and provide friendly, Pythonic documentation. Use this layer if you need to control specific VISA library aspects not exposed by the high-level Resource classes.

    3. Low-level (VisaLibrary static methods): A direct wrapper around the shared VISA library. These functions define argument and response types and handle conversions between Python and foreign types.

    Warning: Avoid using the low-level layer for general tasks. Alternative backends may not implement all low-level functions, which can break compatibility. Most functionality is available via the high-level layer.

  9. Understand PyVISA Resource classes

    main

    In PyVISA, Resources are high-level abstractions used to manage specific instrument sessions. When you call pyvisa.highlevel.ResourceManager.open_resource(), the method returns an instance of a specific resource class based on the resource type (e.g., Serial, TCPIP, USB) specified in the resource string.

    Resources are organized into a hierarchy of generic and specific classes:

  10. How PyVISA interacts with VISA implementations

    main

    PyVISA provides a unified interface for instrument control by leveraging the Virtual Instrument Software Architecture (VISA) standard. It can operate in two primary modes:

    1. VISA Shared Library Wrapper: PyVISA calls functions from existing vendor-provided VISA shared libraries (.dll on Windows, .so on Linux, or .dylib on macOS). This allows you to use professional implementations from vendors like National Instruments, Agilent, Tektronix, or Stanford Research Systems.
    2. Pure Python Implementation: PyVISA can serve as a front-end for PyVISA-Py, which implements the VISA standard directly in Python, allowing direct access to bus systems without requiring vendor-specific shared libraries.

  11. Configure a VISA backend for PyVISA

    main

    PyVISA requires a backend to communicate with hardware. You have two primary options:

    1. Vendor VISA Libraries (e.g., NI-VISA, Keysight IO Library Suite): These are professional driver libraries. PyVISA wraps them to provide the Python interface. You must download and install the library from the vendor (e.g., National Instruments or Keysight) separately.

      • Critical Requirement: The bitness of your Python installation must match the bitness of the VISA library. For example, a 64-bit Python installation cannot open a 32-bit VISA library.

    2. PyVISA-Py (Pure Python Backend): A pure Python implementation of the VISA standard. This is easier to install as it doesn't require vendor drivers, but it currently implements only a limited subset of the VISA standard and may not support all protocols or bus systems.

    # To install the pure Python backend
$ pip install -U pyvisa-py

  12. Install NI-VISA on Linux

    main

    To use NI-VISA on Linux, download and install the NI-VISA for Linux package.

    Supported distributions:

    • openSUSE 12.2
    • openSUSE 12.1
    • Red Hat Enterprise Linux Desktop + Workstation 6
    • Red Hat Enterprise Linux Desktop + Workstation 5
    • Scientific Linux 6.x
    • Scientific Linux 5.x

    For Arch Linux and related distributions, the AUR package ni-visa is known to work for USB and TCPIP interfaces. You must restart your system after installation for the changes to take effect.