README

QTScope - a simple, plugin based oscilloscope program

Copyright (C) 2004 Matthias Hennig <hennig@cn.stir.ac.uk>
Copyright (C) 2005 Bernd Porr <berndporr@f2s.com>
Copyright (C) 2013 Steffen Mauch <steffen.mauch@gmail.com>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA


SUMMARY:
--------

QTScope is a program to display the signals acquired from daq devices
via the comedi library. It is based on the QT Widget Library
and provides a plugin architecture which makes it easy to
write own visualisation plugins.

It was originally written specifically for the USB DUX board
(http://www.linux-usb-daq.co.uk/), but today the aim is to be compatible
with any board with a comedi driver. 
The data aquisition is done in regular
intervals. Under 10000Hz data data is scrolled into the data window.
Above 10000Hz the program does snapshots of 5000 samples and
displays them every second on the screen.


WHAT YOU WILL NEED:
-------------------

This program was developed/tested using a linux distribution
with and QT library 4.x.
the following software should be installed:

Comedi: a free driver/library framework for a number of data
acquisition devices http://www.comedi.org

QT (Version > 4):
http://qt-project.org/

Qwt Widget Library 6.x:
For details about this nice and useful project, see:
http://qwt.sourceforge.net/

For the SHWFS plugin Eigen 3
http://eigen.tuxfamily.org
(for WFS plugin otherwise in
plugins/plugins.pro line with 'wfs \'
has to be removed!)


INSTALLATION:
-------------

1) provide the paths to QT:

   export QTDIR=/path/to/qt

2) qmake qtscope.pro

   (sometimes qmake may not be directly accessible, 
    then you can usually find it under
   /usr/lib/qt4/bin/qmake or /usr/share/qt4/bin/qmake)

3) make

4) As root:

   make install
   
   This will install the program to /usr/local/bin 
   and the plugins to /usr/local/lib/qtscope/plugins.
   
   alternatively
   sudo ./bin/qtscope
   if you just want to try QTScope!
   

TODO:
-----

A lot!

Newer versions will probably contain these planned extensions:

- more visualisation plugins
- data storage facility
- filter plugins for data processing
- plugin for digital input and output (some basics already done)
- plugin for analog output (some basics already done) 


WRITING PLUGINS:
----------------

It is extremely simple to write a plugin for QTScope! A plugin
basically just frequently receives the new data and is free to do
whatever it likes. A QTimer object is responsible for the readout. The
base class for a plugin is called "scopePlotPlugin". Each plugin needs
the following data structure to announce its existence:

pluginInfo myPluginInfo = {...};

whith the tye:

typedef struct pluginInfo{
  QString name;          // the name
  QString type;          // the type, so far not unused (use "Plot")
  int channelsRequest;   // number of channels the plugin requests
  int type_comedi;       // entry of comedi_subdevice_type which the
                         // plugin does support, i.e. COMEDI_SUBD_AI
};

enum comedi_subdevice_type {
  COMEDI_SUBD_UNUSED,     /* unused by driver */
  COMEDI_SUBD_AI,         /* analog input */
  COMEDI_SUBD_AO,         /* analog output */
  COMEDI_SUBD_DI,         /* digital input */
  COMEDI_SUBD_DO,         /* digital output */
  COMEDI_SUBD_DIO,        /* digital input/output */
  COMEDI_SUBD_COUNTER,    /* counter */
  COMEDI_SUBD_TIMER,      /* timer */
  COMEDI_SUBD_MEMORY,     /* memory, EEPROM, DPRAM */
  COMEDI_SUBD_CALIB,      /* calibration DACs */
  COMEDI_SUBD_PROC,       /* processor, DSP */
  COMEDI_SUBD_SERIAL,     /* serial IO */
  COMEDI_SUBD_PWM         /* PWM */
};

The following methods are declared as virtual in the base class:

- virtual void setDataSource(double *) = 0;
  QTScope creates arrays of the type double that contain the data. 
  The plugin just gets the pointer.
  If the plugin expects more than one source, 
  this function is called repeatedly. 

- virtual void insertValues(int) = 0;
  Called when num new data values are available.

- virtual void replot() = 0;
  A screen refresh is due for the plugin.

- samplingRateChanged() = 0;
  The sampling rate "freq" has changed