rearraged API docs; link to datasheets for pinouts

adafruit_mcp3xxx/analog_in.py

@@ -27,46 +27,22 @@
 
 * Author(s): Brent Rubell
 
-.. note:: The ADC chips' input pins (AKA "channels") are aliased in this library as integer
-    variables whose names start with "P". Each module that contains a driver class for a
-    particular ADC chip (in this library) has these aliases predefined accordingly. This is done
-    for code readability and prevention of erroneous SPI commands. The following example code
-    explains this best:
+.. warning::
+    The ADC chips supported by this library do not use negative numbers. If the resulting
+    differential read is less than 0, then the returned integer value (and voltage value) is ``0``.
+    If for some reason the voltage on a channel is greater than the reference voltage or
+    less than 0, then the returned integer value is ``65472‬`` or ``0`` respectively.
 
-    .. code-block:: python
-
-        >>> import adafruit_mcp3xxx.mcp3008 as MCP
-        >>> print('channel', MCP.P0)
-        channel 0
-        >>> print('channel', MCP.P7)
-        channel 7
-        >>> print('channel', MCP.P8)
-        Traceback (most recent call last):
-          File "<stdin>", line 1, in <module>
-        AttributeError: 'module' object has no attribute 'P8'
 """
 
 from .mcp3xxx import MCP3xxx
 
 class AnalogIn():
     """AnalogIn Mock Implementation for ADC Reads.
 
-    :param ~mcp3002.MCP3002,~mcp3004.MCP3004,~mcp3008.MCP3008 mcp: The mcp object.
+    :param MCP3002,MCP3004,MCP3008 mcp: The mcp object.
     :param int positive_pin: Required pin for single-ended.
     :param int negative_pin: Optional pin for differential reads.
-
-    .. important::
-        The ADC chips supported by this library do not handle negative numbers when returning the
-        differential read of 2 channels. If the resulting differential read is less than 0, the
-        returned integer is ``0``. If for some reason the voltage on a channel is greater than the
-        reference voltage (Vin) or less than 0, then the returned integer is ``65472‬`` or ``0``
-        (applies to single ended and differential reads).
-
-        It is also worth noting that the differential reads (comparisons done by the ADC chip) are
-        limited to certain pairs of channels. Please refer to the driver class of your ADC chip for
-        a list of available differential mappings (comparisons). Otherwise, it is recommended to
-        compute the differences between single-ended reads of separate channels for more flexible
-        results.
     """
     def __init__(self, mcp, positive_pin, negative_pin=None):
         if not isinstance(mcp, MCP3xxx):
@@ -75,17 +51,19 @@ def __init__(self, mcp, positive_pin, negative_pin=None):
         self._pin_setting = positive_pin
         self.is_differential = negative_pin is not None
         if self.is_differential:
-            self._pin_setting = self._mcp.DIFF_PINS.get((self._pin_setting, negative_pin), None)
-        if self._pin_setting is None:
-            # this scope (kinda) checks positive_pin datatype also
-            raise ValueError("Differential pin mapping not defined. Please read the docs.")
+            self._pin_setting = self._mcp.DIFF_PINS.get((positive_pin, negative_pin), None)
+            if self._pin_setting is None:
+                raise ValueError("Differential pin mapping not defined. Please read the docs.")
 
     @property
     def value(self):
-        """Returns the value of an ADC pin as an integer."""
+        """Returns the value of an ADC pin as an integer. Due to 10-bit accuracy of the chip, the
+        returned values range [0, 65472]."""
         return self._mcp.read(self._pin_setting, is_differential=self.is_differential) << 6
 
     @property
     def voltage(self):
-        """Returns the voltage from the ADC pin as a floating point value."""
+        """Returns the voltage from the ADC pin as a floating point value. Due to the 10-bit
+        accuracy of the chip, returned values range from 0 to (``reference_voltage`` *
+        65472 / 65535)"""
         return (self.value * self._mcp.reference_voltage) / 65535

adafruit_mcp3xxx/mcp3002.py

@@ -27,6 +27,11 @@
 converter instance.
 
 * Author(s): Brent Rubell, Brendan Doherty
+
+For proper wiring, please refer to `Package Type diagram
+<http://ww1.microchip.com/downloads/en/devicedoc/21294e.pdf#G1.1011678>`_ and `Pin Description
+<http://ww1.microchip.com/downloads/en/devicedoc/21294e.pdf#G1.1034774>`_ section of the MCP3002
+datasheet.
 """
 from .mcp3xxx import MCP3xxx
 
@@ -42,7 +47,7 @@ class MCP3002(MCP3xxx):
     - (P0, P1) = CH0 - CH1
     - (P1, P0) = CH1 - CH0
 
-    See also the notes in the `AnalogIn <api.html#id3>`_ class.
+    See also the warning in the `AnalogIn`_ class API.
     """
     DIFF_PINS = {
         (0, 1) : P0,

adafruit_mcp3xxx/mcp3004.py

@@ -26,6 +26,11 @@
 converter instance.
 
 * Author(s): Brent Rubell
+
+For proper wiring, please refer to `Package Types diagram
+<https://cdn-shop.adafruit.com/datasheets/MCP3008.pdf#page=1>`_ and `Pin Description section
+<https://cdn-shop.adafruit.com/datasheets/MCP3008.pdf#G1.1035093>`_ of the MCP3004/MCP3008
+datasheet.
 """
 
 from .mcp3xxx import MCP3xxx
@@ -46,7 +51,7 @@ class MCP3004(MCP3xxx):
     - (P2, P3) = CH2 - CH3
     - (P3, P2) = CH3 - CH2
 
-    See also the notes in the `AnalogIn <api.html#id3>`_ class.
+    See also the warning in the `AnalogIn`_ class API.
     """
     DIFF_PINS = {
         (0, 1) : P0,

adafruit_mcp3xxx/mcp3008.py

@@ -26,6 +26,11 @@
 converter instance.
 
 * Author(s): Brent Rubell
+
+For proper wiring, please refer to the `Package Types diagram
+<https://cdn-shop.adafruit.com/datasheets/MCP3008.pdf#page=1>`_ and `Pin Description section
+<https://cdn-shop.adafruit.com/datasheets/MCP3008.pdf#G1.1035093>`_ of the MCP3004/MCP3008
+datasheet.
 """
 
 from .mcp3xxx import MCP3xxx
@@ -54,7 +59,7 @@ class MCP3008(MCP3xxx):
     - (P6, P7) = CH6 - CH7
     - (P7, P6) = CH7 - CH6
 
-    See also the notes in the `AnalogIn <api.html#id3>`_ class.
+    See also the warning in the `AnalogIn`_ class API.
     """
     DIFF_PINS = {
         (0, 1) : P0,

adafruit_mcp3xxx/mcp3xxx.py

@@ -40,6 +40,18 @@
 * Adafruit CircuitPython firmware for the supported boards:
   https://github.com/adafruit/circuitpython/releases
 * Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
+
+.. note:: The ADC chips' input pins (AKA "channels" in the datasheets) are aliased in this library
+    as integer variables whose names start with "P" (eg ``MCP3008.P0`` is channel 0 on the MCP3008
+    chip). Each module that contains a driver class for a particular ADC chip has these aliases
+    predefined accordingly. This is done for code readability and prevention of erroneous SPI
+    commands.
+
+.. important::
+    The differential reads (comparisons done by the ADC chip) are limited to certain pairs of
+    channels. These predefined pairs are referenced in this documentation as differential mappings.
+    Please refer to the driver class of your ADC chip (`MCP3008`_, `MCP3004`_, `MCP3002`_) for a
+    list of available differential mappings.
 """
 
 __version__ = "0.0.0-auto.0"
@@ -49,9 +61,8 @@
 
 class MCP3xxx:
     """
-    MCP3xxx Interface. A base class meant for instantiating
-    :class:`~adafruit_mcp3xxx.mcp3008.MCP3008`, :class:`~adafruit_mcp3xxx.mcp3004.MCP3004`,
-    or :class:`~adafruit_mcp3xxx.mcp3002.MCP3002` child classes.
+    This abstract base class is meant to be inherited by `MCP3008`_, `MCP3004`_,
+    or `MCP3002`_ child classes.
 
     :param ~adafruit_bus_device.spi_device.SPIDevice spi_bus: SPI bus the ADC is connected to.
     :param ~digitalio.DigitalInOut cs: Chip Select Pin.
@@ -65,14 +76,20 @@ def __init__(self, spi_bus, cs, ref_voltage=3.3):
 
     @property
     def reference_voltage(self):
-        """Returns the MCP3xxx's reference voltage."""
+        """Returns the MCP3xxx's reference voltage. (read-only)"""
         return self._ref_voltage
 
     def read(self, pin, is_differential=False):
-        """SPI Interface for MCP3xxx-based ADCs reads.
+        """SPI Interface for MCP3xxx-based ADCs reads. Due to 10-bit accuracy, the returned
+        value ranges [0, 1023].
 
         :param int pin: individual or differential pin.
         :param bool is_differential: single-ended or differential read.
+
+        .. note:: This library offers a helper class called `AnalogIn`_ for both single-ended
+            and differential reads. If you opt to not implement `AnalogIn`_ during differential
+            reads, then the ``pin`` parameter should be the first of the two pins associated with
+            the desired differential mapping.
         """
         self._out_buf[1] = ((not is_differential) << 7) | (pin << 4)
         with self._spi_device as spi:

docs/api.rst

@@ -1,21 +1,21 @@
-API
-------------
-
-.. automodule:: adafruit_mcp3xxx.mcp3xxx
-    :members:
-
-.. automodule:: adafruit_mcp3xxx.mcp3008
-    :members:
-    :show-inheritance:
-
-.. automodule:: adafruit_mcp3xxx.mcp3004
-    :members:
-    :show-inheritance:
-
-.. automodule:: adafruit_mcp3xxx.mcp3002
-    :members:
-    :exclude-members: read
-    :show-inheritance:
-
-.. automodule:: adafruit_mcp3xxx.analog_in
-    :members:
+API
+------------
+
+.. automodule:: adafruit_mcp3xxx.mcp3xxx
+    :members:
+
+.. automodule:: adafruit_mcp3xxx.analog_in
+    :members:
+
+.. automodule:: adafruit_mcp3xxx.mcp3008
+    :members:
+    :show-inheritance:
+
+.. automodule:: adafruit_mcp3xxx.mcp3004
+    :members:
+    :show-inheritance:
+
+.. automodule:: adafruit_mcp3xxx.mcp3002
+    :members:
+    :exclude-members: read
+    :show-inheritance: