diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/constants.rst | 4 | ||||
| -rw-r--r-- | docs/architecture.rst | 81 | ||||
| -rw-r--r-- | docs/backends.rst | 71 | ||||
| -rw-r--r-- | docs/conf.py | 2 | ||||
| -rw-r--r-- | docs/configuring.rst | 32 | ||||
| -rw-r--r-- | docs/faq.rst | 31 | ||||
| -rw-r--r-- | docs/getting.rst | 56 | ||||
| -rw-r--r-- | docs/getting_nivisa.rst | 44 | ||||
| -rw-r--r-- | docs/index.rst | 11 | ||||
| -rw-r--r-- | docs/rvalues.rst | 11 | ||||
| -rw-r--r-- | docs/tutorial.rst | 39 |
11 files changed, 238 insertions, 144 deletions
diff --git a/docs/api/constants.rst b/docs/api/constants.rst index a3f14cb..398ad1c 100644 --- a/docs/api/constants.rst +++ b/docs/api/constants.rst @@ -1,10 +1,10 @@ .. _api_constants: -.. py:module:: pyvisa.constants - Constants module ---------------- +.. py:module:: pyvisa.constants + Provides user-friendly naming to values used in different functions. diff --git a/docs/architecture.rst b/docs/architecture.rst index 3402a05..fafe3be 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -13,14 +13,18 @@ PyVISA implements convenient and Pythonic programming in three layers: You will normally not need to access these functions directly. If you do, it probably means that we need to improve layer 2. - All level 1 functions are **static methods** of :class:`pyvisa.highlevel.VisaLibrary`. + All level 1 functions are **static methods** of + :class:`pyvisa.highlevel.VisaLibrary`. - .. warning:: Notice however that low-level functions might not be present in all backends. - For broader compatibility, do no use this layer. All the functionality should - is available via the next layer. + .. warning:: + + Notice however that low-level functions might not be present in all + backends. For broader compatibility, do no use this layer. All the + functionality should is available via the next layer. - 2. Middle-level: A wrapping Python function for each function of the shared visa library. + 2. Middle-level: A wrapping Python function for each function of the shared + visa library. These functions call the low-level functions, adding some code to deal with type conversions for functions that return values by reference. @@ -30,27 +34,35 @@ PyVISA implements convenient and Pythonic programming in three layers: aspects of the VISA library which are not implemented by the corresponding resource class. - All level 2 functions are **bound methods** of :class:`pyvisa.highlevel.VisaLibrary`. + All level 2 functions are **bound methods** of + :class:`pyvisa.highlevel.VisaLibrary`. - 3. High-level: An object-oriented layer for :class:`pyvisa.highlevel.ResourceManager` and :class:`pyvisa.resources.Resource` + 3. High-level: An object-oriented layer for + :class:`pyvisa.highlevel.ResourceManager` and + :class:`pyvisa.resources.Resource` - The ``ResourceManager`` implements methods to inspect connected resources. You also - use this object to open other resources instantiating the appropriate ``Resource`` - derived classes. + The ``ResourceManager`` implements methods to inspect connected resources. + You also use this object to open other resources instantiating the + appropriate ``Resource`` derived classes. - ``Resource`` and the derived classes implement functions and attributes access - to the underlying resources in a Pythonic way. + ``Resource`` and the derived classes implement functions and attributes + access to the underlying resources in a Pythonic way. -Most of the time you will only need to instantiate a ``ResourceManager``. For a given resource, -you will use the :meth:`pyvisa.highlevel.ResourceManager.open_resource` method to obtain the appropriate object. If needed, you will -be able to access the ``VisaLibrary`` object directly using the :attr:`pyvisa.highlevel.ResourceManager.visalib` attribute. +Most of the time you will only need to instantiate a ``ResourceManager``. For a +given resource, you will use the +:meth:`pyvisa.highlevel.ResourceManager.open_resource` method to obtain the +appropriate object. If needed, you will be able to access the ``VisaLibrary`` +object directly using the :attr:`pyvisa.highlevel.ResourceManager.visalib` +attribute. -The ``VisaLibrary`` does the low-level calls. In the default NI Backend, levels 1 and 2 are -implemented in the same package called :mod:`pyvisa.ctwrapper` (which stands for ctypes wrapper). -This package is included in PyVISA. +The ``VisaLibrary`` does the low-level calls. In the default NI Backend, +levels 1 and 2 are implemented in the same package called +:mod:`pyvisa.ctwrapper` (which stands for ctypes wrapper). This package is +included in PyVISA. -Other backends can be used just by passing the name of the backend to ``ResourceManager`` -after the `@` symbol. See more information in :ref:`backends`. +Other backends can be used just by passing the name of the backend to +``ResourceManager`` after the `@` symbol. See more information in +:ref:`backends`. Calling middle- and low-level functions @@ -61,17 +73,19 @@ After you have instantiated the ``ResourceManager``:: >>> import visa >>> rm = visa.ResourceManager() -you can access the corresponding ``VisaLibrary`` instance under the ``visalib`` attribute. +you can access the corresponding ``VisaLibrary`` instance under the ``visalib`` +attribute. -As an example, consider the VISA function ``viMapAddress``. It appears in the low-level -layer as the static method ``viMapAddress`` of ``visalib`` attributed and also appears -in the middle-level layer as ``map_address``. +As an example, consider the VISA function ``viMapAddress``. It appears in the +low-level layer as the static method ``viMapAddress`` of ``visalib`` attributed +and also appears in the middle-level layer as ``map_address``. -You can recognize low and middle-level functions by their names. Low-level functions -carry the same name as in the shared library, and they are prefixed by **vi**. -Middle-level functions have a friendlier, more pythonic but still recognizable name. -Typically, camelCase names where stripped from the leading **vi** and changed to underscore -separated lower case names. The docs about these methods is located here :ref:`api`. +You can recognize low and middle-level functions by their names. Low-level +functions carry the same name as in the shared library, and they are prefixed +by **vi**. Middle-level functions have a friendlier, more pythonic but still +recognizable name. Typically, camelCase names where stripped from the leading +**vi** and changed to underscore separated lower case names. The docs about +these methods is located here :ref:`api`. Low-level @@ -83,11 +97,12 @@ for example:: >>> rm.visalib.viMapAddress(<here goes the arguments>) To call this functions you need to know the function declaration and how to -interface it to python. To help you out, the ``VisaLibrary`` object also contains -middle-level functions. +interface it to python. To help you out, the ``VisaLibrary`` object also +contains middle-level functions. -It is very likely that you will need to access the VISA constants using these methods. -You can find the information about these constants here :ref:`api_constants` +It is very likely that you will need to access the VISA constants using these +methods. You can find the information about these constants here +:ref:`api_constants` Middle-level diff --git a/docs/backends.rst b/docs/backends.rst index 53a7601..43b1b23 100644 --- a/docs/backends.rst +++ b/docs/backends.rst @@ -5,19 +5,20 @@ A frontend for multiple backends ================================ A small historical note might help to make this section clearer. So bear with -with me for a couple of lines. Originally PyVISA was a Python wrapper to the VISA -library. More specifically, it was :py:mod:`ctypes` wrapper around the NI-VISA. -This approach worked fine but made it difficult to develop other ways to communicate -with instruments in platforms where NI-VISA was not available. Users had to change -their programs to use other packages with different API. +with me for a couple of lines. Originally PyVISA was a Python wrapper to the +VISA library. More specifically, it was :py:mod:`ctypes` wrapper around the +NI-VISA. This approach worked fine but made it difficult to develop other ways +to communicate with instruments in platforms where NI-VISA was not available. +Users had to change their programs to use other packages with different API. -Since 1.6, PyVISA is a frontend to VISA. It provides a nice, Pythonic API and can -connect to multiple backends. Each backend exposes a class derived from VisaLibraryBase -that implements the low-level communication. The ctypes wrapper around NI-VISA is the -default backend (called **ni**) and is bundled with PyVISA for simplicity. +Since 1.6, PyVISA is a frontend to VISA. It provides a nice, Pythonic API and +can connect to multiple backends. Each backend exposes a class derived from +VisaLibraryBase that implements the low-level communication. The ctypes wrapper +around NI-VISA is the default backend (called **ni**) and is bundled with +PyVISA for simplicity. -You can specify the backend to use when you instantiate the resource manager using the -``@`` symbol. Remembering that **ni** is the default, this:: +You can specify the backend to use when you instantiate the resource manager +using the ``@`` symbol. Remembering that **ni** is the default, this:: >>> import visa >>> rm = visa.ResourceManager() @@ -32,20 +33,21 @@ You can still provide the path to the library if needed:: >>> import visa >>> rm = visa.ResourceManager('/path/to/lib@ni') -Under the hood, the :class:`pyvisa.highlevel.ResourceManager` looks for the requested backend and instantiate -the VISA library that it provides. +Under the hood, the :class:`pyvisa.highlevel.ResourceManager` looks for the +requested backend and instantiate the VISA library that it provides. PyVISA locates backends by name. If you do: >>> import visa >>> rm = visa.ResourceManager('@somename') -PyVISA will try to import a package/module named ``pyvisa-somename`` which should be -installed in your system. This is a loosly coupled configuration free method. -PyVISA does not need to know about any backend out there until you actually -try to use it. +PyVISA will try to import a package/module named ``pyvisa-somename`` which +should be installed in your system. This is a loosly coupled configuration free +method. PyVISA does not need to know about any backend out there until you +actually try to use it. -You can list the installed backends by running the following code in the command line:: +You can list the installed backends by running the following code in the +command line:: python -m visa info @@ -62,8 +64,9 @@ What does a minimum backend looks like? Quite simple:: WRAPPER_CLASS = MyLibrary -Additionally you can provide a staticmethod named get_debug_info` that should return a -dictionary of debug information which is printed when you call ``python -m visa info`` +Additionally you can provide a staticmethod named get_debug_info` that should +return a dictionary of debug information which is printed when you call +``python -m visa info`` or ``pyvisa-info`` .. note:: @@ -72,24 +75,27 @@ dictionary of debug information which is printed when you call ``python -m visa pyvisa will be named ``pyvisa-*-script`` and they are obviously not backends. Examples are the ``pyvisa-shell`` and ``pyvisa-info`` scripts. -An important aspect of developing a backend is knowing which VisaLibraryBase method to -implement and what API to expose. +An important aspect of developing a backend is knowing which VisaLibraryBase +method to implement and what API to expose. -A **complete** implementation of a VISA Library requires a lot of functions (basically almost -all level 2 functions as described in :ref:`architecture` (there is also a complete list at the -bottom of this page). But a working implementation does not require all of them. +A **complete** implementation of a VISA Library requires a lot of functions +(basically almost all level 2 functions as described in :ref:`architecture` +(there is also a complete list at the bottom of this page). But a working +implementation does not require all of them. As a **very minimum** set you need: - - **open_default_resource_manager**: returns a session to the Default Resource Manager resource. + - **open_default_resource_manager**: returns a session to the Default + Resource Manager resource. - **open**: Opens a session to the specified resource. - **close**: Closes the specified session, event, or find list. - - **list_resources**: Returns a tuple of all connected devices matching query. + - **list_resources**: Returns a tuple of all connected devices matching + query. (you can get the signature below or here :ref:`api_visalibrarybase`) -But of course you cannot do anything interesting with just this. In general you will -also need: +But of course you cannot do anything interesting with just this. In general you +will also need: - **get_attribute**: Retrieves the state of an attribute. - **set_atribute**: Sets the state of an attribute. @@ -99,10 +105,11 @@ If you need to start sending bytes to MessageBased instruments you will require: - **read**: Reads data from device or interface synchronously. - **write**: Writes data to device or interface synchronously. -For other usages or devices, you might need to implement other functions. Is really up to you -and your needs. +For other usages or devices, you might need to implement other functions. Is +really up to you and your needs. -These functions should raise a :class:`pyvisa.errors.VisaIOError` or emit a :class:`pyvisa.errors.VisaIOWarning` if necessary. +These functions should raise a :class:`pyvisa.errors.VisaIOError` or emit a +:class:`pyvisa.errors.VisaIOWarning` if necessary. Complete list of level 2 functions to implement:: diff --git a/docs/conf.py b/docs/conf.py index dd66e73..096e536 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -294,4 +294,4 @@ epub_copyright = copyright # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'python': ('http://docs.python.org/2', None)}
+intersphinx_mapping = {'python': ('http://docs.python.org/3', None)}
diff --git a/docs/configuring.rst b/docs/configuring.rst index 867722e..02bce68 100644 --- a/docs/configuring.rst +++ b/docs/configuring.rst @@ -2,27 +2,31 @@ Configuring the backend ============================ -Currently there are two backends available: The one included in pyvisa which -uses the NI library. This is used by default and the configuration is described -in the next chapter. -And then there is pyvia-py a pure python implementation of the VISA libary. -It can be selected by passing a parameter to the ResourceManager: + +Currently there are two backends available: The one included in pyvisa, which +uses the NI library, and the backend provided by pyvisa-py, which is a pure python implementation of the VISA library. +If no backend is specified, pyvisa uses the NI backend if the NI library has been installed (see next section for details). Failing that, it uses the pyvisa-py backend. + +You can also select a desired backend by passing a parameter to the ResourceManager, shown here for pyvisa-py: >>> visa.ResourceManager('@py') -Alternativly it can also be selected by setting the environment variable +Alternatively it can also be selected by setting the environment variable PYVISA_LIBRARY. It takes the same values as the ResourceManager constructor. Configuring the NI backend ========================== -.. note:: The NI backend requires that you install first the NI-VISA library. You can get - info here: (:ref:`getting_nivisa`) +.. note:: + + The NI backend requires that you install first the NI-VISA library. You can + get info here: (:ref:`getting_nivisa`) -In most cases PyVISA will be able to find the location of the shared visa library. -If this does not work or you want to use another one, you need to provide the library -path to the :class:`pyvisa.highlevel.ResourceManager` constructor:: +In most cases PyVISA will be able to find the location of the shared visa +library. If this does not work or you want to use another one, you need to +provide the library path to the :class:`pyvisa.highlevel.ResourceManager` +constructor:: >>> rm = ResourceManager('Path to library') @@ -65,9 +69,9 @@ You can define a site-wide configuration file at Under Windows, this file is usually placed at :file:`c:\\Python27\\share\\pyvisa\\.pyvisarc`. -If you encounter any problem, take a look at the :ref:`faq`. There you will find the -solutions to common problem as well as useful debugging techniques. If everything fails, -feel free to open an issue in our `issue tracker`_ +If you encounter any problem, take a look at the :ref:`faq`. There you will +find the solutions to common problem as well as useful debugging techniques. If +everything fails, feel free to open an issue in our `issue tracker`_ .. _`home directory`: http://en.wikipedia.org/wiki/Home_directory .. _`issue tracker`: https://github.com/pyvisa/pyvisa/issues diff --git a/docs/faq.rst b/docs/faq.rst index 24df6df..b23146a 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -59,9 +59,9 @@ Check that the path provided to the constructor or in the configuration file Error: Could not found VISA library ----------------------------------- -This error occurs when you have not provided a path for the VISA library and PyVISA -is not able to find it for you. You can solve it by providing the library path to the -``VisaLibrary`` or ``ResourceManager`` constructor:: +This error occurs when you have not provided a path for the VISA library and +PyVISA is not able to find it for you. You can solve it by providing the +library path to the ``VisaLibrary`` or ``ResourceManager`` constructor:: >>> visalib = VisaLibrary('/path/to/library') @@ -94,31 +94,34 @@ architecture. Error while accessing /usr/local/vxipnp/linux/bin/libvisa.so.7:/usr/local/vxipnp/linux/bin/libvisa.so.7: wrong ELF class: ELFCLASS32 -First, determine the details of your installation with the help of the following debug command:: +First, determine the details of your installation with the help of the +following debug command:: python -m visa info -You will see the 'bitness' of the Python interpreter and at the end you will see the list of VISA -libraries that PyVISA was able to find. +You will see the 'bitness' of the Python interpreter and at the end you will +see the list of VISA libraries that PyVISA was able to find. The solution is to: 1. Install and use a VISA library matching your Python 'bitness' - Download and install it from **National Instruments's VISA**. Run the debug - command again to see if the new library was found by PyVISA. If not, + Download and install it from **National Instruments's VISA**. Run the + debug command again to see if the new library was found by PyVISA. If not, create a configuration file as described in :ref:`configuring`. - If there is no VISA library with the correct bitness available, try solution 2. + If there is no VISA library with the correct bitness available, try + solution 2. or 2. Install and use a Python matching your VISA library 'bitness' - In Windows and Linux: Download and install Python with the matching bitness. - Run your script again using the new Python + In Windows and Linux: Download and install Python with the matching + bitness. Run your script again using the new Python - In Mac OS X, Python is usually delivered as universal binary (32 and 64 bits). + In Mac OS X, Python is usually delivered as universal binary (32 and + 64 bits). You can run it in 32 bit by running:: @@ -132,8 +135,8 @@ or alias python32="arch -i386 python" - into your .bashrc or .profile or ~/.bash_profile (or whatever file depending - on which shell you are using.) + into your .bashrc or .profile or ~/.bash_profile (or whatever file + depending on which shell you are using.) You can also create a `virtual environment`_ for this. diff --git a/docs/getting.rst b/docs/getting.rst index fda7fb7..e89baf1 100644 --- a/docs/getting.rst +++ b/docs/getting.rst @@ -10,46 +10,67 @@ You can install it using pip_:: $ pip install -U pyvisa -NI Backend ----------- - -In order for PyVISA to work, you need to have a suitable backend. PyVISA includes -a backend that wraps the `National Instruments's VISA`_ library. However, you need to download -and install the library yourself (See :ref:`getting_nivisa`). There are multiple -VISA implementations from different vendors. PyVISA is tested only against +Backend +------- + +In order for PyVISA to work, you need to have a suitable backend. PyVISA +includes a backend that wraps the `National Instruments's VISA`_ library. +However, you need to download and install the library yourself +(See :ref:`getting_nivisa`). There are multiple VISA implementations from +different vendors. PyVISA is tested only against `National Instruments's VISA`_. -.. warning:: PyVISA works with 32- and 64- bit Python and can deal with 32- and 64-bit VISA libraries without any extra configuration. What PyVISA cannot do is open a 32-bit VISA library while running in 64-bit Python (or the other way around). +.. warning:: + + PyVISA works with 32- and 64- bit Python and can deal with 32- and 64-bit + VISA libraries without any extra configuration. What PyVISA cannot do is + open a 32-bit VISA library while running in 64-bit Python (or the other + way around). + +**You need to make sure that the Python and VISA library have the same bitness** - **You need to make sure that the Python and VISA library have the same bitness** +Alternatively, you can install `PyVISA-Py`_ which is a pure Python +implementation of the VISA standard. You can install it using pip_:: + + $ pip install -U pyvisa-py + +.. note:: + + At the moment, `PyVISA-Py` implements only a limited subset of the VISA + standard and does not support all protocols on all bus systems. Please + refer to its documentation for more details. Testing your installation ------------------------- -That's all! You can check that PyVISA is correctly installed by starting up python, and creating a ResourceManager: +That's all! You can check that PyVISA is correctly installed by starting up +python, and creating a ResourceManager: >>> import visa >>> rm = visa.ResourceManager() >>> print(rm.list_resources()) -If you encounter any problem, take a look at the :ref:`faq`. There you will find the -solutions to common problem as well as useful debugging techniques. If everything fails, -feel free to open an issue in our `issue tracker`_ +If you encounter any problem, take a look at the :ref:`faq`. There you will +find the solutions to common problem as well as useful debugging techniques. +If everything fails, feel free to open an issue in our `issue tracker`_ Using the development version ----------------------------- -You can install the latest development version (at your own risk) directly form GitHub_:: +You can install the latest development version (at your own risk) directly +form GitHub_:: $ pip install -U https://github.com/pyvisa/pyvisa/zipball/master -.. note:: If you have an old system installation of Python and you don't want to - mess with it, you can try `Anaconda CE`_. It is a free Python distribution by - Continuum Analytics that includes many scientific packages. +.. note:: + + If you have an old system installation of Python and you don't want to + mess with it, you can try `Anaconda CE`_. It is a free Python distribution + by Continuum Analytics that includes many scientific packages. .. _easy_install: http://pypi.python.org/pypi/setuptools @@ -60,3 +81,4 @@ You can install the latest development version (at your own risk) directly form .. _GitHub: https://github.com/pyvisa/pyvisa .. _`National Instruments's VISA`: http://ni.com/visa/ .. _`issue tracker`: https://github.com/pyvisa/pyvisa/issues +.. _`PyVISA-Py`: http://pyvisa-py.readthedocs.io/en/latest/ diff --git a/docs/getting_nivisa.rst b/docs/getting_nivisa.rst index 393f2eb..1661878 100644 --- a/docs/getting_nivisa.rst +++ b/docs/getting_nivisa.rst @@ -3,15 +3,25 @@ NI-VISA Installation ==================== -In every OS, the NI-VISA library bitness (i.e. 32- or 64-bit) has to match the Python bitness. So first you need to install a NI-VISA that works with your OS and then choose the Python version matching the installed NI-VISA bitness. +In every OS, the NI-VISA library bitness (i.e. 32- or 64-bit) has to match the +Python bitness. So first you need to install a NI-VISA that works with your OS +and then choose the Python version matching the installed NI-VISA bitness. -PyVISA includes a debugging command to help you troubleshoot this (and other things):: +PyVISA includes a debugging command to help you troubleshoot this +(and other things):: python -m visa info + +or equivalently:: -According to National Instruments, NI VISA **5.4.1** is available for: + pyvisa-info -.. note:: If NI-VISA is not available for your system, take a look at the :ref:`faq`. +According to National Instruments, NI VISA **17.5** is available for the +following platforms. + +.. note:: + + If NI-VISA is not available for your system, take a look at the :ref:`faq`. Mac OS X @@ -24,7 +34,9 @@ Supports: - Mac OS X 10.7.x x86 and x86-64 - Mac OS X 10.8.x -*64-bit VISA applications are supported for a limited set of instrumentation buses. The supported buses are ENET-Serial, USB, and TCPIP. Logging VISA operations in NI I/O Trace from 64-bit VISA applications is not supported.* +*64-bit VISA applications are supported for a limited set of instrumentation +buses. The supported buses are ENET-Serial, USB, and TCPIP. Logging VISA +operations in NI I/O Trace from 64-bit VISA applications is not supported.* Windows ------- @@ -43,7 +55,8 @@ Suports: - Windows Vista (32-bit version) - Windows XP Service Pack 3 -*Support for Windows Server 2003 R2 may require disabling physical address extensions (PAE).* +*Support for Windows Server 2003 R2 may require disabling physical address +extensions (PAE).* Linux ----- @@ -59,10 +72,19 @@ Supports: - Scientific Linux 6.x - Scientific Linux 5.x -*Currently, only 32-bit applications are supported on the x86-64 architecture.* +More details details can be found in the `README`_ of the installer. + +.. note:: -.. note:: NI-VISA runs on other linux distros but the installation is more cumbersome. + NI-VISA runs on other linux distros but the installation is more + cumbersome. On Arch linux and related distributions, the AUR package + `ni-visa`_ (early development) is known to work for the USB and TCPIP + interfaces. Please note that you should restart after the installation for + things to work properly. -.. _`NI-VISA for Mac OS X`: http://www.ni.com/download/ni-visa-14.0.2/5075/en/ -.. _`NI-VISA for Windows`: http://www.ni.com/download/ni-visa-5.4.1/4626/en/ -.. _`NI-VISA for Linux`: http://www.ni.com/download/ni-visa-5.4.1/4629/en/ + +.. _`README`: http://download.ni.com/support/softlib//visa/NI-VISA/17.0/Linux/README.txt +.. _`ni-visa`: https://aur.archlinux.org/packages/ni-visa/ +.. _`NI-VISA for Mac OS X`: http://www.ni.com/download/ni-visa-17.5/7224/en/ +.. _`NI-VISA for Windows`: http://www.ni.com/download/ni-visa-17.5/7220/en/ +.. _`NI-VISA for Linux`: http://www.ni.com/download/ni-visa-17.0/6700/en/ diff --git a/docs/index.rst b/docs/index.rst index 874589a..a0dfb8c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -47,9 +47,14 @@ work together with arbitrary peripherical devices, although they may be limited to certain interface devices, such as the vendor's GPIB card. The VISA specification has explicit bindings to Visual Basic, C, and G -(LabVIEW's graphical language). However, you can use VISA with any language -capable of calling functions in a shared library (`.dll`, `.so`, `.dylib`). -PyVISA is Python wrapper for such shared library ... and more. +(LabVIEW’s graphical language). Python can be used to call functions from a +VISA shared library (`.dll`, `.so`, `.dylib`) allowing to directly leverage the +standard implementations. In addition, Python can be used to directly access +most bus systems used by instruments which is why one can envision to implement +the VISA standard directly in Python (see the `PyVISA-Py` project for more +details). PyVISA is both a Python wrapper for VISA shared libraries but +can also serve as a front-end for other VISA implementation such as +`PyVISA-Py`. User guide diff --git a/docs/rvalues.rst b/docs/rvalues.rst index aecb6a6..a8b909e 100644 --- a/docs/rvalues.rst +++ b/docs/rvalues.rst @@ -82,6 +82,17 @@ the IEEE convention. If your instrument uses HP data block you can pass ``header_fmt='hp'`` to ``read_binary_values``. If your instrument does not use any header for the data simply ``header_fmt='empty'``. +By default PyVISA assumes, that the instrument will add the termination +character at the end of the data block and actually makes sure it reads it to +avoid issues. This behavior fits well a number of devices. However some devices +omit the termination character, in which cases the operation will timeout. +In this situation, first makes sure you can actually read from the instrument +by reading the answer using the ``read_raw`` function (you may need to call it +multiple time), and check that the advertized length of the block match what +you get from your instrument (plus the header). If it is so, then you can +safely pass ``expect_termination=False``, and PyVISA will not look for a +termination character at the end of the message. + Writing ASCII values -------------------- diff --git a/docs/tutorial.rst b/docs/tutorial.rst index d099d57..b44cc6a 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -22,24 +22,30 @@ Let's go *in medias res* and have a look at a simple example:: This example already shows the two main design goals of PyVISA: preferring simplicity over generality, and doing it the object-oriented way. -After importing ``visa``, we create a ``ResourceManager`` object. If called without -arguments, PyVISA will use the default backend (NI) which tries to find the -VISA shared library for you. You can check, the location of the shared library -used simply by: +After importing ``visa``, we create a ``ResourceManager`` object. If called +without arguments, PyVISA will use the default backend (NI) which tries to find +the VISA shared library for you. You can check, the location of the shared +library used simply by: >>> print(rm) <ResourceManager('/path/to/visa.so')> -.. note:: In some cases, PyVISA is not able to find the library for you - resulting in an ``OSError``. To fix it, find the library path - yourself and pass it to the ResourceManager constructor. - You can also specify it in a configuration file as discussed - in :ref:`configuring`. +.. note:: + + In some cases, PyVISA is not able to find the library for you resulting in + an ``OSError``. To fix it, find the library path yourself and pass it to + the ResourceManager constructor. You can also specify it in a configuration + file as discussed in :ref:`configuring`. Once that you have a ``ResourceManager``, you can list the available resources using the ``list_resources`` method. The output is a tuple listing the -:ref:`resource_names`. +:ref:`resource_names`. You can use a dedicated regular expression syntax to +filter the instruments discovered by this method. The syntax is described in +details in :py:meth:`~pyvisa.highlevel.ResourceManager.list_resources`. The +default value is '?*::INSTR' which means that by default only instrument +whose resource name ends with '::INSTR' (in particular USB RAW resources and +TCPIP SOCKET resources are not listed). In this case, there is a GPIB instrument with instrument number 14, so you ask the ``ResourceManager`` to open "'GPIB0::14::INSTR'" and assign the returned @@ -51,14 +57,15 @@ Notice ``open_resource`` has given you an instance of ``GPIBInstrument`` class >>> print(my_instrument) <GPIBInstrument('GPIB::14')> -There many ``Resource`` subclasses representing the different types of resources, but -you do not have to worry as the ``ResourceManager`` will provide you with the appropiate -class. You can check the methods and attributes of each class in the :ref:`api_resources` +There many ``Resource`` subclasses representing the different types of +resources, but you do not have to worry as the ``ResourceManager`` will provide +you with the appropriate class. You can check the methods and attributes of +each class in the :ref:`api_resources` Then, you query the device with the following message: ``'\*IDN?'``. Which is the standard GPIB message for "what are you?" or -- in some cases -- -"what's on your display at the moment?". ``query`` is a short form for a ``write`` -operation to send a message, followed by a ``read``. +"what's on your display at the moment?". ``query`` is a short form for a +``write`` operation to send a message, followed by a ``read``. So:: @@ -87,5 +94,3 @@ one ``query()`` call. Thus, the above source code is equivalent to:: print(itc4.query("V")) It couldn't be simpler. - - |