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

=============
 Description
=============

The code is organized in 2 layers; a low-level communication layer,
and a highter level which allows to describe precisely a GPIB device,
communicate asynchronously with it, etc.

Low level
=========

The low level communication process is managed by the module
``pygpibtoolkit.prologix``, in which there is a class names ``GPIB``
that knows how to initialize the GPIB device, send commands and
receive data from the bus, perform GPIB polls, etc.

Example::

  from pygpibtoolkit.prologix import GPIB
  cnx = GPIB() # by default, it is the controller in charge
  idn = cnx.send_command("*IDN?", 12) # sends the idn command to device at GPIBaddress 12
  print idn

  cnx.set_address(12) # we will talk to this device 12 for a while
  datablock = cnx.send_command('DDBN')

  if cnx.check_srq():
      print "A Service Request has been sent"

But that's basically it. You can send commands to devices, wait for an
answer, check SRQ line.

High level
==========

The high level API is organized around a GPIB controller class
(``pygpibtoolkit.gpibcontroller.GPIBController``) which is responsible
for managing every connection stuff. It will run a thread responsible
for communication processes, will regularly check SRQ line (and
respond accordingly, with ability to register callbacks), etc.

It will also provide a ``send_command`` method, but this latter will
have a much higher means: the operation can be done synchronously or
asynchronously (with a callback to call upon completion), etc.

It will also hold device managers for found devices on the GPIB bus.

Each device manager is a class responsible for communication
specifically with a specified device. It will provide (if the device
manager has been written) simple ways to send GPIB commands of the
device; every GPIB command will be presented as a method of the
manager.

Talking with a device can then be as simple as::

    from pygpibtoolkit.gpibcontroller import GPIBController
    c = GPIBController()
    devices = c.detect_devices()
    # devices is a dict which keys are the GPIB addresses
    # and values, the managers for each device
    hp3562 = devices[3]

    # ok, let's tell the HP3562 to put channel 1 in AC couplig mode,
    hp3562.C1AC("AC")
    # and put it in linear measure mode
    hp3562.LNRS() #EMEAS("LINEAR RES")
    # and Freq response mode
    hp3562.FRQR()
    # set span freq and center freq
    hp3562.FRS("10khz")
    hp3562.CF("7212hz")
    # then get the resulting trace data block
    trace = hp3562.DDBN()
    # which we can easily display
    header, data = hp3562.decode_trace(trace)
    import pylab
    pylab.plot(data)
    pylab.show()

    # ok, let's stop gracefully our cession
    c.stop()