Metadata-Version: 2.1
Name: pyusbdux
Version: 2.0.3
Summary: API for the USB-DUX DAQ boxes for Linux (https://github.com/glasgowneuro/usbdux)
Home-page: https://github.com/glasgowneuro/usbdux
Author: Bernd Porr
Author-email: mail@berndporr.me.uk
License: GPL v3
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
License-File: LICENSE

==========================
Python API for the USB-DUX
==========================

USB-DUX are open source & hardware data acquisition boxes designed for Linux

https://github.com/glasgowneuro/usbdux

pyusbdux supports the USB-DUX-sigma: 16 analogue inputs (isolated, 24 bit, 1 kHz), 4 analogue out (isolated, 8 bit) and 8 digital I/O


Installation instructions
=========================

Make sure that you have all `comedi` libraries,
`swig` and `python3` installed (both runtime and development).
Use your favourite package manager to install the packages.

Then install `pyusbdux` by typing::
  
      pip3 install pyusbdux [--user] [--upgrade]



Quick start guide
=================

Here are the basic steps how to use the API::

      # load the module
      import pyusbdux as dux

      # create a callback interface
      class DataCallback(dux.Callback):
          def hasSample(self,sample): # sample arrived
              print("s:",sample) # process sample

      cb = DataCallback()

      # opens the 1st USBDUX device (autodetect)
      dux.open()

      # Start asynchronous data acquisition in the background: one channel, fs=250Hz
      dux.start(cb,1,250)

      # do nothing or run a gui
      input() # do nothing here

      # shutdown
      dux.stop()
      dux.close()


API documentation
==================

These are the commands which allow you to access the analogue inputs asynchronously
and the analogue outputs, digital input and outputs synchronously::

      # opens the comedi device with comediDeviceNumber
      open(comediDeviceNumber)
      open()                      # opens 1st USB-DUX device (autodetect)

      # Callback interface
      class DataCallback(dux.Callback):
          def hasSample(self,sample): # sample arrived
              # implement your callback handler here

      # Starts acquisition of n_channels at the sampling rate of fs.
      # Expects an instance of Callback with overloaded hasSample(self,sample).
      start(Callback,n_channels, fs)
      start(Callback,n_channels)           # at fs=250

      # gets the actual sampling rate of the running acquisition
      getSamplingRate()

      # stops the background acquisition
      stop()

      # writes to a digital pin the value 0 or 1
      digital_out(channel, value)

      # reads from a digital pin
      digital_in(channel)

      # writes to an analogue output pin (raw ADC values)
      analoge_out(channel, value)

      # gets the max raw value of the analogue output
      get_analogue_out_max_raw_value()

      # closes the comedi device
      close()

      # returns the name of the board connected
      get_board_name()

Any error in comedi throws an exception in python.


Example / demo programs
=======================

In the folder https://github.com/berndporr/pyusbdux/tree/master/examples are example
scripts which show you how to sample data from the analogue and digital ports.


Troubleshooting
===============

Spyder
------

Start your program from the terminal and never within Spyder. Here is
an example::

    ~/pyusbdux$ cd examples
    ~/pyusbdux/examples$ python3 ./realtime_plot.py

The problem with Spyder is that it won't let your Python program terminate properly so
that you can examine variables etc. However, this means that
the USB-DUX board keeps running even if it seems that execution has finished.
If you then re-run your program
it won't be able to talk to your USB-DUX.

Bottomline: Use Spyder only for editing, instead run your program from the terminal. Never start
your program from within Spyder.


After an update still the old version is being used
---------------------------------------------------

If you use the `--user` option to install / update packages Python might keep older versions.

Solution: Do a `pip uninstall pyusbdux` multiple times until no version is left 
on your computer. Then install it again as described above.


