doc/introduction.rst

.. -*- coding: utf-8 -*-

==============
 Introduction
==============

pygpibtoolkit_ is a Python_ toolkit for talking with GPIB devices. It
consist in a set of python modules (low-level and some more
high-level) in order to ease writing python code to play with GPIB
devices.

There are also some utility commands and GUI tools written using this
library (and PyQt4 for GUI parts).

The aim of the project is to have an infrastructure that make it easy
to write code to command/interact with GPIB-controlled devices, and,
as a corrolary, make it easy to write "description" code for specific
test equipments.

Features
========

- Control GPIB devices using cheap Prologix_ USB-GPIB devices using a
  "high" level API; some other GPIB backends could be implemented, but
  I for now only have a Prologix USB bundle...

- A simple (and incomplete) GPIB plotter is available. 

- Infrastructure to "easily" create description of a specific test
  equipment.

Known test equipment
====================

For now, the following test equipment have been (partially)
implemented:

- HP 3562A/3563A Dynamic Signal Analyzer
- Simple GPIB plotter

The devices I should implement soon (well, ASAP):

- HP 8904A Signal Synthetizer
- HP 3456A Meter

=======
 Tools
=======

Every tool presented in this section can be found in the `bin`
directory, and can display a *help* message using the ``-h`` or
``--help`` option.

For the sake of testing these tools, some example files are proposed
in the `example` directory.

`examples/hpgl_plots` are examples of HPGL files (resulting from
plotting from my HP3562A).

`examples/datablocks` are examples of HP3562A state, trace and coords
datablocks dumped.

The `mockup` mode of the tools presented below are using these files
as data source.


GUI Tools
=========

qgpibplotter
------------

This is a little app to emulate a GPIB HPGL plotter.

Once started, one can load and display a previously saved HPGL file
(using the File menu).

However, the main usage is to use it as a passive device on the GPIB
bus (default address is 5, but this may be configured in user
preferences). There is a main "On Line" button which can be in out
out. When "online", it will receive plots from every device on the
GPIB bus performing plot commands.

There is "test" mode, in which a fake GPIB connection will be used
instead of the real one. So is one want to see *qgpibplotter* in
action, just run it with the ``-m`` option (mockup). Type

  qgpibplotter -h

for details.

q3562
-----

This a small GUI application that allow to easily retrieve state, trace
and coord datablocks from a HP3562A/HP3563A device (see HP manuals of
these devices for details).

There is "test" mode, in which a fake GPIB connection will be used
instead of the real one. So is one want to see *qgpibplotter* in
action, just run it with the ``-m`` option (mockup). Type

  q3562 -h

for details.

Command line tools
==================

gpib_detect
-----------

Simple GPIB device detector. The computer GPIB device is configured so
it is the Controller In Charge on the GPIB bus. It takes a while
(several seconds) to run the retection procedure.

Once complete, it will simply display the list of devices found on the
bus, with a decription of the device (if available, ie. if it replies
to the IDN? command, which is not the case of older devices).

dump_datablock
--------------

Retrieve a datablock from a HP3562A/HP3563A device. The datablock can
be the state, trace or coord datablock, and it can use the ASCII,
BINARY or ANSI dumping mode. The resulting data are saved in a file.

read_XXX
--------

These 3 tools can be used to display a datablock previously dumped in
a file (using *dump_datablock*). 


..
..

.. _pygpibtoolkit: http://www.logilab.org/project/pygpibtoolkit
.. _Prologix: http://www.prologix.com
.. _Python: http://www.python.org