Merge pull request #36 from dhhagan/dev

Dev

README.md

@@ -1,9 +1,7 @@
 [![Build Status](https://travis-ci.org/dhhagan/py-opc.svg?branch=develop)](https://travis-ci.org/dhhagan/py-opc)
 [![PyPI version](https://badge.fury.io/py/py-opc.svg)](https://badge.fury.io/py/py-opc)
 [![Coverage Status](https://coveralls.io/repos/dhhagan/py-opc/badge.svg?branch=master&service=github)](https://coveralls.io/github/dhhagan/py-opc?branch=master)
-[![Join the chat at https://gitter.im/dhhagan/py-opc](https://badges.gitter.im/dhhagan/py-opc.svg)](https://gitter.im/dhhagan/py-opc?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-[![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.48803.svg)](http://dx.doi.org/10.5281/zenodo.48803)
-
+[![DOI](https://zenodo.org/badge/30832320.svg)](https://zenodo.org/badge/latestdoi/30832320)
 
 # py-opc
 

docs/index.rst

@@ -7,9 +7,9 @@ Welcome to py-opc's documentation!
 ==================================
 
 **py-opc** is a python module that enables one to use easily operate the Alphasense
-OPC-N2 optical particle counter through a Raspberry Pi over the SPI bus. It was originally
-designed using a Rapsberry Pi 2 Model B and Python3.5; however, it should work on other versions
-as well.
+OPC-N2 optical particle counter through a Raspberry Pi over the SPI bus using either a SPI-USB converter
+or directly over the GPIO pins. It was originally designed using a Rapsberry Pi 2 Model B
+and Python3.5; however, it should work on other versions as well.
 
 There are a variety of OPC Models and firmware versions from Alphasense; a table documenting which ones
 are supported will be added. If you own an OPC-N2 with a firmware version that has not been tested, please
@@ -18,26 +18,43 @@ do so and submit as an issue on the GitHub repository.
 Installation
 ------------
 
-You can install this package using ``pip``::
+You can install this package directly from pypi using ``pip``::
 
       pip install py-opc
 
 You can upgrade by issuing the command::
 
       pip install py-opc --upgrade
 
+If interested in testing a development version, clone (or download) the repository and then install as follows::
+
+      python setup.py develop
+
+
 Requirements
 ------------
 
-The following packages are required:
+One of the following packages is required:
 
   * py-spidev_
+  * pyusbiss_
 
 .. _py-spidev: https://github.com/doceme/py-spidev
+.. _pyusbiss: https://github.com/DancingQuanta/pyusbiss
+
+Use the spidev library if you are planning to connect to OPC to the microcontroller via the GPIO pins.  Use
+the pyusbiss library if connecting via a SPI-USB adapter.
+
 
 Setting Up the Raspberry Pi
 ---------------------------
 
+There are now two simple ways to connect your Alphasense OPC to a Raspberry Pi (or similar device): directly via the GPIO
+pins, or using a SPI-USB converter.
+
+Connecting via GPIO
+~~~~~~~~~~~~~~~~~~~
+
 If you are not familiar with setting up a Raspberry Pi to be used as a SPI device,
 here are a couple of great tutorials: RPi_, Drogon_, and Hensley_. A few important things
 to note:
@@ -64,6 +81,14 @@ are stated below:
 .. _Drogon: https://projects.drogon.net/understanding-spi-on-the-raspberry-pi/
 .. _Hensley: http://www.brianhensley.net/2012/07/getting-spi-working-on-raspberry-pi.html
 
+Connecting via a USB-SPI Converter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To connect your OPC to the Raspberry Pi directly, you can use a SPI-USB converter. They can be found
+fairly inexpensively online or directly from Alphasense.
+
+You will then be able to directly connect the OPC to your Raspberry Pi's USB port.
+
 Getting Help
 ------------
 
@@ -99,6 +124,10 @@ Examples
 
 Setting up the SPI Connection
 -----------------------------
+
+Using the SpiDev Library via GPIO Pins
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ::
 
       import spidev
@@ -112,6 +141,17 @@ Setting up the SPI Connection
       spi.mode = 1
       spi.max_speed_hz = 500000
 
+Using the pyusbiss Library via USB Port
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+      import usbiss
+      import opc
+
+      # Open a SPI connection
+      spi = usbiss.USBISS("/dev/ttyACM0", 'spi', spi_mode = 2, freq = 500000)
+
 
 Initiating the OPCN2
 --------------------
@@ -142,7 +182,7 @@ API Reference
 .. module:: opc
 .. autoclass:: OPC
    :members: _16bit_unsigned, _calculate_float, read_info_string, ping, _calculate_mtof,
-            _calculate_temp, _calculate_pressure, _calculate_bin_boundary, _calculate_period, ping
+            _calculate_temp, _calculate_pressure, lookup_bin_boundary _calculate_bin_boundary, _calculate_period, ping
 .. autoclass:: OPCN1
    :members: on, off, read_gsc_sfr, read_bin_boundaries, write_gsc_sfr, read_bin_particle_density,
             write_bin_particle_density, read_histogram

opc/__init__.py

@@ -4,27 +4,27 @@
 from .lookup_table import OPC_LOOKUP
 
 from time import sleep
-import spidev
 import struct
 import warnings
 import re
 
 from .exceptions import firmware_error_msg
 
+
 __all__ = ['OPCN2', 'OPCN1']
 __version__ = get_distribution('py-opc').version
 
 class OPC(object):
     """Generic class for any Alphasense OPC. Provides the common methods and calculations
     for each OPC.
 
-    :param spi_connection: spidev.SpiDev connection
+    :param spi_connection: spidev.SpiDev or usbiss.USBISS connection
     :param debug: Set true to print data to console while running
     :param model: Model number of the OPC ('N1' or 'N2') set by the parent class
 
     :raises: opc.exceptions.SpiConnectionError
 
-    :type spi_connection: spidev.SpiDev
+    :type spi_connection: spidev.SpiDev or usbiss.USBISS
     :type debug: boolean
     :type model: string
 
@@ -48,7 +48,7 @@ def __init__(self, spi_connection, **kwargs):
         self.firmware   = {'major': None, 'minor': None, 'version': None}
         self.model      = kwargs.get('model', 'N2')
 
-        # Check to make sure the connection is a valid SpiDev instance
+        # Check to make sure the connection has the xfer attribute
         msg = ("The SPI connection must be a valid SPI master with "
                "transfer function 'xfer'")
         assert hasattr(spi_connection, 'xfer'), msg
@@ -409,8 +409,13 @@ def write_config_variables2(self, config_vars):
 
         return
 
-    def histogram(self):
-        """Read and reset the histogram.
+    def histogram(self, number_concentration = True):
+        """Read and reset the histogram. As of v1.3.0, histogram
+        values are reported in particle number concentration (#/cc) by default.
+
+        :param number_concentration: If true, histogram bins are reported in number concentration vs. raw values.
+
+        :type number_concentration: boolean
 
         :rtype: dictionary
 
@@ -519,6 +524,27 @@ def histogram(self):
             warnings.warn("Data transfer was incomplete.")
             return None
 
+        # If histogram is true, convert histogram values to number concentration
+        if number_concentration is True:
+            _conv_ = data['SFR'] * data['Sampling Period'] # Divider in units of ml (cc)
+
+            data['Bin 0']   = data['Bin 0'] / _conv_
+            data['Bin 1']   = data['Bin 1'] / _conv_
+            data['Bin 2']   = data['Bin 2'] / _conv_
+            data['Bin 3']   = data['Bin 3'] / _conv_
+            data['Bin 4']   = data['Bin 4'] / _conv_
+            data['Bin 5']   = data['Bin 5'] / _conv_
+            data['Bin 6']   = data['Bin 6'] / _conv_
+            data['Bin 7']   = data['Bin 7'] / _conv_
+            data['Bin 8']   = data['Bin 8'] / _conv_
+            data['Bin 9']   = data['Bin 9'] / _conv_
+            data['Bin 10']  = data['Bin 10'] / _conv_
+            data['Bin 11']  = data['Bin 11'] / _conv_
+            data['Bin 12']  = data['Bin 12'] / _conv_
+            data['Bin 13']  = data['Bin 13'] / _conv_
+            data['Bin 14']  = data['Bin 14'] / _conv_
+            data['Bin 15']  = data['Bin 15'] / _conv_
+
         return data
 
     def save_config_variables(self):

setup.py

@@ -5,7 +5,7 @@
     Written originally by David H Hagan
 '''
 
-__version__ = '1.2.0'
+__version__ = '1.3.0'
 
 try:
     from setuptools import setup