.. -*- mode: rst; coding: utf-8; ispell-local-dictionary: "british"; -*-
..
.. vpp43.txt - VISA VPP-4.3.2 functions documentation
..
.. Copyright © 2005, 2006, 2007, 2008
.. Torsten Bronger <bronger@physik.rwth-aachen.de>,
.. Gregor Thalhammer <gth@users.sourceforge.net>.
..
.. This file is part of PyVISA.
..
.. PyVISA is free software; you can redistribute it and/or modify it under
.. the terms of the MIT licence:
..
.. Permission is hereby granted, free of charge, to any person obtaining a
.. copy of this software and associated documentation files (the "Software"),
.. to deal in the Software without restriction, including without limitation
.. the rights to use, copy, modify, merge, publish, distribute, sublicense,
.. and/or sell copies of the Software, and to permit persons to whom the
.. Software is furnished to do so, subject to the following conditions:
..
.. The above copyright notice and this permission notice shall be included in
.. all copies or substantial portions of the Software.
..
.. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
.. IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
.. FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
.. THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
.. LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
.. FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
.. DEALINGS IN THE SOFTWARE.
..
======================================
The VISA library implementation
======================================
---------------------------------
Part of the PyVISA package
---------------------------------
:Date: |today|
:Author: Torsten Bronger
:Maintainer: Florian Bauer <pyvisa-devel@lists.sourceforge.net>
:Downloads: See the `PyVISA project page`_.
:Abstract: This document covers the ``vpp43.py`` module, which is part of the
PyVISA_ package. This module implements thin wrappers around all functions
defined in the `VISA specification`_. Thus it enables the programmer to
communicate with measurement and test devices via GPIB, RS232, USB etc.
.. _PyVISA: http://pyvisa.sourceforge.net/
.. _`PyVISA project page`: _PyVISA
.. _`VISA specification`: http://www.ivifoundation.org/Downloads/Class%20Specifications/vpp43.doc
.. contents::
About the vpp43 module
======================
This module ``vpp43`` is a cautious yet thorough adaption of the VISA
specification for Python. The "textual languages" VISA specification can't be
implemented as is because Python is rather different from C and Visual Basic,
most notably because of lacking call-by-reference. The second important
difference are strings: In C they are null-terminated whereas Python doesn't
have this constraint.
The slightly odd name ``vpp43`` for this module derives from the necessity to
make (name)space for the ``visa`` module that is supposed to realise the actual
high-level VISA access in Python. The `VXIplug&play Systems Alliance`_ used to
maintain the VISA specifications, and, although today the `IVI foundation`_ is
responsible for this task, the files are still called ``vpp43.doc`` etc. So I
thought ``vpp43`` was an appropriate name.
.. _`VXIplug&play Systems Alliance`: http://www.vxipnp.org/
.. _`IVI foundation`: http://ivifoundation.org
You may wonder why I did choose new names for all routines. I did so because
Python has its own naming guidelines, and because it shows that the routines
had to be adapted. However, I didn't change them really: Every routine is a
1:1 counterpart. By calling them from C, you could even create a C-based VISA
implementation with the original function signatures and semantics. Moreover,
the new names are mere expansions of the original ones.
Connecting to the VISA shared object
====================================
``vpp43`` tries to find the VISA library for itself. On Windows, this is not a
big problem. ``visa32.dll`` must be in your ``PATH``. If it isn't, move it
there or expand your ``PATH``.
However, on Linux you may need to give the explicit path to the shared object
file. You do so by saying for example::
import pyvisa.vpp43 as vpp43
vpp43.visa_library.load_library("/path/to/my/libvisa.so.7")
By default, ``vpp43`` looks for the library in
``/usr/local/vxipnp/linux/bin/libvisa.so.7``. Please pay attention to the fact
that the library must have been successfully loaded *before* any VISA call is
made.
Alternatively, you can tell PyVISA so by creating a file ``~/.pyvisarc``. This
has the format of an INI file. For example, if the library is at
``/usr/lib/libvisa.so.7``, the file ``.pyvisarc`` must contain the following::
[Paths]
VISA library: /usr/lib/libvisa.so.7
Please note that ``[Paths]`` is treated case-sensitively.
You can define a site-wide configuration file at
``/usr/share/pyvisa/.pyvisarc``. (It may also be ``/usr/local/...`` depending
on the location of your Python.)
Diagnostics
===========
This module can raise a couple of ``vpp43``-specific exceptions.
:Name: VisaIOError
:Description: This is an error of the underlying VISA library, as described in
table 3.3.1 in the `VISA specification for textual languages`_. The
exception member ``error_code`` contains the (always negative) VISA error
number, as listed in that table.
:Name: VisaIOWarning
:Description: This is a warning of the underlying VISA library, as described in
table 3.3.1 in the `VISA specification for textual languages`_. The
exception member ``completion_code`` contains the (always positive) VISA
completion number, as listed in that table.
Normally you don't see these warnings. You can turn them into exceptions
with::
import warnings
warnings.filterwarnings("error")
Consult the description of the ``warnings`` package for further
information.
.. _`VISA specification for textual languages`:
http://www.ivifoundation.org/Downloads/Class%20Specifications/vpp432.doc
:Name: TypeError
:Description: The current implementation of `printf`_, `scanf`_, `sprintf`_,
`sscanf`_, and `queryf`_ have the limitation that only integers, floats,
and strings are allowed as types for the arbitrary arguments.
Additionally, only format string directives for C longs, C doubles, and C
strings are allowed to use, albeit not checked. However, if you pass a
list or a unicode string, you get this exception.
The same exception is raised if an unsupported type is passed as user
handle to `install_handler`_. See there for a list of supported types.
:Name: UnknownHandler
:Description: Raised if an unknown `handler`/`user_handle` pair is passed to
`uninstall_handler`_. In particular, you must save the user handle
returned by `install_handler`_ in order to pass it to uninstall_handler.
Moreover, this module may pass exceptions generated by ctypes. This may be
because you've passed a wrong type to a function, or that the VISA library file
was not found, but it may also mean a bug in ``vpp43`` itself. So if you don't
see why the exception was raised, contact the current maintainers of PyVISA.
The PyVISA function reference
=============================
Please note that all descriptions given in this reference serve mostly as
reminders. For real descriptions consult a `VISA specification`_ or `NI-VISA
Programmer Reference Manual`_. However, whenever there are PyVISA-specific
semantics, they are listed here, too.
.. _`VISA specification`:
http://www.ivifoundation.org/Downloads/Class%20Specifications/vpp43.doc
.. _`NI-VISA Programmer Reference Manual`:
http://digital.ni.com/manuals.nsf/websearch/87E52268CF9ACCEE86256D0F006E860D
assert_interrupt_signal
.......................
Asserts the specified device interrupt or signal.
:Call: assert_interrupt_signal(vi, mode, status_id)
:VISA name: viAssertIntrSignal
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`mode` : integer
This specifies how to assert the interrupt.
`status_id` : integer
This is the status value to be presented during an interrupt
acknowledge cycle.
:Return values:
None.
assert_trigger
..............
Assert software or hardware trigger.
:Call: assert_trigger(vi, protocol)
:VISA name: viAssertTrigger
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`protocol` : integer
Trigger protocol to use during assertion. Valid values are:
``VI_TRIG_PROT_DEFAULT``, ``VI_TRIG_PROT_ON``, ``VI_TRIG_PROT_OFF``,
and ``VI_TRIG_PROT_SYNC``.
:Return values:
None.
assert_utility_signal
.....................
Asserts the specified utility bus signal.
:Call: assert_utility_signal(vi, line)
:VISA name: viAssertUtilSignal
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`line` : integer
Specifies the utility bus signal to assert.
:Return values:
None.
buffer_read
...........
Similar to `read`_, except that the operation uses the formatted I/O read
buffer for holding data read from the device.
:Call: buffer = buffer_read(vi, count)
:VISA name: viBufRead
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`count` : integer
Maximal number of bytes to be read.
:Return values:
`buffer` : string
The buffer with the received data from device.
buffer_write
............
Similar to `write`_, except the data is written to the formatted I/O write
buffer rather than directly to the device.
:Call: return_count = buffer_write(vi, buffer)
:VISA name: viBufWrite
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`buffer` : string
The data block to be sent to device.
:Return values:
`return_count` : integer
The number of bytes actually transferred.
clear
.....
Clear a device.
:Call: clear(vi)
:VISA name: viClear
:Parameters:
`vi` : integer
Unique logical identifier to a session.
:Return values:
None.
close
.....
Close the specified session, event, or find list.
:Call: close(vi)
:VISA name: viClose
:Parameters:
`vi` : integer, ViEvent, or ViFindList
Unique logical identifier to a session, event, or find list.
:Return values:
None.
disable_event
.............
Disable notification of an event type by the specified mechanisms.
:Call: disable_event(vi, event_type, mechanism)
:VISA name: viDisableEvent
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`event_type` : integer
Logical event identifier.
`mechanism` : integer
Specifies event handling mechanisms to be disabled. The queuing
mechanism is disabled by specifying ``VI_QUEUE``, and the callback
mechanism is disabled by specifying ``VI_HNDLR`` or
``VI_SUSPEND_HNDLR``. It is possible to disable both mechanisms
simultaneously by specifying ``VI_ALL_MECH``.
:Return values:
None.
discard_events
..............
Discard event occurrences for specified event types and mechanisms in a
session.
:Call: discard_events(vi, event_type, mechanism)
:VISA name: viDiscardEvents
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`event_type` : integer
Logical event identifier.
`mechanism` : integer
Specifies the mechanisms for which the events are to be discarded. The
``VI_QUEUE`` value is specified for the queuing mechanism and the
``VI_SUSPEND_HNDLR`` value is specified for the pending events in the
callback mechanism. It is possible to specify both mechanisms
simultaneously by specifying ``VI_ALL_MECH``.
:Return values:
None.
enable_event
............
Enable notification of a specified event.
:Call: enable_event(vi, event_type, mechanism, context)
:VISA name: viEnableEvent
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`event_type` : integer
Logical event identifier.
`mechanism` : integer
Specifies event handling mechanisms to be enabled. The queuing
mechanism is enabled by specifying ``VI_QUEUE``, and the callback
mechanism is enabled by specifying ``VI_HNDLR`` or
``VI_SUSPEND_HNDLR``. It is possible to enable both mechanisms
simultaneously by specifying bit-wise "or" of ``VI_QUEUE`` and one of
the two mode values for the callback mechanism.
`context` : integer : optional
According to the VISA specification, this must be ``Vi_NULL`` always.
(This is also the default value, of course.)
:Return values:
None.
find_next
.........
:Call: instrument_description = find_next(find_list)
:VISA name: viFindNext
:Parameters:
`find_list` : ViFindList
Describes a find list. This parameter must be created by
`find_resources`_.
:Return values:
`instrument_description` : string
Returns a string identifying the location of a device. Strings can then
be passed to `open`_ to establish a session to the given device.
find_resources
..............
:Call: find_list, return_counter, instrument_description =
find_resources(session, regular_expression)
:VISA name: viFindRsrc
:Parameters:
`session` : integer
Resource Manager session (should always be the Default Resource Manager
for VISA returned from `open_default_resource_manager`_).
`regular_expression` : integer
This is a regular expression followed by an optional logical
expression.
:Return values:
`find_list` : ViFindList
Returns a handle identifying this search session. This handle will be
used as an input in `find_next`_.
`return_counter` : integer
Number of matches.
`instrument_description` : string
Returns a string identifying the location of a device. Strings can then
be passed to `open`_ to establish a session to the given device.
flush
.....
Manually flush the specified buffers associated with formatted I/O operations
and/or serial communication.
:Call: flush(vi, mask)
:VISA name: viFlush
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`mask` : integer
Specifies the action to be taken with flushing the buffer.
:Return values:
None.
get_attribute
.............
Retrieve the state of an attribute.
:Call: attribute_state = get_attribute(vi, attribute)
:VISA name: viGetAttribute
:Parameters:
`vi` : integer, ViEvent, or ViFindList
Unique logical identifier to a session.
`attribute` : integer
Session, event, or find list attribute for which the state query is
made.
:Return values:
`attribute_state` : integer, string, or list of integers
The state of the queried attribute for a specified resource.
gpib_command
............
Write GPIB command bytes on the bus.
:Call: return_count = gpib_command(vi, buffer)
:VISA name: viGpibCommand
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`buffer` : string
Buffer containing valid GPIB commands.
:Return values:
`return_count` : integer
Number of bytes actually transferred.
gpib_control_atn
................
Controls the state of the GPIB ATN interface line, and optionally the active
controller state of the local interface board.
:Call: gpib_control_atn(vi, mode)
:VISA name: viGpibControlATN
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`mode` : integer
Specifies the state of the ATN line and optionally the local active
controller state. See the Description section for actual values.
:Return values:
None.
gpib_control_ren
................
Controls the state of the GPIB REN interface line, and optionally the
remote/local state of the device.
:Call: gpib_control_ren(vi, mode)
:VISA name: viGpibControlREN
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`mode` : integer
Specifies the state of the REN line and optionally the device
remote/local state. See the Description section for actual values.
:Return values:
None.
gpib_pass_control
.................
Tell the GPIB device at the specified address to become controller in charge
(CIC).
:Call: gpib_pass_control(vi, primary_address, secondary_address)
:VISA name: viGpibPassControl
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`primary_address` : integer
Primary address of the GPIB device to which you want to pass control.
`secondary_address` : integer
Secondary address of the targeted GPIB device. If the targeted device
does not have a secondary address, this parameter should contain the
value ``VI_NO_SEC_ADDR``.
:Return values:
None.
gpib_send_ifc
.............
Pulse the interface clear line (IFC) for at least 100 microseconds.
:Call: gpib_send_ifc(vi)
:VISA name: viGpibSendIFC
:Parameters:
`vi` : integer
Unique logical identifier to a session.
:Return values:
None.
in_8, in_16, in_32
..................
Read in an 8-bit, 16-bit, or 32-bit value from the specified memory space and
offset.
:Call: | value_8 = in_8(vi, space, offset)
| value_16 = in_16(vi, space, offset)
| value_32 = in_32(vi, space, offset)
:VISA name: viIn8, viIn16, viIn32
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`space` : integer
Specifies the address space.
`offset` : integer
Offset in bytes of the address or register from which to read.
:Return values:
`value_8`, `value_16`, `value_32` : integer
Data read from bus (8 bits for `in_8`, 16 bits for `in_16`, and 32
bits for `in_32`).
install_handler
...............
Install handlers for event callbacks. A handler must have the following
signature::
def event_handler(vi, event_type, context, user_handle):
...
Its parameters mean the following:
`vi` : integer
Unique logical identifier to a session.
`event_type` : ViEvent
Logical event identifier. With ``event_type.value`` you get its value as
an integer.
`context` : ViEvent
A handle specifying the unique occurrence of an event.
`user_handle` : ctypes pointer type
A *pointer* to the user handle in ctypes form. See below at "Return
values" for how to use it, however, you have to substitute
``user_handle.contents`` for ``converted_user_handle`` in the explanation.
:Call: converted_user_handle = install_handler(vi, event_type, handler,
user_handle)
:VISA name: viInstallHandler
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`event_type` : integer
Logical event identifier.
`handler` : callable
Interpreted as a valid reference to a handler to be installed by a
client application.
`user_handle` : ``None``, float, integer, string, or list of floats or integers : optional
A value specified by an application that can be used for identifying
handlers uniquely for an event type. It defaults to ``None``.
:Return values:
`converted_user_handle` : ctypes type
An object representing the user_handle. Use it to communicate with
your handler. If your user_handle was a list, you get its elements as
usual with ``converted_user_handle[index]``. You can even convert it
to a list with ``list(converted_user_handle)`` (however, this yields a
copy).
For strings, use ``converted_user_handle.value`` if it's supposed to be
interpreted as a null-terminated string, or
``converted_user_handle.raw`` if you want to see *all* bytes. You can
also write to both expressions, however, slicing is only possible for
reading.
For simple types, you can say ``converted_user_handle.value`` (read and
write).
**Attention:** You must assure that you never write values to
converted_user_data which are longer (in bytes) than the initial
values. So be careful not to write a string longer than the original
one, nor a longer list. You'd be alerted by exceptions, though.
lock
....
Establish an access mode to the specified resource.
:Call: access_key = lock(vi, lock_type, timeout, requested_key)
:VISA name: viLock
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`lock_type` : integer
Specifies the type of lock requested, which can be either
``VI_EXCLUSIVE_LOCK`` or ``VI_SHARED_LOCK``.
`timeout` : integer
Absolute time period in milliseconds that a resource waits to get
unlocked by the locking session before returning this operation with an
error.
`requested_key` : ctypes string : optional
This parameter is not used if `lock_type` is ``VI_EXCLUSIVE_LOCK``
(exclusive locks). When trying to lock the resource as
``VI_SHARED_LOCK`` (shared), you can either omit it so that VISA
generates an `access_key` for the session, or you can suggest an
`access_key` to use for the shared lock.
:Return values:
`access_key` : ctypes string : optional
This value is ``None`` if `lock_type` is ``VI_EXCLUSIVE_LOCK``
(exclusive locks). When trying to lock the resource as
``VI_SHARED_LOCK`` (shared), the function returns a unique access key
for the lock if the operation succeeds. This `access_key` can then be
passed to other sessions to share the lock.
map_address
...........
Map the specified memory space into the process's address space.
:Call: address = map_address(vi, map_space, map_base, map_size, access,
suggested)
:VISA name: viMapAddress
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`map_space` : integer
Specifies the address space to map.
`map_base` : ViBusAddress
Offset in bytes of the memory to be mapped.
`map_size` : integer
Amount of memory to map in bytes.
`access` : integer : optional
Must be ``VI_FALSE``.
`suggested` : integer : optional
If not ``VI_NULL`` (the default), the operating system attempts to map
the memory to the address specified in suggested. There is no
guarantee, however, that the memory will be mapped to that
address. This operation may map the memory into an address region
different from suggested.
:Return values:
`address` : ViAddr
Address in your process space where the memory was mapped.
map_trigger
...........
Map the specified trigger source line to the specified destination line.
:Call: map_trigger(vi, trigger_source, trigger_destination, mode)
:VISA name: viMapTrigger
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`trigger_source` : integer
Source line from which to map.
`trigger_destination` : integer
Destination line to which to map.
`mode` : integer
Specifies the trigger mapping mode. This should always be VI_NULL.
:Return values:
None.
memory_allocation
.................
Allocate memory from a device's memory region.
:Call: memory_allocation(vi, size)
:VISA name: viMemAlloc
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`size` : integer
Specifies the size of the allocation.
:Return values:
offset : ViBusAddress
Returns the offset of the allocated device memory.
memory_free
...........
Free memory previously allocated using `memory_allocation`_.
:Call: memory_free(vi, offset)
:VISA name: viMemFree
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`offset` : ViBusAddress
Specifies the memory previously allocated with `memory_allocation`_.
:Return values:
None.
move
....
Move a block of data.
:Call: move(vi, source_space, source_offset, source_width, destination_space,
destination_offset, destination_width, length)
:VISA name: viMove
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`source_space` : integer
Specifies the address space of the source.
`source_offset` : integer
Offset in bytes of the starting address or register from which to
read.
`source_width` : integer
Specifies the data width of the source.
`destination_space` : integer
Specifies the address space of the destination.
`destination_offset` : integer
Offset in bytes of the starting address or register to which to write.
`destination_width` : integer
Specifies the data width of the destination.
`length` : integer
Number of elements to transfer, where the data width of the elements to
transfer is identical to source data width.
:Return values:
None.
move_asynchronously
...................
Move a block of data asynchronously.
:Call: job_id = move_asynchronously(vi, source_space, source_offset,
source_width, destination_space, destination_offset, destination_width,
length)
:VISA name: viMoveAsync
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`source_space` : integer
Specifies the address space of the source.
`source_offset` : integer
Offset in bytes of the starting address or register from which to
read.
`source_width` : integer
Specifies the data width of the source.
`destination_space` : integer
Specifies the address space of the destination.
`destination_offset` : integer
Offset in bytes of the starting address or register to which to write.
`destination_width` : integer
Specifies the data width of the destination.
`length` : integer
Number of elements to transfer, where the data width of the elements to
transfer is identical to source data width.
:Return values:
`job_id` : ViJobId
The job identifier of this asynchronous move operation. Each time an
asynchronous move operation is called, it is assigned a unique job
identifier.
move_in_8, move_in_16, move_in_32
.................................
Move a block of data from the specified address space and offset to local
memory in increments of 8, 16, or 32 bits.
:Call: | buffer_8 = move_in_8(vi, space, offset, length)
| buffer_16 = move_in_16(vi, space, offset, length)
| buffer_32 = move_in_32(vi, space, offset, length)
:VISA name: viMoveIn8, viMoveIn16, viMoveIn32
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`space` : integer
Specifies the address space.
`offset` : ViBusAddress
Offset in bytes of the starting address or register from which to
read.
`length` : integer
Number of elements to transfer, where the data width of the elements to
transfer is identical to data width (8, 16, or 32 bits).
:Return values:
`buffer_8`, `buffer_16`, `buffer_32` : list of integers
Data read from bus as a Python list of values.
move_out_8, move_out_16, move_out_32
....................................
Move a block of data from local memory to the specified address space and
offset in increments of 8, 16, or 32 bits.
:Call: | move_out_8(vi, space, offset, length, buffer_8)
| move_out_16(vi, space, offset, length, buffer_16)
| move_out_32(vi, space, offset, length, buffer_32)
:VISA name: viMoveOut8, viMoveOut16, viMoveOut32
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`space` : integer
Specifies the address space.
`offset` : ViBusAddress
Offset in bytes of the starting address or register from which to
write.
`length` : integer
Number of elements to transfer, where the data width of the elements to
transfer is identical to data width (8, 16, or 32 bits).
`buffer_8`, `buffer_16`, `buffer_32` : sequence of integers
Data to write to bus. This may be a list or a tuple, however in any
case in must contain integers.
:Return values:
None.
open
....
Open a session to the specified device.
:Call: vi = open(session, resource_name, access_mode, open_timeout)
:VISA name: viOpen
:Parameters:
`session` : integer
Resource Manager session (should always be the Default Resource Manager
for VISA returned from `open_default_resource_manager`_).
`resource_name` : string
Unique symbolic name of a resource.
`access_mode` : integer : optional
Defaults to ``VI_NO_LOCK``. Specifies the modes by which the resource
is to be accessed. The value ``VI_EXCLUSIVE_LOCK`` is used to acquire
an exclusive lock immediately upon opening a session; if a lock cannot
be acquired, the session is closed and an error is returned. The value
``VI_LOAD_CONFIG`` is used to configure attributes to values specified
by some external configuration utility; if this value is not used, the
session uses the default values provided by this
specification. Multiple access modes can be used simultaneously by
specifying a "bitwise OR" of the above values.
`open_timeout` : integer : optional
If the `access_mode` parameter requests a lock, then this parameter
specifies the absolute time period in milliseconds that the resource
waits to get unlocked before this operation returns an error;
otherwise, this parameter is ignored. Defaults to
``VI_TMO_IMMEDIATE``.
:Return values:
`vi` : integer
Unique logical identifier reference to a session.
open_default_resource_manager
.............................
Return a session to the Default Resource Manager resource.
:Call: session = open_default_resource_manager()
:VISA name: viOpenDefaultRM
:Parameters:
None.
:Return values:
`session` : integer
Unique logical identifier to a Default Resource Manager session.
get_default_resource_manager
............................
This is a deprecated alias for `open_default_resource_manager`_.
out_8, out_16, out_32
.....................
:Call: | out_8(vi, space, offset, value_8)
| out_16(vi, space, offset, value_16)
| out_32(vi, space, offset, value_32)
:VISA name: viOut8, viOut16, viOut32
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`space` : integer
Specifies the address space.
`offset` : integer
Offset in bytes of the address or register to which to write.
`value_8`, `value_16`, `value_32`: integer
Data to write to bus (8 bits for out_8, 16 bits for out_16, and 32 bits
for out_32).
:Return values:
None.
parse_resource
..............
Parse a resource string to get the interface information.
:Call: interface_type, interface_board_number = parse_resource(session,
resource_name)
:VISA name: viParseRsrc
:Parameters:
`session` : integer
Resource Manager session (should always be the Default Resource Manager
for VISA returned from `open_default_resource_manager`_).
`resource_name` : string
Unique symbolic name of a resource.
:Return values:
`interface_type` : integer
Interface type of the given resource string.
`interface_board_number` : integer
Board number of the interface of the given resource string.
parse_resource_extended
.......................
Parse a resource string to get extended interface information.
**Attention:** Calling this function may raise an ``AttributeError`` because
some older VISA implementation don't have the function ``viParseRsrcEx``.
:Call: interface_type, interface_board_number, resource_class,
unaliased_expanded_resource_name, alias_if_exists =
parse_resource_extended(session, resource_name)
:VISA name: viParseRsrcEx
:Parameters:
`session` : integer
Resource Manager session (should always be the Default Resource Manager
for VISA returned from `open_default_resource_manager`_).
`resource_name` : string
Unique symbolic name of a resource.
:Return values:
`interface_type` : integer
Interface type of the given resource string.
`interface_board_number` : integer
Board number of the interface of the given resource string.
`resource_class` : string
Specifies the resource class (for example "INSTR") of the given
resource string.
`unaliased_expanded_resource_name` : string
This is the expanded version of the given resource string. The format
should be similar to the VISA-defined canonical resource name.
`alias_if_exists` : string
Specifies the user-defined alias for the given resource string, if a
VISA implementation allows aliases and an alias exists for the given
resource string. If not, this is ``None``.
peek_8, peek_16, peek_32
........................
Read an 8-bit, 16-bit, or 32-bit value from the specified address.
:Call: | value_8 = peek_8(vi, address)
| value_16 = peek_16(vi, address)
| value_32 = peek_32(vi, address)
:VISA name: viPeek8, viPeek16, viPeek32
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`address` : ViAddr
Specifies the source address to read the value.
:Return values:
`value_8`, `value_16`, `value_32` : integer
Data read from bus (8 bits for peek_8, 16 bits for peek_16, and 32 bits
for peek_32).
poke_8, poke_16, poke_32
........................
Write an 8-bit, 16-bit, or 32-bit value to the specified address.
:Call: | poke_8(vi, address, value_8)
| poke_16(vi, address, value_16)
| poke_32(vi, address, value_32)
:VISA name: vipoke_8
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`address` : integer
Specifies the destination address to store the value.
`value_8`, `value_16`, `value_32` : integer
Data to write to bus (8 bits for poke_8, 16 bits for poke_16, and 32
bits for poke_32).
:Return values:
None.
printf
......
Convert, format, and send the parameters ``...`` to the device as specified by
the format string.
.. Warning::
The current implementation only supports the following C data types:
``long``, ``double`` and ``char*`` (strings). Thus, you can only use these
three data types in format strings for printf, scanf and the like.
:Call: printf(vi, write_format, ...)
:VISA name: viPrintf
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`write_format` : string
String describing the format for arguments.
`...` : integers, floats, or strings
Arguments sent to the device according to `write_format`.
:Return values:
None.
queryf
......
Perform a formatted write and read through a single operation invocation.
.. Warning::
The current implementation only supports the following C data types:
``long``, ``double`` and ``char*`` (strings). Thus, you can only use these
three data types in format strings for printf, scanf and the like.
:Call: value1, value2, ... = queryf(vi, write_format, read_format, (...), ...,
maximal_string_length = 1024)
:VISA name: viQueryf
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`write_format` : string
String describing the format for arguments.
`read_format` : string
String describing the format for arguments.
`(...)` : tuple of integers, floats, or strings
Arguments sent to the device according to `write_format`. May be
``None``.
`...` : integers, floats, or strings
Arguments to be read from the device according to `read_format`. It's
totally insignificant which values they have, they serve just as a
cheap way to determine what types are to be expected. So actually this
argument list shouldn't be necessary, but with the current
implementation, it is, sorry.
These arguments may be (however needn't be) the same names used for
storing the result values. Alternatively, you can give literals.
`maximal_string_length` : integer : keyword argument
The maximal length assumed for string result arguments. Note that
string results must *never* exceed this length. It defaults to 1024.
:Return values:
`value1`, `value2`, ... : integers, floats, or strings
Arguments read from the device according to `read_format`. Of course,
this must be the same sequence (as far as data types are concerned) as
the given argument list `...` above.
read
....
Read data from device synchronously.
:Call: buffer = read(vi, count)
:VISA name: viRead
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`count` : integer
Maximal number of bytes to be read.
:Return values:
`buffer` : string
Represents the buffer with the received data from device.
read_asynchronously
...................
Read data from device asynchronously.
:Call: buffer, job_id = read_asynchronously(vi, count)
:VISA name: viReadAsync
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`count` : integer
Maximal number of bytes to be read.
:Return values:
`buffer` : ctypes string buffer
Represents the buffer with the data received from device. It's not a
native Python data type because it's filled in the background
(i.e. asynchronously). After you assured that the reading is finished,
you get its value with::
buffer.raw[:return_count]
You get ``return_count`` via the attribute ``VI_ATTR_RET_COUNT``. See
the `VISA reference`_ for further information.
`job_id` : ViJobId
Represents the location of a variable that will be set to the job
identifier of this asynchronous read operation.
.. _`VISA reference`:
http://digital.ni.com/manuals.nsf/websearch/87E52268CF9ACCEE86256D0F006E860D
read_stb
........
Read a status byte of the service request.
:Call: status = read_stb(vi)
:VISA name: viReadSTB
:Parameters:
`vi` : integer
Unique logical identifier to a session.
:Return values:
`status` : integer
Service request status byte.
read_to_file
............
Read data synchronously, and store the transferred data in a file.
:Call: return_count = read_to_file(vi, filename, count)
:VISA name: viReadToFile
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`file_name` : string
Name of file to which data will be written.
`count` : integer
Maximal number of bytes to be read.
:Return values:
`return_count` : integer
Number of bytes actually transferred.
scanf
.....
Read, convert, and format data using the format specifier. Store the formatted
data in the given optional parameters.
.. Warning::
The current implementation only supports the following C data types:
``long``, ``double`` and ``char*`` (strings). Thus, you can only use these
three data types in format strings for printf, scanf and the like.
:Call: value1, value2, ... = scanf(vi, read_format, ..., maximal_string_length
= 1024)
:VISA name: viScanf
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`read_format` : string
String describing the format for arguments.
`...` : integers, floats, or strings
Arguments to be read from the device according to `read_format`. It's
totally insignificant which values they have, they serve just as a
cheap way to determine what types are to be expected. So actually this
argument list shouldn't be necessary, but with the current
implementation, it is, sorry.
These arguments may be (however needn't be) the same names used for
storing the result values. Alternatively, you can give literals.
`maximal_string_length` : integer : keyword argument
The maximal length assumed for string result arguments. Note that
string results must *never* exceed this length. It defaults to 1024.
:Return values:
`value1`, `value2`, ... : integers, floats, or strings
Arguments read from the device according to `read_format`. Of course,
this must be the same sequence (as far as data types are concerned) as
the given argument list `...` above.
set_attribute
.............
Set the state of an attribute.
:Call: set_attribute(vi, attribute, attribute_state)
:VISA name: viSetAttribute
:Parameters:
`vi` : integer, ViEvent, or ViFindList
Unique logical identifier to a session.
`attribute` : integer
Session, event, or find list attribute for which the state is
modified.
`attribute_state` : integer
The state of the attribute to be set for the specified resource. The
interpretation of the individual attribute value is defined by the
resource.
:Return values:
None.
set_buffer
..........
Set the size for the formatted I/O and/or serial communication buffer(s).
:Call: set_buffer(vi, mask, size)
:VISA name: viSetBuf
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`mask` : integer
Specifies the type of buffer.
`size` : integer
The size to be set for the specified buffer(s).
:Return values:
None.
sprintf
.......
Same as `printf`_, except the data is written to a user-specified buffer rather
than the device.
.. Warning::
The current implementation only supports the following C data types:
``long``, ``double`` and ``char*`` (strings). Thus, you can only use these
three data types in format strings for printf, scanf and the like.
:Call: buffer = sprintf(vi, write_format, ..., buffer_length = 1024)
:VISA name: viSPrintf
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`write_format` : string
String describing the format for arguments.
`...` : integers, floats, or strings
Arguments sent to the buffer according to `write_format`.
`buffer_length` : integer : keyword argument
Length of the user-specified buffer in bytes. Defaults to 1024.
:Return values:
`buffer` : string
Buffer where the formatted data was written to.
sscanf
......
Same as `scanf`_, except that the data is read from a user-specified buffer
instead of a device.
.. Warning::
The current implementation only supports the following C data types:
``long``, ``double`` and ``char*`` (strings). Thus, you can only use these
three data types in format strings for printf, scanf and the like.
:Call: value1, value2, ... = sscanf(vi, buffer, read_format, ...,
maximal_string_length = 1024)
:VISA name: viSScanf
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`buffer` : string
Buffer from which data is read and formatted.
`read_format` : string
String describing the format for arguments.
`...` : integers, floats, or strings
Arguments to be read from the device according to `read_format`. It's
totally insignificant which values they have, they serve just as a
cheap way to determine what types are to be expected. So actually this
argument list shouldn't be necessary, but with the current
implementation, it is, sorry.
These arguments may be (however needn't be) the same names used for
storing the result values. Alternatively, you can give literals.
`maximal_string_length` : integer : keyword argument
The maximal length assumed for string result arguments. Note that
string results must *never* exceed this length. It defaults to 1024.
:Return values:
`value1`, `value2`, ... : integers, floats, or strings
Arguments read from the device according to `read_format`. Of course,
this must be the same sequence (as far as data types are concerned) as
the given argument list `...` above.
status_description
..................
Return a user-readable description of the status code passed to the operation.
:Call: description = status_description(vi, status)
:VISA name: viStatusDesc
:Parameters:
`vi` : integer, ViEvent, or ViFindList
Unique logical identifier to a session.
`status` : integer
Status code to interpret.
:Return values:
`description` : string
The user-readable string interpretation of the status code passed to
the operation.
terminate
.........
Request a VISA session to terminate normal execution of an operation.
:Call: terminate(vi, degree, job_id)
:VISA name: viTerminate
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`degree` : integer
``VI_NULL``
`job_id` : ViJobId
Specifies an operation identifier.
:Return values:
None.
uninstall_handler
.................
Uninstall handlers for events.
:Call: uninstall_handler(vi, event_type, handler, user_handle)
:VISA name: viUninstallHandler
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`event_type` : integer
Logical event identifier.
`handler` : callable
Interpreted as a valid reference to a handler to be uninstalled by a
client application.
`user_handle` : ctypes type : optional
A value specified by an application that can be used for identifying
handlers uniquely in a session for an event. It *must* be the object
returned by `install_handler`_. Consequently, it defaults to
``None``.
:Return values:
None.
unlock
......
Relinquish a lock for the specified resource.
:Call: unlock(vi)
:VISA name: viUnlock
:Parameters:
`vi` : integer
Unique logical identifier to a session.
:Return values:
None.
unmap_address
.............
Unmap memory space previously mapped by `map_address`_.
:Call: unmap_address(vi)
:VISA name: viUnmapAddress
:Parameters:
`vi` : integer
Unique logical identifier to a session.
:Return values:
None.
unmap_trigger
.............
Undo a previous map from the specified trigger source line to the specified
destination line.
:Call: unmap_trigger(vi, trigger_source, trigger_destination)
:VISA name: viUnmapTrigger
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`trigger_source` : integer
Source line used in previous map.
`trigger_destination` : integer
Destination line used in previous map.
:Return values:
None.
usb_control_in
..............
Request arbitrary data from the USB device on the control port.
:Call: buffer = usb_control_in(vi, request_type_bitmap_field,
request_id, request_value, index, length)
:VISA name: viUsbControlIn
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`request_type_bitmap_field` : integer
Bitmap field for defining the USB control port request. The bitmap
fields are as defined by the USB specification. The direction bit must
be device-to-host.
`request_id` : integer
Request ID for this transfer. The meaning of this value depends on
`request_type_bitmap_field`.
`request_value` : integer
Request value for this transfer.
`index` : integer
Specifies the interface or endpoint index number, depending on
`request_type_bitmap_field`.
`length` : integer : optional
Number of data in bytes to request from the device during the Data
stage. If this value is not given or 0, an empty string is returned.
:Return values:
`buffer` : string
Actual data received from the device during the Data stage. If
`length` is not given or 0, an empty string is returned.
usb_control_out
...............
Send arbitrary data to the USB device on the control port.
:Call: usb_control_out(vi, request_type_bitmap_field, request_id, request_value,
index, buffer)
:VISA name: viUsbControlOut
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`request_type_bitmap_field` : integer
Bitmap field for defining the USB control port request. The bitmap
fields are as defined by the USB specification. The direction bit must
be host-to-device.
`request_id` : integer
Request ID for this transfer. The meaning of this value depends on
`request_type_bitmap_field`.
`request_value` : integer
Request value for this transfer.
`index` : integer
Specifies the interface or endpoint index number, depending on
`request_type_bitmap_field`.
`buffer` : string : optional
Actual data to send to the device during the Data stage. If not given,
nothing is sent.
:Return values:
None.
vprintf, vqueryf, vscanf, vsprintf, vsscanf
...........................................
These variants make no sense in Python, so I realised them as mere aliases
(just drop the "v").
vxi_command_query
.................
Send the device a miscellaneous command or query and/or retrieve the response
to a previous query.
:Call: vxi_command_query(vi, mode, command)
:VISA name: viVxiCommandQuery
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`mode` : integer
Specifies whether to issue a command and/or retrieve a response.
`command` : integer
The miscellaneous command to send.
:Return values:
`response` : integer
The response retrieved from the device. If the mode specifies just
sending a command, this parameter may be ``VI_NULL``.
wait_on_event
.............
Wait for an occurrence of the specified event for a given session.
:Call: out_event_type, out_context = wait_on_event(vi, in_event_type, timeout)
:VISA name: viWaitOnEvent
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`in_event_type` : integer
Logical identifier of the event(s) to wait for.
`timeout` : integer
Absolute time period in milliseconds that the resource shall wait for a
specified event to occur before returning the time elapsed error.
:Return values:
`out_event_type` : integer
Logical identifier of the event actually received.
`out_context` : ViEvent
A handle specifying the unique occurrence of an event.
write
.....
Write data to device synchronously.
:Call: return_count = write(vi, buffer)
:VISA name: viWrite
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`buffer` : string
Contains the data block to be sent to the device.
:Return values:
`return_count` : integer
The number of bytes actually transferred.
write_asynchronously
....................
Write data to device asynchronously.
:Call: job_id = write_asynchronously(vi, buffer)
:VISA name: viWriteAsync
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`buffer` : string
Contains the data block to be sent to the device.
:Return values:
`job_id` : ViJobId
The job identifier of this asynchronous write operation.
write_from_file
...............
Take data from a file and write it out synchronously.
:Call: return_count = write_from_file(vi, filename, count)
:VISA name: viWriteFromFile
:Parameters:
`vi` : integer
Unique logical identifier to a session.
`filename` : string
Name of file from which data will be read.
`count` : integer
Maximal number of bytes to be written.
:Return values:
`return_count` : integer
Number of bytes actually transferred.
.. LocalWords: rst british vpp PyVISA ies dll Gregor Thalhammer ViSession atn
.. LocalWords: viAssertIntrSignal viAssertTrigger PROT viAssertUtilSignal ren
.. LocalWords: viBufRead viBufWrite viClear viClose ViEvent ViFindList HNDLR
.. LocalWords: viDisableEvent viDiscardEvents viEnableEvent viFindNext gpib
.. LocalWords: viFindRsrc viFlush viGetAttribute viGpibCommand ADDR ifc viIn
.. LocalWords: viGpibControlATN viGpibControlREN viGpibPassControl ViHndlr
.. LocalWords: viGpibSendIFC viInstallHandler viLock viMapAddress ViAddr TMO
.. LocalWords: ViBusAddress viMapTrigger viMemAlloc viMemFree viMove ViJobId
.. LocalWords: viMoveAsync viMoveIn viMoveOut viOpen viOpenDefaultRM viOut
.. LocalWords: viParseRsrc unaliased viParseRsrcEx INSTR viPeek vipoke printf
.. LocalWords: scanf viPrintf queryf viQueryf viRead viReadAsync stb viScanf
.. LocalWords: viReadSTB viReadToFile viSetAttribute viSetBuf sprintf sscanf
.. LocalWords: viSPrintf viSScanf viStatusDesc viTerminate viUninstallHandler
.. LocalWords: viUnlock viUnmapAddress viUnmapTrigger usb viUsbControlIn vxi
.. LocalWords: viUsbControlOut vprintf vqueryf vscanf vsprintf vsscanf IVI
.. LocalWords: viVxiCommandQuery viWaitOnEvent viWrite viWriteAsync WINNT def
.. LocalWords: viWriteFromFile FixMe VisaIOError TypeError ctypes Enthought
.. LocalWords: VisaIOWarning UnknownHandler pyvisa